CLI Setup Command

Install 1MCP CLI hooks and reference files for Codex or Claude.

Synopsis

npx -y @1mcp/agent cli-setup (--codex | --claude) [options]

Description

The cli-setup command installs lightweight bootstrap files that point Codex or Claude at the 1MCP CLI workflow. It writes:

• A managed 1MCP.md bootstrap document
• Hook configuration so the startup doc is injected on session start
• A startup file reference from AGENTS.md or CLAUDE.md

cli-setup does not replace instructions. It makes sure the session is prepared to use instructions, inspect, and run in the right order.

Think of cli-setup as the bridge from an existing agent workflow to 1MCP CLI mode. It teaches the client how to start, but the live discovery and execution flow still happens through instructions, inspect, and run.

Required Client Selection

Choose exactly one target:

• --codex - Install setup files for Codex only
• --claude - Install setup files for Claude only

Passing neither or both returns an error.

Options

• --scope <global|repo|all> - Setup scope (default: global)
• --repo-root <path> - Repository root used for repo-scoped setup

Scope Behavior

• global - Writes into the user's home-level Codex or Claude directories
• repo - Writes repo-local setup files under the selected repository root
• all - Writes both global and repo-scoped setup files

Files Written

Codex

• Global managed doc: ~/.codex/1MCP.md
• Global hooks: ~/.codex/hooks.json
• Global startup reference: ~/.codex/AGENTS.md
• Repo managed doc: <repo>/.codex/1MCP.md
• Repo hooks: <repo>/.codex/hooks.json
• Repo startup reference: <repo>/AGENTS.md

Claude

• Global managed doc: ~/.claude/1MCP.md
• Global hooks: ~/.claude/settings.json
• Global startup reference: ~/.claude/CLAUDE.md
• Repo managed doc: <repo>/.claude/1MCP.md
• Repo hooks: <repo>/.claude/settings.json
• Repo startup reference: <repo>/CLAUDE.md

Examples

Install Global Codex Setup

npx -y @1mcp/agent cli-setup --codex

Install Repo-Local Claude Setup

npx -y @1mcp/agent cli-setup --claude --scope repo --repo-root .

Install Both Global and Repo-Local Codex Setup

npx -y @1mcp/agent cli-setup --codex --scope all

Codex Follow-Up

When --codex is used, the command also prints a required config.toml snippet enabling Codex hooks and the workspace-write sandbox with network access.

Resulting Workflow

The managed startup docs tell the client to:

1. Run 1mcp instructions unless the current session already received those instructions from hooks
2. If the provider or tool is unknown, optionally use 1mcp inspect --search <query> (or add a server target); otherwise inspect the known target directly
3. Run 1mcp inspect <server> and read the applicable server instructions before picking a tool
4. Run 1mcp inspect <server>/<tool> before invocation
5. Run 1mcp run <server>/<tool> --args '<json>' only after inspecting the schema

Search defaults to case-insensitive literal substring matching. Use a quoted --search 'filesystem/*read?' --glob pattern for whole-reference */? matching. --include-descriptions adds effective descriptions to matching; --show-descriptions independently displays them.

Rerun the same cli-setup command to refresh managed guidance in any scope. Repeated runs are idempotent and preserve unrelated startup-document content and hooks. Startup references stay lightweight, and hooks continue to call 1mcp instructions.

See Also

• CLI Mode Guide - Conceptual overview of the agent-facing CLI workflow
• Instructions Command - The bootstrap command that cli-setup points sessions toward
• Inspect Command - Discover tools and schemas
• Run Command - Invoke a selected tool
• Codex Integration Guide - End-to-end setup for Codex