Concepts

dst is a thin client. It carries your identity and your active workspace, then talks to Destesi’s services over HTTPS. Understanding four things — authentication, workspace context, config resolution, and output contracts — is enough to use every command and to script the CLI reliably in CI.

One binary for the whole suite

dst is a single command tree with a subcommand per product. The same login and the same active workspace flow into every one:

• dst snap — git-style branching for Postgres and S3 (see Snap)
• dst preview — ephemeral per-PR preview environments (see Preview)
• dst review — read recent AI code reviews (see Code Review)
• dst mcp — connect Destesi to your AI coding agent (see MCP)
• dst workspace — create, list, switch, and manage members of workspaces
• dst third-party-apps — connect a GitHub account so previews can pull private repos
• dst api-key, dst login, dst logout, dst whoami — identity and credentials
• dst init — scan a repo and write a .destesi.yml
• dst upgrade, dst version — keep the binary current

This mirrors the suite itself: one account, one workspace, many products. See What is Destesi for the bigger picture.

Authentication: sessions vs. bearer tokens

dst authenticates with a bearer token sent as Authorization: Bearer <token>. There are two ways to get one, suited to two different environments.

Browser session login (interactive)

dst login

Opens your browser, you approve the session, and the resulting token is written to ~/.dst/config.yaml. This is the path for your laptop. Verify and end a session with:

dst whoami     # who am I, against the current API
dst logout     # revoke the token server-side and clear local credentials

If a browser isn’t available (a remote host, a container), dst login prints a verification URL and a code so you can approve from another device.

API keys (CI and automation)

For pipelines, mint a long-lived key and hand it to the runner as an environment variable — no browser, no interactive login:

dst api-key create --label "my laptop"        # a personal token
dst api-key list                              # see your keys
dst api-key revoke <id>                        # revoke one

For CI specifically, mint a preview-runner key. It is scoped to preview:write on a single workspace, so leaking it from a build log can’t touch your database branches, other workspaces, or the rest of your account:

dst api-key create --preview-runner --workspace my-workspace --label github-actions -o token

The plaintext token is shown once at creation — store it immediately. Provide it to dst in CI via the DESTESI_API_KEY environment variable (see below); no dst login is required.

Tip

Mint the narrowest key that does the job. A personal token can do anything you can; a --preview-runner key can only manage previews in one workspace. Third-party credentials like GitHub are never embedded in a dst key — those live in Connect.

See Accounts & SSO for how sessions work across the suite and Auth in the CLI for the credential model in depth.

Workspace context

Almost every product command runs against your active workspace — the unit of collaboration where all your data lives. Set it once:

dst workspace switch my-workspace

The active workspace is saved in ~/.dst/config.yaml and reused by dst snap, dst preview, dst third-party-apps, and friends. A workspace is identified by its slug (a lowercase, URL-safe handle like my-workspace); dst workspace switch accepts either the slug or the workspace id and resolves to the canonical slug. Run a product command before selecting a workspace and dst tells you exactly what to do:

no active workspace — run `dst workspace switch <name>` first

In CI, set the workspace with the DESTESI_WORKSPACE environment variable instead of switching interactively. See Workspaces.

Config resolution

dst reads its settings from ~/.dst/config.yaml (written by dst login and dst workspace switch), then layers environment variables on top. Environment variables always win, so a CI runner can override whatever a developer image happened to ship with. Precedence, highest first:

1. Per-command flags — e.g. --api-url, --workspace
2. Environment variables — DESTESI_API_URL, DESTESI_IDENTITY_API_URL, DESTESI_API_KEY, DESTESI_WORKSPACE
3. ~/.dst/config.yaml — the on-disk config

Empty environment variables are ignored — unsetting one means “leave the on-disk value alone”, not “force it empty”. The config file is created with 0600 permissions in a 0700 directory because it holds your bearer token. See the reference for the full list of fields and variables.

Output formats and exit codes

The CLI is designed to be both readable at a terminal and parseable in a script.

• Most commands print a human-readable table by default and accept -o json (or --output json) for the full object.
• Single-field formats keep pipelines to one line: dst preview show <id> -o url prints just the public URL; -o id prints just the id; dst review list -o ids prints one id per line.
• dst preview wait uses distinct exit codes so a CI step can branch on the result: 0 healthy, 1 failed, 2 timed out, 3 deleted while waiting.

These shapes are part of the contract — scripts can depend on them. The reference lists the supported format for each command.

How it fits the suite

dst is one of several ways into Destesi — alongside the web apps and the MCP server. They all share the same backbone:

• One identity, one workspace. The token dst carries is the same single sign-on identity you use in the browser, scoped to the same workspace.
• Credentials live in Connect. To preview a private GitHub repo, the workspace connects a GitHub account once; products fetch that credential at call time. You never store a third-party token per product. See Connect.
• Artifacts land in Drive. Output that products produce is registered in Drive, the single library across the suite.
• What you can do is gated by entitlements. Your plan determines which products and limits apply — see Entitlements.

Command reference

Workspaces

Auth in the CLI

Connect