Reference

Every command, flag, config field, and environment variable dst recognizes. Run dst <command> --help for the same information at the terminal.

Global flags

Available on every command:

Flag	Description
--api-url <url>	Override the API base URL for this invocation (persisted only when set explicitly).

dst version prints the installed version.

Configuration

dst reads ~/.dst/config.yaml, then layers environment variables on top. Environment variables win over the file; per-command flags win over both.

Config file fields (~/.dst/config.yaml)

Field	Description
api_url	Base URL of the Destesi API. Defaults to https://api.destesi.io.
identity_api_url	Base URL of the identity service (workspaces, members, invites). When unset, it is derived from api_url.
auth_token	Bearer token written by dst login or dst login --token.
active_workspace	Slug of the active workspace, set by dst workspace switch.
active_snap_dsn	DSN of the last branch selected with dst snap switch.

The file is written with 0600 permissions (it holds your token). Do not commit it.

Environment variables

Variable	Maps to	Use
DESTESI_API_URL	api_url	Point dst at a specific API host.
DESTESI_IDENTITY_API_URL	identity_api_url	Set when the identity service runs on a different host than the API.
DESTESI_API_KEY	auth_token	Supply a bearer token in CI without running dst login.
DESTESI_WORKSPACE	active_workspace	Select the workspace in CI without dst workspace switch.
DST_DOWNLOAD_URL	—	Override the release host used by dst upgrade.
DST_SKIP_CHECKSUM=1	—	Skip the upgrade tarball integrity check (emergency use only).

Caution

The tenant variable is DESTESI_WORKSPACE. The CLI has no separate tenant variable beyond this one.

The install script (get.destesi.io/install.sh) additionally honors DST_INSTALL_DIR (override the target directory) and DST_DOWNLOAD_URL (override the release host).

Identity and credentials

dst login

Authenticate and save credentials to ~/.dst/config.yaml.

Flag	Description
--token <key>	Log in directly with an API key instead of the browser flow.
--api-url <url>	Override the API URL for this login.

With no flags, dst login runs the browser approval flow and prints a verification URL + code for headless hosts.

dst logout

Revoke the current token server-side (best effort) and clear local credentials.

dst whoami

Print the authenticated user for the current API. Errors if not logged in or the token is invalid/expired.

dst api-key

Manage API keys. Aliases: apikey, key.

dst api-key create — mint a key.

Flag	Description
--label <text>	Human-readable label.
--preview-runner	Mint a CI-scoped key (preview:write on a single workspace).
--workspace <slug-or-id>	Workspace for a preview-runner key (defaults to the active workspace).
-o, --output <fmt>	human (default), json, or token (raw token only — ideal for gh secret set).

The plaintext token is shown once. Store it immediately.

dst api-key list — list your keys.

dst api-key revoke <id> — revoke a key. Alias: rm.

dst workspace

Manage workspaces. Alias: ws. A workspace is identified by its slug (a lowercase, URL-safe handle); every subcommand resolves a slug-or-id to the canonical slug.

Subcommand	Description
create <slug>	Create a workspace. --name <text> sets the display name (defaults to the slug).
list	List workspaces you belong to (the active one is marked *).
switch <slug-or-id>	Set the active workspace.
members	List members. --workspace <slug-or-id> overrides the active workspace.
invite <email>	Invite a user. --role member|admin (default member), --workspace <slug-or-id>.
remove <user-id>	Remove a member. --workspace <slug-or-id>.

dst snap

Git-style branching for Postgres and S3. See Snap for the product guide.

Remotes — dst snap remote

Manage data sources. Alias: connector.

dst snap remote postgres <dsn> — register a Postgres source.

Flag	Description
--name <text>	Optional display name.
--tunnel-mode none|ssh	Connect through an SSH bastion.
--tunnel-bastion-host, --tunnel-bastion-user	Bastion host and user (SSH mode).
--tunnel-remote-host, --tunnel-remote-port	Database host and port behind the bastion.
--tunnel-key-secret-ref <uri>	Reference to a pre-uploaded SSH private key.
--output text|json	Output format (default text).

# Direct connection
dst snap remote postgres "postgres://user:pass@db.example.com:5432/app" --name prod

# Through an SSH bastion (key already uploaded as a secret ref)
dst snap remote postgres "postgres://user:pass@10.0.1.20:5432/app" \
  --name prod \
  --tunnel-mode ssh \
  --tunnel-bastion-host bastion.example.com \
  --tunnel-bastion-user ec2-user \
  --tunnel-remote-host 10.0.1.20 --tunnel-remote-port 5432 \
  --tunnel-key-secret-ref secret://snap/keys/bastion

dst snap remote s3 <bucket> — register an S3-compatible source.

Flag	Description
--name <text>	Optional display name.
--region <region>	S3 region (default us-east-1, or AWS_REGION).
--endpoint <url>	Custom endpoint for S3-compatible storage (MinIO, etc.).
--access-key-id, --secret-access-key	Credentials (or AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY).
--path-style	Use path-style addressing.
--output text|json	Output format (default text).

# AWS S3 (region defaults to us-east-1 or $AWS_REGION; creds from the env)
dst snap remote s3 my-prod-assets --name assets --region us-west-2

# MinIO or other S3-compatible storage: custom endpoint + path-style
dst snap remote s3 my-bucket \
  --endpoint https://minio.example.com \
  --path-style \
  --access-key-id AKIA... --secret-access-key ...

dst snap remote list — list remotes in the active workspace. dst snap remote show <id> — show remote details. dst snap remote remove <id> — delete a remote. Alias: delete.

Branches

dst snap create <name> — clone from a remote or fork from a branch.

Flag	Description
--connector-id <id>	Remote to clone from (required unless --from-snap).
--from-snap <id>	Fork from an existing branch instead (inherits its remote).
--max-lag <seconds>	Maximum acceptable sync lag.
--at-checkpoint <id>	Pin to a specific source checkpoint.
--override <table.column=expr>	Rewrite a column as rows hydrate (repeatable) — e.g. users.email='me@example.com'.
--overrides-file <path>	JSON file of override rules.

The command waits for provisioning and prints the branch’s DSN when ready.

dst snap list — list branches in the active workspace. dst snap status <id> — show a branch’s status and endpoint DSN. dst snap switch <id> — set the active branch (saves its DSN to config). dst snap delete <id> — delete a branch.

dst snap try <postgres-url> — one-shot: register the remote, create a branch, wait, print the DSN.

Flag	Description
--as <name>	Branch name (default: auto-generated).
--wait-timeout <duration>	Max wait for provisioning (default 5m).
--quiet	Print only the final DSN — suitable for eval $(dst snap try ...).

Fixtures — dst snap fixture

Pin a known-good branch and fork future branches from it.

Subcommand	Description
save <snap-id>	Pin a ready branch. --name <text> (required), --desc <text>.
list	List fixtures in the active workspace.
show <id-or-name>	Show a fixture.
restore <id-or-name>	Fork a new branch from a fixture. --as <name> (required), --max-lag <seconds>.
delete <id-or-name>	Delete a fixture (the source branch is unaffected).

Trace — dst snap trace <snap-id>

Show recent SQL trace events from a branch’s proxy. Requires SNAP_TRACE_SQL=1 on the branch. --print prints the psql command instead of running it.

dst preview

Ephemeral per-PR preview environments. See Preview for the product guide.

dst preview create

Register a new preview.

Flag	Description
--from-dir <path>	Tar and upload a local directory containing docker-compose.yml.
--repo <owner/name>	Pull source from a connected GitHub repo (requires --third-party-app).
--branch <name>, --commit <sha>	Branch and commit to preview.
--third-party-app <id>	Connected GitHub app providing the repo token.
--from-remote <name-or-id>	Database remote to clone from.
--from-snap <id>	Fork a specific branch for the database (power users).
--env NAME=value	Environment variable override (repeatable).
--env-secret NAME=value	Secret environment variable override (repeatable).
--public-service <name>, --public-port <n>	Service and port to expose (auto-detected otherwise).
--ttl <duration>	Time until auto-teardown (default 24h).

dst preview upsert

Idempotent create keyed by (workspace, pr_number) — call repeatedly from GitHub Actions. GitHub-only.

Flag	Description
--repo <owner/name>	GitHub repo (required).
--pr-number <n>	Pull request number (required — the identity key).
--third-party-app <id>	Connected GitHub app (required).
--branch <name>, --commit <sha>	Head branch and commit of the PR.
--pr-title, --pr-body, --pr-body-file, --pr-url	PR metadata (--pr-body and --pr-body-file are mutually exclusive).
--from-remote, --from-snap, --env, --env-secret, --public-service, --public-port, --ttl	As for create.
--oauth provider=/callback/path[,scope...]	OAuth passthrough config (repeatable).
--dev-mode	Require docker-compose.dev.yml and run with hot reload.
-o, --output <fmt>	json (default), id, url, or status.

dst preview wait <id>

Block until the preview reaches a terminal state. Exit codes: 0 healthy, 1 failed, 2 timeout, 3 deleted.

Flag	Description
--timeout <duration>	Max wait (default 10m).
--interval <duration>	Poll cadence (default 3s).

Other preview commands

Command	Description
dst preview list	List previews. --status <state> filters; --json emits JSON.
dst preview show [id]	Show a preview. --by-pr <n> looks up by PR; -o json|id|url|status.
dst preview logs <id>	Stream container logs. --container, --tail <n>, -f/--follow.
dst preview events <id>	List recent events. --limit <n> (default 50).
dst preview trace <id>	Unified status + events + log tail. --tail <n>, -f/--follow.
dst preview redeploy <id>	Queue a teardown + rebuild.
dst preview delete [id]	Delete a preview. --by-pr <n> deletes by PR (no-op if none exists). Alias: rm.

dst review

Read recent AI code reviews for repos that opted in via .destesi.yml on their default branch. The CLI is a viewer — reviews are produced server-side. See Code Review.

dst review list — list recent reviews across every GitHub App installation attached to your workspace. Each row is an AI-generated review the review-controller produced server-side for a PR on an opted-in repo; the CLI only reads them — to request a fresh pass, comment @destesi review on the PR.

Flag	Description
--limit <n>	Max items (server caps at 200; default 50).
-o, --output <fmt>	json (default), text, or ids.

# Readable table: STATE  PR  REPO  HEAD  ID
dst review list --output text

# Just the ids, for piping into another command
dst review list --output ids --limit 10

dst third-party-apps

Connect a GitHub account to the active workspace so previews can pull private repos. Alias: tpa.

Subcommand	Description
connect-github	Open the browser and complete a GitHub authorization handshake. --timeout <duration> (default 5m).
add-github	Register a GitHub connection with a personal access token. --token <pat> (or GITHUB_TOKEN), --login <account>.
list	List connections for the active workspace.
remove <id>	Remove a connection. Aliases: rm, delete.

Note

This wires a GitHub connection that the preview product uses to fetch repo contents. Manage credentials for the whole suite — and for products beyond previews — in Connect.

dst mcp

Add the Destesi MCP server to Claude Code so your AI agent can use Destesi tools. MCP (the Model Context Protocol) is the open standard that lets agents like Claude Code or Cursor call your Snap remotes and branches as first-class tools — cloning a remote, forking a branch, or polling an operation, all from a chat prompt. The command points the agent at <api_url>/mcp over authenticated HTTP and prints the tools it gains (remotes, branches, fixtures, history). If you are not logged in, it runs the login flow first; when the Claude Code CLI isn’t found, it prints the manual claude mcp add setup instructions instead. See MCP.

dst init

Scan the current repo for docker-compose.yml, .env files with Postgres DSNs, and migration directories, then write a .destesi.yml summarizing what it found (safe to commit).

Flag	Description
--dir <path>	Directory to scan (default: current).
--force	Overwrite an existing .destesi.yml.
--quiet	Suppress the human-readable report.
--compose <path>	Override the auto-detected docker-compose path.
--rewrite-env	Rewrite DATABASE_URL in detected .env files to point at the branch proxy (creates .bak backups).

dst upgrade

Self-update the dst binary in place. Downloads the latest release, verifies its SHA-256 against the published checksums, and replaces the running binary atomically.

Flag	Description
--check	Report whether an update exists; install nothing.

Override the release host with DST_DOWNLOAD_URL. DST_SKIP_CHECKSUM=1 bypasses the integrity check (emergency use only).

Next steps

ConceptsHow auth, workspaces, and output formats fit together.

TroubleshootingThe real errors dst emits and how to fix them.

SnapGit-style branching for Postgres and S3 — the product behind dst snap.

PreviewEphemeral per-PR environments behind dst preview.

Code ReviewAI reviews on opted-in repos, surfaced by dst review.

MCPHand your agent the Destesi toolset that dst mcp installs.