CLI Commands

agentpack <command> [args]. Global flags may appear before or after the subcommand. Launcher arguments are forwarded unchanged; use -- when an underlying agent flag overlaps an agentpack flag.

Global flags

When --env, --definition-root, or an env use/env bind binding is set, lock/manifest operations use the definition root while .agents and overlays use the workspace. See Portable Environments.

Help and errors use the terminal’s native foreground and transparent background, with no semantic colors or theme detection. Contextual help is available at every level, for example agentpack mcp add --help.

Shell completion

Generate a completion script using the built-in completion command:

agentpack completion bash
agentpack completion zsh
agentpack completion fish
agentpack completion powershell

The command prints the script to stdout so you can source it directly or save it in your shell’s completion directory.

Lifecycle commands

agentpack init

Create agentpack.toml and an empty pack.lock in the project root, and ensure AGENTPACK_HOME exists. Fails if agentpack.toml already exists.

agentpack init
agentpack init --name my-project --version 0.1.0

agentpack add <spec>

Resolve a package spec, append it under [dependencies], refresh pack.lock, then sync.

agentpack add anthropics/skills/skills/canvas-design
agentpack add github.com/acme/monorepo/packages/rules@v1.2.0
agentpack add ./local-rules
agentpack add anthropics/skills/skills/canvas-design --no-sync

A spec may be a module ID, owner/repo[/path] shorthand, a GitHub tree/blob URL, a single-segment local/alias name, or a filesystem path. An optional @ref pins a branch, tag, or commit. --no-sync skips the sync step. (Requires a manifest.)

--plugin <name> adds one plugin of a marketplace catalog; the spec then names the marketplace repository:

agentpack add anthropics/claude-plugins-official --plugin stripe
agentpack add anthropics/claude-plugins-official@f359d43 --plugin hookify

The catalog entry says where the plugin lives, and agentpack adds that: a directory of the marketplace repository (a relative path or {"source": "local"}), or another GitHub repository ({"source": "github"}, {"source": "url"}, {"source": "git-subdir"}, with its path). An entry’s sha is used as the pin, otherwise its ref; a plugin inside the marketplace repository follows the @ref you gave. The manifest records the plugin’s own repository and path, and pack.lock pins its commit, so later commands do not need the catalog. A name in the catalog’s renames map is followed. An entry that is not a git repository on github.com (npm, another host) is refused with a message that says so.

If add fails at any step, including the sync, agentpack.toml and pack.lock are left exactly as they were.

agentpack remove <spec>

Drop a matching [dependencies] entry, prune mode selectors that targeted it, refresh pack.lock, then sync unless --no-sync.

agentpack remove github.com/acme/monorepo/packages/rules

agentpack lock

Resolve agentpack.toml and rewrite pack.lock (direct + transitive). Network calls for ref/tag resolution; no content download.

agentpack lock                        # keep commits and MCP versions already pinned
agentpack lock --update               # re-resolve floating pins from GitHub and npm dist-tags
agentpack lock --allow-unpinned-mcp   # record an MCP server as unpinned if its registry is unreachable

lock records a content_hash for every package (downloading any package it has no hash for) and a record for every MCP server. See Integrity and Verification.

agentpack sync

Ensure the cache and rebuild staging for every harness. Recomputes pack.lock from the manifest when [dependencies] is non-empty.

agentpack sync
agentpack --mode writing sync
agentpack sync --dry-run        # report actions without writing
agentpack sync --verify-only    # check cache + staging integrity only
agentpack sync --update-lock    # re-resolve floating pins while syncing
agentpack sync --repair         # re-fetch cache entries that do not match pack.lock

Every sync compares each cache entry with the content_hash in pack.lock and exits non-zero on a mismatch without staging anything. A lock whose entries are malformed or inconsistent is refused the same way, and sync never changes the pins of entries that are already locked; see what sync may write.

--verify-only runs the lock and cache checks without rebuilding, then hashes the staged files and fails, naming each file, if any was modified, added or removed since the last sync. A plain sync rebuilds staging and prints which changed files it replaced. --repair downloads the pinned commit again, verifies it, replaces the cache entry, and reports what it replaced. For a check that must not mutate lock, cache, staging, or the checkout, use preflight instead.

agentpack preflight

Pure offline inspection of a locked environment. Does not download, repair, rewrite pack.lock, rebuild staging, or write workspace overlays. Prints a human summary or --json report with stable finding codes, severity, source, target, and remedy. Optional --contract / contract.json and --receipt ID|PATH|latest for observed coverage / freshness. --mode selects the same mode as restore and launch. Receipt policy and strictness must match the preflight invocation; stale or incomplete receipts fail closed. Strict external launches evaluate the default contract under their staging lease.

agentpack preflight --agent claude
agentpack preflight --agent opencode --json --policy ci
agentpack --env team --workspace . --strict-external preflight --agent claude
agentpack preflight --agent claude --receipt RECEIPT_ID --json

agentpack probe

Explicit native observation (never inside preflight). Claude: plugin list --json + plugin details against the staged bundle. Codex: version, plus validated 0.159.2 and 0.159.3 skill discovery from native prompt input with a disposable home. Claude Code 2.1.296 and both Codex versions also record the workspace_session catalog of a session started in the checkout, including which copy holds each packaged skill’s name. --agent opencode (1.17.11) samples 60 debug skill listings, because OpenCode’s choice between same-named skills varies between runs. Observations carry an explicit scope; they do not prove user-level configuration or model use. Writes a receipt under $AGENTPACK_HOME/projects/<hash>/probe-receipts/.

agentpack sync
agentpack probe --agent claude
agentpack --mode review probe --agent codex --json
agentpack --strict-external probe --agent claude --policy ci
agentpack --strict-external preflight --agent claude --policy ci --receipt latest

agentpack env

Manage portable external definitions under $AGENTPACK_HOME/environments (or an explicit --dir). env bind is an alias for env use. env restore is frozen: exact locked cache + staging rebuild, no pack.lock rewrite.

agentpack env init team --from .
agentpack env use team --project /path/to/checkout
agentpack env status
agentpack env export team.bundle --from team
agentpack env import team.bundle --name team
agentpack --env team --workspace /path/to/checkout --mode review env restore
agentpack env unuse
agentpack env list

agentpack support export

Write a redacted diagnostic capsule from a probe receipt (--output required). Paths, free-form native messages, arbitrary values and secret-bearing digests are omitted; preview notes are printed before sharing.

agentpack support export RECEIPT_ID --output ./support-capsule.json

Launchers

Each launcher runs a fast pre-sync, stages for its harness, and execs the binary. Trailing arguments are forwarded. Launches convert artifacts and hooks only for the selected harness and omit routine hook-rendering messages. Bare agentpack sync builds every harness.

agentpack claude --model opus
agentpack --proxy claude
agentpack --yolo codex
agentpack --mode writing claude

See the harness guides for what each one stages.

agentpack eject

IDE extensions and desktop apps (Claude Code in VS Code, the Cursor editor, the Codex extension, the Antigravity editor) do not start through a launcher. eject syncs, copies the staged tree to .agentpack/eject/ in the project, points its paths at that copy, and registers it where each agent reads project configuration:

Claude Code is given plain project files rather than a plugin: a project-declared marketplace is installed only after a person accepts it in an interactive session. OpenCode and Grok run in a terminal; use their launchers. Cursor does not run hooks in non-interactive (-p) runs. Eject refuses, before writing anything, to replace a file or a setting it did not write. Every file and key it adds is recorded in .agentpack/eject/manifest.json; --remove takes out exactly those, keeping the rest of each file. Run it again after changing agentpack.toml.

agentpack eject                 # every supported agent
agentpack eject claude cursor   # only these
agentpack eject --remove

agentpack mcp

Manage [mcp.servers] in the manifest. add/remove update the server records in pack.lock and sync afterward unless --no-sync.

agentpack mcp add retrieval --command uvx --args mcp-retrieval --env API_KEY=sk-...
agentpack mcp add playwright --command npx --args @playwright/mcp@latest --allow-unpinned
agentpack mcp remove retrieval
agentpack mcp list      # all servers with provenance and lock status

add resolves an npm server to an exact version and fails if the registry is unreachable; --allow-unpinned records it as unpinned instead. See MCP Servers.

agentpack mode

Manage [modes] in the manifest.

agentpack mode list
agentpack mode show writing
agentpack mode create review
agentpack mode base review none
agentpack mode enable review package:github.com/acme/shared-rules
agentpack mode disable review mcp:filesystem
agentpack mode delete review        # `default` is reserved
agentpack mode tui                  # interactive editor

See Modes for selector syntax.

agentpack extra sync-claude

Reconciles a project’s .claude/skills and .agents/skills directories so a local skill authored under either one reaches both. Claude Code only discovers project-local skills under .claude/skills, while the dot-agents convention shares project-local content across every harness under .agents/skills. This is unrelated to fetched pack content or $STAGING — it only touches the two real directories in your project.

A skill present on only one side is copied to the other. A skill present on both sides with differing content is reconciled toward whichever copy has the newer file modification time.

agentpack extra sync-claude             # reconcile in place
agentpack extra sync-claude --dry-run   # show what would change