CLI errors

#upgrade_required

Your CLI is older than something the server needs. Two different things produce this, and they differ in blast radius: either ONE package is too large for the safety limits built into your version — everything else keeps working — or your CLI is below the minimum version the API accepts at all, in which case every command fails, including login.

The CLI carries its own install-safety limits so a compromised server cannot fill your disk or write outside the target directory. Those limits are fixed at the version you installed, so a package published above them needs a newer CLI — and only that package is refused. Separately, the API enforces a minimum CLI version for wire-breaking changes; a client below it is rejected before it authenticates, so that refusal is account-wide, not package-scoped. The error text tells you which one you hit: a named skill means the first, a minimum-version number means the second.

Fix

• npx promptdock@latest install <handle>/<slug>
• If you installed globally: npm i -g promptdock@latest
• In CI, unpin the version or raise the pin to the version named in the error.
• If you cannot even log in, it is the account-wide floor — upgrade first, then run `promptdock login`.

#manifest_bounds

The server returned a file list larger than this CLI will ever install. Nothing was downloaded or written.

This is the untrusted-server backstop, not a policy limit. You would normally see the friendlier `upgrade_required` refusal before any download starts. Reaching this one means the response did not match what the CLI asked for.

Fix

• Update: npx promptdock@latest install <handle>/<slug>
• If it persists on the latest CLI it is a server bug, not a package problem — capture the exact message and `promptdock --version`.

#manifest_path

A file had a path the CLI refuses to write — a traversal segment, an absolute path, a backslash, a control character, or a Windows reserved name. Nothing was written.

The CLI re-validates every path itself so a compromised server cannot turn an install into an arbitrary file write. It never trusts the server's validation.

Fix

• There is no workaround, by design — do not retry with one.
• Report it from the skill's page on promptdock.ai — the Report control is under the title. A published package should never contain such a path.

#integrity

A file's SHA-256 did not match the manifest. The install was abandoned and the staging directory discarded — existing files were not touched.

Every file is hashed after download and compared before anything is moved into place. A mismatch means the bytes changed in transit or at rest.

Fix

• Retry — a transient network fault is the usual cause.
• If it repeats for the same skill, report it from that skill's page on promptdock.ai (the Report control is under the title).

#receipt_schema

`.promptdock.json` in the target directory uses a schema this CLI does not understand, so it will not guess at an uninstall or update.

The receipt is the only record of which files an install owns. Acting on one it cannot read risks deleting files it does not own.

Fix

• npx promptdock@latest update
• Or remove the directory by hand if you no longer want the skill.

#receipt_invalid

`.promptdock.json` exists but is corrupt or missing required fields.

Without a valid receipt the CLI cannot tell which files it owns.

Fix

• Remove the directory by hand, then reinstall.
• npx promptdock@latest install <handle>/<slug>

#local_changes

Installed files no longer match the checksums in the receipt, so the update or uninstall stopped.

Overwriting would silently discard your edits. The CLI would rather stop than lose work you did on purpose.

Fix

• Copy your changes somewhere safe first.
• Then re-run with --force to overwrite.

#insufficient_tier

The skill's contents are available on a paid plan and your account is on a lower tier.

Premium skills unlock by subscription, not per item.

Fix

• https://promptdock.ai/pricing
• Free skills install with no plan at all.

#cap_hit

You have unlocked the maximum number of distinct premium skills in a rolling 24-hour window.

The cap counts distinct skills, not installs. Re-installing something already unlocked does not count again.

Fix

• Wait for the window named in the error.
• Skills you have already unlocked keep installing.

#not_found

The ref did not resolve to a skill you can see.

Either the ref is wrong, or the skill is a draft, unlisted, or has been taken down.

Fix

• The format is handle/slug — for example: npx promptdock@latest install alice/seo-audit
• A pasted promptdock.ai skill URL also works.
• Check the account: npx promptdock@latest whoami

#access_denied

The browser approval for this CLI session was denied.

Someone chose Deny on the device-approval screen, or approved a different code.

Fix

• npx promptdock@latest login
• Check the code in the browser matches the one in your terminal.

#login_timeout

The pairing code was not approved before it expired.

Codes are short-lived on purpose — an unclaimed code should not stay valid.

Fix

• npx promptdock@latest login

#auth

There is no stored token, or the one on disk was rejected.

Tokens are per machine and can be revoked from the dashboard or by `promptdock logout`.

Fix

• npx promptdock@latest login
• Or set PROMPTDOCK_TOKEN in CI.

#verdict

The server answered with a decision this CLI does not know how to act on.

The server is newer than the CLI.

Fix

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

#rate_limited

The API asked you to slow down. Nothing was installed or changed.

CLI routes are rate limited per account and per IP. The per-IP half is the one that surprises people: several developers behind one office NAT, or a CI fleet on shared egress, share a bucket even with different accounts.

Fix

• Wait for the period named in the message, then retry.
• In CI, stagger parallel jobs rather than starting them in one burst.
• If you are behind a shared NAT with colleagues, that is the likely cause — it is not your account alone.

#internal

Something failed that the CLI has no specific handling for. It stopped rather than continuing in an unknown state.

This is the catch-all at the top level. Reaching it means the failure was not one of the named cases on this page — most often an environment problem (a Node version below 18, a broken install) rather than anything about your account or the skill.

Fix

• Check your Node version: `node -v` — the CLI needs 18 or newer.
• Reinstall: `npm i -g promptdock@latest`, or run via `npx promptdock@latest`.
• If it repeats, capture the exact message and `promptdock --version` before anything else — that pair is what makes it diagnosable.

#api

A request failed. Usually the server explained why in the message above this footer — but if you were told the response redirected somewhere unexpected, nothing reached the server at all.

For an ordinary failure the server's own message is more specific than anything this page can say. For the redirect case the CLI refuses to follow a cross-domain or non-https hop, because a captive portal or a MITM can mint one — so it stops rather than sending your token onward.

Fix

• Read the message above — for an ordinary failure it is the most specific thing you have.
• If it mentions a redirect: check PROMPTDOCK_API_BASE, and whether you are behind a captive portal or a corporate proxy.
• Retry if it looks transient. If it is a skill-content problem, use the Report control on that skill's page.

#network

The request never got a response.

Usually connectivity. Note that Node's built-in fetch does NOT read HTTPS_PROXY / HTTP_PROXY — behind a corporate proxy, requests fail even though curl works.

Fix

• Check your connection, then retry.
• Behind a proxy, run on a network that does not require one — the proxy env vars have no effect.
• Check https://promptdock.ai loads in a browser.

#eacces

The CLI could not write to the install directory.

The directory is owned by another user, or is read-only.

Fix

• Choose a different location: --dir ./my-skills
• Or fix the permissions on the path in the message.

#enospc

The write ran out of space. The partial staging directory was discarded.

The CLI stages into a sibling directory and renames, so a full disk fails cleanly rather than half-writing.

Fix

• Free up space and retry.

#existing_dir

The target exists and is not a previous install of this skill.

The CLI will not merge into a directory whose contents it does not own.

Fix

• Install elsewhere: --dir ./somewhere-else
• Or overwrite deliberately: --force

#io

A read or write failed for a reason the CLI could not classify.

The underlying error is printed in the message above, and it names the path.

Fix

• Read the message above.
• Retry, or choose a different --dir.

#download

One of the package's files failed to fetch. Nothing was installed.

Download URLs are short-lived; a slow or interrupted install can outlive them.

Fix

• Retry — a fresh set of URLs is issued each time.

#not_installed

`update` or `uninstall` found no promptdock receipt in that directory.

The CLI only manages directories it installed, identified by `.promptdock.json`.

Fix

• npx promptdock@latest list
• Then re-run against a directory that appears in it.

#no_receipt

`list` or `update` scanned the known locations and found no receipts.

Either nothing is installed, or it was installed somewhere the CLI does not scan.

Fix

• Point at it explicitly: --dir ./path
• Or install one: npx promptdock@latest install <handle>/<slug>

#config

`~/.promptdock/config.json` could not be read, written, or locked down to owner-only permissions.

The config holds your API token. If the CLI cannot set 0600 on it, it refuses to keep the token rather than leave it world-readable.

Fix

• Check ownership and permissions on ~/.promptdock/
• Or use PROMPTDOCK_TOKEN instead of a stored token.

#usage

The arguments did not make sense for that command.

Most often: a non-interactive run (CI, a pipe) without --target/--dir and -y, which the CLI will not guess at.

Fix

• npx promptdock@latest --help
• In CI, pass --target, --dir and -y explicitly.