The Global Wrapper
Every invocation goes through the root ./ds bash script before Commander ever sees your subcommand. For an AWS-bound command it does three things, in order: an AWS SSO auth gate, a stage/region "bind" step, then execution of your actual command. ds run local, ds worktree, ds pool, ds work, ds merge-path, ds verify, ds secrets, ds machine, ds fleet, ds agent, ds quickbooks and ds graph skip the first two and run straight away — the ones that need AWS check the account themselves.
./ds [-b] [-r] [-u] <command> [subcommand] [args]
| Flag | Description |
|---|---|
-b |
Force re-bind stage/region config, even if a cached .ds/bind/<stage>-<region>.env already exists |
-r |
Target the remote stage — unsets IS_LOCAL, sets DEVSTRIDE_REMOTE=true |
-u |
Skip the AWS SSO auth check entirely (aws sts get-caller-identity / aws sso login) |
It never opens a login nobody can finish
When the auth check fails, a person at a terminal (stdin or stderr is a terminal) gets the browser login. With no terminal at all — an agent's shell — the wrapper prints
aws sso login --profile <profile>and exits 1 instead of hanging on a device-code prompt nobody can see. A machine certificate identity is never sent to a login at all: the wrapper reports the identity as refused and exits 1. When the active profile (AWS_PROFILE, elseAWS_DEFAULT_PROFILE, elsedefault) is a role on top of another profile throughsource_profile, the wrapper follows that chain and logs in to the profile that actually signs in, naming both in its message. Details in The AWS SSO Gate.
Bind caching
Unless
-bis passed, the wrapper reuses the cached.ds/bind/$DEVSTRIDE_STAGE-$DEVSTRIDE_REGION.envfile if one exists, and only regenerates it (viacli/bin/store_bind.mjs) when it's missing. If you change stage/region config and the CLI doesn't seem to pick it up, run with-b.
Every command in this reference is invoked as ./ds <command> <subcommand> [flags] — each <command>.ts file under cli/commands/ is its own Commander program, resolved by name from the second CLI argument.