docs · cli reference

CLI reference

Every subcommand the pakx binary ships. Pair with the agents.yml reference (what you write) and the registry HTTP API reference (what the publish flow talks to).

pakx --help prints the same info from the binary itself; pakx <subcommand> --help drills into a single command.

pakx init

pakx init [--yes] [--force] [--name <name>] [--agent <id>...]

Interactive scaffolder for agents.yml. `--yes` skips the prompts and uses the defaults; `--force` overwrites an existing file.

Flags

--yes: — Skip all prompts.
--force: — Overwrite an existing agents.yml.
--name <name>: — Set the project name without prompting.
--agent <id>: — Add an agent to the manifest's `agents:` list. Repeatable.

writes: agents.yml

pakx add

pakx add <id> [--type <kind>] [--no-validate]

Append a dependency to agents.yml. Best-effort validation against the federated index unless --no-validate is set.

Flags

--type, -t <kind>: — Override package-type inference. One of: skills, mcp, subagents, prompts, commands, hooks.
--no-validate: — Skip the registry-validation network call.

writes: agents.yml

pakx install

pakx install [-C <dir>] [--no-lockfile]

Resolve every dependency in agents.yml via the federated registry, write the right config files for every detected agent (e.g. .mcp.json for Claude Code), and emit agents.lock.

Flags

-C, --directory <dir>: — Run as if from <dir>.
--no-lockfile: — Resolve + install but skip writing agents.lock.

writes: agents.lock, .mcp.json (per detected agent)

pakx list

pakx list [-C <dir>]

Print pinned lockfile entries with [ok] / [drift] markers against on-disk reality. Read-only.

Flags

-C, --directory <dir>: — Run as if from <dir>.

pakx doctor

pakx doctor [-C <dir>]

Five-section health check: manifest, lockfile, drift, adapter detection, on-disk vs lockfile. Prints the running pakx version + host OS at the top.

Flags

-C, --directory <dir>: — Run as if from <dir>.

exit: 0 if all checks pass, 1 if any warn/fail.

pakx search

pakx search <query> [-n <limit>] [--no-smithery] [--no-pakx]

Free-text search across every federated source (Official MCP Registry, Smithery, pakx-registry). Empty query returns the first page.

Flags

-n, --limit <n>: — Max results to display (default 20).
--no-smithery: — Skip the Smithery source even if it's reachable.
--no-pakx: — Skip the first-party pakx-registry source.

pakx info

pakx info <owner>/<name> [--registry <url>] [--json]

Print registry-side metadata + version list for a published package. Read-only; does not install.

Flags

--registry <url>: — Override the pakx-registry base URL (default https://registry.pakx.dev).
--json: — Print structured JSON instead of the human-friendly table.

pakx login

pakx login [--token <token>] [--registry <url>]

Validate an API token against the registry's /api/v1/whoami and write it to ~/.pakx/credentials.json (mode 0600 on Unix). Token can be passed via --token, the PAKX_TOKEN env var, or an interactive prompt.

Flags

--token <token>: — Token to validate + store. Also reads PAKX_TOKEN.
--registry <url>: — Override the registry base URL.

writes: ~/.pakx/credentials.json

pakx whoami

pakx whoami [--offline] [--registry <url>]

Print the GitHub login pakx is authenticated as. --offline reads from credentials without a network round-trip.

Flags

--offline: — Skip the /api/v1/whoami round-trip.

pakx pack

pakx pack [-C <dir>]

Build a deterministic gzipped tarball from a directory containing SKILL.md. Sorted entries, zeroed mtime/uid/gid, mode 0o644, max 50 MiB.

writes: <name>-<version>.tgz

pakx publish

pakx publish [-C <dir>] [--dry-run]

Pack + POST package + PUT tarball to registry.pakx.dev. --dry-run packs but skips the upload.

Flags

--dry-run: — Build the tarball + verify the metadata round-trip without uploading.

pakx unpublish

pakx unpublish <owner>/<name>@<version>

Soft-delete a published version. The version row is tombstoned so existing manifests keep resolving.

pakx upgrade

pakx upgrade   (alias: pakx update)

Hit github.com/repos/pakxdev/pakx/releases/latest, semver-compare to the running binary, print the channel-appropriate install command. Read-only — does not rewrite the installed binary.

pakx completion

pakx completion <bash|zsh|fish|powershell|elvish>

Emit a shell-completion script for the chosen shell. Generated from the same Cli struct that drives the binary, so completions never drift out of sync. Pipe into the appropriate shell-specific location.

pakx config

pakx config [--json]

Print the resolved CLI configuration — credentials path, federated-search cache dir, and the three registry URLs (official MCP, Smithery, pakx). Read-only. Useful when filing bug reports or wiring up the CLI on a new machine.

Flags

--json: — Emit the same fields as a JSON object for piping into jq.

Environment variables

PAKX_TOKEN — bearer token used by pakx publish / pakx unpublish / pakx whoami. Also accepted via --token on pakx login.
RUST_LOG — standard tracing-subscriber filter. RUST_LOG=debug pakx install prints every upstream URL it hits.

Exit codes

0 on success; 1 on any user-facing error (missing manifest, validation failure, network). Errors print to stderr; success-side output goes to stdout so commands pipe cleanly.