Sol Documentation

Agent-optimized CLI for Upsun.

What is Sol?

Sol is a minimal CLI optimized for AI code agents. It provides:

Lean output by default - List commands return essential fields only (up to 99% smaller)
TOON format by default - Token-efficient encoding (~50% smaller than JSON)
No interactive prompts - Flags and stdin only
Predictable exit codes - 0 success, 1 user error, 2 API error, 3 internal
Machine-readable errors - Error codes and structured details
JSON output - Use -o json when humans need to read it

Authentication

# Log in (opens browser for OAuth)
sol auth:login

# Check authentication status
sol auth:info

# Log out (removes stored credentials)
sol auth:logout

For CI/automated environments, use an API token instead of interactive login:

export UPSUN_TOKEN=your-api-token
sol auth:info  # Shows authentication via environment variable

Projects & Environments

# List projects (lean output: id, title, region)
sol project:list

# List projects with all fields
sol project:list --full

# Project details
sol project:info PROJECT_ID

# List environments (lean output: id, name, status, parent)
sol environment:list --project PROJECT_ID

# List environments with all fields
sol environment:list --project PROJECT_ID --full

# Environment details
sol environment:info main --project PROJECT_ID

# SSH into environment
sol ssh --project PROJECT_ID --environment main

Activities

# List recent activities (lean output: id, type, state, created_at)
sol activity:list --project PROJECT_ID

# List activities with all fields
sol activity:list --project PROJECT_ID --full

# Filter by state/type
sol activity:list --project PROJECT_ID --state complete --limit 5

# View activity log
sol activity:log ACTIVITY_ID --project PROJECT_ID

Variables

# List project variables
sol variable:list --project PROJECT_ID

# List environment variables
sol variable:list --project PROJECT_ID --environment main

# Set a variable
sol variable:set MY_VAR "value" --project PROJECT_ID

# Set sensitive variable (value hidden)
sol variable:set SECRET "value" --project PROJECT_ID --sensitive

# Delete a variable
sol variable:delete MY_VAR --project PROJECT_ID

Environment Lifecycle

# Create a branch environment
sol environment:branch feature-x --project PROJECT_ID --parent main

# Create and wait for completion
sol environment:branch feature-x --project PROJECT_ID --wait

# Activate an inactive environment
sol environment:activate staging --project PROJECT_ID

# Deactivate an environment
sol environment:deactivate staging --project PROJECT_ID

# Delete an environment (must be deactivated first)
sol environment:delete old-feature --project PROJECT_ID

Deployments

# Push code to Upsun (triggers deployment)
sol push --project PROJECT_ID

# Push to a specific branch
sol push --project PROJECT_ID --target staging

# Force push
sol push --project PROJECT_ID --force

# Redeploy an environment (runs post_deploy hook only)
sol redeploy --project PROJECT_ID --environment main

# Redeploy and wait for completion
sol redeploy --project PROJECT_ID --environment main --wait

Environment Merge & Sync

# Merge environment into its parent
sol environment:merge staging --project PROJECT_ID

# Merge and wait for completion
sol environment:merge staging --project PROJECT_ID --wait

# Sync code and data from parent
sol environment:sync feature-x --project PROJECT_ID --data --code

# Sync code only
sol environment:sync feature-x --project PROJECT_ID --code

Services, Apps & Routes

# List services in an environment
sol service:list --project PROJECT_ID --environment main

# List applications
sol app:list --project PROJECT_ID --environment main

# Validate app configuration
sol app:config-validate --project PROJECT_ID

# List routes
sol route:list --project PROJECT_ID --environment main

# Get environment URL
sol environment:url --project PROJECT_ID --environment main

# Get service relationships
sol environment:relationships --project PROJECT_ID --environment main

Backups

# List backups for an environment
sol backup:list --project PROJECT_ID --environment main

# Get backup details
sol backup:get BACKUP_ID --project PROJECT_ID --environment main

# Create a backup
sol backup:create --project PROJECT_ID --environment main

# Create a safe backup (waits for running activities)
sol backup:create --project PROJECT_ID --environment main --safe

# Restore a backup
sol backup:restore BACKUP_ID --project PROJECT_ID --environment main

# Restore to a different branch
sol backup:restore BACKUP_ID --project PROJECT_ID --environment main --target staging

# Delete a backup
sol backup:delete BACKUP_ID --project PROJECT_ID --environment main

Organizations & Users

# List organizations
sol organization:list

# Get organization details
sol organization:info ORG_ID

# List project users
sol user:list --project PROJECT_ID

Resources

# Get resource allocation for an environment
sol resources:get --project PROJECT_ID --environment main

# Set resources for a service
sol resources:set --project PROJECT_ID --environment main --service db --cpu 1 --memory 1024

# Set resources for an app
sol resources:set --project PROJECT_ID --environment main --app myapp --cpu 0.5 --memory 512

Integrations

# List integrations
sol integration:list --project PROJECT_ID

# Get integration details
sol integration:get INTEGRATION_ID --project PROJECT_ID

Domains & Certificates

# List domains
sol domain:list --project PROJECT_ID

# List certificates
sol certificate:list --project PROJECT_ID

SSH Keys

# List SSH keys
sol ssh-key:list

Output Formats

Sol optimizes output for agent context windows:

Lean output (default for list commands):

project:list returns id, title, region (4KB vs 22KB full)
environment:list returns id, name, status, parent (86B vs 28KB full)
activity:list returns id, type, state, created_at (409B vs 4KB full)
Use --full flag when you need all fields

Format options:

# TOON (default) - token-efficient for LLMs (~50% smaller than JSON)
sol project:list

# JSON - use when humans need to read the output
sol project:list --output json

# Full output with all fields
sol project:list --full

Command Schema

Get machine-readable documentation for any command:

# Get schema for a specific command
sol project:list --schema

# Get schema in TOON format
sol variable:set --schema --output toon

# List all available commands
sol --schema

Global Flags

Flag	Short	Default	Description
`--output`	`-o`	`toon`	Output format: toon, json
`--project`	`-p`		Project ID
`--environment`	`-e`		Environment name
`--quiet`	`-q`	`false`	Suppress non-essential output
`--no-cache`		`false`	Bypass cache for this request
`--debug`		`false`	Show API request/response details
`--schema`		`false`	Output command schema instead of running

Command-Specific Flags

Flag	Short	Commands	Description
`--full`	`-f`	`project:list`, `environment:list`, `activity:list`, etc.	Include all fields in output
`--wait`	`-w`	`environment:branch`, `environment:activate`, `environment:merge`, `redeploy`, etc.	Wait for activity to complete
`--safe`		`backup:create`	Wait for running activities before backup
`--target`		`backup:restore`	Restore to a different environment
`--code`		`environment:sync`	Sync code from parent
`--data`		`environment:sync`	Sync data from parent
`--app`	`-a`	`ssh`, `environment:relationships`, `resources:set`	Target a specific application
`--service`	`-s`	`resources:set`	Target a specific service

Configuration

Config file: ~/.sol/config.yaml

default_project: abc123
default_environment: main

output:
  format: toon
  color: auto

cache:
  enabled: true
  ttl_seconds: 600

Environment Variables

Variable	Description
`UPSUN_TOKEN`	API token (overrides keychain)
`UPSUN_PROJECT`	Default project ID
`UPSUN_ENVIRONMENT`	Default environment

Error Format

All errors return structured output:

error AUTH_EXPIRED
  message "Authentication expired and refresh failed"
  hint "Run 'sol auth:login' to re-authenticate"

Exit Codes

Code	Meaning
0	Success
1	User error (bad input, auth failed)
2	API error (server error, network issue)
3	Internal error (bug in CLI)