CLI Reference

The km CLI is grouped by workflow stage. Every command picks its AWS profile automatically based on the operation.

Command	What it does
`km configure`	Set domain, account IDs, SSO URL, region, `resource_prefix`, `email_subdomain`
`km configure github`	Configure GitHub App token integration (`--discover` to find installations)
`km bootstrap`	Deploy SCP containment policy + KMS key + artifacts bucket
`km init`	Build Lambdas/sidecars, provision shared VPC/network (`--sidecars`, `--lambdas`)
`km doctor`	Validate platform health (20+ checks; `--all-regions`)
`km info`	Show platform config, accounts, SES quota, AWS spend, DynamoDB tables

Command	What it does
`km validate <profile>`	Check a profile YAML against the schema
`km create <profile>`	Provision a sandbox (`--no-bedrock`, `--docker`, `--alias`, `--on-demand`, `--ttl`, `--idle`)
`km clone <sandbox>`	Duplicate a running sandbox (`--alias`, `--count`, `--no-copy`)
`km list` (alias: `ls`)	List sandboxes with live status (`--wide`, `--json`, `--tags`)
`km status <sandbox>`	Budget, identity, idle countdown, resources
`km shell <sandbox>`	SSM session (`--root`, `--ports`, `--learn`, `--ami`)
`km agent <sandbox> --claude`	Interactive Claude session via SSM
`km agent run <sandbox>`	Non-interactive Claude/Codex (`--prompt`, `--wait`, `--interactive`, `--codex`)
`km agent attach <sandbox>`	Attach to a running agent's tmux session
`km agent results <sandbox>`	Fetch latest run output
`km agent list <sandbox>`	List all agent runs with status

Command	What it does
`km extend <sandbox> <dur>`	Add time before TTL expires
`km pause <sandbox>`	Hibernate (preserves RAM state on on-demand)
`km stop <sandbox>`	Stop instance, preserve infrastructure
`km resume <sandbox>`	Resume a paused or stopped sandbox
`km lock <sandbox>`	Prevent accidental destroy/stop/pause
`km unlock <sandbox>`	Re-enable lifecycle commands
`km destroy <sandbox>` (alias: `kill`)	Teardown sandbox (`--remote` by default; `--yes`)
`km budget add <sandbox>`	Top up compute or AI budget
`km rsync save/load <sandbox>`	Save/restore sandbox home directory snapshots
`km roll`	Rotate platform and sandbox credentials (`--platform`, `--sandbox`, `--dry-run`)

Command	What it does
`km at '<time>' <cmd>`	Schedule deferred/recurring operation (`create`, `destroy`, `pause`, `resume`, `extend`, `budget-add`, `agent run`)
`km at list`	List scheduled operations
`km at cancel <name>`	Cancel a scheduled operation

Command	What it does
`km logs <sandbox>`	Tail CloudWatch audit logs
`km otel <sandbox>`	AI spend summary + OTEL S3 data (`--prompts`, `--events`, `--tools`, `--timeline`)

Command	What it does
`km email send`	Send signed email between sandboxes or to/from operator (`--cc`, `--use-bcc`, `--reply-to`)
`km email read <sandbox>`	Read sandbox mailbox with signature verification (`--json`, `--mark-read`)

Command	What it does
`km slack init`	Bootstrap: validate token, write SSM params, create channel, send Connect invite, deploy bridge
`km slack test`	End-to-end smoke test through the bridge
`km slack status`	Print SSM-backed Slack config
`km slack rotate-token`	Rotate Slack bot token (validates, persists, force-cold-starts bridge, smoke tests)
`km slack rotate-signing-secret`	Rotate Slack App signing secret

Command	What it does
`km ami list`	List operator-baked AMIs (`--wide`)
`km ami bake <sandbox>`	Snapshot running sandbox into a custom AMI
`km ami copy <ami-id> --region <dst>`	Copy AMI to another region
`km ami delete <ami-id>`	Deregister AMI + delete EBS snapshots atomically

Command	What it does
`km uninit`	Destroy all shared regional infrastructure (reverse of `km init`)
`km unbootstrap`	Destroy foundation infrastructure (reverse of `km bootstrap`)

Provide feedback