Caatinga CLI Reference
The Caatinga CLI (@caatinga/cli) provides commands for every stage of smart contract development, from initialization to testing and upgrades. The binary is invoked as ctg.
Canonical Workflow
init → doctor → build → deploy → generate → read / invoke → browserRun ctg doctor before changing deploy state or troubleshooting the environment.
--help on any subcommand works reliably as of 3.9.2 — earlier versions could crash with Maximum call stack size exceeded on some subcommands.
Command Matrix
| Command | Description | Common Flags |
|---|---|---|
ctg init |
Scaffold new Soroban project | <name>, -t, --template, --minimal (alias --empty) |
ctg doctor |
Health check of toolchain & config | --network, --source, --all-networks, --strict, --strict-env, --strict-bindings |
ctg build |
Compile Rust contracts to WASM | [contract] (omit to build every contract) |
ctg deploy |
Deploy WASM binaries following DAG | [contract], --network, --source, -y, --force, --upgrade, --if-changed, --dry-run, --no-deps, --no-generate, --no-wire, --no-sync-env |
ctg upgrade |
In-place WASM upgrade on existing instance | <contract>, --network, --source, -y, --if-changed, --expected-hash, --no-build, --generate, --sync-env |
ctg estimate deploy |
Simulate a deploy and print the fee estimate | <contract>, --network, --source (required) |
ctg inspect |
Compare a deployed contract with its local artifact | <contract>, --network |
ctg rollback |
Restore a previous contractId from artifact history (local only) |
<contract>, --to <contractId>, --network, -y |
ctg migrate artifacts |
Upgrade caatinga.artifacts.json to the current schema |
— |
ctg wire |
Run postDeploy / postDeployRead hooks |
--network, --source, -y |
ctg sync-env |
Write frontend.envFile from the frontend.env mapping |
--network |
ctg generate |
Generate TS client bindings | [contract], --network, --strict-network |
ctg status |
Local artifacts + binding freshness table (no RPC) | --network, --json, --strict |
ctg invoke |
Execute state-changing contract calls | <contract>.<method>, --<arg> <value>, --source, -y, --no-resolve-aliases |
ctg read |
Simulate read-only contract state queries | <contract>.<method>, --<arg> <value>, --expect, --summary, --quiet, --source (required on mainnet) |
ctg smoke |
Run read-only smoke checks from smoke.reads / postDeployRead |
--network, --source (required on mainnet) |
ctg regression |
Local CI recipe: pnpm test → build → deploy --if-changed → generate → smoke |
--source (required), --network, -y, --skip-<step> |
ctg ci run |
CI helper: doctor → smoke, re-running the installed ctg |
--network, --source, --strict, --skip-smoke |
ctg identity |
Export/import Stellar CLI identity for CI | export, import <archive>, --path |
ctg version |
Print the CLI version and the npm dist-tag advisory | — |
ctg zk |
Circom Groth16 ZK proof helpers (init, build, prove, invoke) |
--allow-dev-ceremony |
-y, --yes skips the mainnet confirmation prompt (or set CAATINGA_ASSUME_YES=true).
ctg generate fails with CAATINGA_INVALID_CONFIG unless frontend.bindingsOutput is set in caatinga.config.ts — which is the case for every --minimal project. doctor and status only recommend running generate once it can actually succeed. See CAATINGA_INVALID_CONFIG for the exact snippet to add.
ctg sync-env no longer wipes the target env file (3.9.2+). It rewrites only the keys mapped in frontend.env; unrelated variables, comments, and blank lines are preserved, and new keys are appended.
ctg init --minimal ships a Cargo.lock (3.9.2+), so cargo test works in the generated project without first resolving a dependency graph that could otherwise pick an incompatible ed25519-dalek version.