Use `octocode-cli` subcommands to execute Octocode MCP tools from a terminal without wiring MCP. Use when the user asks to "run octocode from shell", "use octocode without MCP", "call githubSearchCode from CLI", or wants a one-off GitHub code/file/PR search in the terminal.
Six subcommands, one tool each. Pick by task shape. Always add --json and pipe to jq.
| What you need | Command | Key flags |
|---|---|---|
| Find where a symbol is defined or used | search-code | --query 'symbol' --owner X --repo Y |
| Read a specific file (whole or a window) | get-file | --match-string 'anchor' or --start-line N --end-line M or --full-content |
| Map a repo's layout | view-structure | --depth 2 |
| Find repos by topic/popularity | search-repos | --topics a,b --stars '>=100' |
| PR history on a repo |
search-prs |
--owner X --repo Y --merged |
| Resolve a package to a repo + read metadata | package-search | --name pkg --ecosystem npm |
These three rules decide whether the CLI is fast or slow:
get-file calls in one message so the shell runs them concurrently. Sequential loops waste wall-clock.search-code should be the broadest that plausibly returns <20 hits. If you got reasonable results, read them — don't re-query to "narrow down". Iterating search-code is the #1 reason the CLI ever feels slow.printf '{"queries":[
{"keywordsToSearch":["useState"],"owner":"facebook","repo":"react"},
{"keywordsToSearch":["useEffect"],"owner":"facebook","repo":"react"}
]}' | octocode-cli search-code --json | jq
# One search returns the defining file and call sites together
octocode-cli search-code --query 'runCLI' --owner bgauryy --repo octocode-mcp --limit 10 --json | jq
# Read the hit that looks like the definition
octocode-cli get-file --owner bgauryy --repo octocode-mcp \
--path packages/octocode-cli/src/cli/index.ts \
--match-string 'export function runCLI' --json | jq
# Structure first — one call, entire tree
octocode-cli view-structure --owner bgauryy --repo octocode-mcp --depth 2 --json | jq
Then fetch every package.json in a single message by issuing parallel get-file calls (your agent's parallel tool-use, not a sequential loop). A 5-package mapping is 1 structure call + 5 parallel fetches = 2 round-trips, not 6.
# ONE search with a distinctive keyword. The top hit's path is the answer.
octocode-cli search-code --query 'discriminatedUnion' --owner colinhacks --repo zod --limit 5 --json | jq
Don't re-query to "confirm". Once you have a path that plausibly defines the symbol, answer from it.
# Seed with the entry function
octocode-cli search-code --query 'runCLI' --owner bgauryy --repo octocode-mcp --json | jq
For each callee name you find, search it to locate the next hop. 3–4 search-code calls reach a handler; 10+ means you're lost — back out and try a broader seed query.
--query 'a,b,c' → ['a','b','c'].--match-string → matchString, --full-content → fullContent.--merged, --draft, --full-content, --with-comments, --with-commits, --npm-fetch-metadata, --python-fetch-metadata.--limit, --depth, --start-line, --end-line. Non-numeric exits 1.id, mainResearchGoal, researchGoal, reasoning are auto-filled — don't pass them.--json prints compact structuredContent only (no text preamble, no envelope). Byte-equivalent to MCP payload. Pipe into jq.0 on success, 1 on missing flag / bad stdin / validation / tool error.Uses Octocode-stored creds or gh CLI token, in that order.
octocode-cli login # or: gh auth login