@tokenoftrust/cli — the tot developer CLI

One command to go from a Token of Trust invite to a running store.

npm i -g @tokenoftrust/cli

tot clone                    # list the stores you can build on
tot clone <tenant> my-store  # mirrors `git clone`; dir defaults to <tenant>
cd my-store
tot dev                      # run it locally with save→reload — no Docker needed
tot preview                  # bundle your edits into a compliance-reviewed preview
tot ship                     # promote a reconciled preview live (diff + one confirm)

Prerequisites: Node.js and an invite. Nothing else. tot dev downloads the moat-free storefront runner and runs it as a plain host process — no Docker install or hand-provisioned AWS credentials.

For Storefront Private App contracts, examples, and LLM-ready developer material, start at Storefront Devkit — Apps / Private. The tot app commands use the CLI's self-contained helper; they do not require a separately published npm SDK.

Commands

| Command | Status | What it does | | --- | --- | --- | | tot clone [<tenant>] [<dir>] | built | Clone a store you're entitled to build on (mirrors git clone), with an authenticated remote configured. Dir defaults to <tenant>. No arg → list your stores. | | tot validate | next | Lint your store before you preview. | | tot dev | built | Run your store locally with save→reload — natively. | | tot preview | built | Bundle your edits into a compliance-reviewed preview (validates, auto-commits the known content trees, pushes the preview ref, opens/updates a candidate PR, reports the reconcile/compliance verdict + preview URL). tot submit / tot deploy still work as teaching aliases for this same flow. | | tot ship | built | Promote a reconciled preview live: always shows a diff-vs-live and asks for one [y/N] confirm (no --yes, refuses outside a terminal); records an approval request if you're not authorised to ship yourself. | | tot pr [list\|view\|close] | built | See and manage the candidate PRs tot preview opens (gh pr-shaped). | | tot doctor | built | Check this machine is ready and show which context tot detected. |

Context-aware

The same tot does the right thing wherever you run it (walks up like git):

• storefront monorepo — a full platform checkout;
• tenant checkout — a standalone content/ public/ theme.json .tot/config.json clone (tenant read from .tot/config.json);
• loose — anywhere else; tot clone <tenant> gets you a checkout.

tot doctor prints the detected context.

Auth

tot talks to the Token of Trust MCP (default https://mcp.tokenoftrust.com, override with --mcp or MCP_BASE_URL). It is single-plane: the only identity is you, signed in against the MCP over OAuth.

• Run tot login once — it opens your browser (or falls back to a device code on a headless box), you sign in as yourself, and the session is cached at ~/.tot/credentials.json and refreshed silently. Every later command (tot clone, tot start, tot preview, tot ship, …) runs as you, with no re-auth. Entitlement is derived server-side from your ToT memberships.
• Not signed in? On a terminal, tot start / tot clone offer to sign you in right there and continue in-flow — no "run tot login, then re-run".
• The old operator env-triple (TOT_API_KEY / TOT_SECRET_KEY / TOT_APP_DOMAIN) no longer signs the CLI in — tot-mcp went OAuth-first on 2026-07-23. If those vars are set, tot prints a one-line advisory and uses your tot login session anyway; it never reads them for auth.

Optional: multiple identities at once (TOT_PROFILE)

Most people never set this — the single default session is all you need, and a plain tot login just replaces it. Reach for a profile only when you want more than one identity live at the same time: a staff @tokenoftrust.com sign-in alongside a plain developer one, or many parallel test identities. Set it per shell and each gets its own credential file under ~/.tot (the renderer cache and everything else stay shared):

# terminal A                     # terminal B
export TOT_PROFILE=staff         export TOT_PROFILE=dev
tot login                        tot login

The value is an opaque label — any string works, so it's easy to script parallel identities:

export TOT_PROFILE=$(uuidgen)    # a fresh isolated identity per terminal / test worker
tot login

A clean short name (staff, dev, test-7) becomes a readable credentials.<name>.json; any other value (symbols, uppercase, long) is hashed to a stable credentials.h<hash>.json — so an arbitrary id never collides or escapes ~/.tot. Unset → the default session, unchanged. tot whoami shows the active profile.

Design notes

Dependency-free by design (global fetch + git + the system tar), so npm i -g @tokenoftrust/cli stays light. tot dev is the only command that pulls in the storefront runner: for a standalone checkout it downloads the moat-free runner artifact (dev_renderer_artifact, entitlement-gated) once per version to ~/.tot/cache/renderer/<version>/, pnpm installs it there (via corepack — no separate pnpm install needed), and reuses that cache on every later run. See src/ for the small modules: context.mjs (detection), mcp.mjs (transport), auth.mjs (the identity seam), commands/.