CLI options

Use this page as a reference for all commands and flags when running the tool from your terminal or CI pipelines.

Commands

github-code-search <query> --org <org> [options]   # default (backward-compatible)
github-code-search query <query> --org <org> [options]
github-code-search upgrade [--debug]
github-code-search completions [--shell <shell>]

Command	Description
<query> / query <query>	Search GitHub code (default command)
upgrade	Check for a new release and auto-upgrade the binary
completions	Print a shell completion script for bash, zsh or fish to stdout

Upgrade options

Option	Type	Default	Description
--debug	boolean (flag)	false	Print verbose diagnostics: resolved binary path, available release assets, selected asset, HTTP response status, downloaded byte count, and result of each file operation (write, chmod, mv, xattr).

Completions options

Option	Type	Default	Description
--shell <shell>	bash | zsh | fish	auto-detected	Target shell for the completion script. When omitted, the shell is detected from $SHELL. If detection fails, the command exits with an error listing the valid values.

Search options

Option	Type	Required	Default	Description
--org <org>	string	✅	—	GitHub organization to search in. Automatically injected as org:<org> in the query.
--exclude-repositories <repos>	string	❌	""	Comma-separated list of repositories to exclude. Short form (repoA,repoB) or full form (org/repoA,org/repoB) both accepted.
--exclude-extracts <refs>	string	❌	""	Comma-separated extract refs to exclude. Format: repoName:path/to/file:index. Short form (without org prefix) accepted.
--no-interactive	boolean (flag)	❌	true (on)	Disable interactive mode. Interactive mode is on by default; pass this flag to disable it. Also triggered by CI=true.
--format <format>	markdown | json	❌	markdown	Output format. See Output formats.
--output-type <type>	repo-and-matches | repo-only	❌	repo-and-matches	Controls output detail level. repo-only lists repository names only, without individual extracts.
--include-archived	boolean (flag)	❌	false	Include archived repositories in results (excluded by default).
--group-by-team-prefix <prefixes>	string	❌	""	Comma-separated team-name prefixes for grouping result repos by GitHub team (e.g. squad-,chapter-). Requires read:org scope.
--no-cache	boolean (flag)	❌	true (on)	Bypass the 24 h team-list cache and re-fetch teams from GitHub. Cache is on by default; pass this flag to disable it. Only applies with --group-by-team-prefix.

Global options

Option	Description
-V, --version	Output version, git commit SHA, OS and architecture
-h, --help	Display help

Notes

• --no-interactive and CI=true are equivalent — either one disables the TUI.
• The --exclude-repositories and --exclude-extracts options accept both the short form (without org prefix) and the full org/repo form.
• --no-cache has no effect unless --group-by-team-prefix is also set.
• The upgrade subcommand does not require --org or GITHUB_TOKEN (token is used only if already set, to avoid rate limiting).
• After a successful upgrade, existing completion files are refreshed automatically. New files are never created by upgrade — use completions or install.sh for initial installation.
• The completions subcommand prints to stdout; pipe it to a file or source it in your shell's config to enable tab completion.