CLI command reference

Generated from the published CLI’s own --help, so every block below is exactly what your terminal prints. Where that help is itself inaccurate about what the binary does, a correction is called out beneath it. Currently documenting promptdock v1.2.0 — the version npx promptdock@latest installs. For the walkthrough instead, start at the CLI guide.

In this guide

Synopsis
Commands
login
logout
whoami
install
uninstall
update
list
help
Install targets
Environment variables

Synopsis

What promptdock --help prints.

promptdock v1.2.0 — install AI agent skills from promptdock.ai

  Usage
    npx promptdock@latest install <handle>/<slug>

  Commands
    login [--token pdk_…]     log in (browser hand-off, or store a CI token)
    logout                    remove the local token (revoke in Settings to kill it server-side)
    whoami [--json]           show the signed-in account
    install <ref> [options]   install a skill (ref = handle/slug, @handle/slug, or a pasted URL)
    uninstall <ref|--all>     remove an installed skill (receipt-driven; never touches unmanaged files)
    update [ref] [--all]      update installed skills to the latest approved version
    upgrade                   alias of update
    list [--json]             show installed skills (receipts)
    help                      this map

  Install options
    -g, --global              install into the tool's per-user dir (skips the scope prompt)
    --target <tool>           pick the tool (claude, codex, gemini, cursor, copilot, kimi, openai); scope is still asked — add -g or -y to skip
    --dir <path>              install into an explicit directory
    -y, --yes                 skip prompts (needs an unambiguous target; NEVER implies --force)
    --force                   replace a non-empty foreign directory / overwrite local edits
    --dry-run                 resolve + print what would happen; installs nothing
    --json                    machine-readable output

  Update/uninstall options
    --check                   (update) report available updates without applying
    --all                     operate across project-local AND global scopes
    -g, --global              operate on the global scope (bare commands are project-local)

  Targets
      claude    .claude/skills/<slug>   (-g: ~/.claude/skills/<slug>)
      codex     .codex/skills/<slug>   (-g: ~/.codex/skills/<slug>)  (experimental)
      gemini    .gemini/skills/<slug>   (-g: ~/.gemini/skills/<slug>)  (experimental)
      cursor    .cursor/skills/<slug>   (-g: ~/.cursor/skills/<slug>)  (experimental)
      copilot   .github/skills/<slug>   (-g: ~/.copilot/skills/<slug>)  (experimental)
      kimi      .kimi/skills/<slug>   (-g: ~/.kimi/skills/<slug>)  (experimental)
      openai    .openai/skills/<slug>   (-g: ~/.openai/skills/<slug>)  (experimental)

  Environment
    PROMPTDOCK_TOKEN          bearer token for CI/non-interactive use (Settings → CLI sessions → Generate token)
    PROMPTDOCK_API_BASE       API origin override (default https://www.promptdock.ai)
    NO_COLOR                  disable colored output

  Exit codes
    0 ok · 1 usage · 2 auth · 3 denied/gated · 4 integrity · 5 filesystem · 6 network

  Docs: https://promptdock.ai/docs/cli

Correction — this is wrong in v1.2.0’s own help. The logout line is wrong in the same way: promptdock logout revokes the session server-side itself, so you do not need to revoke it in Settings afterwards. Settings → Account → CLI sessions is the fallback for a machine you no longer have, or for a logout that could not reach the server — the CLI warns on stderr in that case.

Commands

Each block is that command’s --help, verbatim. Flags marked takes a value need one — --target claude or --target=claude; the rest are switches. An unknown flag is a usage error, never a silent no-op.

promptdock login

promptdock login [--token pdk_…]

Log in via the browser hand-off: the CLI prints a code, opens promptdock.ai,
you approve there, and the terminal continues. --token stores a token minted in
Settings → Account → CLI sessions (the CI path; or set PROMPTDOCK_TOKEN).

Flags: --token (takes a value)

promptdock logout

promptdock logout

Removes the locally-stored token (~/.promptdock/config.json). The server-side
session stays valid until revoked in Settings → Account → CLI sessions.

Correction — this is wrong in v1.2.0’s own help. promptdock logout revokes the session server-side before it clears the local token — it calls DELETE /api/v1/cli/tokens/current, and prints “the session was revoked server-side” when that succeeds. The session survives only if that call could not reach the server, and the CLI warns on stderr when that happens. Otherwise there is nothing left to revoke in Settings → Account → CLI sessions afterwards.

promptdock whoami

promptdock whoami [--json]

Shows the signed-in handle, role, and token expiry.

Flags: --json

promptdock install

promptdock install <handle>/<slug> [-g] [--target <tool>] [--dir <path>] [-y] [--force] [--dry-run] [--json]

Installs a skill. Interactively it asks two things: which TOOL, then whether
to install for THIS PROJECT or for your USER ACCOUNT (each shown as its real
destination path). -g answers the second one up front; --dir answers both.

Non-interactive sessions (CI) must pass --target or --dir plus -y, and
authenticate via PROMPTDOCK_TOKEN. -y skips the prompts ONLY — a non-empty
foreign directory still requires --force, and scope stays project-local
unless -g is passed. --dry-run resolves and prints the plan without
installing (and without spending any premium-unlock slot).

Flags: --json · --global · --yes · --force · --dry-run · --target (takes a value) · --dir (takes a value)

promptdock uninstall

promptdock uninstall <handle>/<slug> | --all [-g] [--target <tool>] [--dir <path>] [--force] [-y] [--json]

Removes an installed skill using its .promptdock.json receipt — only files the
receipt lists are ever deleted. Locally-modified files block removal without
--force (copy your changes out first).

Flags: --json · --global · --yes · --force · --all · --target (takes a value) · --dir (takes a value)

promptdock update

Also spelled promptdock upgrade — the same command, kept for npm muscle memory.

promptdock update [<handle>/<slug>] [--all] [--check] [-g] [-y] [--force] [--json]

Updates installed skills to the latest approved version. Bare `update` covers
the project-local scope; -g the global scope; --all both. --check reports
without applying. Locally-modified files block an update without --force.

Flags: --json · --global · --yes · --force · --all · --check · --target (takes a value) · --dir (takes a value)

promptdock list

promptdock list [--json] [-g] [--all]

Lists installed skills from their receipts: ref, version, target, installed-at.

Flags: --json · --global · --all

promptdock help

promptdock help — prints the global command map.

Two flags that surprise people

--all means two things at once. On update and list it widens the SCOPE — project-local and your user account, instead of just this directory. On uninstall it also stands in for the skill ref, so promptdock uninstall --all removes every installed skill in both scopes, not just the one you were thinking of. Run promptdock list --all first to see exactly what that covers.

--dir overrides --target. An explicit directory answers both the tool question and the scope question, so a --target passed alongside it is ignored rather than reconciled.

Install targets

Where each tool expects its skills to live. --target picks the tool; scope picks the column. Tools already set up in your working directory float to the top of the interactive picker.

Experimentalmeans the path is that tool’s documented convention but has not been verified end to end by us — the install itself works the same; whether the tool picks the skill up is what is unconfirmed. Verified today: Claude Code. If an experimental target does not load a skill, the files are still on disk at the path below and nothing was lost.

Tool	`--target`	This directory	Your account (`-g`)
Claude Code	claude	.claude/skills/<slug>	~/.claude/skills/<slug>
Codexexperimental	codex	.codex/skills/<slug>	~/.codex/skills/<slug>
Gemini CLIexperimental	gemini	.gemini/skills/<slug>	~/.gemini/skills/<slug>
Cursorexperimental	cursor	.cursor/skills/<slug>	~/.cursor/skills/<slug>
GitHub Copilotexperimental	copilot	.github/skills/<slug>	~/.copilot/skills/<slug>
Kimiexperimental	kimi	.kimi/skills/<slug>	~/.kimi/skills/<slug>
OpenAI/GPTexperimental	openai	.openai/skills/<slug>	~/.openai/skills/<slug>

Environment variables

The variables the published CLI documents in its own help.

Variable	What it does
PROMPTDOCK_TOKEN	bearer token for CI/non-interactive use (Settings → CLI sessions → Generate token)
PROMPTDOCK_API_BASE	API origin override (default https://www.promptdock.ai)
NO_COLOR	disable colored output

Two more things affect a run without appearing in the table. TERM=dumb (Emacs shell buffers, some IDE consoles) turns colour off and swaps the arrow-key pickers for a numbered reader — you are still asked the same questions, you type a number instead. There is no FORCE_COLOR: colour is off whenever output is not a terminal, and cannot be forced back on.

Behind a proxy:the CLI uses Node’s built-in fetch, which ignores HTTPS_PROXY and HTTP_PROXY — it detects them only to say so in the network error. On Node 24 and newer, NODE_USE_ENV_PROXY=1 makes fetch honour them.