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

# Wizard CLI

> Complete reference for the @useorgx/wizard CLI — onboarding, MCP config, auth, surfaces, plugins, and workspace management.

## Overview

For reusable cloud images and unattended runtime setup, use the
[Cloud agents guide](https://docs.useorgx.com/docs/guides/cloud-agents.md). It separates credential-free
preparation from per-session verification and includes an agent installation skill.

For a first evaluation without local configuration changes, use the
[Pick up where you left off walkthrough](https://docs.useorgx.com/docs/guides/synthetic-data-trial.md).
The local wizard is a separate setup path: depending on the selected client
and integration, it can install session hooks and capture local session
metadata or work context. Review [data handling](https://docs.useorgx.com/docs/resources/security.md) before
running it on a machine containing employer code.

## Choose the smallest useful setup

| Path | Why choose it | What changes |
| - | - | - |
| [Interactive example](https://useorgx.com/try) | Understand the ledger before connecting anything | Prepared page state only; no MCP execution |
| [Browser MCP walkthrough](https://docs.useorgx.com/docs/guides/synthetic-data-trial.md) | Test actual continuity with example records | OAuth connection and explicit hosted tool calls; no local wizard or hooks |
| Local wizard | Carry work across supported developer tools | Client configuration, skills/rules, and integration hooks; review the scope before continuing |

The explicit-consent wizard update offers **Explore the browser example**,
**Continue with local setup**, or **Exit** before setup work. Unattended setup
requires `--yes`. Check `setup --help` before relying on these options. If it
does not list `--yes`, your installed package predates this flow: use the
browser walkthrough or wait for a package version with explicit consent.

### Why capture choices matter

MCP access and session capture are different decisions. MCP receives the
arguments a client sends to a tool. Session hooks observe local runtime events
to support continuity; metadata can reveal project names and local paths even
when prompt content is excluded.

In the explicit-consent update, `hooks install` defaults to `metadata-only`.
Choosing `--work-capture bounded` adds redacted request excerpts to work-episode
capture. Redaction is not a confidentiality guarantee. Other plugin and setup
integrations have their own capture behavior; this flag is not a global policy.
The command prints the targets and capture mode before asking for confirmation.

Inspect configuration with `hooks doctor` and `surface list`. Hook event files
live under `~/.config/useorgx/wizard/hooks/`; they can contain session IDs,
working-directory/transcript paths, timestamps, and event summaries.
Review a replay or publishing command separately before uploading local records.

Use `uninstall --help` to review removal choices and `surface remove <name>`
to remove a selected client integration. Removing local integration or clearing local auth does not revoke all
remote credentials or delete hosted records. Revoke the connection and review
[stored-data deletion and remaining copies](https://docs.useorgx.com/docs/resources/security.md) separately.

For work data, ask your security reviewer to approve the specific data classes,
access scope, retention, and provider boundary. Request missing deployment
evidence at [security@useorgx.com](mailto:security@useorgx.com). A successful
connection is not a security review.

`@useorgx/wizard` is a terminal-based way to connect OrgX and verify the
resulting client configuration.
It detects supported local MCP clients, opens browser auth, and writes local MCP
configuration after your setup choices. Node 22 or newer is required.

```bash theme={"dark"}
npx @useorgx/wizard@latest setup
```

> [!NOTE]
>
> The wizard is available on npm as `@useorgx/wizard`. For local development or CI, use `pnpm install && pnpm dev -- <command>`.

## Web orientation: map the work before planning it

The web orientation workbench is the guided path for a new workspace. Before
OrgX proposes an initiative, it asks for the outcome and an explicit evidence
depth:

* **Connected workflow map** (`bounded_sync`) uses the repositories and
  connectors already authorized for the workspace.
* **Map + cited deep search** (`deep_search`) adds deliberate external
  research. Citations and provider limitations remain attached to the
  discovery run; they are not presented as observed internal workflow facts.

The selected mode is saved in the orientation journey and repeated in the
discovery dossier. A deep-search result is still a proposal input: a person
must review and confirm the resulting operating process before activation.
Selecting deep search may take longer and incur provider cost, so the choice
is always visible and never inferred from a missing connector.

Deep search only contributes workflow candidates when the provider returns the
explicit schema block requested by the discovery prompt. Each candidate links
back to the cited report, is marked as inferred, and asks a confirmation
question about ownership or completion. If the report is prose-only or the
block fails validation, the wizard keeps the report as observational evidence
and shows the limitation instead of guessing a workflow.

The same evidence-gated flow is available from the terminal with the
[`map` command](#map).

***

## Quick Setup

**1. Run setup**

```bash theme={"dark"}
npx @useorgx/wizard@latest setup
```

Detects supported local clients, opens browser auth, pairs your workspace, and writes local MCP config.

&#x20;

**2. Verify the connection**

```bash theme={"dark"}
npx @useorgx/wizard@latest doctor
```

Checks local configuration and the health checks reported by your release.
Verify hosted OAuth separately inside your selected client.

**3. Start working**

Open your MCP-capable client (Claude, Cursor, Codex, VS Code, Windsurf, Zed) and confirm OrgX tools are available. Run `orgx_search` to verify the live connection.

***

## Command Reference

### `setup`

The primary onboarding command. In an interactive shell it:

1. Detects all supported local surfaces
2. Opens a secure browser auth flow if no key is present
3. Guides workspace selection (keep existing, promote another, or create new)
4. Writes the right local MCP config for each detected client
5. Optionally installs companion plugins for Claude Code, Codex, and OpenClaw
6. Offers to install starter OrgX skill packs

```bash theme={"dark"}
npx @useorgx/wizard@latest setup
```

In versions before the explicit-consent update, non-interactive `setup` can
patch detected surfaces without prompts. The update requires `--yes` before
that behavior. Do not use unattended setup as an inspection command.

For skill refresh, use `skills sync` or `skills add` after reviewing `skills --help`.
These commands do not imply a background updater is installed.

***

### `surface` Commands

Manage which local clients have OrgX wired in.

```bash theme={"dark"}
npx @useorgx/wizard@latest surface list
```

Shows all supported surfaces and their current status (configured, not configured, unsupported).

```bash theme={"dark"}
npx @useorgx/wizard@latest surface add <name>
```

Patches OrgX config into a specific surface. `<name>` is a surface slug such as `claude`, `cursor`, `codex`, `vscode`, `windsurf`, or `zed`.

```bash theme={"dark"}
npx @useorgx/wizard@latest surface remove <name>
```

Removes OrgX-managed config from a specific surface, leaving any non-OrgX config intact.

***

### `mcp` Commands

Fine-grained control over MCP server entries across clients.

```bash theme={"dark"}
npx @useorgx/wizard@latest mcp add [surface]
```

Adds the OrgX MCP server entry to the specified client (or all detected clients if no surface is given). Supported: Claude, Cursor, Codex, VS Code, Windsurf, Zed.

```bash theme={"dark"}
npx @useorgx/wizard@latest mcp remove [surface]
```

Removes the OrgX MCP server entry from the specified client.

The managed MCP URL is `https://mcp.useorgx.com/mcp`. To use a profile:

```bash theme={"dark"}
https://mcp.useorgx.com/mcp?profile=commander
```

See [Tool Profiles](https://docs.useorgx.com/docs/agent-ops/tool-profiles.md) for the available profiles.

> [!NOTE]
>
> The wizard manages local clients. For ChatGPT, add OrgX from the ChatGPT
> plugin directory; see the
> [ChatGPT integration guide](https://docs.useorgx.com/docs/guides/chatgpt-integration.md).

***

### `plugins` Commands

Manage OrgX companion plugins for supported IDEs.

```bash theme={"dark"}
npx @useorgx/wizard@latest plugins list
```

Shows availability and install status for Claude Code, Codex, and OpenClaw.

```bash theme={"dark"}
npx @useorgx/wizard@latest plugins add [target...]
```

Installs the managed OrgX companion plugin into one or more supported targets.
Use `claude` for Claude Code:

```bash theme={"dark"}
npx -y @useorgx/wizard@latest plugins add claude
```

This self-hosted Claude Code plugin provides static skills and commands plus
native-OAuth MCP. It does not install transcript/context telemetry hooks or
dynamic skill/agent sync.

```bash theme={"dark"}
npx @useorgx/wizard@latest plugins remove [target...]
```

Uninstalls the managed OrgX companion plugin from the specified targets.

***

### `auth` Commands

Manage your OrgX API key and workspace pairing.

```bash theme={"dark"}
npx @useorgx/wizard@latest auth status
```

Shows the resolved OrgX API key source (env var, keychain, or file) and verifies it against the OrgX API.

```bash theme={"dark"}
npx @useorgx/wizard@latest auth login [--base-url <url>]
```

Opens browser pairing against OrgX, waits for approval, saves the returned per-user key, and bootstraps OpenClaw auth if detected. Use `--api-key <oxk_...>` for CI or when the browser can't open.

```bash theme={"dark"}
npx @useorgx/wizard@latest auth set-key "$ORGX_API_KEY" [--base-url <url>]
```

Verifies a per-user OrgX key, saves it to the wizard auth store, and bootstraps OpenClaw auth if detected. Safe to use in CI with `ORGX_BASE_URL` set.

```bash theme={"dark"}
npx @useorgx/wizard@latest auth clear
```

Removes the wizard-local saved OrgX API key. Does not remove keys stored in system keychain separately.

**Auth resolution order**: `ORGX_API_KEY` env var → wizard auth store (keychain or file) → OpenClaw config.

> [!TIP]
>
> When `keytar` is available, the wizard stores the raw API key in the system
> keychain and keeps only metadata in `auth.json`. If `keytar` is unavailable,
> it falls back to file-backed storage.

***

### `map`

Map observed company workflows into evidence-gated operating-process
candidates from the terminal. `map` (alias: `discovery`) runs the same
discovery flow as the web orientation workbench: it starts a discovery run,
prints the observed process cards with confidence and confirmation questions,
and can propose one selected candidate as an operating process.

```bash theme={"dark"}
npx @useorgx/wizard@latest map "Map customer intake, handoffs, systems of record, and completion criteria"
```

Under the hood, `map` calls `POST /api/v1/discovery-runs` with your API key and
a stable `Idempotency-Key`, then — only when you select a candidate — calls
`POST /api/v1/discovery-runs/{runId}/propose`. A proposed operating process
still requires explicit human confirmation before activation.

| Flag | Description |
| - | - |
| `--deep-search` | Use `deep_search` mode (cited external research) instead of the default `bounded_sync`. |
| `--source <kinds>` | Comma-separated source kinds to report and constrain (for example `github,notion`). |
| `--workspace-id <id>` | Workspace override; defaults to the current OrgX workspace. |
| `--candidate <id-or-num>` | Propose one returned process card by id or 1-based display number. |
| `--idempotency-key <key>` | Stable retry key; defaults to a hash of workspace, mode, query, and sources. |
| `--yes` | Approve the explicit proposal in non-interactive mode. |
| `--json` | Emit machine-readable discovery and proposal output. |

```bash theme={"dark"}
# Bounded discovery from connected sources, then propose the first candidate
npx @useorgx/wizard@latest map --source github "Where does work enter and leave the team?" --candidate 1 --yes

# Cited deep search with machine-readable output
npx @useorgx/wizard@latest map --deep-search --json "Map the release process"
```

Requires `wizard auth login` and a current workspace. In non-interactive mode,
proposing a candidate requires `--yes`.

***

### `workspace` Commands

Inspect and manage your OrgX workspaces.

```bash theme={"dark"}
npx @useorgx/wizard@latest workspace current
```

Reads the current OrgX workspace from the API. Useful for verifying which workspace is active in your environment.

```bash theme={"dark"}
npx @useorgx/wizard@latest workspace list
```

Lists all accessible workspaces for the authenticated user.

```bash theme={"dark"}
npx @useorgx/wizard@latest workspace create <name>
```

Creates a new workspace and makes it active immediately.

```bash theme={"dark"}
# Example
npx @useorgx/wizard@latest workspace create "Q2 Product Launch" --description "Workspace for Q2 initiatives"
```

```bash theme={"dark"}
npx @useorgx/wizard@latest workspace set-default <id>
```

Updates the default workspace to the one matching `<id>`.

***

### `skills` Commands

Install OrgX skill packs into your local Claude or Cursor environment.

```bash theme={"dark"}
npx @useorgx/wizard@latest skills add [pack...]
```

This command:

1. Writes `.cursor/rules/orgx.md` — Cursor rules for OrgX-aware code generation
2. Generates `.claude/skills/orgx/SKILL.md` — the hosted OrgX Claude skill
3. Installs the default starter packs: `morning-briefing`, `initiative-kickoff`, `bulk-create`, `nightly-recap`

Pull from `useorgx/skills` on GitHub. See [Skills](https://docs.useorgx.com/docs/platform/skills.md) for a full list of available packs and the app runtime source-lock model.

```bash theme={"dark"}
# Install specific packs
npx @useorgx/wizard@latest skills add morning-briefing initiative-kickoff
```

***

### `doctor`

Check local configuration, endpoint reachability, and the checks reported by
this installed release:

```bash theme={"dark"}
npx @useorgx/wizard@latest doctor
```

Doctor does not establish that your selected host's OAuth session can call
hosted MCP tools. Finish verification inside that client with one permitted
read and confirm the expected workspace. A healthy endpoint can still have a
missing or expired client authorization. Runner readiness and capture delivery
are independent checks.

***

## CI Mode

The wizard supports non-interactive CI environments:

```bash theme={"dark"}
# Set up auth without browser
ORGX_API_KEY=oxk_... npx @useorgx/wizard@latest auth status

# Or
npx @useorgx/wizard@latest auth set-key "$ORGX_API_KEY" --base-url https://useorgx.com

# Verify everything
npx @useorgx/wizard@latest doctor
```

`doctor` is CI-safe — it exits non-zero only on blocking issues.

***

## Troubleshooting

> [accordion] doctor reports 'hosted mcp unreachable'
>
> Verify network access to `https://mcp.useorgx.com/health`. If you're behind a corporate proxy, ensure the proxy allows WebSocket and SSE connections to `mcp.useorgx.com`.

> [accordion] doctor reports 'orgx auth invalid'
>
> Re-run `auth login` to mint a fresh key:
>
> ```bash theme={"dark"}
> npx @useorgx/wizard@latest auth login
> ```
>
> Or use the manual fallback:
>
> ```bash theme={"dark"}
> npx @useorgx/wizard@latest auth login --api-key oxk_...
> npx @useorgx/wizard@latest auth set-key "$ORGX_API_KEY"
> ```

> [accordion] Workspace resolution fails
>
> Verify your current base URL and API key:
>
> ```bash theme={"dark"}
> npx @useorgx/wizard@latest auth status
> npx @useorgx/wizard@latest workspace list
> ```
>
> If `workspace list` fails, re-run `auth login`.

> [accordion] MCP tools don't appear in my client
>
> Check which surfaces are configured:
>
> ```bash theme={"dark"}
> npx @useorgx/wizard@latest surface list
> ```
>
> Then add the missing surface:
>
> ```bash theme={"dark"}
> npx @useorgx/wizard@latest surface add cursor
> npx @useorgx/wizard@latest surface add claude
> ```
>
> Restart your client after patching.

> [accordion] Skills not available in Claude
>
> Run:
>
> ```bash theme={"dark"}
> npx @useorgx/wizard@latest skills add
> ```
>
> This writes `.claude/skills/orgx/SKILL.md` and installs the starter packs. Restart Claude Code to pick up the new skills.

***

## Next Steps

> [card] [Skills Reference](https://docs.useorgx.com/docs/platform/skills.md)
>
> Full list of available skill packs and what each one does.

> [card] [OpenClaw Plugin](https://docs.useorgx.com/docs/guides/openclaw-plugin-setup.md)
>
> Pair OrgX directly in your browser session with auto MCP config.

> [card] [Tool Profiles](https://docs.useorgx.com/docs/agent-ops/tool-profiles.md)
>
> Reduce tool-surface overhead by connecting with a focused profile.

> [card] [MCP Reference](https://docs.useorgx.com/docs/api/mcp-tools.md)
>
> Full API reference for every OrgX MCP tool.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.