A comprehensive Claude Code skill for managing Upsun projects using the Upsun CLI.

This skill enables Claude Code to help you manage Upsun projects through the Upsun CLI (v5.6.0+), covering:

• 130+ CLI commands across 30 namespaces
• Deployment workflows with safe production deployment patterns
• Environment management including branching, merging, and synchronization
• Backup and restore operations with verification and 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 log access
• 7 helper scripts for health checks, pre-deployment validation, and automation

1. Upsun CLI v5.6.0 or higher installed and authenticated

   # Install Upsun CLI (if not already installed)
   curl -fsSL https://raw.githubusercontent.com/platformsh/cli/main/installer.sh | VENDOR=upsun bash
   
   # Or via brew
   brew install platformsh/tap/upsun-cli
   
   # Authenticate
   upsun auth:browser-login

2. Claude Code - Available at claude.ai/code

You have four options to install this skill:

Install via Claude Code plugin system:

# In Claude Code, run:
/plugin marketplace add upsun/claude-marketplace
/plugin install upsun-skill

# Or if using a custom marketplace:
/plugin marketplace add YOUR_ORG/your-marketplace
/plugin install upsun-skill@your-marketplace

The plugin will automatically:

• Install the skill and all helper scripts
• Set up recommended permissions
• Make the skill available across all your projects

Install for all your projects manually:

# Clone to personal skills directory
mkdir -p ~/.claude/skills
cd ~/.claude/skills
git clone https://github.com/upsun/claude-skill.git upsun

# Or download and extract
curl -L https://github.com/upsun/claude-skill/archive/main.zip -o upsun.zip
unzip upsun.zip -d ~/.claude/skills/
mv ~/.claude/skills/claude-skill-main ~/.claude/skills/upsun

Install for a specific project (shared with team via Git):

# From your project directory
mkdir -p .claude/skills
cd .claude/skills
git clone https://github.com/upsun/claude-skill.git upsun

This method is ideal for teams - the skill is committed to Git and automatically available to all team members.

Download and place in either skills directory:

1. Download from Releases
2. Extract to ~/.claude/skills/upsun/ or .claude/skills/upsun/
3. Ensure the skills/upsun/SKILL.md file is present

If you installed via /plugin install, recommended permissions are automatically suggested. Accept them to enable full functionality.

Add Upsun CLI permissions to your Claude Code settings:

For project-specific permissions, create or edit .claude/settings.local.json:

{
  "permissions": {
    "allow": [
      "Bash(upsun auth:*)",
      "Bash(upsun environment:*)",
      "Bash(upsun activity:*)",
      "Bash(upsun backup:*)",
      "Bash(upsun project:*)",
      "Bash(upsun logs:*)",
      "Bash(upsun resources:*)",
      "Bash(upsun metrics:*)",
      "Bash(upsun user:*)",
      "Bash(upsun organization:*)"
    ]
  }
}

For global permissions, edit ~/.claude/settings.json with the same structure.

1. Open Claude Code in a project or terminal
2. Ask Claude: "Can you help me deploy to Upsun?"
3. Claude should activate the Upsun skill and offer assistance

The skill activates automatically when you mention Upsun-related tasks:

• "Deploy to Upsun"
• "Create a new Upsun environment"
• "Backup the production environment"
• "Check Upsun environment status"
• "Scale Upsun resources"
• "Manage Upsun users"

Deploy to production:

"Deploy my changes to the production environment on Upsun"

Create and test a feature branch:

"Create a new feature environment for testing my authentication changes"

Health check:

"Check the health of my production Upsun environment"

Backup before changes:

"Create a verified backup of production before I deploy"

Resource optimization:

"Audit resource usage across all my Upsun environments"

• 11 reference files covering all aspects of Upsun management
• 130+ commands documented with examples and best practices
• Progressive disclosure - only loads documentation as needed
• Cross-referenced - easy navigation between related topics

7 battle-tested scripts for common operations:

1. check-auth.sh - Verify Upsun authentication
2. health-check.sh - 8-step environment health check
3. pre-deploy-check.sh - Pre-deployment validation
4. backup-with-verification.sh - Create and verify backups
5. safe-restore.sh - Safe restore with automatic rollback
6. environment-status.sh - JSON status output for automation
7. resource-audit.sh - Multi-environment resource analysis

• Safe production deployments
• Feature branch development
• Hotfix procedures
• Environment synchronization
• Disaster recovery
• Resource optimization
• Team management
• Database operations

• SKILL.md - Main skill navigation and quick reference
• CLAUDE.md - Development guide for contributing
• references/ - Detailed command documentation
  • COMMAND-INDEX.md - Alphabetical command reference
  • environments.md - Environment lifecycle
  • deployments.md - Deployment patterns
  • backups.md - Backup/restore procedures
  • services-databases.md - Database operations
  • resources-scaling.md - Resource management
  • access-security.md - Security and access control
  • integration-variables.md - Configuration
  • development-tools.md - Developer tools
  • projects-organizations.md - Project management
  • troubleshooting.md - Common issues

This skill uses a progressive disclosure architecture:

1. SKILL.md (entry point) - Workflow navigation and common operations
2. references/ (on-demand) - Detailed documentation loaded as needed
3. scripts/ (zero-context) - Executable helpers that only output results

This design minimizes context usage while providing comprehensive coverage.

Contributions are welcome! See CLAUDE.md for development guidelines.

# Clone the repository
git clone https://github.com/YOUR_USERNAME/claude-skill.git
cd claude-upsun-skill

# Test helper scripts (requires Upsun authentication)
./scripts/check-auth.sh
./scripts/health-check.sh PROJECT_ID ENVIRONMENT_NAME

1. Update existing reference files in references/
2. Add cross-references to related documents
3. Update SKILL.md if adding commonly-used commands
4. Test that Claude can find and use the new documentation

1. Follow the template in existing scripts
2. Include proper error handling and authentication checks
3. Make executable: chmod +x scripts/new-script.sh
4. Test with real Upsun projects
5. Document in relevant reference files

• Upsun CLI v5.6.0 or higher
• Claude Code (CLI or IDE extension)
• Authenticated Upsun account
• Bash shell for helper scripts

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

• Upsun Documentation: https://docs.upsun.com
• Upsun CLI Reference: https://docs.upsun.com/administration/cli/reference.html
• Claude Code Documentation: https://code.claude.com/docs
• Issues: Please report issues on the GitHub repository

• Built for the Upsun Platform-as-a-Service
• Designed for Claude Code by Anthropic
• Utilizes Upsun CLI v5.6.0 command structure