Introduction to the ds CLI

The ds command-line interface is the entry point for working with DevStride's AWS infrastructure and databases from a developer machine. It wraps AWS authentication and SST (the framework that deploys the backend Lambda/API Gateway stack and the frontend static site) behind a small set of Commander-based subcommands.

What ds Wraps

• AWS, authenticated via AWS SSO (or, on an unattended agent machine, the machine's own certificate identity) — every AWS-bound invocation checks your session before doing anything else. The fully-local and machine-management commands skip that check; see The AWS SSO Gate.
• SST — ds run backend runs sst dev (SST's live-lambda mode) against the backend; the frontend ships as an SST StaticSite in the same deploy.
• Drizzle SQL migrations against the stage's bound PostgreSQL database.
• Stripe, for a read-only billing inventory and test-mode proofs.
• A CQRS code generator for scaffolding backend commands and queries.
• The machine itself: the fully-local Docker stack, the fixed checkout pool and its leases, the secrets bundles that write .env, and an agent machine's certificate identity.

Postgres is hosted on Neon on every stage, and a few commands know that (ds golden push and import prefer the direct, non-pooled endpoint; ds data copy works around idle timeouts). Neon's copy-on-write branching is not exposed as a CLI operation: seeding goes through pg_dump/pg_restore and additive org copies instead. There is no infrastructure-as-code tool here beyond SST.

Entry-Point Mechanics

ds is not a single monolithic program — it's a thin bash dispatcher that compiles and runs one TypeScript file per invocation. The chain is:

./ds [-b] [-r] [-u] <command> [subcommand] [args]
    │
    ├─ ./ds                     ← root bash script: parses -b/-r/-u, runs the SSO gate,
    │                              resolves/regenerates the stage+region bind cache
    │
    ├─ ./cli/run_script.sh       ← esbuild-bundles cli/commands/<command>.ts
    │                              to .ds/.tmp/<command>.mjs
    │
    └─ node .ds/.tmp/<command>.mjs "$@"   ← the actual Commander program runs,
                                             then the temp bundle is deleted

Concretely, running ds migrations run:

1. ./ds parses wrapper flags, runs the SSO gate (unless -u), resolves the stage/region bind cache, then hands off everything after the flags to cli/run_script.sh.
2. cli/run_script.sh takes $1 (migrations) and calls node ./cli/bin/build.js ./cli/commands/migrations.ts ./.ds/.tmp/migrations.mjs — an esbuild bundle, built fresh on every single run.
3. It executes that bundle with the remaining args (run), which resolves to a Commander subcommand inside cli/commands/migrations.ts.
4. On exit, it deletes the temp .mjs/.mjs.map and propagates the child process's exit code.

Every top-level command is its own file under cli/commands/*.ts — there is no central command registry; each file builds its own Commander program and parses process.argv independently.

Global Wrapper Flags

These three flags belong to the ./ds wrapper itself, not to any subcommand, and must come before the command name:

./ds [-b] [-r] [-u] <command> [subcommand] [args]

The AWS SSO Gate

For any AWS-bound command, ./ds runs an AWS auth check before your command's code ever executes:

1. If DEVSTRIDE_DEV_PROFILE is set, it's exported as AWS_PROFILE.
2. AWS_SDK_LOAD_CONFIG=1 is exported, so AWS SDK v2 (used by some Node-side scripts) reads SSO profiles from ~/.aws/config instead of only ~/.aws/credentials.
3. aws sts get-caller-identity is run. If it succeeds, you'll see Already authenticated. If it fails, what happens next depends on who could finish a login:
   • A person at a terminal — stdin or stderr is a terminal — gets No active session found. Logging in... and the browser login (aws sso login). This includes a person pushing from a terminal, whose git hooks still show stderr.
   • No terminal at all — an agent's shell — gets one line naming the exact command, aws sso login --profile <profile>, and ./ds exits 1 without running your command. It used to open the device-code login where nobody could see it and appear to hang for minutes.
   • A machine certificate identity (a profile written by ds machine enroll) is never sent to a login, because a login cannot repair a certificate. ./ds says the identity was refused — the machine was revoked, its certificate expired, or its key is gone — and exits 1.

Stage/Region Bind Cache

After the SSO gate, ./ds resolves which stage and region you're targeting and caches that resolution to disk:

• The cache file lives at .ds/bind/<DEVSTRIDE_STAGE>-<DEVSTRIDE_REGION>.env.
• If that file doesn't exist yet, or you passed -b, ./ds runs node ./cli/bin/store_bind.mjs $DEVSTRIDE_STAGE $DEVSTRIDE_REGION to (re)generate it.
• The resulting .env file is exported into the shell environment before cli/run_script.sh is invoked, so every subcommand sees a consistent, already-resolved stage/region without re-deriving it itself.

In practice this means the first ./ds command after switching DEVSTRIDE_STAGE or DEVSTRIDE_REGION pays a one-time bind cost, and every subsequent invocation reuses the cached file until you force a refresh with -b.

The 18 Top-Level Commands

There are twenty top-level commands, one file each under cli/commands/. Each is its own Commander program — there's no shared subcommand namespace beyond these eighteen.

Next Steps

• Command Reference — the complete list of every subcommand and flag across all eighteen commands
• Local Development — running the backend and frontend day-to-day, migrations, and data import/export
• Dockerized Worktree Development — many isolated no-AWS instances at once, one per git worktree, each with its own dataset
• Golden Dataset — the Acme demo/test fixture and where its canonical docs live