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:

Copy the exact command from any skill page. Find a skill.

@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. If you reach that page without a code, for example after confirming a new account's email, enter the code your terminal shows. 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. npx promptdock@latest logout revokes it server-side and then clears it locally; you can also revoke any session from Settings → Account → CLI sessions.

Installing it globally with npm i -g promptdock enables the short form, without npx and @latest; a global copy does not update itself (see Keep it up to date).

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

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

Those usage lines are generated from the published CLI’s own --help (v1.2.2), so they match the binary you just ran, with npx promptdock@latest in place of the short promptdock the help prints. Every flag, install path and environment variable is on the command reference. From a terminal, npx promptdock@latest <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, so run under that name the CLI first prints:

promptdock upgrade updates your installed skills; it does not update the promptdock CLI. To update the CLI: npm i -g promptdock@latest (or use npx promptdock@latest).

Changed a skill after installing it? Install and update keep every file you added. A file you edited, or a file of yours where the new version ships one, stops the command with nothing changed (exit 4): the receipt records a checksum for each file it installed, so each one is named with its reason. Move those files out and run the command again, or add --force to replace just those files; every other file you added stays. Line endings alone do not count as an edit. See local_changes.

That is how 1.2.2 and later behave. promptdock 1.2.1 and older replaced the whole folder: update deleted the files you had added, and re-running install over a skill you had edited also overwrote your edits. If that may have happened to you, compare the folder with your version control to see what changed.

To keep a known-good copy, commit the installed folder, including its .promptdock.json, to version control. update replaces it with the latest version; restore the committed copy to go back.

Upgrading the CLI itself

Three version gates can refuse an old CLI, and they differ in what still works:

• A package can require a newer CLI than yours. Only that package is refused, and everything else keeps working.
• Installing and updating skills has its own minimum, because promptdock 1.2.1 and older can overwrite files you edited and delete files you added. Below it, install and update are refused, while login, list and uninstall keep working.
• The API enforces a minimum CLI version for wire-breaking changes. Below it, every command fails, including login.

The same upgrade fixes all three, and running npx promptdock@latest means you are never below any of them. A globally installed copy (npm i -g promptdock) does not update itself — that is the one setup where these gates can surprise you. Every refusal links to upgrade_required.