> ## 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
`@useorgx/wizard` is the fastest way to get OrgX connected from your terminal. It detects local MCP clients, opens browser auth, writes your 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 -- `.
***
## 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 non-interactive environments (CI, scripts), `setup` still runs automated surface patching without the interactive prompts.
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](/agent-ops/tool-profiles) for the available profiles.
***
### `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 targets: `claude-code`, `codex`, `openclaw`. Omit `target` to install into all detected targets.
```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
```
***
### `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](/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 (only when `ORGX_SERVICE_KEY` is set)
* **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.