CLI commands

Agents Pack CLI 0.1.1. Invoke the binary as agents-pack.

agents-pack <command> [options]
agents-pack --version
agents-pack --help

Run agents-pack <command> --help for command-specific help. Content-changing commands support --dry-run (print the plan without writing) and, where noted, --yes (apply without interactive confirmation).

For workflows and day-to-day usage, see Initialize, Install and remove components, Create user components, Fork and customize, Update, pin, and rollback, and Eject and uninstall.

Global flags

`--version`

Print the CLI version and exit.

agents-pack --version

`--help`

Print general help: usage, the command list, and a pointer to per-command help.

agents-pack --help

Commands

Command	Summary
`init`	Initialize Agents Pack in global or repository scope.
`status`	Inspect the current Agents Pack installation.
`list`	List installed and available components.
`install`	Install a component from the current pack.
`remove`	Remove an optional component.
`create`	Create a canonical user-owned skill or subagent.
`fork`	Copy an official component into user ownership.
`sync`	Render user-owned components for selected agents.
`update`	Preview or apply a content-pack update.
`pin`	Keep the currently installed pack version.
`unpin`	Allow forward content-pack updates again.
`rollback`	Restore an older pack version from the local cache.
`eject`	Remove managed Agents Pack content safely.

`init`

Initialize Agents Pack in global or repository scope.

agents-pack init --scope <repository|global> --agents <list> --components <choice> [--pack <path>] [--yes] [--dry-run]

Options

Option	Description
`--scope <scope>`	Install in `repository` or `global` scope.
`--agents <list>`	Comma-separated `claude`, `codex`, `cursor` selection, or `all`.
`--components <choice>`	`recommended`, `all`, or comma-separated component IDs.
`--pack <path>`	Use a local content-pack directory instead of the official pack.
`--yes`	Apply without an interactive confirmation.
`--dry-run`	Print the plan without writing.

Notes

Interactive use may omit --scope, --agents, and --components. Non-interactive use must provide them together with --yes (or use --dry-run only).
--agents all is shorthand for --agents claude,codex,cursor.
Required components are always included when you pass explicit IDs.
--pack records a local installation source; that installation never silently switches to the public registry.
Global scope does not support Cursor. See Platforms and agents.
Only one active scope is supported at a time. See Repository vs global.

Examples

agents-pack init \
  --scope repository \
  --agents claude,codex,cursor \
  --components recommended \
  --dry-run

agents-pack init \
  --scope repository \
  --agents all \
  --components recommended \
  --yes

`status`

Inspect the current Agents Pack installation.

agents-pack status

Status is always read-only, including when recovery is required. It accepts no options.

Typical report contents:

repository or global scope
pack ID and version
official or local source
pin state
selected agents
official and user-owned component names
managed outputs as clean, missing, modified, or malformed
warnings such as unsynchronized user-owned source

If a previous mutation was interrupted, status reports that recovery is required but does not modify anything. Rerun the interrupted mutating command to recover safely.

`list`

List installed and available components.

agents-pack list [--installed|--available] [--kind <kind>]

Options

Option	Description
`--installed`	Show only selected components.
`--available`	Show only unselected components.
`--kind <kind>`	Filter by `instruction`, `skill`, or `subagent`.

--installed and --available cannot be combined. User-owned components appear in installed listings with a user-owned label.

Examples

agents-pack list
agents-pack list --installed
agents-pack list --available
agents-pack list --kind skill
agents-pack list --available --kind subagent

`install`

Install a component from the current pack.

agents-pack install <component-id> [--yes] [--dry-run]

Options

Option	Description
`--yes`	Apply without an interactive confirmation.
`--dry-run`	Print the plan without writing.

Accepts exactly one official component ID. Uses the exact installed pack from the local cache; does not contact the registry. Repeating an install that is already satisfied is a safe no-op.

Examples

agents-pack install ap-frontend-design --dry-run
agents-pack install ap-frontend-design --yes

See Install and remove components.

`remove`

Remove an optional component.

agents-pack remove <component-id> [--yes] [--dry-run]

Options

Option	Description
`--yes`	Apply without an interactive confirmation.
`--dry-run`	Print the plan without writing.

Accepts exactly one official component ID. Required components cannot be removed. Uses the exact installed pack from the local cache. Repeating a remove that is already satisfied is a safe no-op.

Examples

agents-pack remove ap-frontend-design --dry-run
agents-pack remove ap-frontend-design --yes

`create`

Create a canonical user-owned skill or subagent.

agents-pack create skill <name> --description <text> [--yes] [--dry-run]
agents-pack create subagent <name> --description <text> [--write] [--yes] [--dry-run]

The canonical source is created under .agents-pack/user (repository) or ~/.agents-pack/user (global). Edit that source, then run sync to regenerate provider copies.

Options

Option	Description
`--description <text>`	Explain what the component does and when to use it.
`--write`	Give a subagent workspace-write access; default is read-only. Valid only for subagents.
`--yes`	Apply without an interactive confirmation.
`--dry-run`	Print the plan without writing.

Notes

Names cannot use the reserved ap- prefix.
Interactive use can prompt for a missing description. Non-interactive use requires --description.
New subagents are read-only unless you pass --write.

Examples

agents-pack create skill deploy-app \
  --description "Deploy this application safely. Use for staging or production deployment." \
  --yes

agents-pack create subagent release-checker \
  --description "Review release correctness and operational risk. Use before deployment." \
  --yes

agents-pack create subagent api-implementer \
  --description "Implement approved API changes. Use after an API plan is accepted." \
  --write \
  --yes

See Create user components and File layout.

`fork`

Copy an official component into user ownership.

agents-pack fork <official-component> --name <user-name> [--yes] [--dry-run]

The new name cannot use the reserved ap- prefix. Only official skills and subagents can be forked. Official instruction components cannot be forked.

Options

Option	Description
`--name <name>`	Name for the user-owned copy.
`--yes`	Apply without an interactive confirmation.
`--dry-run`	Print the plan without writing.

Forking copies the exact installed official source, records a separate user-owned component, and renders it for every selected agent. Future official updates do not overwrite your copy. The original official component stays installed unless you remove it separately.

Examples

agents-pack fork ap-debug --name my-debug --dry-run
agents-pack fork ap-debug --name my-debug --yes

See Fork and customize.

`sync`

Render user-owned components for selected agents.

agents-pack sync [--yes] [--dry-run]

Options

Option	Description
`--yes`	Apply without an interactive confirmation.
`--dry-run`	Print the plan without writing.

Requires at least one canonical user-owned component. Edit under .agents-pack/user/ or ~/.agents-pack/user/, then sync. Direct edits to generated provider copies are treated as drift and block synchronization.

Examples

agents-pack sync --dry-run
agents-pack sync --yes
agents-pack status

`update`

Preview or apply a content-pack update. This updates instructions, skills, subagents, and pack release notes — not the CLI executable. To upgrade the CLI, rerun the installer.

agents-pack update --check [--pack <path>]
agents-pack update [--pack <path>] [--yes] [--dry-run]

Options

Option	Description
`--pack <path>`	Use a local candidate instead of the official registry.
`--check`	Show version and release information without writing.
`--yes`	Apply without an interactive confirmation.
`--dry-run`	Print the update plan without writing.

Notes

--check cannot be combined with --yes or --dry-run.
Official installations use the registry by default. Local installations require --pack.
Your explicit component selection is preserved. New optional or recommended components become available but are not silently installed.
User-owned canonical content is not part of the official update.
A pinned installation can still run --check, but applying a different pack version stops until you unpin.

Examples

agents-pack update --check
agents-pack update --dry-run
agents-pack update --yes

agents-pack update --check --pack /path/to/new-local-pack
agents-pack update --pack /path/to/new-local-pack --yes

See Update, pin, and rollback.

`pin`

Keep the currently installed pack version.

agents-pack pin

Accepts no options. Takes effect immediately. Idempotent. Still validates that managed outputs are clean.

A pinned installation can still check for updates, install available components, and remove optional components. Applying a different pack version stops until you unpin.

`unpin`

Allow forward content-pack updates again.

agents-pack unpin

Accepts no options. Takes effect immediately. Idempotent. Still validates that managed outputs are clean.

`rollback`

Restore an older pack version from the local cache.

agents-pack rollback [version] [--yes] [--dry-run]

Without a version, rollback chooses the newest cached version older than the installed version. A successful rollback pins that version.

Options

Option	Description
`--yes`	Apply without an interactive confirmation.
`--dry-run`	Print the rollback plan without writing.

Notes

Rollback only uses previously cached packs with the same pack ID. It never downloads a missing historical version.
User-owned canonical content is preserved.
Run unpin when you are ready to move forward again.

Examples

agents-pack rollback --dry-run
agents-pack rollback --yes
agents-pack rollback 0.24.0 --dry-run
agents-pack rollback 0.24.0 --yes

`eject`

Remove managed Agents Pack content safely.

agents-pack eject [--yes] [--dry-run]

Options

Option	Description
`--yes`	Apply without an interactive confirmation.
`--dry-run`	Print the removal plan without writing.

Eject removes:

official generated provider files and managed blocks
user-generated provider copies
the official installation configuration and lock
the user-generated output lock

Eject preserves canonical user-owned source under .agents-pack/user/ or ~/.agents-pack/user/. It refuses to delete modified, missing, or malformed managed content.

Removing the CLI binary is separate; see Eject and uninstall.

Examples

agents-pack eject --dry-run
agents-pack eject --yes

CLI commands

CLI commands

Global flags

--version

--help

Commands

init

Options

Notes

Examples

status

list

Options

Examples

install

Options

Examples

remove

Options

Examples

create

Options

Notes

Examples

fork

Options

Examples

sync

Options

Examples

update

Options

Notes

Examples

pin

unpin

rollback

Options

Notes

Examples

eject

Options

Examples

Related

`--version`

`--help`

`init`

`status`

`list`

`install`

`remove`

`create`

`fork`

`sync`

`update`

`pin`

`unpin`

`rollback`

`eject`