CLI Reference

Pluxx has two command families:

deterministic project commands
agent-invoking refinement commands

That split is intentional. Pluxx owns import, validation, packaging, installation, migration, and deterministic MCP replay. Host agents are optional and only participate in semantic refinement.

Deterministic project commands

These commands do not invoke Claude Code, Cursor, Codex, or OpenCode.

`pluxx --version`

Print the installed CLI version.

pluxx --version

`pluxx upgrade [--version ...]`

Upgrade the global npm install used by pluxx on your PATH.

pluxx upgrade
pluxx upgrade --version x.y.z

Repo-local node ../../bin/pluxx.js ... and npx @orchid-labs/pluxx ... are separate entrypoints.

`pluxx init --from-mcp ...`

Scaffold a Pluxx source project from a live MCP server or local stdio command.

npx @orchid-labs/pluxx init --from-mcp https://example.com/mcp

For local stdio imports, pass the real executable command. Do not assume the npm package name is also the runnable bin name. Examples:

installed locally: npx @orchid-labs/pluxx init --from-mcp "./node_modules/.bin/acme-mcp" --yes
one-shot via npm: npx @orchid-labs/pluxx init --from-mcp "npx -y -p @acme/mcp acme-mcp" --yes

init --from-mcp also accepts the same sourced-context flags when you want the first scaffold to start from better product truth:

npx @orchid-labs/pluxx init --from-mcp https://example.com/mcp \
  --website https://example.com \
  --docs https://docs.example.com/mcp \
  --ingest-provider auto

When sourced context is provided, init now writes the same provenance artifacts used by Agent Mode:

.pluxx/sources.json
.pluxx/docs-context.json

If you already know every tool from that MCP should be preapproved in the generated source project:

npx @orchid-labs/pluxx init --from-mcp https://example.com/mcp --approve-mcp-tools

That flag writes canonical permission intent into pluxx.config.ts:

permissions.allow = ["MCP(<server>.*)"]

`pluxx discover-mcp`

List MCP servers already configured in supported local host configs.

npx @orchid-labs/pluxx discover-mcp
npx @orchid-labs/pluxx discover-mcp --host codex opencode --json

Discovery covers Claude Code, Cursor, Codex, and OpenCode. Use it when a working MCP already exists in a host and you want to turn that setup into a maintained Pluxx source project.

`pluxx init --from-installed-mcp <host:name>`

Scaffold from one discovered installed MCP server.

npx @orchid-labs/pluxx init --from-installed-mcp codex:acme --yes

The import preserves source shape and env references without copying literal secret values from host config.

`pluxx sync [--from-mcp ...]`

Refresh an existing Pluxx source project from its MCP source while preserving managed boundaries.

npx @orchid-labs/pluxx sync

`pluxx doctor`

Inspect the source project and report config, scaffold, runtime, and packaging issues.

npx @orchid-labs/pluxx doctor

`pluxx doctor --consumer <bundle>`

Inspect a built or installed bundle from the end-user side. User story:

The installed plugin looks wrong on my machine. I want to inspect the shipped bundle itself, not the source repo.

npx @orchid-labs/pluxx doctor --consumer dist/claude-code

`pluxx lint`

Validate the source project against Pluxx and platform rules.

npx @orchid-labs/pluxx lint

`pluxx eval`

Evaluate scaffold and prompt-pack quality before publish. User story:

The project builds, but I want to know whether the generated taxonomy, instructions, and prompt packs are coherent enough to ship.

npx @orchid-labs/pluxx eval

`pluxx build`

Generate platform bundles under dist/.

npx @orchid-labs/pluxx build

Build and install in one step:

npx @orchid-labs/pluxx build --install

If local hook commands are present:

npx @orchid-labs/pluxx build --install --trust

`pluxx test`

Run the default verification contract against the source project and built outputs.

npx @orchid-labs/pluxx test

Test and install in one step:

npx @orchid-labs/pluxx test --install

pluxx test --install now verifies the installed consumer bundle state after install, not just the generated dist/ output. If a host still looks wrong after install, follow it with:

npx @orchid-labs/pluxx doctor --consumer <installed-path>

Use --behavioral with --install --trust when the project includes an installed-host example-query smoke set:

npx @orchid-labs/pluxx test --install --trust --behavioral

`pluxx install --target ...`

Install built bundles into local host tooling for testing.

npx @orchid-labs/pluxx install --target claude-code,codex

Preview the install plan as JSON:

npx @orchid-labs/pluxx install --dry-run --json

Dry-run JSON includes hostDetection for Claude Code, Cursor, Codex, and OpenCode plus targetSelection. Detection is read-only and informational: explicit --target values remain authoritative, project config alone does not count as an installed host signal, and Pluxx never mutates host config just because a host was detected. If the plugin contains local hooks, pass --trust after reviewing them:

npx @orchid-labs/pluxx install --target codex --trust

`pluxx verify-install --target ...`

Inspect installed host-visible plugin state.

npx @orchid-labs/pluxx verify-install --target codex

verify-install checks installed paths, stale cache/version problems, consumer-side bundle shape, and installed stdio MCP runtime launch behavior.

`pluxx migrate <path>`

Import an existing host-native plugin into a Pluxx source project. User story:

We already have one plugin. We want to move into Pluxx without rewriting everything by hand.

npx @orchid-labs/pluxx migrate ./existing-plugin

`pluxx mcp proxy --from-mcp ... [--record ...]`

Run a local stdio proxy in front of a live MCP. With --record, save a deterministic schema-v2 tape. Pluxx recursively redacts common sensitive keys, URL userinfo and sensitive query values, source-command credentials, and recognized authorization values before writing the file. Raw recording is not supported. Privacy warning: redaction is a credential-safety boundary, not a general content classifier. Tool results can contain private documents or customer data under ordinary field names. Review every tape before committing, uploading, or sharing it.

npx @orchid-labs/pluxx mcp proxy \
  --from-mcp https://example.com/mcp \
  --record tape.json

`pluxx mcp proxy --replay <tape.json>`

Replay a recorded MCP session without hitting the live server again. Replay accepts existing schema-v1 tapes and current schema-v2 tapes, validates their structure strictly, preserves the expected interaction after a mismatch, and fails when the input ends with unused interactions. Unsupported schema versions return an explicit migration error. User story:

I need the same MCP behavior in CI, local debugging, or a demo without depending on the live service.

npx @orchid-labs/pluxx mcp proxy --replay tape.json

Agent-invoking commands

These commands prepare or invoke a host coding agent.

`pluxx agent prepare`

Generate the context pack and file boundaries for a host coding agent.

npx @orchid-labs/pluxx agent prepare \
  --docs https://docs.example.com/overview \
  --website https://example.com \
  --ingest-provider auto

If you pass a deep docs page like https://docs.firecrawl.dev/mcp-server, Pluxx now treats it as a seed, keeps that page in the context pack, and also infers the broader docs root when it can. Docs ingestion now has an explicit provider contract:

auto: prefer Firecrawl when FIRECRAWL_API_KEY is configured, otherwise use the local OSS path
firecrawl: require Firecrawl and fail fast if no API key is configured
local: force the built-in fetch + extraction path

When website or docs URLs are provided, agent prepare now writes two additional provenance artifacts:

.pluxx/sources.json
.pluxx/docs-context.json

Those files capture which URLs Pluxx used, which docs roots it inferred or discovered, and the structured product/setup/auth signals extracted from those pages.

`pluxx agent prompt taxonomy|instructions|review`

Generate the prompt pack for one refinement pass without running a host agent yet.

npx @orchid-labs/pluxx agent prompt taxonomy

`pluxx agent run taxonomy|instructions|review --runner claude|cursor|codex|opencode`

Run a host coding agent headlessly against the prepared Pluxx context.

npx @orchid-labs/pluxx agent run taxonomy --runner codex

Useful flags:

--model <name> to override the host runner’s local default model
--no-verify to skip the post-pass verification step
--verbose-runner to stream raw runner output
--attach <url> for OpenCode only

If you do not pass --model, Pluxx uses the runner’s local default model and prints that model in the command output when it can detect it.

`pluxx autopilot --from-mcp ... --runner ...`

Compose deterministic import, optional semantic refinement, and final verification in one flow.

npx @orchid-labs/pluxx autopilot \
  --from-mcp https://example.com/mcp \
  --runner claude \
  --name acme \
  --display-name "Acme" \
  --author "Acme"

Use --mode quick|standard|thorough to control how much semantic refinement autopilot performs. pluxx autopilot accepts the same --ingest-provider auto|local|firecrawl flag and passes it through to the shared docs-ingestion layer used by Agent Mode. Autopilot can also build, install one selected host, and run installed-state verification in the same flow:

npx @orchid-labs/pluxx autopilot \
  --from-mcp https://example.com/mcp \
  --runner codex \
  --mode standard \
  --install \
  --install-target codex \
  --trust

If you want autopilot to seed a fully preapproved MCP permission policy in the generated source project:

npx @orchid-labs/pluxx autopilot \
  --from-mcp https://example.com/mcp \
  --runner codex \
  --approve-mcp-tools

Where the agent actually does work

The host agent is only used for:

taxonomy refinement
instruction rewriting
review passes
autopilot runs that include those passes

The host agent is not used for:

MCP introspection
scaffold generation
linting
evaluation
bundle generation
install
installed-state verification
proxy record/replay
migration
consumer-side doctor checks

Good starting flows

Deterministic-first flow

npx @orchid-labs/pluxx init --from-mcp https://example.com/mcp
npx @orchid-labs/pluxx doctor
npx @orchid-labs/pluxx lint
npx @orchid-labs/pluxx eval
npx @orchid-labs/pluxx build
npx @orchid-labs/pluxx test

npx @orchid-labs/pluxx agent prepare --docs https://docs.example.com/overview
npx @orchid-labs/pluxx agent run taxonomy --runner codex
npx @orchid-labs/pluxx agent run instructions --runner codex

One coordinated flow

npx @orchid-labs/pluxx autopilot \
  --from-mcp https://example.com/mcp \
  --runner codex \
  --mode standard

Start

Build

Learn

Platform Guides

Examples

Reference

CLI Reference

Deterministic project commands

`pluxx --version`

`pluxx upgrade [--version ...]`

`pluxx init --from-mcp ...`

`pluxx discover-mcp`

`pluxx init --from-installed-mcp <host:name>`

`pluxx sync [--from-mcp ...]`

`pluxx doctor`

`pluxx doctor --consumer <bundle>`

`pluxx lint`

`pluxx eval`

`pluxx build`

`pluxx test`

`pluxx install --target ...`

`pluxx verify-install --target ...`

`pluxx migrate <path>`

`pluxx mcp proxy --from-mcp ... [--record ...]`

`pluxx mcp proxy --replay <tape.json>`

Agent-invoking commands

`pluxx agent prepare`

`pluxx agent prompt taxonomy|instructions|review`

`pluxx agent run taxonomy|instructions|review --runner claude|cursor|codex|opencode`

`pluxx autopilot --from-mcp ... --runner ...`

Where the agent actually does work

Good starting flows

Deterministic-first flow

Deterministic scaffold, then semantic refinement

One coordinated flow

​Deterministic project commands

​pluxx --version

​pluxx upgrade [--version ...]

​pluxx init --from-mcp ...

​pluxx discover-mcp

​pluxx init --from-installed-mcp <host:name>

​pluxx sync [--from-mcp ...]

​pluxx doctor

​pluxx doctor --consumer <bundle>

​pluxx lint

​pluxx eval

​pluxx build

​pluxx test

​pluxx install --target ...

​pluxx verify-install --target ...

​pluxx migrate <path>

​pluxx mcp proxy --from-mcp ... [--record ...]

​pluxx mcp proxy --replay <tape.json>

​Agent-invoking commands

​pluxx agent prepare

​pluxx agent prompt taxonomy|instructions|review

​pluxx agent run taxonomy|instructions|review --runner claude|cursor|codex|opencode

​pluxx autopilot --from-mcp ... --runner ...

​Where the agent actually does work

​Good starting flows

​Deterministic-first flow

​Deterministic scaffold, then semantic refinement

​One coordinated flow

Deterministic project commands

`pluxx --version`

`pluxx upgrade [--version ...]`

`pluxx init --from-mcp ...`

`pluxx discover-mcp`

`pluxx init --from-installed-mcp <host:name>`

`pluxx sync [--from-mcp ...]`

`pluxx doctor`

`pluxx doctor --consumer <bundle>`

`pluxx lint`

`pluxx eval`

`pluxx build`

`pluxx test`

`pluxx install --target ...`

`pluxx verify-install --target ...`

`pluxx migrate <path>`

`pluxx mcp proxy --from-mcp ... [--record ...]`

`pluxx mcp proxy --replay <tape.json>`

Agent-invoking commands

`pluxx agent prepare`

`pluxx agent prompt taxonomy|instructions|review`

`pluxx agent run taxonomy|instructions|review --runner claude|cursor|codex|opencode`

`pluxx autopilot --from-mcp ... --runner ...`

Where the agent actually does work

Good starting flows

Deterministic-first flow

Deterministic scaffold, then semantic refinement

One coordinated flow