Skip to content

CLI Reference

All commands are invoked as sc <command> (or uv run sc <command> inside a uv-managed project).

Global behaviour

  • Commands look for config.py (preferred) or sc.py in the current directory.
  • --env defaults to CONFIG.default_env when using config.py, or production for legacy sc.py.
  • State is stored in sc.state.<env>.json (per-env file).
  • A lock is held for the duration of any write command (build, deploy, destroy).

sc init

Scaffold a new project in the current directory.

sc init

Creates / updates:

  • config.py — minimal ProjectConfig stub (if not already present)
  • .gitignore — adds sc.state.json, sc.state.*.json, .sc/, .dist/

Run this once when starting a new project.

sc build

Deploy all components, then run tests.

sc build [COMPONENT] [OPTIONS]
Argument / Option Description
COMPONENT (optional) Run only this named component
--env, -e Environment name (default: CONFIG.default_env)
--dry-run Render templates and print commands; do not apply or test
--verbose, -v Print rendered paths, full command output, and state summaries
--json Print a JSON result object on success
--secrets-in-plaintext Allow secrets to appear in verbose output (use with care)

Steps:

  1. Renders component files to .dist/<name>/
  2. Runs terraform init + terraform apply -auto-approve (or the component's steps)
  3. Saves state and outputs to sc.state.<env>.json
  4. Runs all HttpTest assertions; prints a result table

sc build is the primary day-to-day command. It combines sc deploy + sc test in one call.

sc deploy

Deploy without running tests.

sc deploy [COMPONENT] [OPTIONS]

Same options as sc build, minus the test step. Useful when you want to apply infra and test separately.

sc destroy

Destroy all components (or a single one).

sc destroy [COMPONENT] [OPTIONS]
Argument / Option Description
COMPONENT (optional) Destroy only this component
--env, -e Environment name
--dry-run Print the destroy commands without running them
--verbose, -v Print full command output

Runs terraform destroy -auto-approve for each TerraformComponent. Clears saved state after a successful destroy.

sc plan

Render and plan without applying.

sc plan [COMPONENT] [OPTIONS]
Argument / Option Description
COMPONENT (optional) Plan only this component
--env, -e Environment name
--dry-run Skip running commands; only render templates
--verbose, -v Print full command output

Runs terraform init + terraform plan for each TerraformComponent. No state is modified.

sc test

Run smoke tests against already-deployed infrastructure.

sc test [COMPONENT] [OPTIONS]
Argument / Option Description
COMPONENT (optional) Run tests whose URL comes from this component's outputs
--env, -e Environment name
--verbose, -v Print each test name before running

Reads outputs from sc.state.<env>.json (no Terraform calls). Useful for re-running tests without redeploying.

sc output

Print saved output values.

sc output COMPONENT [KEY] [--env ENV]
Argument Description
COMPONENT Component name (e.g. infra)
KEY (optional) Specific output key (e.g. ip)

Without KEY, prints the full state record as JSON.

sc output infra ip          # prints: 34.123.1.164
sc output infra             # prints full JSON bundle

sc unlock

Release a stuck lock.

sc unlock [--env ENV] [--force]
Option Description
--force Delete the lock file and remote git tag without checking ownership

Use --force after a crash left a lock behind.

Environment variable: SC_OPERATOR

If set, this value is recorded as the operator in state and audit log entries, overriding the git user.email lookup.

SC_OPERATOR="ci-bot@example.com" sc build