CLI for managing Fargate deployments with domain purchasing, multi-environment support, and optional services
npm install @armynante/fieldwork-deployA command-line interface for managing AWS Fargate deployments with domain purchasing, multi-environment support, and optional services (RDS, Redis, S3, SQS).
``bash`
bun install
`bashInitialize a new project
deploy init my-app
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.clickPurchase 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 listAttach domain to deployment
deploy domain attach myapp.click --project abc123 --env stagingDelete 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 stagingSet a secret (stored in AWS SSM Parameter Store)
deploy env vars set DATABASE_PASSWORD mysecret --env staging --secretGet a variable value
deploy env vars get API_URL --env stagingList all variables for an environment
deploy env vars list --env stagingShow values (including decrypted secrets)
deploy env vars list --env staging --show-valuesImport from .env file (mark specific keys as secrets)
deploy env vars import .env.staging --env staging --secrets DATABASE_PASSWORD,API_KEYDelete a variable
deploy env vars delete API_URL --env staging
`$3
`bash
Initialize project
deploy init my-app --domain myapp.clickCreate and configure staging
deploy env create staging
deploy service add redis
deploy infra apply --env stagingSet environment variables
deploy env vars set NODE_ENV production --env staging
deploy env vars set DATABASE_URL postgres://... --env staging --secretDeploy application
deploy deploy --env stagingView logs
deploy logs --followExec 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 testRun specific test file
bun run test src/cli/agent-workflow.test.tsRun with verbose output
bun run test --reporter=verboseRun 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 completeSee 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
``MIT