Upsun CLI Management Skill

Comprehensive skill for managing Upsun Platform-as-a-Service projects using the Upsun CLI (v5.6.0+).

Overview

This skill enables AI coding agents to help you manage Upsun projects through the Upsun CLI. Upsun is a unified, multi-cloud Platform-as-a-Service built for teams that need flexibility without compromise. This skill covers:

• 130+ CLI commands across 30 namespaces
• Deployment workflows for safe production deployments
• Environment management including branching, merging, and synchronization
• Backup and restore operations with safety checks
• Resource scaling and autoscaling configuration
• Database operations for PostgreSQL, MongoDB, Redis, and Valkey
• Security and access management for teams and users
• Development tools including SSH, tunnels, and logs

Prerequisites

Authentication Required: You must be authenticated to Upsun before using any commands.

Check authentication status:

upsun auth:info

If not authenticated, log in via browser:

upsun auth:browser-login

Or using an API token:

upsun auth:api-token-login

All helper scripts in this skill include automatic authentication checking.

Quick Start

Most Common Operations

List your projects:

upsun projects

List environments in a project:

upsun environments -p PROJECT_ID

Deploy changes to an environment:

upsun push -p PROJECT_ID -e ENVIRONMENT_NAME

Create a backup before major changes:

upsun backup:create -p PROJECT_ID -e ENVIRONMENT_NAME

View environment logs:

upsun logs -p PROJECT_ID -e ENVIRONMENT_NAME

What Do You Want to Do?

Deploy & Manage Code

Deploy changes:

environment:push

,

environment:deploy

,

environment:redeploy

Create test environment:

environment:branch

Merge changes:

environment:merge

Monitor deployments:

activity:list

,

activity:log

→ See references/deployments.md for deployment patterns

Manage Environments

List environments:

environment:list

View details:

environment:info

,

environment:url

Create branch:

environment:branch

Activate/deactivate:

environment:activate

,

environment:delete

Pause/resume:

environment:pause

,

environment:resume

Sync from parent:

environment:synchronize

→ See references/environments.md for environment lifecycle → Use

scripts/environment-status.sh

for comprehensive status

Backup & Restore

Create backup:

backup:create

List backups:

backup:list

View backup details:

backup:get

Restore backup:

backup:restore

Delete old backups:

backup:delete

→ See references/backups.md for backup patterns → Use

scripts/backup-with-verification.sh

for verified backups

Manage Projects & Organizations

Create project:

project:create

List projects:

project:list

Get project:

project:get

(clone locally) Initialize project:

project:init

Manage organizations:

organization:*

Manage teams:

team:*

→ See references/projects-organizations.md

Work with Databases & Services

Database dump:

db:dump

Run SQL:

db:sql

MongoDB operations:

service:mongo:dump

,

service:mongo:export

,

service:mongo:shell

Redis CLI:

service:redis-cli

Valkey CLI:

service:valkey-cli

View relationships:

environment:relationships

→ See references/services-databases.md

Scale Resources & Monitor Performance

View resources:

resources:get

Set resources:

resources:set

Configure autoscaling:

autoscaling:set

,

autoscaling:get

Monitor metrics:

metrics:cpu

,

metrics:memory

,

metrics:disk

View container sizes:

resources:size:list

→ See references/resources-scaling.md → Use

scripts/resource-audit.sh

for cross-environment analysis

Manage Access & Security

Add/remove users:

user:add

,

user:delete

,

user:list

Manage teams:

team:create

,

team:user:add

SSH keys:

ssh-key:add

,

ssh-key:list

,

ssh-key:delete

SSL certificates:

certificate:add

,

certificate:list

Authentication:

auth:browser-login

,

auth:api-token-login

→ See references/access-security.md

Configure Domains, Routes & Variables

Add domain:

domain:add

List routes:

route:list

Manage variables:

variable:create

,

variable:list

,

variable:update

Configure integrations:

integration:add

,

integration:list

View environment URLs:

environment:url

→ See references/integration-variables.md

Development Tools

SSH to environment:

environment:ssh

Transfer files:

environment:scp

Create tunnels:

tunnel:open

,

tunnel:single

View logs:

environment:logs

Run Drush commands:

environment:drush

Enable Xdebug:

environment:xdebug

→ See references/development-tools.md

Helper Scripts

This skill includes helper scripts for complex operations. All scripts include authentication checking and error handling.

Authentication & Health

scripts/check-auth.sh

- Verify authentication status and guide user through login if needed

scripts/health-check.sh PROJECT_ID ENVIRONMENT_NAME

- Comprehensive environment health check including deployment status, activities, metrics, and routes

Deployment Safety

scripts/pre-deploy-check.sh PROJECT_ID ENVIRONMENT_NAME

- Pre-deployment validation to catch common issues before deploying

Backup Operations

scripts/backup-with-verification.sh PROJECT_ID ENVIRONMENT_NAME [--live]

- Create backup and verify success, returns backup ID

scripts/safe-restore.sh PROJECT_ID ENVIRONMENT_NAME BACKUP_ID [--target ENV]

- Safe restore with pre-restore backup and validation

Status & Monitoring

scripts/environment-status.sh PROJECT_ID ENVIRONMENT_NAME

- Detailed environment status in JSON format

scripts/resource-audit.sh PROJECT_ID

- Resource usage analysis across all environments

Command Discovery

Browse by Category

Use the reference documentation to find commands organized by category:

Use Case	Reference File
Alphabetical command lookup	COMMAND-INDEX.md
Environment lifecycle & operations	environments.md
Deployment patterns & workflows	deployments.md
Backup & restore operations	backups.md
Project & organization management	projects-organizations.md
Database & service operations	services-databases.md
Resource scaling & performance	resources-scaling.md
Security & access control	access-security.md
Domains, routes, variables	integration-variables.md
Development tools	development-tools.md
Common issues & solutions	troubleshooting.md

Search by Command Name

If you know the command name, use references/COMMAND-INDEX.md for quick alphabetical lookup of all 130+ commands.

Permission Configuration

Add Upsun permissions to your

opencode.json

:

Minimal (Read-only operations)

{
  "permission": {
    "skill": {
      "upsun": "allow"
    },
    "bash": {
      "upsun auth:info*": "allow",
      "upsun environment:list*": "allow",
      "upsun environment:info*": "allow",
      "upsun activity:list*": "allow",
      "upsun project:list*": "allow"
    }
  }
}

Standard (Common workflows)

{
  "permission": {
    "skill": {
      "upsun": "allow"
    },
    "bash": {
      "upsun auth:*": "allow",
      "upsun environment:*": "allow",
      "upsun activity:*": "allow",
      "upsun backup:*": "allow",
      "upsun deploy*": "allow",
      "upsun project:*": "allow"
    }
  }
}

Full (All operations)

{
  "permission": {
    "skill": {
      "upsun": "allow"
    },
    "bash": {
      "upsun *": "allow"
    }
  }
}

See references/access-security.md for detailed permission scope information.

Common Workflows

Safe Production Deployment

1. Verify authentication:

   scripts/check-auth.sh

2. Pre-deployment checks:

   scripts/pre-deploy-check.sh PROJECT_ID production

3. Create backup:

   scripts/backup-with-verification.sh PROJECT_ID production

4. Deploy:

   upsun environment:deploy -p PROJECT_ID -e production

5. Monitor:

   upsun activity:log ACTIVITY_ID

6. Verify:

   scripts/health-check.sh PROJECT_ID production

Feature Branch Development

1. Create branch:

   upsun environment:branch new-feature -p PROJECT_ID

2. Make changes and push:

   upsun push -p PROJECT_ID -e new-feature

3. Test on branch environment
4. Merge to parent:

   upsun merge -p PROJECT_ID -e new-feature

5. Delete branch:

   upsun environment:delete -p PROJECT_ID -e new-feature

Environment Synchronization

1. Check status:

   scripts/environment-status.sh PROJECT_ID staging

2. Create backup:

   upsun backup:create -p PROJECT_ID -e staging

3. Sync from production:

   upsun sync -p PROJECT_ID -e staging

4. Verify:

   scripts/health-check.sh PROJECT_ID staging

Getting Help

• List all commands:

  upsun list

• Command help:

  upsun COMMAND --help

• Online documentation:

  upsun docs

• Project console:

  upsun console

• Troubleshooting: See references/troubleshooting.md

Version Compatibility

This skill is designed for Upsun CLI v5.6.0 and above. Check your version:

upsun --version

Update the CLI if needed following the Upsun CLI installation guide.