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 Claude 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 → Use examples/deploy-workflow.sh for complete deployment workflow

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

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

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

Command Discovery

Browse by Category

Use the reference documentation to find commands organized by category:

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 .claude/settings.local.json:

Minimal (Read-only operations)

{
  "permissions": {
    "allow": [
      "Bash(upsun auth:info:*)",
      "Bash(upsun environment:list:*)",
      "Bash(upsun environment:info:*)",
      "Bash(upsun activity:list:*)",
      "Bash(upsun project:list:*)"
    ]
  }
}

Standard (Common workflows)

{
  "permissions": {
    "allow": [
      "Bash(upsun auth:*)",
      "Bash(upsun environment:*)",
      "Bash(upsun activity:*)",
      "Bash(upsun backup:*)",
      "Bash(upsun deploy*:*)",
      "Bash(upsun project:*)"
    ]
  }
}

Full (All operations)

{
  "permissions": {
    "allow": [
      "Bash(upsun *:*)"
    ]
  }
}

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

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.