# Upsun > Manage Upsun Platform-as-a-Service projects. Use for deploying, creating environments, backups, scaling resources, database operations, SSH tunnels, logs, and Upsun CLI commands. Use when this capability is needed. - Skill: `tomevault-io/upsun` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/upsun` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/upsun/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/upsun --- # 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: ```bash upsun auth:info ``` If not authenticated, log in via browser: ```bash upsun auth:browser-login ``` Or using an API token: ```bash upsun auth:api-token-login ``` All helper scripts in this skill include automatic authentication checking. ## Quick Start ### Most Common Operations **List your projects:** ```bash upsun projects ``` **List environments in a project:** ```bash upsun environments -p PROJECT_ID ``` **Deploy changes to an environment:** ```bash upsun push -p PROJECT_ID -e ENVIRONMENT_NAME ``` **Create a backup before major changes:** ```bash upsun backup:create -p PROJECT_ID -e ENVIRONMENT_NAME ``` **View environment logs:** ```bash 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](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](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](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](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](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](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](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](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](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](references/COMMAND-INDEX.md) | | Environment lifecycle & operations | [environments.md](references/environments.md) | | Deployment patterns & workflows | [deployments.md](references/deployments.md) | | Backup & restore operations | [backups.md](references/backups.md) | | Project & organization management | [projects-organizations.md](references/projects-organizations.md) | | Database & service operations | [services-databases.md](references/services-databases.md) | | Resource scaling & performance | [resources-scaling.md](references/resources-scaling.md) | | Security & access control | [access-security.md](references/access-security.md) | | Domains, routes, variables | [integration-variables.md](references/integration-variables.md) | | Development tools | [development-tools.md](references/development-tools.md) | | Common issues & solutions | [troubleshooting.md](references/troubleshooting.md) | ### Search by Command Name If you know the command name, use [references/COMMAND-INDEX.md](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) ```json { "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) ```json { "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) ```json { "permission": { "skill": { "upsun": "allow" }, "bash": { "upsun *": "allow" } } } ``` See [references/access-security.md](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](references/troubleshooting.md) ## Version Compatibility This skill is designed for Upsun CLI v5.6.0 and above. Check your version: ```bash upsun --version ``` Update the CLI if needed following the [Upsun CLI installation guide](https://docs.upsun.com/administration/cli.html). --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/gmoigneu) — claim your Tome and manage your conversions.