PromptDock CLI

Before you start

• Node 18 or newer. Check with node --version. There is nothing to install globally — npx fetches the CLI per run.
• A Prompt Dock account. Free accounts can install free skills. Premium skills need a paid plan; the CLI says so before writing anything.
• An AI coding agent — Claude Code today, with 6 more targets whose paths are the documented convention but not yet verified end to end.

1. Install a skill

Every skill page carries its own copyable command. The shape is always the same:

@latest is not decoration — it is what keeps you above the version floor the API enforces. The CLI asks two things: which tool, then whether to install for this project or for your user account, showing the real destination path for each. Tools it can already see in your working directory are listed first.

Nothing is written until you confirm, and the write is all-or-nothing: files land in a sibling staging directory, every checksum is verified, and only then is the directory moved into place. A failed install leaves no half-written skill behind.

Want to see the plan without committing to it? Add --dry-run. It resolves the skill, prints what would happen, installs nothing — and spends no premium-unlock slot.

2. Sign in

The install triggers this automatically the first time, or you can do it up front:

The CLI prints an eight-character code and opens promptdock.ai/cli-auth. You confirm the code there — checking it matches what your terminal shows — and the terminal continues on its own. If the browser did not open, paste the URL it printed. Codes expire; the CLI starts a fresh one rather than failing.

The token is stored in ~/.promptdock/config.json with owner-only permissions. If the CLI cannot lock the file down, it refuses to keep the token at all rather than leaving a readable credential on disk. promptdock logout revokes it server-side and then clears it locally; you can also revoke any session from Settings → Account → CLI sessions.

3. Activate it in your tool

A skill is a folder on disk, and your agent read its skill list when it started. So the last step is not optional: start a new session, or reload the editor. An open Claude Code session will not see a skill installed after it launched.

In Claude Code, a new session then answers /<slug> — the slug is the second half of the ref you installed. Other tools pick skills up on restart. The CLI prints the right sentence for whichever target you chose.

4. Check what you have

promptdock list shows what is installed, where, and at which version. promptdock whoami shows which account this machine is signed in as. Since you are here, the whole command set:

Those usage lines are generated from promptdock v1.2.0’s own --help, so they match the binary you just ran. Every flag, install path and environment variable is on the command reference. From a terminal, promptdock <command> --help prints the same thing.

list reads the .promptdock.json receipt inside each installed folder — the record of exactly which files the CLI wrote and at which version. That receipt is also why uninstall can never delete a file it did not put there. Bare commands look at this directory only; add --all to include the ones installed for your account.

5. Run it in CI

Two things to know before you wire this into a pipeline. Neither is a bug you can work around by holding it differently.

Authenticating without a browser

Mint a token under Settings → Account → CLI sessions, store it as a secret, and expose it as PROMPTDOCK_TOKEN. The CLI uses it and never attempts a browser hand-off. Revoke it from the same screen.

A non-interactive run cannot answer the tool and scope questions, so it must be told: pass --target (or --dir) and -y, or the CLI exits 1 rather than guessing where to write. -y skips the prompts only — it never implies --force, so a non-empty foreign directory still stops the run.

Parsing the output

--json prints one JSON document on stdout. It is not one shape — each command answers with its own, and update has two:

Two gotchas when you parse it. Errors are never JSON — they go to stderr as human text with an exit code, so branch on the exit code first and parse stdout only on success. And if the CLI has to log in, it writes the code and the URL to stdout before any JSON; set PROMPTDOCK_TOKEN so that path never runs.

Exit codes

Stable across releases and never renumbered — this is the contract a pipeline depends on. Every named error also links to its entry in the error reference.

6. Keep it up to date

promptdock update moves installed skills to their latest approved version; --check reports what is available without touching anything. Bare, it covers this directory — add --all for the ones installed against your account too. upgrade is the same command under the name npm taught everyone.

Edited a skill after installing it? The update stops rather than overwriting your work: the receipt records a checksum per file, so a changed file is detected and reported by name. Copy your changes out, then re-run with --force.

Upgrading the CLI itself

Two separate version gates, and they differ in blast radius. A package can require a newer CLI than yours — only that package is refused, and everything else keeps working. Separately, the API enforces a minimum CLI version for wire-breaking changes; below it, every command fails, including login.

The same upgrade fixes both, and running npx promptdock@latest means you are never below either gate. A globally installed copy (npm i -g promptdock) does not update itself — that is the one setup where these gates can surprise you.