> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pluxx.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```bash theme={null}
pluxx --version
```

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

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

```bash theme={null}
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.

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
npx @orchid-labs/pluxx sync
```

### `pluxx doctor`

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

```bash theme={null}
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.

```bash theme={null}
npx @orchid-labs/pluxx doctor --consumer dist/claude-code
```

### `pluxx lint`

Validate the source project against Pluxx and platform rules.

```bash theme={null}
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.

```bash theme={null}
npx @orchid-labs/pluxx eval
```

### `pluxx build`

Generate platform bundles under `dist/`.

```bash theme={null}
npx @orchid-labs/pluxx build
```

Build and install in one step:

```bash theme={null}
npx @orchid-labs/pluxx build --install
```

If local hook commands are present:

```bash theme={null}
npx @orchid-labs/pluxx build --install --trust
```

### `pluxx test`

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

```bash theme={null}
npx @orchid-labs/pluxx test
```

Test and install in one step:

```bash theme={null}
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:

```bash theme={null}
npx @orchid-labs/pluxx doctor --consumer <installed-path>
```

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

```bash theme={null}
npx @orchid-labs/pluxx test --install --trust --behavioral
```

### `pluxx install --target ...`

Install built bundles into local host tooling for testing.

```bash theme={null}
npx @orchid-labs/pluxx install --target claude-code,codex
```

Preview the install plan as JSON:

```bash theme={null}
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:

```bash theme={null}
npx @orchid-labs/pluxx install --target codex --trust
```

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

Inspect installed host-visible plugin state.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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

```bash theme={null}
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
```

### Deterministic scaffold, then semantic refinement

```bash theme={null}
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

```bash theme={null}
npx @orchid-labs/pluxx autopilot \
  --from-mcp https://example.com/mcp \
  --runner codex \
  --mode standard
```