App CLI - PlatformDTC

The dtc app commands of the PlatformDTC CLI turn a local folder into a PlatformDTC app. The folder’s platformdtc.app.toml is the source of truth: the CLI reads it and calls the same partner API the partner dashboard uses, so anything you do from the CLI is visible in the dashboard and the other way round.

Install

One command, no Node.js or npm needed:

curl -fsSL https://platformdtc.com/cli/install.sh | sh

irm https://platformdtc.com/cli/install.ps1 | iex

Then open a new terminal and run dtc --version. Pinning a version, the install location, updating with dtc upgrade and uninstalling are covered in the theme CLI guide. The app you create is a Node.js project, so running it (dtc app dev) needs Node.js 22.13 or later — the CLI itself does not. The starter has no npm dependencies: App Bridge loads from https://cdn.platformdtc.com/app-bridge/v1/app-bridge.js (see Embedded apps). dtc app dev also needs cloudflared to open a public HTTPS tunnel to your machine.

dtc login

Your browser opens PlatformDTC. Sign in with the account that belongs to your partner organization and approve. The CLI asks for the write_apps scope (with the theme scopes read_themes, write_themes and publish_themes), which is what the partner API requires. The result comes back on a local 127.0.0.1 callback; credentials are stored the same way as for the theme CLI. CI and headless machines: set DTC_AGENT_KEY to a static sq_agt_* key that holds write_apps. A key without it, or a key minted for an installed app, is refused by the partner API with 403.

DTC_AGENT_KEY=sq_agt_… dtc app deploy

Commands

Command	Does	Partner API calls
`dtc app init [dir] [--name <name>] [--type api\|embedded\|skill]`	Create a folder from the Node.js app starter and write `platformdtc.app.toml` with `name`, `handle` and `type`. When you are signed in, it then creates the app on your partner account and links the folder, as `dtc app config link` does (`--no-link` skips this). Signed out, it tells you to run `dtc login` and `dtc app config link`.	`GET /partner/apps`, `POST /partner/apps` (signed in)
`dtc app config link [--client-id <id>]`	Link the folder to an app: pick one of your apps (or pass `--client-id`), or create a new app from the toml. Writes `client_id` into the toml. When an app is created, its `client_secret` is printed once and written to `.env` as `PLATFORMDTC_API_SECRET` — never into the toml.	`GET /partner/apps`, `POST /partner/apps`
`dtc app config push [--submit]`	Update the app’s fields from the toml and create a new version with its scopes, justifications, webhook topics, nav links, app proxy and `SKILL.md`. `--submit` submits that version for review.	`PATCH /partner/apps/{id}`, `POST /partner/apps/{id}/versions`, `POST …/versions/{vid}/submit`
`dtc app dev [--store <id>] [--port <port>] [--tunnel-url <url>]`	Run your app locally behind a tunnel and install it on a development store. See `dtc app dev`. Default port `3000`.	`PATCH /partner/apps/{id}`, `POST /partner/apps/{id}/versions`, `GET\|POST /partner/development-stores`
`dtc app deploy [--no-submit]`	Validate the toml, build every extension, upload each bundle, create a new version declaring the extensions (and the tools of an `agent_tools` extension), and submit it for review. `--no-submit` stops before submitting.	`PATCH /partner/apps/{id}`, `POST /partner/apps/{id}/extension-bundles`, `POST /partner/apps/{id}/versions`, `POST …/versions/{vid}/submit`
`dtc app dev-store list`	List your partner organization’s development stores.	`GET /partner/development-stores`
`dtc app dev-store create <name>`	Create a development store.	`POST /partner/development-stores`

All partner API paths are under https://api.platformdtc.com/api/v1/appstore. The options every dtc command accepts (--api, DTC_API_URL, DTC_AGENT_KEY) are listed in the theme CLI guide. Run dtc app <command> --help for every option of a command.

`dtc app dev`

Start your app

Runs npm run dev in the app folder with PORT, PLATFORMDTC_API_KEY (your client_id) and HOST (the tunnel URL) set.

Open a tunnel

Starts cloudflared tunnel --url http://localhost:<port> and reads the https://….trycloudflare.com URL it prints. Pass --tunnel-url <https url> to use a tunnel you run yourself; cloudflared is then not needed.

Point the app at the tunnel

Updates the app’s app_url, embedded_app_url, redirect_uris and webhook_endpoint_url to the tunnel URL and pushes a draft version. http://localhost and 127.0.0.1 URLs are accepted only here.

Install on a development store

Uses --store, the [build] dev_store in the toml, or asks you to pick (or create) a development store, saves the choice to [build] dev_store, and opens the install URL. A draft version installs only on your own development stores.

Stop with Ctrl+C. The app is left pointing at the tunnel, which no longer exists; the CLI prints the command that restores your real URLs:

dtc app config push

cloudflared

dtc app dev exits with code 1 and prints the install command for your system when cloudflared is not on your PATH (unless you pass --tunnel-url).

System	Install
macOS	`brew install cloudflared`
Windows	`winget install --id Cloudflare.cloudflared`
Linux (Debian/Ubuntu)	Download the `.deb` from the cloudflared releases and run `sudo dpkg -i cloudflared-linux-amd64.deb`

No Cloudflare account is needed: dtc app dev uses a quick tunnel.

A typical session

Create the app

dtc app init order-notes --type embedded   # signed in: also creates and links the app
cd order-notes

If you ran dtc app init before dtc login, link the folder now with dtc app config link.

Develop

dtc app dev

Edit your app; the dev server reloads. Webhooks for the development store arrive through the tunnel.

Ship

dtc app deploy

The version goes to review. Follow it in the partner dashboard; an approved version is what merchants install.

Troubleshooting

Message or symptom	Cause	Fix
`403` on any `dtc app` command	The login or `DTC_AGENT_KEY` lacks `write_apps`, or the key belongs to an installed app.	Run `dtc login` again, or mint a key with `write_apps`.
`403` / not a partner	The signed-in account is not a member of a partner organization.	Become a partner or ask your organization’s owner to add you.
`cloudflared` not found	`dtc app dev` needs it for the tunnel.	Install it (above), or pass `--tunnel-url`.
`409` on create or link	The handle is taken or reserved (`installed`, `authorize`, `billing`, `categories`, `category`, `collections`, `collection`, `search`, `partners`, `partner`, `embed`, `new`, `admin`, `api`).	Change `handle` in the toml.
Validation error on `topics`	Non-compliance webhook subscriptions resolve to more than one URL.	Point every `topics` subscription at the same `uri`. See webhooks.
Validation error on `justifications`	A requested scope has no justification.	Add one non-empty line per scope under `[access_scopes.justifications]`.
Version rejected for `http://` URLs	A localhost URL was left in the toml after `dtc app dev`.	Set real `https` URLs and run `dtc app config push`.
Install page refuses the store	The version is a draft and the store is not one of your development stores.	Install on a development store, or get the version approved.
Extension upload rejected	The built bundle is larger than 256 KiB, is not UTF-8 JavaScript, or `entry` points at a missing file.	Check the extension’s `entry` and build output.
`client_secret` lost	It is shown once, at creation.	Rotate it from the dashboard or the rotate endpoint and update `.env`.

​Install

​Sign in

​Commands

​dtc app dev

​cloudflared

​A typical session

​Troubleshooting