CLI reference

The agent-plugins command reads installed plugin instructions, previews package file selection, attaches Agent Plugins to wheels, and locates plugins visible in the current Python environment.

agent-plugins
agent-plugins {read,plan,attach-wheel,locate,list} ...

python -m agent_plugins runs the same entry point.

With no arguments, agent-plugins reads the plugin installed with its own distribution. These commands produce the same stdout:

uvx agent-plugins
uvx agent-plugins read agent-plugins

agent-plugins read

agent-plugins read DISTRIBUTION [--skill NAME]

DISTRIBUTION is an installed Python distribution name. Human output is a Markdown briefing containing:

• Python distribution and plugin manifest metadata, interpreter path, and declared Documentation and Documentation Index URLs
• the bounded selected plugin file tree and installed root
• client extension names and manifest validation issues
• MCP server names and transport types, with configured commands, arguments, environment values, URLs, and headers excluded
• the complete SKILL.md source for every packaged Agent Skill by default

The generated introduction explains environment ownership and relative resource paths, including the disposable tool environment used by uvx. Skill source remains complete. The inventory uses the standard tree bounds of four levels and 100 files, and reports omitted depth or file counts. Inspect the printed installed root when a skill routes to a resource outside that view.

--skill NAME prints one structurally named skill while retaining the package metadata, bounded inventory, extension names, and MCP summary. An unavailable name reports the sorted available skills on stderr.

Use uv to read a package without adding it to the current project:

uvx --with my-package agent-plugins read my-package

The package requirement after --with and the final distribution argument are separate inputs. uv installs the requirement into the temporary command environment. read selects that installed distribution through Python metadata.

To inspect an existing project or notebook installation, run python -m agent_plugins read my-package with that environment's interpreter. Its paths and package version may differ from the isolated tool environment. Use ap.read() inside a Python execution host. The Python API defaults to the same-name skill, while the CLI defaults to all skills.

agent-plugins plan

agent-plugins plan [PROJECT] [--json]

PROJECT is the Python project directory containing pyproject.toml. It defaults to the current directory.

Human output is tab-delimited:

root    /absolute/plugin/root
plugin.json    /absolute/plugin/root/plugin.json
skills/example/SKILL.md    /absolute/plugin/root/skills/example/SKILL.md

--json writes one object:

{
  "project": "/absolute/python/project",
  "root": "/absolute/plugin/root",
  "files": [
    {
      "source": "/absolute/plugin/root/plugin.json",
      "target": "plugin.json"
    }
  ]
}

project, root, and source are absolute native path strings. target is a plugin-root-relative POSIX path.

plan checks configuration and selected files. It does not parse plugin.json, mcp.json, or SKILL.md.

agent-plugins attach-wheel

agent-plugins attach-wheel WHEEL [--project PROJECT] [--output-dir DIRECTORY] [--json]

WHEEL identifies one existing .whl file. --project identifies the directory containing [tool.agent-plugins] and defaults to the current directory.

Without --output-dir, the command atomically rewrites the input after the complete attached artifact succeeds. With --output-dir, it preserves the input and writes the same wheel filename into an existing directory. The command refuses to replace an existing destination.

Human success output is the absolute attached wheel path and a newline:

/absolute/dist/example-1.0.0-py3-none-any.whl

--json writes one object:

{
  "source": "/absolute/dist/example-1.0.0-py3-none-any.whl",
  "output": "/absolute/dist/example-1.0.0-py3-none-any.whl",
  "dist_info": "example-1.0.0.dist-info",
  "plugin_root": "example-1.0.0.agent-plugin",
  "files": [
    "plugin.json",
    "skills/example/SKILL.md"
  ],
  "replaced_existing_plugin": false,
  "removed_signatures": []
}

source and output are absolute native path strings. dist_info, plugin_root, files, and removed_signatures use POSIX archive paths. files remain relative to the plugin root and follow build-plan order.

Attachment replaces the owned marker and payload on a rerun. If the input contains RECORD.jws or RECORD.p7s, the command removes the invalidated signatures, includes their paths in removed_signatures, and writes one warning per path to stderr. JSON stdout remains parseable.

Expected project, plugin, wheel, ZIP, and filesystem failures produce status 1 through the standard AgentPluginError diagnostic. The input wheel remains byte-identical when planning, validation, source reads, ZIP writing, or replacement fails.

agent-plugins locate

agent-plugins locate DISTRIBUTION

DISTRIBUTION is an installed Python distribution name. Success writes the absolute plugin root and a newline to stdout.

agent-plugins list

agent-plugins list [--json]

Human output contains one distribution line followed by its skill instruction paths:

my-project    /absolute/my_project-1.0.0.agent-plugin
    skill    /absolute/my_project-1.0.0.agent-plugin/skills/example/SKILL.md

The command uses tabs for indentation and columns. An environment with no marked distributions prints no human output.

--json writes an array sorted by distribution name without regard to case:

[
  {
    "distribution": "my-project",
    "root": "/absolute/my_project-1.0.0.agent-plugin",
    "skills": [
      "/absolute/my_project-1.0.0.agent-plugin/skills/example/SKILL.md"
    ]
  }
]

The skills field contains absolute SKILL.md paths. An empty result is [].

list follows Python metadata discovery precedence for equivalent distribution names, matching locate. It is fail-fast. A selected marked distribution with unusable metadata or files stops the complete scan.

Output and exit statuses

Status	Meaning	Streams
0	Command completed	Data on stdout
1	AgentPluginError from configuration, packaging metadata, or filesystem state	agent-plugins: error: ... on stderr
2	Argument parsing failure	Usage and diagnostic on stderr

Unexpected Python exceptions follow normal interpreter traceback behavior.