For AI agents: the complete documentation index is available at https://scriptedalchemy.github.io/agent-bundle/llms.txt, the full documentation bundle is available at https://scriptedalchemy.github.io/agent-bundle/llms-full.txt, and this page is available as Markdown at https://scriptedalchemy.github.io/agent-bundle/reference/cli.md.
agent-bundle
  • English

      • CLI 

      npx agent-bundle --help
npx agent-bundle --version

      Commands

      CommandPurpose
      agent-bundle devServe the packaged development workbench on loopback.
      agent-bundle dev proxyBridge host stdio MCP traffic to a running development server.
      agent-bundle buildBuild a validated Agent Bundle artifact.
      agent-bundle prepackBuild and validate the npm pack inventory.
      agent-bundle install <host>Install a built bundle into a supported host.
      agent-bundle doctorInspect host installs and runtime endpoints without changing them.
      agent-bundle validateValidate project source or one artifact.
      agent-bundle evalRun deterministic or native eval suites against a built artifact.
      agent-bundle eval compareCompare two persisted eval runs.
      agent-bundle inspectInspect normalized targets and adapter plans.
      agent-bundle mcp list / invoke / runOperate an MCP server from an artifact.
      agent-bundle hooks list / simulateInspect and simulate generated hooks.

      Shared option groups

      Source commands — build, prepack, validate, eval:

      OptionDefaultMeaning
      --root <root>process.cwd()Project root.
      --config <path>—Configuration file relative to --root.
      --mode <mode>productionConfiguration mode.
      --target <target>all configuredTarget to select. Repeatable.
      --jsonoffWrite one machine-readable JSON document.

      Artifact commands — mcp list, mcp invoke, mcp run, hooks list, hooks simulate: the same --root, --config, --mode, and --json, plus --artifact <path> to use exactly one built artifact and --target <target> to select the artifact target. --target is required for mcp list, mcp invoke, mcp run, and hooks simulate.

      dev

      OptionDefaultMeaning
      --root <root>process.cwd()Project root.
      --port <port>ephemeralLoopback TCP port.
      --agent-api / --no-agent-apiconfig dev.agentApiEnable or disable the authenticated Agent API on /mcp.
      --install-host <host>noneInstall and re-sync a development host. Repeatable; claude, codex, or cursor.
      --open / --no-open--no-openOpen the workbench after the foreground server starts.

      dev runs in the foreground and closes the session on a termination signal. See Developer Workbench.

      dev proxy

      OptionDefaultMeaning
      --server <server>requiredGenerated MCP server name.
      --target <target>portableGenerated target containing the MCP server.
      --url <url>discoveredExplicit loopback development server origin.

      The proxy inherits --root from the parent dev command and writes diagnostics to stderr.

      build and prepack

      Both take the source option group plus:

      OptionDefaultMeaning
      --output <path>config output.distPath, else artifactArtifact output path relative to --root. dist belongs to the package build.

      Both build package outputs when the project declares bin or lib.

      install

      agent-bundle install <host> [--from <bundle-dir>] [--scope <scope>] [--mode <mode>] [--replace] [--json]
      OptionDefaultMeaning
      <host>requiredclaude, codex, or cursor.
      --from <bundle-dir>process.cwd()Target bundle directory or artifact root.
      --scope <scope>useruser, project, or local. Claude accepts all three; Codex and Cursor are user-scoped.
      --mode <mode>localCursor only. local copies the bundle into ~/.cursor/plugins/local/<name>; marketplace stages a committed local marketplace repository under ~/.cursor/agent-bundle/marketplaces/<name> and prints the Customize → Plugins → "Add Plugins from Local Repository" step that makes Cursor manage the plugin as a marketplace install.
      --replace (alias --force)offReplace an existing agent-bundle install of this plugin even when its version differs. Without it, an identical copy is an already-installed no-op, a same-version copy whose content hash differs is replaced automatically, and a different version is AB7005. Foreign directories are always refused (AB7005).

      The emitted standalone install.mjs and the package-relative installer bin accept the same --replace. Cursor copies carry an install receipt (.agent-bundle-install.json), replacement touches owned files only, and --replace adopts a pre-receipt copy; Claude replacement runs claude plugin uninstall --keep-data before reinstalling and Codex runs codex plugin remove before add.

      doctor

      OptionDefaultMeaning
      --host <host>all supportedHost to inspect. Repeatable; claude, codex, or cursor.
      --from <bundle-dir>—Target bundle directory or artifact root to compare against.
      --jsonoffWrite one machine-readable JSON document.

      Doctor exits 1 when it reports any error diagnostic, and never modifies anything. With --from, it reports the installed copy per host as current, stale (same version, different content — AB7308), version-mismatch (AB7309), foreign (AB7321), or not-installed (AB7307). For Cursor it also proves plugin-scoped hook registration from the installed manifest (AB7322), warns when ~/.cursor/hooks.json would deliver a plugin hook a second time (AB7323), and tracks a staged marketplace from unregistered to registered once Cursor imports it (AB7324).

      validate

      OptionDefaultMeaning
      --artifact <path>—Validate exactly this built artifact instead of project source.
      --host-validation / --no-host-validationonRun installed host developer tools for compatible built targets.
      --strictoffPromote host-tool warnings to errors.

      eval

      OptionDefaultMeaning
      --artifact <path>built from sourceEvaluate exactly this built artifact.
      --case <case>allEval case id to run. Repeatable.
      --suite <suite>allEval suite name to run. Repeatable.
      --harness <harness>deterministicdeterministic, claude, or codex.
      --trials <count>suite-declaredRun this many trials of every selected case. A positive integer, at most 100.

      eval compare <baseline> <candidate> takes two persisted run ids and inherits the source options from eval.

      inspect

      inspect takes --root, --config, --mode, --json, and a single --target <target> filter (not repeatable), plus at most one focus flag:

      FlagFocus
      --bundlerThe synthesized bundler configuration.
      --hooksHooks.
      --routesThe compiled route graph.
      --skillsSkills.
      --stateState lifetimes.

      Passing more than one focus is an error. inspect exits 1 when the normalized model is invalid.

      Every inspection plan reports each component with its canonical kind — agent, cli, command, event-route, hook, lsp, mcp-app, mcp-server, native-diagnostics, native-extension, rule, script, skill (AgentComponentKind from agent-bundle/api) — as selected or skipped with its cause, plus a kinds matrix: one entry per kind with the target's own four-state capability judgment and selected/omitted counts. The human output prints one line per target, each omission and its reason, then kinds this host cannot emit:. Filesystem src/events routes report as event-route, judged by the host's event:<canonical event> row, not as hook.

      mcp

      mcp list requires --server <server>. mcp invoke requires --server and --tool <tool>, and takes exactly one of --input <json> or --input-file <path>; the parsed value must be a JSON object, not an array or scalar.

      mcp run requires --server and runs one stdio server in the foreground with inherited stdio:

      OptionDefaultMeaning
      --env-file <path>conventional setLoad exactly this .env file, replacing the project-root set. Repeatable.
      --no-envoffLaunch without loading any .env files. Mutually exclusive with --env-file.
      --plugin-root <path>project rootExpand env plugin-root anchors against this root.

      Because the server owns the JSON-RPC channel for the whole foreground run, mcp run writes nothing of its own to stdout. See Runtime environment for the .env precedence rules and what the plugin-root anchor changes.

      hooks

      hooks list reports the hooks in an artifact. hooks simulate requires --hook <hook> (an id or a name) and the same --input / --input-file pair as mcp invoke.

      Exit codes

      CodeMeaning
      0Success, including --help and --version.
      1A reported failure: an error diagnostic, an invalid model from inspect, a failing or inconclusive eval run, or an uncaught error written to stderr as one AB5000 diagnostic.
      2An argument-parsing failure from the command-line parser.

      An eval run exits 1 when any trial fails or is inconclusive — an inconclusive trial produced no evidence, so it cannot report success either.