upsun

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.