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

``bash
bun install
`

Quick Start

`bash


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

$3

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

$3

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

$3

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

$3

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

$3

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

$3

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

$3

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

$3

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

$3

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

$3

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

$3

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

Global Options

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

Examples

$3

`bash


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

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
`

$3

`bash


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
`

$3

`bash


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 |

$3

`
~/.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.

Testing

The deploy-cli uses a multi-layered testing approach:

$3

| Category | Location | Description |
|----------|----------|-------------|
| Unit tests | src/services/*.test.ts | Isolated service tests with mocked dependencies |
| CLI tests | src/cli/commands/*.test.ts | Command parsing and output tests |
| Integration tests | src/test/integration/*.test.ts | Tests against real Fieldwork API |
| E2E tests | src/cli/agent-workflow.test.ts | Full CLI workflow tests |

$3

Tests are orchestrated via root vitest.config.ts.

`bash


Run all tests

bun run test

Run specific test file

bun run test src/cli/agent-workflow.test.ts

Run with verbose output

bun run test --reporter=verbose

Run a specific test by name

bun run test -t "init creates project"
`

$3

Tests use an isolated environment to avoid conflicts:

| Component | Test Value | Production Value |
|-----------|------------|------------------|
| State directory | $TMPDIR/deploy-cli-test-* | ~/.config/fieldwork/ |
| API server | localhost:3001 (test server) | api.fieldwork.dev |
| Database | localhost:5434 (test DB) | localhost:5433 |
| AWS | LocalStack (localhost:4566) | Real AWS |

Key environment variables for tests:

| Variable | Purpose |
|----------|---------|
| FIELDWORK_STATE_DIR | Override state directory location |
| FIELDWORK_API_URL | Override API server URL |
| FIELDWORK_API_KEY | API key for authentication |
| DEPLOY_CLI_OFFLINE | Set to true to skip API calls entirely |

$3

Integration tests use M2M (Machine-to-Machine) authentication:

1. Tests exchange WorkOS M2M client credentials for a JWT token
2. The Fieldwork API auto-creates a service user for the M2M client ID
3. Resources are scoped to this service user during tests

This allows tests to use the real API without requiring interactive login.

$3

Each test run uses:
- Unique state directory in $TMPDIR
- Isolated database schema (when using TestContext)
- Separate API port per worker for parallel execution
- Automatic cleanup after tests complete

See docs/TESTING-WORKOS.md for auth-specific testing details.

Environment Variables

| Variable | Description |
|----------|-------------|
| AWS_REGION | AWS region (default: us-east-1) |
| AWS_PROFILE | AWS profile to use |
| FIELDWORK_API_URL | Fieldwork API URL (default: https://api.fieldwork.dev) |
| FIELDWORK_API_KEY | API key for Fieldwork API |
| DEPLOY_CLI_OFFLINE | Skip Fieldwork API calls (for offline development) |

Web UI

Start the web UI server:

`bash
deploy server --port 4000
`

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

Publishing

From the repository root:

`bash
bun run publish:deploy
`

Or directly:

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

License

MIT