cli-codebase-ctx

cli-codebase-ctx — repo context and code search CLI for humans and agents.

Requirements

• Go 1.21+
• ripgrep (rg) — optional

Ignore Configuration

Search (both ripgrep and the pure-Go fallback) respects:

• .gitignore at the project root.
• .codebase-ctxignore at the project root (optional). One glob or path pattern per line; lines starting with # are comments. Use this to hide extra paths from search and reduce noise/token usage (e.g. *.min.js, dist/).

Install (Local)

From the project root:

go build -o cli-codebase-ctx .

Or install into $GOPATH/bin (or $GOBIN):

go install .

On Windows the binary will be cli-codebase-ctx.exe when built in-repo.

Run

Global flags (apply to all commands except completion and mcp-server):

• --project-root — project root directory (default: current directory)
• --output — output format: text or json (default: text; defaults to json when stdout is not a TTY)

All commands:

# Root: show help (text) or command tree (JSON)
./cli-codebase-ctx
./cli-codebase-ctx --output json

# Structure: directory tree and key files
./cli-codebase-ctx structure [--depth N] [--max-tree-lines N] [--max-key-files N]

# Runnable: list runnable commands from package.json, Makefile, go.mod
./cli-codebase-ctx runnable [--max-commands N]

# Env: env vars from .env.example / .env.sample
./cli-codebase-ctx env [--max-vars N]

# OpenAPI: summarize spec from URL
./cli-codebase-ctx openapi --url <URL> [--stream]

# Search: ignore-aware code search
./cli-codebase-ctx search PATTERN [--glob GLOB] [--type TYPE] [--max-matches N] [--stream]

# Completion: generate shell completion script
./cli-codebase-ctx completion bash|zsh|fish|powershell

# MCP server: run Model Context Protocol server over stdio
./cli-codebase-ctx mcp-server

# Help: help for any command
./cli-codebase-ctx help [command]

Commands Summary

Command	Purpose	Key flags / args	Output
(root)	Show help or (with --output json) command tree for agents	—	Text (usage) or JSON (tree)
structure	Directory tree + key files	--depth (default 3), --max-tree-lines, --max-key-files	Text, JSON
runnable	List runnable commands	--max-commands (default 200)	Text, JSON
env	Env vars from .env.example	--max-vars (default 200)	Text, JSON
openapi	OpenAPI spec summary	--url (required), --stream	Text, JSON
search	Search codebase	PATTERN (required), --glob, --type, --max-matches (default 100), --stream	Text, JSON
completion	Generate shell completion	One of: bash, zsh, fish, powershell	Script to stdout
mcp-server	Run MCP server over stdio	—	Listens on stdin/stdout
help	Help for any command	Optional: command name	Text (usage)

Use --output json for scriptable/agent output (or rely on auto JSON when piping).

All Commands And Expected Outcome

• cli-codebase-ctx (no subcommand)

  • Text (--output text or default in a terminal): prints usage/help.
  • JSON (--output json): prints a single JSON object with ok, command, result.description, result.commands (list of subcommands with name, use, short), result.global_flags.
  • Exit: 0.

• cli-codebase-ctx structure [--depth N] [--max-tree-lines N] [--max-key-files N]

  • Text: directory tree (depth-limited) and a “Key files: …” line. If truncated, a note about --max-tree-lines / --max-key-files.
  • JSON: ok, command, result with tree, keyFiles, totalTreeLines, shownTreeLines, treeTruncated, totalKeyFiles, shownKeyFiles, keyFilesTruncated, plus next_actions, token_estimate.
  • Exit: 0 on success; non-zero on error (e.g. invalid --project-root), with error/fix on stderr.

• cli-codebase-ctx runnable [--max-commands N]

  • Text: one line per runnable (name (source): script or name (source)). If truncated, a note about --max-commands.
  • JSON: ok, command, result with commands, showing, total, truncated, plus next_actions, token_estimate.
  • Exit: 0 on success; non-zero on error, with error envelope on stderr when --output json.

• cli-codebase-ctx env [--max-vars N]

  • Text: one line per env var (KEY=comment or KEY=), or “No env vars found…” if none. If truncated, a note about --max-vars.
  • JSON: ok, command, result with vars, showing, total, truncated, plus next_actions, token_estimate.
  • Exit: 0 on success; non-zero on error, with error envelope on stderr when --output json.

• cli-codebase-ctx openapi --url <URL> [--stream]

  • Text: table of method, path, operationId; then “Schemas: …”.
  • JSON: ok, command, result with operations, schemas, plus next_actions, token_estimate. With --stream, NDJSON lines (e.g. type: start, type: progress, type: result with envelope).
  • Exit: 0 on success; non-zero on missing/invalid URL or fetch/parse error, with error envelope on stderr when --output json.

• cli-codebase-ctx search PATTERN [--glob GLOB] [--type TYPE] [--max-matches N] [--stream]

  • Text: lines path:line:snippet. If truncated, a note about --max-matches.
  • JSON: ok, command, result with matches, showing, total, truncated, and optionally full_output (temp file path when truncated), plus next_actions, token_estimate. With --stream, NDJSON lines then a final result envelope.
  • Exit: 0 on success; non-zero on error (e.g. bad regex), with error envelope on stderr when --output json.

• cli-codebase-ctx completion bash|zsh|fish|powershell

  • Outcome: writes the completion script for the given shell to stdout. No JSON.
  • Exit: 0 on success; non-zero for unsupported shell.

• cli-codebase-ctx mcp-server

  • Outcome: starts the MCP server; reads JSON-RPC from stdin and writes responses to stdout. Exposes tools: structure, runnable, env, openapi_summary, search.
  • Exit: 0 when the client closes the connection; non-zero on run error.

• cli-codebase-ctx help [command]

  • Outcome: prints usage/help for the root or the given command.
  • Exit: 0.

Exit Codes

• 0 — success
• Non-zero — failure. Errors are printed to stderr; with --output json, errors are a JSON envelope (ok: false, error, fix, next_actions) on stderr.

Shell Completions

Generate and install shell completions:

Bash

./cli-codebase-ctx completion bash > cli-codebase-ctx.bash
# System-wide:
sudo cp cli-codebase-ctx.bash /etc/bash_completion.d/
# Or user-only:
mkdir -p ~/.local/share/bash-completion/completions
cp cli-codebase-ctx.bash ~/.local/share/bash-completion/completions/cli-codebase-ctx

Zsh

./cli-codebase-ctx completion zsh >> _cli-codebase-ctx
# Then add to your fpath and ensure compinit is run, or copy to a site-functions dir.

Fish

./cli-codebase-ctx completion fish >> ~/.config/fish/completions/cli-codebase-ctx.fish

PowerShell

./cli-codebase-ctx completion powershell > cli-codebase-ctx.ps1
# Add to your profile: . C:\path\to\cli-codebase-ctx.ps1
Add-Content $PROFILE ". C:\path\to\cli-codebase-ctx.ps1"

Project Layout

• cmd/ — Cobra commands and CLI wiring (root, structure, runnable, env, openapi, search, completion, mcp-server).
• internal/ — Private packages; business logic:
  • internal/project — project root, structure, manifests, runnable, env
  • internal/search — code search (ripgrep + pure-Go fallback)
  • internal/openapi — OpenAPI summary (2.0 and 3.x)
  • internal/output — text/JSON envelopes and error formatting
  • internal/tokens — token estimation for agent output
  • internal/mcp — MCP server (structure, runnable, env, openapi_summary, search tools)
  • internal/config — optional config