Deploy CLI

A command-line interface for managing AWS Fargate deployments with domain purchasing, multi-environment support, and optional services (RDS, Redis, S3, SQS).

Installation

bun install

Quick Start

# Initialize a new project
deploy init my-app

# Create a staging environment
deploy env create staging

# Apply infrastructure
deploy infra apply --env staging

# Deploy your application
deploy deploy --env staging

Commands

Project Commands

| Command | Description | |---------|-------------| | init [name] | Initialize a new project (interactive or from config) | | projects | List all projects | | project select <id> | Set active project | | project delete <id> | Delete project and optionally destroy infrastructure |

Environment Commands

| Command | Description | |---------|-------------| | env create <name> | Create environment (staging|prod) | | env destroy <name> | Tear down environment | | env list | List environments for current project | | env switch <name> | Switch active environment | | env vars set <KEY> <VALUE> | Set environment variable (use --secret for secrets) | | env vars get <KEY> | Get environment variable value | | env vars list | List all environment variables | | env vars delete <KEY> | Delete environment variable | | env vars import <file> | Import from .env file (use --secrets KEY1,KEY2 for secrets) |

Domain Commands

| Command | Description | |---------|-------------| | domain list | List all domains (registered + pending) | | domain check <name> | Check domain availability and price | | domain purchase <name> | Purchase domain (non-blocking, returns operation ID) | | domain status <op-id> | Check domain operation/provisioning status | | domain info <name> | Show detailed domain info and attachment | | domain attach <name> | Attach domain to deployment (--project, --env) | | domain detach <name> | Detach domain from deployment | | domain delete <name> | Delete domain (hosted zone + disable auto-renew) | | domain sync | Sync domain registry with Route53 |

Service Commands

| Command | Description | |---------|-------------| | service add <type> | Add service (rds|redis|s3|sqs) | | service remove <type> | Remove service | | service list | List enabled services |

Deployment Commands

| Command | Description | |---------|-------------| | deploy [--env <name>] | Build and deploy to environment | | rollback [version] | Rollback to previous or specific version | | status | Show deployment status |

Infrastructure Commands

| Command | Description | |---------|-------------| | infra configure --env <name> | Configure infrastructure (CPU, memory, ports, etc.) | | infra apply --env <name> | Apply Terraform configuration | | infra destroy --env <name> | Destroy infrastructure | | infra status --env <name> | Show infrastructure status | | infra health --env <name> | Run health checks | | infra check --env <name> | Show pending infrastructure changes (terraform plan) | | infra update --env <name> | Apply infrastructure changes (with --auto-approve option) | | infra diff --env <name> | Show human-readable diff of pending changes |

Container Commands

| Command | Description | |---------|-------------| | logs [--follow] | View CloudWatch logs | | exec [command] | ECS Exec into running container |

Config Commands

| Command | Description | |---------|-------------| | config show | Show current configuration | | config set <key> <val> | Set default value | | config export | Export config to file | | config import <file> | Import config from file |

State & Migration Commands

| Command | Description | |---------|-------------| | state | Show CLI state, AWS config, and validate access | | info | Alias for 'state' | | migrate | Migrate data from S3 to DynamoDB (one-time) |

Server Commands

| Command | Description | |---------|-------------| | server [--port <n>] | Start web UI server (default: 4000) |

Claude Integration

| Command | Description | |---------|-------------| | install-agents | Install Claude Code subagents |

Global Options

| Option | Description | |--------|-------------| | --project <id> | Override active project | | --env <name> | Override active environment | | --region <region> | AWS region (default: us-east-1) | | --profile <name> | AWS profile to use | | -v, --verbose | Verbose output | | -h, --help | Show help message | | --version | Show version |

Examples

Domain Lifecycle

# Check domain availability
deploy domain check myapp.click

# Purchase domain (non-blocking)
deploy domain purchase myapp.click
# Returns operation ID immediately

# Check provisioning status
deploy domain status <operation-id>

# List all domains (shows pending + registered)
deploy domain list

# Attach domain to deployment
deploy domain attach myapp.click --project abc123 --env staging

# Delete domain (disables auto-renew, removes from registry)
deploy domain delete myapp.click

Environment Variables Management

# Set a plain text environment variable
deploy env vars set API_URL https://api.example.com --env staging

# Set a secret (stored in AWS SSM Parameter Store)
deploy env vars set DATABASE_PASSWORD mysecret --env staging --secret

# Get a variable value
deploy env vars get API_URL --env staging

# List all variables for an environment
deploy env vars list --env staging

# Show values (including decrypted secrets)
deploy env vars list --env staging --show-values

# Import from .env file (mark specific keys as secrets)
deploy env vars import .env.staging --env staging --secrets DATABASE_PASSWORD,API_KEY

# Delete a variable
deploy env vars delete API_URL --env staging

Full Deployment Flow

# Initialize project
deploy init my-app --domain myapp.click

# Create and configure staging
deploy env create staging
deploy service add redis
deploy infra apply --env staging

# Set environment variables
deploy env vars set NODE_ENV production --env staging
deploy env vars set DATABASE_URL postgres://... --env staging --secret

# Deploy application
deploy deploy --env staging

# View logs
deploy logs --follow

# Exec into container
deploy exec /bin/sh

Storage Architecture

The deploy-cli uses a local-first storage strategy with optional sync to the Fieldwork API.

| Data Type | Storage Location | Purpose | |-----------|------------------|---------| | Light metadata | ~/.config/fieldwork/projects/{id}/ | Project config, environments, services | | Heavy data | {project}/.deploy/ | Terraform logs, state backups | | Terraform state | Fieldwork API (HTTP backend) | Shared .tfstate storage | | Team sync | Fieldwork API (optional) | Shared visibility |

Local Storage Structure

~/.config/fieldwork/
├── global/
│   ├── user-defaults.json     # User preferences
│   └── domains/               # Domain registry
└── projects/
    └── {uuid}/
        ├── config.json        # Project config
        ├── environments/      # Per-environment config
        ├── infrastructure/    # Infrastructure settings
        └── terraform/         # Local TF state (if not using Fieldwork API)

See STATE_MANAGEMENT.md for detailed architecture documentation.

Environment Variables

| Variable | Description | |----------|-------------| | AWS_REGION | AWS region (default: us-east-1) | | AWS_PROFILE | AWS profile to use |

Web UI

Start the web UI server:

deploy server --port 4000

Then open http://localhost:4000 in your browser.

Publishing

From the repository root:

bun run publish:deploy

Or directly:

./scripts/codeartifact-publish.sh Modules/deploy-cli

License

MIT