Command-line reference
This page lists every agent-marketplace command, its flags, defaults, output, and exit status. Use it when you need the exact behavior of a command. If you are new to the tool, start with the quick start.
The agent-marketplace command reads your layered configuration (including local files named by each layer's include field), finds the resources in each configured registry, and writes them into the folders each harness reads. The docs call that last step materialization.
For configuration fields, include syntax, and precedence, see the configuration reference.
Command syntax
agent-marketplace [global flags]
agent-marketplace <command> [arguments] [flags]Running agent-marketplace with no command starts the terminal UI when standard input is a terminal. Otherwise it prints help. Setting AGENT_MARKETPLACE_NO_TUI to any non-empty value also makes a bare invocation print help.
Consumer operations require exact apiVersion: agent-marketplace/v4 in every existing root, including organization and personal-local. Included fragments may omit the field or declare exact v4. Missing root versions fail with v4.api-version-required; unsupported or invalid explicit values fail with v4.api-version, identifying the authored file and apiVersion field. No consumer operation falls back to a legacy reader, and neither CLI startup nor the TUI offers conversion. There is no shipped migrate command. Convert with an older released migrator before upgrading; organization configuration must be converted externally.
Every command checks all the config files and includes it needs, including for ad hoc --from operations, before it downloads anything or writes config, locks, or harness files. If an earlier command was interrupted mid-write, read-only commands report dependency.recovery-required and do not replay it. Commands that can recover may finish that earlier write first, which changes the files it recorded, but start no new work on unsupported input. Apart from that recovery, a refused command leaves existing files and their metadata untouched and creates no missing config file or lock; it may still write logs. Commands that don't use consumer config, such as serve, help, and completion, need no config file.
Global flags
Every command accepts these flags.
| Flag | Type | Required | Default | Description |
|---|---|---|---|---|
--debug | boolean | no | false | Enables debug logging and mirrors logs to standard error. |
--diagnostic | boolean | no | false | Captures a diagnostic telemetry payload for this invocation so you can review it before it is sent. Capture needs the effective telemetry level detailed; at other levels it is turned off. See the telemetry reference. |
--diagnostic-accept-sensitive-data | boolean | no | false | Acknowledges that a diagnostic payload may contain sensitive data. Without a terminal, diagnostic export and telemetry preview --level diagnostic require it. |
-h, --help | boolean | no | false | Prints help for the selected command. |
--version | boolean | no | false | Prints the CLI version. This flag belongs to the root command only. |
Resource kinds
Flags named --kind accept these values unless a command says otherwise:
| Value | Resource |
|---|---|
skill | Agent skill |
command | Harness command |
subagent | Subagent definition |
hook | Harness hook |
mcp | MCP server definition |
collection | Named group of resources. list, search, and remove accept it as a --kind value; install takes a collection by name. |
When install or remove gets a name that more than one resource kind uses, --kind selects the one you mean.
Configuration scopes
install, remove, and deinit use these scope names:
| Scope | Configuration file | Where output goes |
|---|---|---|
repo | <repo>/.agents/config.yaml | The repository |
user | ~/.agents/config.yaml | Your machine (home directory) |
local | <repo>/.agents/config.local.yaml | The repository, personal to your checkout |
Installing a resource defaults to repo, and registering a Marketplace endpoint defaults to user. When you remove a named resource without --scope, the command picks the scope from the selection it finds. remove --from defaults to repo, and deinit defaults to user.
init
Creates a minimal v4 user config (~/.agents/config.yaml) with an explicit harness list. It adds no sources or resources. If a valid user file already exists, init leaves it unchanged and prints User personal config already initialized. Existing unsupported roots or fragments produce the path-specific format refusal instead of being treated as initialized or overwritten. CLI and TUI edits use the v4 source/resource model.
agent-marketplace init [flags]| Flag | Type | Required | Default | Description |
|---|---|---|---|---|
--harnesses | comma-separated strings | without a terminal | none | Target harnesses. Accepted values: claude, codex, cursor, devin, factory, gemini, and windsurf. |
Without --harnesses, init detects installed harnesses, prints Detected harnesses: ..., and asks Use these? [Y/n/e to edit]:. Without a terminal, --harnesses is required. When init creates the file interactively, it also asks Enable basic telemetry? [Y/n]:, unless organization policy already sets the telemetry level.
A new file produces this output:
Initialized user personal config: <home>/.agents/config.yamllist
Lists the resources found in your configured registries, or in one ad hoc registry. It does not edit configuration. A target harness set is optional here; without one, list prints a warning to standard error and continues.
agent-marketplace list [flags]| Flag | Type | Required | Default | Description |
|---|---|---|---|---|
--kind | string | no | all kinds | Filters by skill, command, subagent, hook, mcp, or collection. |
--from | string | no | configured registries | Reads an ad hoc Git URL, GitHub web URL, or GitLab web URL without writing it to configuration. |
--ref | string | no | inferred or registry default | Selects a branch, tag, or commit for --from. Requires --from. |
--path | string | no | inferred or registry root | Selects a subdirectory for --from. Requires --from. |
The table columns are REGISTRY, KIND, NAME, TAGS (metadata), and STATUS. Resources from configured registries have status available, enabled, or required (org). A resource that failed validation has status malformed: <reason>. Valid ad hoc resources have status available, and ones that fail validation show malformed: <reason>.
When configured output is out of sync, the command appends a summary like this:
3 resources out of sync — run 'agent-marketplace sync'When a selected Marketplace pin cannot be resolved from verified local cache evidence, list cannot compute drift and instead prints the following line, with no out-of-sync count:
Sync state unknown: Marketplace cache evidence missing — run 'agent-marketplace sync'search
Searches hosted Marketplace endpoints. It does not edit configuration. An empty query returns the endpoint's default result page.
agent-marketplace search [query] [flags]| Flag | Type | Required | Default | Description |
|---|---|---|---|---|
--marketplace | alias, URL, or all | no | all configured | Searches one configured alias, one configured or ad hoc HTTP(S) endpoint, or every configured endpoint. |
--kind | string | no | all kinds | Filters by skill, command, subagent, hook, mcp, or collection. |
--output | string | no | table | table or json. JSON includes successful results and per-endpoint errors. |
--limit | non-negative integer | no | server default 100 | Maximum results after combining endpoint responses. |
--offset | non-negative integer | no | 0 | Result offset after combining endpoint responses. |
Table output has MARKETPLACE, SOURCE, KIND, NAME, and DESCRIPTION columns. Results are ordered by relevance, but the scores are not printed. When you search several endpoints, each failed endpoint prints warning: <marketplace>: <error> and appears under errors in JSON. The command fails only when no endpoint returned results and at least one endpoint reported an error. When you select a single endpoint with --marketplace and it fails, the command returns that error.
install
Adds selections to one writable config layer, then syncs harness output.
You can select a named resource from a configured Git or directory source, or from --from <registry> with optional --ref and --path. An ad hoc registry becomes a named v4 git or directory source. A relative directory stays relative in repository and personal-local configs, so committed sources keep working on other machines. Installing every resource from an ad hoc registry declares the source with an all: true resource group. Named, bulk, tag, and ad-hoc installs use v4 edits. Unsupported roots or fragments refuse before acquisition or new writes; a valid destination cannot bypass another required invalid layer. See configuration requirements and current limits.
agent-marketplace install <resource-name>... [flags]
agent-marketplace install <collection-name> [flags]
agent-marketplace install <marketplace-endpoint> [--scope user|repo|local]
agent-marketplace install <marketplace-locator> [flags]
agent-marketplace install --marketplace <alias-or-url> <resource-locator> [flags]
agent-marketplace install --tag <tag> [flags]
agent-marketplace install --all [flags]
agent-marketplace install --from <registry> [<resource-name>...] [flags]install accepts several resource names in one command, resolved from the configured registries or from a single --from source:
agent-marketplace install frontend-design review
agent-marketplace install --from https://github.com/example/resources.git frontend-design reviewThe shared --scope, --kind, --ref, and --path options apply to every name. A repeated name is installed once, in the order you first gave it. If a requested name is missing, malformed, ambiguous, or not allowed in the target scope, the command fails before writing configuration, acquisition lock, or materialization changes. Marketplace endpoint registration and locators remain single-resource operations and cannot be combined with other names.
Marketplace locators have one of these forms:
alias:registry/kind/name[@sha256:<64 lowercase hex>]
https://host/r/registry/kind/name[/revisions/sha256:<64 lowercase hex>]| Flag | Type | Required | Default | Description |
|---|---|---|---|---|
--scope | string | no | endpoint: user; resource: repo | Configuration layer: repo, user, or local. |
--kind | string | no | skill where a kind is needed | Selects skill, command, subagent, hook, or mcp, and disambiguates a named registry resource. |
--tag | string | no | none | Installs registry resources whose metadata contains the tag. Without --kind, at least one skill must carry the tag. Supports repo (default), user, and local scope. Cannot be combined with a resource name, --all, --from, or a Marketplace locator. |
--all | boolean | no | false | Installs every discovered registry resource, or only those of --kind when you give it. Supports repo (default), user, and local scope. |
--registry | string | no | all configured registries | Limits --all to one configured registry. Requires --all. Matches the URL the way update and lock do, so a .git suffix or a trailing slash makes no difference, and looks in every config layer. The same source declared in several layers counts as one. If the URL names entries with different refs or paths, the command refuses and lists them. |
--from | string | no | configured registries | Installs directly from an ad hoc Git URL, GitHub web URL, or GitLab web URL. Without a resource name, installs the whole registry. |
--ref | string | no | inferred or registry default | Selects a branch, tag, or commit for --from. Requires --from. |
--path | string | no | inferred or registry root | Selects a subdirectory for --from. Requires --from. |
--marketplace | alias or endpoint URL | no | locator prefix | Resolves a Marketplace resource locator against the selected endpoint. Valid only for one Marketplace resource. |
--as | safe local name | no | resource name | Installs the resource under a different local name while keeping its Marketplace coordinate. |
--accept-risk | boolean | no | false | Accepts security findings for the verified revision. |
--yes | boolean | no | false | Same as --accept-risk, for automation. |
-v, --verbose | boolean | no | false | Shows every collection member and the technical Marketplace preview: revisions, digests, acquisition details, and provenance (where the artifact came from). |
Bulk installs use the selected scope's configuration, acquisition lock, and output roots, just like named installs:
agent-marketplace install --tag security --scope user
agent-marketplace install --all --scope localUser scope cannot copy a repository-relative directory source into the user configuration; use an absolute directory path or a Git source instead.
--as, --accept-risk, and --yes work only with a single Marketplace resource. With --marketplace <url>, pass the full resource URL as the locator. In the current release, a short registry/kind/name locator combined with an endpoint URL fails with an invalid browser locator error, so the full URL or an alias is required. If you pass a GitHub or GitLab web URL that names a branch or tag as the resource name, the command stops and tells you to use --from instead.
Registering a Marketplace endpoint checks the endpoint's well-known identity and canonical URL, then prints Added Marketplace <url> to <config path>, or Marketplace <url> is already configured in <config path> when the same identity is already present in that scope or a broader one. In a v4 configuration, registering the endpoint adds a named marketplace source for it. Installing a resource from that endpoint adds an exact request to the source's resources group and records the verified revision in the lockfile of the same layer.
A Marketplace install resolves and verifies the exact artifact before it changes any config. The default output summarizes the source, security findings, capabilities, and up to ten collection members. --verbose shows all members, the digest, license, provenance, and acquisition mode. Rejected and revoked resources cannot be installed.
When the verified artifact has security findings and standard input is a terminal, the command prints the preview and asks Install despite these risks? [y/N]:. Accepting installs the exact prepared revision. Without a terminal, pass --accept-risk or --yes to accept the findings for that one invocation. Capabilities are shown, but on their own they never require consent.
A successful Marketplace install prints a short confirmation:
✓ Installed frontend-design
✓ Installed coderabbit-skills · 3 skillsInstalls from configured Git or directory registries say where the selection went: in this repo, user-wide, or locally. For example, Installed frontend-design in this repo or Installed collection web-development in this repo. The line lists only resources that the resulting configuration selects. A tag or bundle install keeps any existing exclusion and names the resources it left out, for example Not installed: review; the effective configuration does not select it (for example, an exclusion wins). Install by name to select explicitly. Installing a resource by name clears its exclusion. Missing prerequisites are reported as warnings; install does not install them for you.
For configured Git registries, discovery uses the exact locked inventory of every layer that already has a valid lock. A registry can bootstrap from its branch or tag only when its own configuration layer has no lock. A missing lock in one layer does not make content that appeared after another layer's lock installable.
remove
Removes an explicit selection, or records an exclusion when the resource was selected some other way (for example, by a collection or a registry default). It then syncs output. Required organization resources cannot be removed or excluded.
--from and --ref follow the same rule, so an explicit selection in the target config is dropped. If a selected collection also provides the resource, it stays installed through the collection until a second remove excludes it from the collection.
For hosted Marketplace pins, removing a direct resource clears its direct selection but keeps it if a collection still includes it. Removing a collection clears that collection and removes the members no longer kept by anything else. You can remove a resource installed with --as by either its local name or its canonical Marketplace name. A name that matches more than one direct pin is refused. If a direct pin and another selection share a resource kind and name, remove refuses and suggests --from <endpoint-url> for the pin. Removing a named resource from a configured Marketplace endpoint honors --kind and --scope (default repo) and refuses --ref and --path.
For optional organization Marketplace resources, remove <name> writes an exact exclusion in the user configuration, including when a collection provides the resource. An omitted scope defaults to user; --scope user also works with --from <endpoint-url>. Repo/local scope cannot exclude machine-wide organization resources. The organization collection stays selected and its other members stay installed. Removing the organization collection itself remains unsupported; exclude its optional members individually instead. Required organization content ignores these exclusions.
Named removals, collection-member exclusions, removals of bulk/tag-selected resources, and ad-hoc removals use the v4 editor and preserve unrelated selections and scopes. Included-fragment ownership and required-resource policy still apply. Hosted sources retain their supported explicit-selection and lock rules; unsupported hosted options still refuse. See configuration requirements and current limits.
Removal from a shared native hook aggregate requires ownership proof for an active entry that would no longer be selected. A teammate's committed hook, an identical handwritten entry, or missing or damaged ownership state can therefore cause hook.remove-unowned. The command refuses before changing configuration, acquisition locks or hook files and names the native file where the hook remains active. Review that file and deliberately remove the hook, or explicitly repair ownership before retrying. Matching commands do not authorize automatic deletion. An entry still selected by another hook does not block removing one contributor. File-based hook targets, such as OpenCode, retain their ordinary file-ownership and removal rules.
agent-marketplace remove <resource-name> [flags]
agent-marketplace remove --from <registry> [<resource-name>] [flags]| Flag | Type | Required | Default | Description |
|---|---|---|---|---|
--scope | string | no | inferred for a name; repo with --from | Configuration layer: repo, user, or local. Choosing a scope leaves selections in other scopes unchanged. |
--kind | string | no | inferred | Selects skill, command, subagent, hook, mcp, or collection when a name is ambiguous. |
--from | string | no | configured registries | Targets an ad hoc registry entry, or a configured Marketplace endpoint URL for a named resource. Without a resource name, removes or excludes the whole registry entry for the selected scope. |
--ref | string | no | none | Narrows the Git or directory entry selected by --from. Requires --from. |
--path | string | no | none | Narrows the Git or directory entry selected by --from. Requires --from. |
The output says what happened:
Removed frontend-design
Removed collection web-development
Excluded frontend-design (provided by web-development)
Removed registry entry https://github.com/example/resources.git
Excluded all resources from https://github.com/example/resources.git (local scope)When the command chose the user config on its own, it adds a line such as (excluded in /home/me/.agents/config.yaml — applies across all repos).
lock
Resolves remote Git requirements to exact commits and verified source manifests, and writes them to the lockfile owned by each config layer. With the default all scope it writes the user, repository, and personal-local locks. It writes the organization lock only when you select --scope organization.
agent-marketplace lock [resource ...] [flags]| Flag | Type | Required | Default | Description |
|---|---|---|---|---|
--scope | string | no | all | Lock scope: user, repo, local, all, or organization. With --check, all also checks the organization lock. |
--check | boolean | no | false | Reports whether the selected locks would change, without writing. A needed change returns exit status 1 with lock.change-required (or lock.version-upgrade-required for a v1 lock). |
--upgrade | boolean | no | false | Refreshes all or targeted Git resolutions to the current commit of their refs. |
--registry | string | conditionally | none | Targets one configured Git registry during --upgrade. |
--ref | string | no | none | Narrows --registry to a declared ref. |
--path | string | no | none | Narrows --registry to a locked source root. |
--kind | string | conditionally | none | Resource kind for named --registry upgrade targets. |
Resource names and the targeting flags (--registry, --ref, --path, --kind) require --upgrade. Names, --ref, --path, and --kind also require --registry, and names require --kind. Upgrading one resource upgrades its whole Git source, because the commit is the smallest unit the CLI fetches.
On success the command prints Locks: <n> changed.
lock --check reads the existing config, lock, and exact snapshot files. It does not recover pending transactions, contact remotes, or fill the cache. A fresh lock whose exact snapshot is missing from a cold cache reports lock.snapshot-unavailable. A stale or missing lock reports the needed change without fetching it. A writing run holds the shared exact-cache lease from before its first snapshot fetch or check until the config and lock are published, so gc cannot delete a new snapshot before the published lock references it.
When configuration and lock validation succeed, lock --check reports every selected writable scope with an unrecorded resource-free Marketplace endpoint registration in one run. Each lock.change-required diagnostic names its scope, lock path, and endpoints, in user, repository, then personal-local order. An explicit --scope limits these registration diagnostics to that scope; checks still acquire nothing and write nothing.
The lockfile paths are /etc/agent-marketplace/lock.yaml, ~/.agents/lock.yaml, .agents/lock.yaml, and .agents/lock.local.yaml. Commit the repository lock and keep the personal-local lock out of Git. Some organizations never deploy an organization lock, and the CLI supports that permanently. In that case online commands may fetch organization Git sources from their current ref, or resolve explicit Marketplace requests into a verified lock held only in memory, but they never create the organization lock. Offline Marketplace resolution needs a deployed lock. A present organization lock is exact: if it is malformed, untrusted, or mismatched, commands refuse to continue and change nothing. lock --scope organization is the one exception for a mismatch. It reconciles the lock, re-resolving only the Git entries whose source or ref changed while keeping the rest at their locked commits. Plain directory registries are read live and never appear in these locks.
sync
Resolves the selected resources from exact Git snapshots and brings native harness output in line with configuration. When the organization layer has no lock, its requirements are fetched from their current refs.
agent-marketplace sync [flags]| Flag | Type | Required | Default | Description |
|---|---|---|---|---|
--check | boolean | no | false | Computes lock and output drift without fixing either. Returns exit status 1 when anything is out of sync. |
--locked | boolean | no | false | Requires fresh lockfiles and forbids config or lock writes. |
--offline | boolean | no | false | Uses only trusted local Git and Marketplace caches and never contacts a remote endpoint; lock behavior is the same as --locked. Cached revocation data may be stale. |
--allow-revoked | exact Marketplace revision; repeatable | no | none | Allows one revoked pin for this run: marketplace/registry/kind/name@sha256:<64 lowercase hex>. Cannot be combined with --check. |
--no-backup | boolean | no | false | Skips the configured pre-sync backup of machine-scope harness directories. The mandatory safety backups of shared configuration files still happen. |
--strict | boolean | no | false | Fails on unresolved selections ("selected but not found", "found but failed to load") and on unmet prerequisites. |
--prune-stale | boolean | no | false | After catalogs load successfully, removes direct, non-required selections that no longer exist from configuration, then syncs again. Cannot be combined with --locked or --offline. |
-v, --verbose | boolean | no | false | Prints affected files per target and malformed-resource details instead of only the summary. |
A normal sync prints counts for installed, removed, malformed, and failed resources:
Installed 3 Removed 1 Malformed 0 Errors 0The counts are colored on a terminal; NO_COLOR, CLICOLOR=0, or TERM=dumb turns color off.
If ~/.agents/config.yaml does not exist, a plain sync creates it the way agent-marketplace init --harnesses factory,windsurf would: a v4 config with only apiVersion and harnesses: [factory, windsurf]. Creation first validates every required root/include tree and cannot bypass unsupported input. This step does not overwrite an existing user config; sync still validates it. --check, --locked, and --offline skip first-run creation.
With --check, an in-sync result prints no verdict and returns exit status 0. Drift prints a summary such as sync: 2 out of sync (1 missing, 1 orphaned), lists the planned changes, and returns exit status 1. Materialization and configuration errors also return exit status 1, including a dry-run materialization failure, which is printed as an error: line alongside the run's warnings. Warning-severity materialization diagnostics are printed as warning: lines and do not affect the exit status. --check writes nothing: not config, locks, transaction state, or harness output. It does not recover pending transactions or fetch a cold exact snapshot, and it reports lock.snapshot-unavailable when snapshot files it needs are missing.
If an earlier write was interrupted and left a dependency transaction pending, sync --locked, sync --offline, sync --check, lock --check, list, and status fail with dependency.recovery-required before reading configuration or registries. They leave config, locks, recovery records, and permissions unchanged. A plain sync or lock (without those flags) attempts recovery before continuing. The failed command can be retried after recovery succeeds; blocked recovery leaves it incomplete. A missing transaction-state directory needs no recovery, and these commands do not create it.
update
Moves the selected Git locks to the current commit of their refs and syncs enabled resources. Without targeting flags it updates all writable scopes.
agent-marketplace update [resource ...] [flags]| Flag | Type | Required | Default | Description |
|---|---|---|---|---|
--bump | boolean | no | false | Rewrites eligible refs in v4 sources: to newer matching tags before updating locks. A ref that an included config file declares is reported and left unchanged. A full commit ID is never rewritten. |
--scope | string | no | all | Update scope: user, repo, local, or all. organization is refused. |
--registry | string | no | none | Targets one configured Git registry. |
--ref | string | no | none | Narrows --registry to a declared ref. |
--path | string | no | none | Narrows --registry to a locked source root. |
--kind | string | conditionally | none | Resource kind for named registry targets. |
-v, --verbose | boolean | no | false | Lists individual organization-managed Marketplace pins. |
Resource names, --ref, --path, and --kind require --registry, and names require --kind.
The first line counts the configured registry entries, Git or local directory, whether or not their revision changed. With --bump, it also reports how many refs were rewritten and names any ref it left alone because an included config file declares it. The command checks writable Marketplace mirror pins for newer usable revisions. It does not check or rewrite organization-managed pins. By default the output counts those pins on one line, and --verbose lists each one. Other skipped pins still show their reason. Marketplace values are printed quoted:
Configured registry entries: 2, refs bumped: 1
Marketplace pins updated: 1
Organization-managed Marketplace pins: 15 (not checked for newer revisions; pins unchanged)
Use `agent-marketplace update --verbose` to list organization-managed pins.
Marketplace "https://marketplace.example.com" "source"/"skill"/"review": updated "sha256:..." -> "sha256:..."status
Reports the effective configuration, selected resources, target harnesses, output roots, registry refs, cache freshness, source layers, drift, exclusions, collisions, unmet requirements, and errors. It only reads; it never changes output.
agent-marketplace statusThe report prints these sections in this order. Sections other than TARGET HARNESS SET, SYNCED RESOURCES, and DRIFT appear only when they have content.
| Section | Contents |
|---|---|
MANAGED INSTALLATION | Present when an organization config manages the installation: its path and validation result. |
TARGET HARNESS SET | Effective harness list and the configuration layer that supplied it. When resources selected by the user or organization use a different list than the repository's, a second row shows that list and its layer. |
EXACT REGISTRY LOCKS | Source layer, canonical Git origin, declared ref, exact commit, and whether the cached snapshot is available or missing. |
SYNCED RESOURCES | Resource kind, name, harness, source, collection origin (VIA), target path, registry, ref, and cache state. |
MARKETPLACE PINS | Endpoint identity, registry, resource coordinate, installed name, exact revision and digest, acquisition mode, source layer, revocation and current state, cache state, and update availability. |
HARNESS TARGETS | Target capabilities and resolved repository and machine roots. |
LOCAL REGISTRIES | Registry entries declared in repository-personal configuration. |
ORPHANED FILES | Generated files that a sync would remove. |
NAME COLLISIONS | Registry overlap and resource-name collision diagnostics. |
UNMET REQUIREMENTS | Advisory resource prerequisites and install hints. |
WARNINGS | Configuration, resolution, and materialization warnings, with a remediation hint where one exists. |
DRIFT | In sync, the number of files to write and remove, Unknown (exact registry view incomplete), or Unknown (Marketplace cache evidence missing; run 'agent-marketplace sync') when a selected Marketplace pin lacks verified local cache evidence. |
ERRORS | Configuration, catalog, materialization, or drift-inspection failures. |
Fatal resolution and error-severity materialization diagnostics return exit status 1 after the report is printed; warning-severity diagnostics do not affect the exit status.
Configuration authoring
The CLI reads v4 roots and uses their sources and resources model for discovery, status, sync, and output. A root must declare apiVersion: agent-marketplace/v4. Included fragments may omit apiVersion and inherit v4 from the root.
Each source declares its kind:
gitsources requirerefand use the owning layer's exact Git lock.directorysources are read live and never get a Git lock. Relative paths in the repository.agents/config.yamland.agents/config.local.yamlroots are resolved from the repository root. User and organization configs and included fragments resolve them from the directory of the file that declares them.marketplacesources require a matching verified layer lock for explicit requests.
The configuration reference documents writing source declarations and resource groups by hand. Named Git and directory selections and harness changes use the v4 CLI and TUI editors. The CLI rejects unknown fields, mixed source kinds, invalid locators, and Marketplace lock evidence that does not match. Writable-layer locks can be generated online for explicit hosted requests. When the organization lock is intentionally absent, the CLI fetches and verifies organization Marketplace requests online without writing an organization lock. Offline acquisition without a lock, hosted rebind, and dynamic-selector snapshots remain unsupported; v4-only loading does not enable new hosted options.
doctor
Reports repository detection, configuration diagnostics, harness capabilities and roots, Devin CLI compatibility, and unmet resource requirements.
agent-marketplace doctor [flags]| Flag | Type | Required | Default | Description |
|---|---|---|---|---|
--repair | boolean | no | false | Previews recovery actions for the ownership state of Devin and Codex shared configuration files and, on a terminal, asks you to confirm each one. |
--yes | boolean | no | false | With --repair, adopts entries that exactly match the desired value without prompting. It never removes or replaces an entry. |
doctor detects a locally installed Devin CLI and reports whether it meets the 3000.3 compatibility floor. It recommends selecting the devin harness when a Devin CLI is installed but no harness list contains it. sync never needs a Devin binary, so none of these findings blocks it.
--repair covers hooks.v1.json, config.json#hooks, mcp_config.json, .codex/hooks.json, and .codex/config.toml. It sorts candidates into three groups: exact matches it can adopt, orphans it has evidence for (entries a completed sync wrote that are no longer wanted), and unmanaged entries whose key matches a selected resource but whose value differs. It lists every file it inspected, including files with nothing to repair, and it never edits harness lists. Without a terminal, it only previews, unless --yes can do byte-identical adoption. Removing an orphan or replacing a conflicting entry always needs a per-entry confirmation on a terminal, and the command takes a fresh backup first. --yes without --repair is an error.
Compatibility findings do not block sync. Repair failures, corrupt ownership state, and unparseable shared files return exit status 1.
backup
Manages backups of machine-scope harness output. Backups live in ~/.agent-marketplace/backups/.
agent-marketplace backup <command>backup create
Creates an on-demand backup of the machine paths Agent Marketplace currently manages, then applies the configured backup rotation.
agent-marketplace backup createOn success it prints Backup created for: <targets>. When backups are disabled in config, it prints Backup is disabled in config; skipping. and exits successfully. When no machine paths are managed, it prints No managed paths to back up. If configuration cannot be resolved, it prints each error and exits with status 1.
backup list
Prints Backups directory: <path>, then the backup timestamps grouped by harness target. With no backups, it prints No backups found.
agent-marketplace backup listbackup restore
Copies the latest backup over the selected machine harness root. Files that are not in the backup stay in place.
agent-marketplace backup restore --target <harness>| Flag | Type | Required | Default | Description |
|---|---|---|---|---|
-t, --target | string | yes | none | Harness target: claude, codex, cursor, devin, factory, gemini, or windsurf. |
On success it prints Overlay-restored <target> from backup <timestamp>. The command refuses a target root that is not a directory or is a symbolic link, and creates the root when it does not exist.
gc
Removes cache entries that are no longer reachable from the validated configuration and active locks in the current context: the organization, user, current repository, and personal-local layers, including their includes. This covers mutable and exact Git cache entries and unreferenced hosted Marketplace artifacts.
What gc keeps:
- Exact Git snapshots referenced by a locked source and commit.
- Git object stores whose canonical source URL appears in a lock or in configuration, including organization sources with no organization lock.
- Marketplace blobs, manifests, revision metadata, and index-only occurrence snapshots referenced by exact configured pins.
- Protected derived-cache namespaces and persistent coordination locks.
It removes unreferenced object stores and abandoned staging directories.
The cache is shared by all your repositories, but gc only looks at the current one. Running it in repository A can delete a source that only repository B uses. B then has to fetch it again, which fails offline or when the remote no longer has the locked commit. --dry-run reports what would be deleted without deleting it.
gc first finishes any pending dependency-transaction recovery, holding the shared exact-cache lease while it publishes the recovered config and lock state. It then takes the exclusive exact-cache lease and reloads every applicable configuration layer and lock before deciding what is reachable. Missing required locks, malformed configuration or locks, and untrusted locks block deletion. A present organization lock must also match its configuration.
agent-marketplace gc [flags]| Flag | Type | Required | Default | Description |
|---|---|---|---|---|
--dry-run | boolean | no | false | Lists cache entries that would be removed without deleting them. |
The command prints one line per removed entry, followed by two totals:
Removed 2 cache entries
Removed 1 marketplace artifact directoriesWith --dry-run, each line starts with Would remove instead.
serve
Runs a hosted Marketplace from a separate Marketplace operator configuration.
agent-marketplace serve --config <path> [--role api|worker|all]| Flag | Type | Required | Default | Description |
|---|---|---|---|---|
--config | path | yes | none | Marketplace operator YAML file. |
--role | string | no | all | api runs the public and operations listeners, worker runs background indexing, and all runs both. |
At startup the command opens the configured stores, makes sure the Marketplace instance exists, and applies configured revocations before either role reports ready. It runs until it is cancelled or a role fails.
serve reindex
Queues and processes refresh work outside the scheduler.
agent-marketplace serve reindex [registry-slug-or-id] --config <path>| Flag | Type | Required | Default | Description |
|---|---|---|---|---|
--config | path | yes | none | Marketplace operator YAML file. |
With no registry argument, the command reindexes every configured registry. With one slug or ID, it reindexes only that registry. It applies revocations before fetching and checks store readiness after processing.
serve reset
Resets one registry's generated catalog during a maintenance window. It accepts exactly one registry slug or ID; there is no all-registry default.
agent-marketplace serve reset <registry-slug-or-id> --config <path> --dry-run
agent-marketplace serve reset <registry-slug-or-id> --config <path> --confirm-maintenance| Flag | Type | Required | Default | Description |
|---|---|---|---|---|
--config | path | yes | none | Marketplace operator YAML file. |
--dry-run | boolean | no | false | Reports affected row counts without resetting catalog data. Takes precedence over --confirm-maintenance. |
--confirm-maintenance | boolean | for reset | false | Confirms all API/workers are stopped, metadata is backed up, and controllable shared caches are invalidated. |
Reset deletes the selected registry's resource revisions, assessments, collections, occurrence and publication history, current catalog pointers, and blob-ownership references in one metadata transaction. Its refresh status becomes unknown. Registry settings, managed configuration and administrative history, policies, revocations, other registries, and all blob bytes remain intact. Shared blobs are not deleted. Database-managed mode resolves the selector from managed configuration rather than stale operator YAML.
The command refuses a destructive reset while any job holds a live lease, but cannot verify external process shutdown or cache invalidation. The registry is unavailable until a subsequent serve reindex <registry-slug-or-id> --config <path> succeeds; reindexing is not automatic. References from other registries may be unavailable until rebuilding completes, and historical revisions absent from the current source are not recovered by reindexing. Existing locks and cached revision metadata may need refreshing. Reset does not make older clients compatible with newer artifact contents.
Both modes open the configured stores, including normal schema initialization. Output begins with Would reset catalog or Reset catalog, followed by per-table row counts. The command returns nonzero on invalid arguments, missing confirmation, an unknown registry, live job leases, or a storage failure; a failed metadata transaction rolls back the reset.
serve adopt
Adopts catalog settings during a controlled maintenance window and records the database as the configuration authority.
agent-marketplace serve adopt --config <path> --actor <id> --reason <text> --idempotency-key <key> --confirm-maintenance| Flag | Type | Required | Default | Description |
|---|---|---|---|---|
--actor | string | yes | none | Operator identity recorded in the maintenance audit. |
--config | path | yes | none | Path to the Marketplace operator config file. |
--confirm-maintenance | boolean | yes | false | Confirms all API and worker processes are stopped, backups exist, and shared caches are invalidated. The command refuses to run without it. |
--idempotency-key | string | yes | none | Stable key reused when retrying this adoption. |
--reason | string | yes | none | Reason recorded in the adoption audit. |
Adoption requires a controlled maintenance window: every API and worker process stopped, the database and blob storage backed up, and controllable shared caches invalidated. The command does not verify external process shutdown or cache invalidation. The configuration file must set management.mode: database. On success it prints Adopted marketplace configuration at revision <n>. Database authority is durable; runtime safety checks still apply.
deinit
Removes the files Agent Marketplace manages for one scope. User scope also removes orphaned registry caches, but keeps the machine output that organization requirements still resolve to. A present organization lock is read exactly, and an invalid lock stops the teardown. When the organization lock is absent, a normal deinit may fetch the organization registry to keep its output and cache. --dry-run never fetches, so an uncached, unlocked organization registry produces a warning. Configuration files stay unless you pass --purge-config.
agent-marketplace deinit [flags]| Flag | Type | Required | Default | Description |
|---|---|---|---|---|
--scope | string | no | user | Teardown scope: user, repo, or local. repo and local both remove repository-scoped output. |
--purge-config | boolean | no | false | Also deletes the scope's configuration file and the lockfile it owns, including an orphaned lock. Other layers and included fragments stay. Transaction coordination files and unrelated recovery records stay. A pending transaction that touches these files blocks the purge until it is recovered. |
--dry-run | boolean | no | false | Reports the output, caches, configuration files, and lockfiles that would be removed, without deleting them. |
The output reports Removed <n> managed artifact(s) (or Would remove ... with --dry-run), or No managed artifacts to remove, followed by each removed cache and purged file.
Unreadable configuration does not stop the teardown. The command prints a warning, assumes the default materialization mode, and notes that output created in another mode may remain.
telemetry
Reads and changes your telemetry preference and local telemetry state. When an organization config sets a telemetry level, that level applies instead of your preference, and the organization can also lock the endpoint. See the telemetry reference.
agent-marketplace telemetry <command>telemetry status
Prints the effective level and its source, the endpoint hostname, header references, retention policy, community-reporting state, whether the installation is managed, the installation ID, queue statistics, the number of retained diagnostic payloads, the last delivery failure, and any fields locked by the organization.
agent-marketplace telemetry statusHeader values are never printed.
telemetry enable
Sets your telemetry level, and optionally a user-managed OTLP/HTTP endpoint. The user config must already exist; otherwise the command tells you to run agent-marketplace init first.
agent-marketplace telemetry enable --level <level> [--endpoint <url>]| Flag | Type | Required | Default | Description |
|---|---|---|---|---|
--level | string | yes | none | basic or detailed. off is rejected; use telemetry disable instead. |
--endpoint | URL string | no | existing effective endpoint | Stores a user endpoint. Refused when organization policy sets the endpoint. |
A level lower than the organization's level is rejected. On success the command prints Telemetry enabled at "<level>".
telemetry disable
Sets your telemetry preference to off and prints Telemetry disabled for user preference.
agent-marketplace telemetry disableIf organization policy keeps telemetry on, the command also prints Organization policy keeps telemetry active at "<level>".
telemetry preview
Writes a representative payload to a local file without sending it.
agent-marketplace telemetry preview --level <level>| Flag | Type | Required | Default | Description |
|---|---|---|---|---|
--level | string | yes | none | Preview level: basic, detailed, or diagnostic. |
A diagnostic preview asks for confirmation on a terminal. Without a terminal, it requires the global --diagnostic-accept-sensitive-data flag. The output prints Preview payload written to <path> with the level, endpoint host, retention policy, and header references.
telemetry purge
Removes queued telemetry records and retained diagnostic payloads, then prints how many of each it removed. It does not reset the installation ID or change telemetry preferences.
agent-marketplace telemetry purgetelemetry reset-id
Replaces the installation ID and purges pending telemetry tied to the old ID. The output prints Installation ID reset. New ID: <id>.
agent-marketplace telemetry reset-idtui
Starts the interactive terminal UI for browsing Git registries and hosted Marketplaces, editing selections, choosing harnesses, and syncing. See the terminal UI reference for keys and screens.
agent-marketplace tuiThe command finds the repository root from the current directory and uses your home directory for machine-scope configuration and output. It shows configured resources before any network discovery, loads up to 50 results from each Marketplace, and starts a Marketplace search 250 milliseconds after you stop typing. Discovery results stay fresh for five minutes and can be shown as stale results for up to 24 hours when an endpoint fails.
Marketplace installation verifies the exact revision before saving it. Security findings show the verified preview and require confirmation; capability metadata alone does not. Blocked and revoked resources stay visible but cannot be installed.
completion
Generates shell completion scripts with Cobra's built-in completion commands.
agent-marketplace completion bash [--no-descriptions]
agent-marketplace completion zsh [--no-descriptions]
agent-marketplace completion fish [--no-descriptions]
agent-marketplace completion powershell [--no-descriptions]| Flag | Type | Required | Default | Description |
|---|---|---|---|---|
--no-descriptions | boolean | no | false | Leaves command and flag descriptions out of the generated completions. |
The script is written to standard output.
Exit statuses
| Status | Condition |
|---|---|
0 | The command succeeded. Warnings, such as a missing target set for list, unmet advisory prerequisites, or non-blocking compatibility findings, do not change this status. |
1 | Argument validation, configuration loading, registry access, resolution, conversion, materialization, repair, backup, or filesystem work returned an error. |
1 | sync --check found drift, or lock --check found a lock that would change. |
1 | sync --strict found a selected resource that was missing or malformed, or an unmet prerequisite. |
The CLI defines no other numeric statuses. Argument and runtime errors are printed to standard error, each followed by at least one hint: line naming the suggested next step; see What to do in the diagnostics reference. Reports and normal results are printed to standard output.