CLI guide - PlatformDTC

@platformdtc/cli gives you — and any coding agent working in your editor — a PlatformDTC theme as a local folder. It talks to the same Agent Gateway /themes endpoints as the remote MCP server, and runs the same theme check locally.

Install

Requires Node.js 20 or later.

npm install -g @platformdtc/cli
dtc --version

dtc login

Your browser opens PlatformDTC. Sign in, choose the store, choose the permissions to grant, and approve. The CLI receives the result on a local 127.0.0.1 callback — nothing to copy and paste. Credentials are kept in your operating system’s keychain (macOS Keychain, or libsecret on Linux), or otherwise in ~/.config/platformdtc/credentials.json, readable only by you. Access tokens last one hour and are refreshed automatically. CI and headless machines: set DTC_AGENT_KEY to a static sq_agt_* key with the theme scopes the job needs. When it is set, the CLI uses it and does not use stored credentials.

DTC_AGENT_KEY=sq_agt_… dtc theme check

Commands

Command	Does	Gateway calls
`dtc login [--no-browser]`	Sign in with OAuth 2.1 + PKCE	`/oauth/*`
`dtc logout`	Revoke and remove stored tokens	`POST /oauth/revoke`
`dtc theme list [--json]`	List the store’s themes with id, name, role, expiry and preview URL	`GET /themes`
`dtc theme init [dir] [--theme <id>] [--force] [--json]`	Set up a folder from the live theme (or `--theme`), and write `AGENTS.md`, `CLAUDE.md` and `.cursor/rules/platformdtc-theme.mdc`. Existing instruction files are kept unless `--force`.	`GET /themes`, `GET /themes/{id}/manifest`, `GET /themes/{id}/files`
`dtc theme manifest [--theme <id>] [--json]`	Every path with its owner and editability, plus the section and block types templates can use	`GET /themes/{id}/manifest`
`dtc theme pull [--theme <id>] [--only <globs>] [--delete] [--json]`	Download editable files that differ locally. `--delete` removes local theme files that no longer exist remotely.	`GET /themes/{id}/manifest`, `GET /themes/{id}/files`
`dtc theme push [--theme <id>] [--only <globs>] [--nodelete] [--force] [--json]`	Upload local changes to a development theme. Remote editable files missing locally are deleted unless `--nodelete`. The live theme is refused (`THEME_IS_LIVE`): push to a development theme, then `dtc theme publish --theme <id>`. `--allow-live` is still accepted but has no effect. `--force` overwrites remote changes instead of reporting `CONFLICT`.	`PUT /themes/{id}/files`, `POST /themes/{id}/files/delete`
`dtc theme check [--only <paths>] [--mode development\|publish] [--remote] [--theme <id>] [--json]`	Run theme check locally, or on the server with `--remote`. Exits 1 on errors.	— (`POST /themes/{id}/check` with `--remote`)
`dtc theme dev [--theme <id>] [--name <name>] [--editor-sync] [--poll-interval <ms>] [--no-check]`	Create or reuse your development theme, upload the folder, print a preview link, then sync every save and check the changed files. `--editor-sync` also brings down changes made in the dashboard editor (default poll 3000 ms). `--theme` cannot be the live theme.	`POST /themes`, `GET /themes/{id}/manifest`, `PUT /themes/{id}/files`, `POST /themes/{id}/preview`
`dtc theme share [--name <name>] [--json]`	Upload the folder to a new development theme and print a preview link to send to someone	`POST /themes`, `PUT /themes/{id}/files`, `POST /themes/{id}/preview`
`dtc theme publish [--theme <id>] [-y, --yes] [--no-wait] [--timeout <seconds>] [--json]`	Check locally in publish mode, publish, and follow the publish until it is live (default wait 900 s). If a publish of the theme is already in progress, follows that job instead of starting another.	`POST /themes/{id}/publish`, `GET /themes/{id}/publish-status`
`dtc theme publish-status [--theme <id>] [--json]`	The latest publish of a theme	`GET /themes/{id}/publish-status`
`dtc theme delete --theme <id> [-f, --force] [--json]`	Delete a development theme (unpublished themes are deleted in the dashboard)	`DELETE /themes/{id}`
`dtc theme versions [--theme <id>] [--json]`	List saved versions	`GET /themes/{id}/versions`
`dtc theme rollback <version-id> [--theme <id>] [-y, --yes] [--json]`	Restore a saved version of a development theme	`POST /themes/{id}/rollback`

Options every command accepts:

Option	Environment variable	Default
`--api <url>`	`DTC_API_URL`	`https://api.platformdtc.com`
`--store <id>`	`DTC_STORE_ID`	the store your sign-in or key is bound to
`--path <dir>` (theme commands)	—	current directory
—	`DTC_AGENT_KEY`	a static `sq_agt_*` key; overrides stored credentials

--theme defaults to the theme the folder was initialized from. --only takes comma-separated globs (*, **, ?, {a,b}) and can be repeated. Run dtc theme <command> --help for every option of a command.

A typical session

Set up the folder

mkdir my-store-theme && cd my-store-theme
dtc theme init

init links the folder to a theme and writes AGENTS.md and CLAUDE.md so Claude Code, Codex and Cursor know the rules of a PlatformDTC theme. Those files, .dtcignore, and editor folders such as .cursor/ and .claude/ stay local and are never pushed.

Develop

dtc theme dev

Works against a development theme, never your live theme. Edit templates/*.json or add a section under theme/custom/sections/ — yourself or with your agent — and open the preview.

Check

dtc theme check

Fix every error. TypeScript errors are warnings here and errors on publish, so fix those too.

dtc theme share

Uploads the folder to a new development theme and prints a temporary preview link for a colleague or client.

Publish

dtc theme publish

Runs theme check locally in publish mode, then publishes; the server runs the same check again and refuses the publish with CHECK_FAILED if anything is wrong. If your store requires approval, the command reports that the publish is waiting — approve it in Settings → Developer → Build with your agent.

How push keeps other people’s changes safe

The CLI remembers the checksum of every file it last pulled or pushed (in .platformdtc/state.json, which is git-ignored). When you push a file, it sends that checksum as checksum_before. If someone changed the file on PlatformDTC in the meantime — the merchant in the theme editor, or another agent — the server refuses that file with CONFLICT instead of overwriting their work. Pull, merge, and push again. Push also follows the ownership rules: platform-owned files are refused with PLATFORM_OWNED, and node_modules/, .next/, out/, .git/ and data/ are never uploaded. theme/custom/index.ts is generated by the platform and is never uploaded either. Add your own exclusions to .dtcignore, one glob per line. Large pushes are split automatically into batches of at most 50 files and 2 MiB (a single file may be at most 2 MiB). Each batch is saved as one version. Every write carries an Idempotency-Key, so a request retried after a network error is applied once.

Versions and rollback

Every successful write — from the CLI, an agent or the editor — is recorded as a theme version.

dtc theme versions
dtc theme rollback --version <version-id>

Rolling back a development theme does not change your live store; publish it to put it live.

Local dev MCP for your agent

Give a local agent the docs, schemas and validators without granting it access to your store:

claude mcp add platformdtc-dev -- npx -y @platformdtc/dev-mcp

See MCP tool reference → Local dev MCP.

​Install

​Sign in

​Commands

​A typical session

​How push keeps other people’s changes safe

​Versions and rollback

​Local dev MCP for your agent