Octocode CLI

Two things in one binary: manage Octocode MCP across your IDEs, and run any Octocode tool directly from the terminal.

Website · CLI Reference · GitHub

Install

# Homebrew (macOS / Linux): installs the `octocode` command globally
brew install bgauryy/octocode/octocode

# equivalent short form
brew tap bgauryy/octocode && brew install octocode

# or npm (global)
npm install -g octocode-cli

# or run once without installing
npx octocode-cli install

Verify, then sign in:

octocode --version        # → octocode v1.5.3
octocode login            # GitHub OAuth (device flow)

The installed command is octocode (not octocode-cli). Homebrew pulls in Node automatically.

Quick Start

octocode login                          # GitHub authentication
octocode install --ide cursor           # wire MCP into an editor
octocode install --ide cursor --check   # pre-flight: check writability & current state
octocode skills install --targets claude-code   # add Agent Skills
octocode tools                          # list every tool
octocode tools localSearchCode --queries '{"path":".","pattern":"TODO"}'

The 14 Tools

Call any tool directly from the terminal. Great for scripts, pipelines, and one-off queries. No MCP server required.

| Group | Tool | What it does | |-------|------|--------------| | GitHub | githubSearchCode | Search code across GitHub [EXTERNAL] | | | githubSearchRepositories | Search repositories by keywords/topics [EXTERNAL] | | | githubSearchPullRequests | Search pull requests [EXTERNAL] | | | githubGetFileContent | Read file content (matchString, line ranges) [EXTERNAL] | | | githubViewRepoStructure | List a repo's directory tree [EXTERNAL] | | | githubCloneRepo | Clone a repo/subtree to disk for local + LSP analysis | | Local | localSearchCode | Search code patterns with ripgrep (PCRE2) | | | localFindFiles | Find files by name/metadata | | | localGetFileContent | Read local file content | | | localViewStructure | View a local directory tree | | LSP | lspGotoDefinition | Navigate to a symbol's definition | | | lspFindReferences | Find all usages of a symbol | | | lspCallHierarchy | Trace function call relationships | | Package | packageSearch | Resolve an npm package to its source repo + metadata |

# Discover
octocode --agent                                  # agent bootstrap: protocol + tools + input fields
octocode --agent --full                           # …plus every tool's full JSON schema inline
octocode tools                                    # list all tools
octocode tools localSearchCode                    # show one tool's schema
octocode tools localSearchCode githubSearchCode   # batch schemas
octocode instructions                             # alias of --agent (add --full for all schemas)

# Run
octocode tools localSearchCode --queries '{"path":".","pattern":"TODO"}'
octocode tools githubSearchCode --queries '{"keywordsToSearch":["useReducer"],"owner":"facebook","repo":"react"}'
octocode tools localSearchCode --queries '{"path":".","pattern":"TODO"}' --json     # full MCP envelope
octocode tools localSearchCode --queries '{"path":".","pattern":"TODO"}' --compact  # leanest (structuredContent only)

The shared metadata fields (id, researchGoal, reasoning, mainResearchGoal) are auto-filled. Provide only tool-specific fields.

For agents: run octocode --agent once for the full bootstrap (protocol + every tool + input fields + the mandatory "read the schema before calling" rule + the exit-code table). Then octocode tools <name> to confirm a tool's exact schema before calling it. This checklist is also printed at the top of octocode --help.

GitHub Token

Octocode resolves a GitHub token in this order: environment variable → Octocode-managed token (octocode login) → gh CLI.

For env-based setup, any of these are accepted (checked in this priority): OCTOCODE_TOKEN, GH_TOKEN, GITHUB_TOKEN.

export GITHUB_TOKEN=ghp_xxx        # or OCTOCODE_TOKEN / GH_TOKEN
octocode token --source           # show which token & source is being used
octocode token --validate         # ping the GitHub API to verify it
octocode token                    # masked on screen; raw when piped, e.g. export GH_TOKEN=$(octocode token)
octocode token --reveal           # print the full token on screen

Commands

| Command | Aliases | What it does | |---------|---------|--------------| | install --ide <ide> | i, setup | Configure octocode-mcp for an IDE | | install --ide <ide> --check | | Pre-flight: verify config path is writable, show what would change | | install --ide <ide> --method npx | | Installation method (npx is the only/default method) | | install --ide <ide> --force | | Overwrite an existing configuration | | install --ide <ide> --rollback | | Restore the most recent backup configuration | | install --ide <ide> --rollback --backup-path <file> | | Restore a specific backup file | | auth / login / logout | a, gh / l / | GitHub authentication | | login --force | | Log out the current session and re-authenticate in one step | | login --git-protocol <ssh\|https> | | Set the git protocol used for clones | | login --hostname <host> | | Target a GitHub Enterprise host | | logout --yes | | Skip the confirmation prompt | | auth refresh | | Refresh an Octocode-managed token (source-aware) | | token | t | Print the resolved GitHub token | | token --type <auto\|octocode\|gh> | | Force a specific token source instead of auto-resolution | | token --source | | Show which source resolved the token | | token --validate | | Ping the GitHub API to verify the token and show rate-limit | | token --reveal | | Print the full token on screen (default: masked on a terminal, raw when piped) | | status | s | Full health check: auth + MCP clients + cache | | status --sync | | Also include per-MCP sync analysis | | sync | sy | Sync MCP configs across all IDEs | | sync --dry-run | | Show what sync would do without writing anything | | sync --status | | Show sync analysis without syncing | | sync --force | | Auto-resolve conflicts (use first variant found) | | skills | sk | Install / remove / list / search / read / sync skills | | skills search <query> | | In a terminal: immediate results from skills.sh. In scripts/agents (non-TTY): emits the research protocol | | skills search --direct | | Force direct results from skills.sh (auto-enabled in a terminal; use this in scripts/pipes) | | skills search --direct --install | | Fetch and install top result automatically | | skills read <path \| owner/repo/path \| github-url> | | Preview a SKILL.md from disk or GitHub (--full for untruncated) | | skills install --targets <t1,t2> | | Install all bundled skills to targets | | skills install --skill <name> --targets <t> | | Install one specific skill | | skills install --local <path> --targets <t> | | Install a local skill folder | | skills install --dry-run | | Preview installs without writing | | skills install --mode <copy\|symlink> | | Symlink instead of copy (default copy) | | skills remove --skill <name> --targets <t> | | Remove a skill | | skills list / skills list --target <t> | | List installed skills (optionally filter to one target) | | skills sync <from> <to> | | Copy skills between targets | | mcp list | | Scan all OS MCP config files | | mcp list --client <id> | | Search registry for a specific client | | mcp list --installed | | List only installed MCPs with env-var status | | mcp list --search <text> / --category <name> | | Filter the list | | mcp status --client <id> | | Show servers in one config + env var status | | mcp install --id <id> --client <id> | | Install one MCP server | | mcp install --id a,b,c | | Batch-install MCPs (parallel preflight) | | mcp install --id <id> --config <path> | | Install into a custom config file | | mcp install --id <id> --env K=V,K2=V2 | | Set env vars for the installed server | | mcp install --id <id> --force | | Overwrite an existing entry | | mcp remove --id <id> --client <id> | | Remove an MCP server | | cache status | | Inspect cache sizes (repos, skills, logs) | | cache clean --all | | Clean repos + skills + logs | | cache clean --repos / --skills / --logs | | Clean specific targets | | cache clean --tools | | Clean all tool caches (local + lsp + api) | | cache clean --local / --lsp / --api | | Clean individual tool caches | | cache clean --all --dry-run | | Show what would be freed without deleting | | cache clean --all --yes | | Skip the confirmation prompt | | tools [name...] | | List tools, show schema(s), or run with --queries '<json>' | | instructions | | Print MCP instructions + every tool schema |

Most subcommands accept --hostname <host> for GitHub Enterprise.

Global Flags

| Flag | Description | |------|-------------| | --json, -j | Raw JSON output (full MCP envelope) for tool runs | | --compact | Leanest tool output: minified structuredContent only (~60% smaller than --json) | | --agent | Print the agent bootstrap: protocol + every tool + input fields (add --full for all JSON schemas) | | --no-color | Disable ANSI colors (also honored via NO_COLOR=1) | | --version, -v | Print the CLI version | | --help, -h | Show help for the CLI or a command |

Environment

| Variable | Purpose | |----------|---------| | OCTOCODE_TOKEN | GitHub token (checked first) | | GH_TOKEN | GitHub token (checked second) | | GITHUB_TOKEN | GitHub token (checked third) | | OCTOCODE_HOME | Override the data directory (default ~/.octocode) |

Exit Codes

| Code | Meaning | |------|---------| | 0 | Success | | 1 | General error | | 2 | Invalid input / unsupported flags | | 3 | Unknown tool or command | | 4 | Authentication failure | | 5 | Tool / API execution error | | 7 | Rate limited |

Typed codes 2–7 apply to the tool surface (tools, --tool) and command dispatch, so agents can branch on the failure mode without parsing output. Management commands (install, auth, sync, …) use 0/1.

Supported Clients

cursor, claude / claude-desktop, claude-code, windsurf, zed, vscode-cline, vscode-roo, vscode-continue, opencode, trae, antigravity, codex, gemini-cli, goose, kiro

Troubleshooting

octocode status --sync                   # Full health check including sync analysis
octocode token --validate                # Verify your GitHub token against the API
octocode token --source                  # Debug token resolution chain
octocode install --ide cursor --check    # Pre-flight before installing
octocode sync --dry-run                  # Preview sync changes before applying
octocode cache clean --all --dry-run     # See what cache clean would free

Docs

• CLI Reference: full command and flag reference
• Skills Guide: bundled skills installation
• Configuration Reference
• Troubleshooting

Privacy & Telemetry

De-identified telemetry (command usage, error rates) helps improve the CLI. Source code, env values, and repo contents are not collected.

Privacy Policy · Terms of Usage

MIT. Copyright 2026 Octocode AI.