> ## 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 a first evaluation without local configuration changes, use the [Pick up where you left off walkthrough](/docs/guides/synthetic-data-trial). 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](/docs/resources/security) 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](/docs/guides/synthetic-data-trial) | 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 ` to remove a selected client integration. Disable any background updater you enabled. 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](/docs/resources/security) 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, writes local MCP config, and bootstraps your workspace — all from one command. ```bash theme={"dark"} npx @useorgx/wizard@latest setup ``` The wizard is available on npm as `@useorgx/wizard`. For local development or CI, use `pnpm install && pnpm dev -- `. ## 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 ```bash theme={"dark"} npx @useorgx/wizard@latest setup ``` Detects supported local clients, opens browser auth, pairs your workspace, and writes local MCP config. {' '} `bash npx @useorgx/wizard@latest doctor ` Checks local config, MCP reachability, auth validity, and current-workspace connectivity. Exits non-zero when blocking issues remain. 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. Pass `--auto-update` to register a persistent background updater that keeps your skills current without manual intervention: ```bash theme={"dark"} npx @useorgx/wizard@latest setup --auto-update ``` On macOS this installs a `launchd` plist at `~/Library/LaunchAgents/com.useorgx.wizard-update.plist` that runs `wizard update --silent` weekly. On Linux it installs a `systemd` user timer. See [Auto-Update](#auto-update) for details. *** ### `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 ``` Patches OrgX config into a specific surface. `` is a surface slug such as `claude`, `cursor`, `codex`, `vscode`, `windsurf`, or `zed`. ```bash theme={"dark"} npx @useorgx/wizard@latest surface remove ``` 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](/docs/agent-ops/tool-profiles) for the available profiles. The wizard manages local clients. For ChatGPT Developer Mode, add `https://mcp.useorgx.com/mcp?profile=chatgpt` from [chatgpt.com/plugins](https://chatgpt.com/plugins). *** ### `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 ] ``` Opens browser pairing against OrgX, waits for approval, saves the returned per-user key, and bootstraps OpenClaw auth if detected. Use `--api-key ` for CI or when the browser can't open. ```bash theme={"dark"} npx @useorgx/wizard@latest auth set-key [--base-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. 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. *** ### `update` Pull the latest skills from `useorgx/skills`, patch the local MCP config for all detected clients, and emit a change summary. ```bash theme={"dark"} npx @useorgx/wizard@latest update ``` The update command: 1. Fetches the remote HEAD of `useorgx/skills` on GitHub 2. Compares each installed skill pack against the remote version 3. Writes updated skill files (`.claude/skills/orgx/*.md`, `.cursor/rules/orgx.md`) 4. Patches the local MCP config for every detected client to pick up any server changes 5. Emits a diff summary showing which skills were updated, added, or unchanged `useorgx/skills` is the canonical skill authoring repo. The OrgX app/cloud runtime uses a pinned generated cache of that repo for fast, network-free agent runs; local CLI installs and Cursor/Claude rules are generated from the same source so the runtimes do not drift. | Flag | Description | | ----------------- | --------------------------------------------------------------------------------- | | `--silent` | Suppress all output except errors. Suitable for cron jobs or background updaters. | | `--dry-run` | Show what would be updated without writing any files. | | `--packs ` | Comma-separated list of specific skill packs to update (default: all installed). | ```bash theme={"dark"} # Update silently (for cron/launchd) npx @useorgx/wizard@latest update --silent # Preview changes without writing npx @useorgx/wizard@latest update --dry-run # Update specific packs only npx @useorgx/wizard@latest update --packs morning-briefing,initiative-kickoff ``` *** ### `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 ` | Comma-separated source kinds to report and constrain (for example `github,notion`). | | `--workspace-id ` | Workspace override; defaults to the current OrgX workspace. | | `--candidate ` | Propose one returned process card by id or 1-based display number. | | `--idempotency-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 ``` 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 ``` Updates the default workspace to the one matching ``. *** ### `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](/docs/platform/skills) 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` Verifies your local setup end-to-end. ```bash theme={"dark"} npx @useorgx/wizard@latest doctor ``` Checks: * Local config files exist and are valid * `https://mcp.useorgx.com/health` is reachable * An authenticated MCP session can call `get_setup_status` * npm registry reachability for `@useorgx/wizard` * Current-workspace connectivity * Local OpenClaw health (if installed) * Remote setup status — OrgX-operated deployments only; this check is skipped on customer machines and needs nothing from you * **Skill version staleness** — compares each installed skill pack against remote HEAD and warns when skills are out of date When installed skills are behind the remote HEAD, `doctor` prints a skill version table: ``` Skill Version Check ┌─────────────────────┬─────────────┬─────────────┬────────┐ │ Skill Pack │ Installed │ Latest │ Status │ ├─────────────────────┼─────────────┼─────────────┼────────┤ │ morning-briefing │ 1.2.0 │ 1.3.1 │ stale │ │ initiative-kickoff │ 1.1.0 │ 1.1.0 │ ok │ │ bulk-create │ 1.0.2 │ 1.0.3 │ stale │ │ nightly-recap │ 1.0.0 │ 1.0.0 │ ok │ └─────────────────────┴─────────────┴─────────────┴────────┘ 2 skill packs are stale. Run: npx @useorgx/wizard@latest update ``` Skill staleness warnings are non-fatal (exit 0) but prompt you to run `wizard update`. Exits non-zero when blocking connectivity issues remain. Warnings (like unpublished npm package) are non-fatal. Run `doctor` after any config change or when a client reports that OrgX tools are unavailable. *** ## Auto-Update Enable the persistent weekly background updater to keep your skills current without manual `update` runs. ```bash theme={"dark"} npx @useorgx/wizard@latest setup --auto-update # or, if already set up: npx @useorgx/wizard@latest update --enable-background ``` ### macOS (launchd) The wizard installs a `launchd` plist at: ``` ~/Library/LaunchAgents/com.useorgx.wizard-update.plist ``` This agent runs `wizard update --silent` every 7 days using `StartInterval`. To inspect or disable it: ```bash theme={"dark"} # Check status launchctl list | grep useorgx # Disable launchctl unload ~/Library/LaunchAgents/com.useorgx.wizard-update.plist # Re-enable launchctl load -w ~/Library/LaunchAgents/com.useorgx.wizard-update.plist ``` ### Linux (systemd user timer) The wizard installs a `systemd` user service + timer pair: ``` ~/.config/systemd/user/orgx-wizard-update.service ~/.config/systemd/user/orgx-wizard-update.timer ``` The timer fires weekly (`OnCalendar=weekly`). To manage it: ```bash theme={"dark"} # Enable and start systemctl --user enable --now orgx-wizard-update.timer # Check status systemctl --user status orgx-wizard-update.timer # Disable systemctl --user disable --now orgx-wizard-update.timer ``` ### Opt-out To remove the background updater without affecting other wizard config: ```bash theme={"dark"} npx @useorgx/wizard@latest update --disable-background ``` This removes the launchd plist (macOS) or systemd timer (Linux) and stops all background update activity. *** ## 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 oxk_... --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 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`. 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 oxk_... ``` 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`. 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. 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 Full list of available skill packs and what each one does. Pair OrgX directly in your browser session with auto MCP config. Reduce tool-surface overhead by connecting with a focused profile. Full API reference for every OrgX MCP tool.