Skip to main content

​
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.
The wizard is available on npm as @useorgx/wizard. For local development or CI, use pnpm install && pnpm dev -- <command>.

​
Quick Setup

1

Run setup

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

Verify the connection

bash npx @useorgx/wizard@latest doctor Checks local config, MCP reachability, auth validity, and current-workspace connectivity. Exits non-zero when blocking issues remain.
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
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:
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 for details.

​
surface Commands

Manage which local clients have OrgX wired in.
Shows all supported surfaces and their current status (configured, not configured, unsupported).
Patches OrgX config into a specific surface. <name> is a surface slug such as claude, cursor, codex, vscode, windsurf, or zed.
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.
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.
Removes the OrgX MCP server entry from the specified client. The managed MCP URL is https://mcp.useorgx.com/mcp. To use a profile:
See Tool Profiles for the available profiles.

​
plugins Commands

Manage OrgX companion plugins for supported IDEs.
Shows availability and install status for Claude Code, Codex, and OpenClaw.
Installs the managed OrgX companion plugin into one or more targets: claude-code, codex, openclaw. Omit target to install into all detected targets.
Uninstalls the managed OrgX companion plugin from the specified targets.

​
auth Commands

Manage your OrgX API key and workspace pairing.
Shows the resolved OrgX API key source (env var, keychain, or file) and verifies it against the OrgX API.
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.
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.
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.
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.

​
workspace Commands

Inspect and manage your OrgX workspaces.
Reads the current OrgX workspace from the API. Useful for verifying which workspace is active in your environment.
Lists all accessible workspaces for the authenticated user.
Creates a new workspace and makes it active immediately.
Updates the default workspace to the one matching <id>.

​
skills Commands

Install OrgX skill packs into your local Claude or Cursor environment.
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 for a full list of available packs and the app runtime source-lock model.

​
doctor

Verifies your local setup end-to-end.
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 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.

​
macOS (launchd)

The wizard installs a launchd plist at:
This agent runs wizard update --silent every 7 days using StartInterval. To inspect or disable it:

​
Linux (systemd user timer)

The wizard installs a systemd user service + timer pair:
The timer fires weekly (OnCalendar=weekly). To manage it:

​
Opt-out

To remove the background updater without affecting other wizard config:
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:
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:
Or use the manual fallback:
Verify your current base URL and API key:
If workspace list fails, re-run auth login.
Check which surfaces are configured:
Then add the missing surface:
Restart your client after patching.
Run:
This writes .claude/skills/orgx/SKILL.md and installs the starter packs. Restart Claude Code to pick up the new skills.

​
Next Steps

Skills Reference

Full list of available skill packs and what each one does.

OpenClaw Plugin

Pair OrgX directly in your browser session with auto MCP config.

Tool Profiles

Reduce tool-surface overhead by connecting with a focused profile.

MCP Reference

Full API reference for every OrgX MCP tool.