Loadoutz CLI

One-command setup for connecting MCP clients to a Loadoutz owner URL.

Quickstart

npx loadoutz@latest connect https://mcp.loadoutz.io/mcp/u/<owner>

Then run:

npx loadoutz@latest doctor

Auth model (v1)

• OAuth-first by default.
• --token is fallback auth for the current run only.
• --persist-token is required to write fallback token to shell profile.
• If you use --interactive with --token (without --persist-token), CLI prompts whether to persist (default: No).

Privacy

• No telemetry or analytics in v1.

Commands

npx loadoutz@latest connect <owner-url>
npx loadoutz@latest doctor
npx loadoutz@latest validate --url <owner-url>
npx loadoutz@latest skill install
npx loadoutz@latest skill print

connect

Primary onboarding flow. It validates URL, detects installed clients, writes configs, runs verification ping, installs ~/.loadoutz/skill.md, and prints summary.

Exit code contract:

• exits 0 when at least one auto-config client is written
• exits 1 only when zero auto-config clients are written

doctor

Checks install/config/validation state for detected clients and supports backup restore.

validate

Runs JSON-RPC validation against your owner URL with actionable next-step guidance.

skill install / skill print

Installs or prints the universal skill context file at ~/.loadoutz/skill.md.

v1 scope and status

Included in v1:

• connect, doctor, validate
• skill install, skill print
• global scope + --project
• OAuth-first writers with token fallback only when provided
• connect exit contract: fail only when zero auto-config writes succeed

Out of scope in v1:

• provider/loadout lifecycle management in CLI
• OAuth token lifecycle/rotation in CLI

Implemented client matrix:

• Auto-config: Codex CLI, VS Code, Continue, Cursor, Cline, Roo Code, Claude Desktop, OpenCode, Windsurf, Claude Code, Zed, Gemini CLI
• Manual lane: Codex App

Deferred client matrix:

• VS Code Insiders
• Kilo Code
• GitHub Copilot
• Aider
• Claude.ai web (manual)
• Replit (manual)

Troubleshooting

Auth errors (401 / 403)

• Complete OAuth flow in your primary client and rerun:

npx loadoutz@latest doctor

• If client requires fallback token:

npx loadoutz@latest connect <owner-url> --token <token>

• Persist fallback token only when needed:

npx loadoutz@latest connect <owner-url> --token <token> --persist-token

Network / URL errors (404, 5xx, timeout, DNS)

npx loadoutz@latest validate --url <owner-url>

Confirm URL is owner-scoped:

https://mcp.loadoutz.io/mcp/u/<owner>

Path / permission errors on config write

• Re-run with permission to write target config files.
• Then run:

npx loadoutz@latest doctor

Requirements

• Node.js >=18

License

MIT