From fb2f84b06b55196d2de97b911651e48557b4df31 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20HOUZ=C3=89?= Date: Sat, 19 Sep 2026 13:08:07 +0200 Subject: [PATCH] Add GCS_DEFAULT_ORG env var to avoid repeating --org on every invocation --org is now a regular Commander option using .env("GCS_DEFAULT_ORG") for CLI > env var precedence, instead of requiredOption. searchAction validates presence explicitly and exits with a clear error when neither is set. Closes #207 --- README.md | 4 ++++ docs/getting-started/first-search.md | 2 +- docs/getting-started/index.md | 15 +++++++++++++++ docs/reference/cli-options.md | 3 ++- docs/reference/environment.md | 12 ++++++++++++ github-code-search.ts | 23 ++++++++++++++++++++--- 6 files changed, 54 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 5344269..0270c72 100644 --- a/README.md +++ b/README.md @@ -35,6 +35,10 @@ powershell -c "irm https://raw.githubusercontent.com/fulll/github-code-search/ma github-code-search query "TODO" --org my-org ``` +> [!TIP] +> `GITHUB_TOKEN` falls back to `gh auth token` when unset and the [GitHub CLI](https://cli.github.com/) is installed and authenticated. +> Set `GCS_DEFAULT_ORG=my-org` to omit `--org` on every call. See [Environment variables](https://fulll.github.io/github-code-search/reference/environment). + ## Features - **Org-wide search** — queries all repositories in a GitHub organization in one command, with automatic pagination up to 1 000 results diff --git a/docs/getting-started/first-search.md b/docs/getting-started/first-search.md index 49e35c9..f5032f8 100644 --- a/docs/getting-started/first-search.md +++ b/docs/getting-started/first-search.md @@ -7,7 +7,7 @@ This guide walks through a complete search session from first invocation to stru Make sure you have: - `github-code-search` [installed](/getting-started/installation) -- `GITHUB_TOKEN` set in your environment ([see Prerequisites](/getting-started/)) +- `GITHUB_TOKEN` set in your environment, or the [GitHub CLI](https://cli.github.com/) installed and authenticated ([see Prerequisites](/getting-started/)) ## Run a search diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md index 2cf6490..48d1168 100644 --- a/docs/getting-started/index.md +++ b/docs/getting-started/index.md @@ -35,6 +35,21 @@ Add this to your shell profile (`~/.zshrc`, `~/.bashrc`, `~/.config/fish/config. Never commit your token to version control. Use environment variables or a secrets manager. ::: +::: tip Already using the GitHub CLI? +If `GITHUB_TOKEN` isn't set and [`gh`](https://cli.github.com/) is installed and authenticated (`gh auth login`), `github-code-search` automatically retrieves a token via `gh auth token` — no extra setup needed. +::: + +## Default organization + +If you mostly search a single organization, set `GCS_DEFAULT_ORG` once to omit `--org` on every call: + +```bash +export GCS_DEFAULT_ORG=my-org +github-code-search "useFeatureFlag" +``` + +An explicit `--org` flag always takes precedence over `GCS_DEFAULT_ORG`. See [Environment variables](/reference/environment) for details. + ## Next step → [Install github-code-search](/getting-started/installation) diff --git a/docs/reference/cli-options.md b/docs/reference/cli-options.md index ad49d29..ec3c756 100644 --- a/docs/reference/cli-options.md +++ b/docs/reference/cli-options.md @@ -33,7 +33,7 @@ github-code-search completions [--shell ] | Option | Type | Required | Default | Description | | ------------------------------------ | --------------------------------- | -------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `--org ` | string | ✅ | — | GitHub organization to search in. Automatically injected as `org:` in the query. | +| `--org ` | string | ❌¹ | — | GitHub organization to search in. Automatically injected as `org:` in the query. Falls back to the `GCS_DEFAULT_ORG` environment variable when omitted. See [Environment variables](/reference/environment#gcs_default_org). | | `--exclude-repositories ` | string | ❌ | `""` | Comma-separated list of repositories to exclude. Short form (`repoA,repoB`) or full form (`org/repoA,org/repoB`) both accepted. | | `--exclude-extracts ` | 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`. | @@ -57,6 +57,7 @@ github-code-search completions [--shell ] ## Notes +- ¹ `--org` is required unless the `GCS_DEFAULT_ORG` environment variable is set. An explicit `--org` always takes precedence. - `--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. diff --git a/docs/reference/environment.md b/docs/reference/environment.md index 6fbec1a..ecb12c8 100644 --- a/docs/reference/environment.md +++ b/docs/reference/environment.md @@ -7,6 +7,7 @@ | Variable | Required | Default | Description | | ------------------------------ | -------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `GITHUB_TOKEN` | ✅ | — | GitHub personal access token. Used to authenticate API calls. See [Prerequisites](/getting-started/). | +| `GCS_DEFAULT_ORG` | ❌ | — | Default value for `--org` when the flag is omitted. An explicit `--org` always takes precedence. See [CLI options](/reference/cli-options). | | `CI` | ❌ | `false` | Set to `true` to disable the interactive TUI and print results directly to stdout. Automatically set by GitHub Actions, GitLab CI, CircleCI and most CI platforms. | | `GITHUB_CODE_SEARCH_CACHE_DIR` | ❌ | OS-dependent (below) | Override the directory used to cache the team list when `--group-by-team-prefix` is set. | @@ -24,6 +25,17 @@ Add this to your shell profile (`~/.zshrc`, `~/.bashrc`, `~/.config/fish/config. | `public_repo` | Searching public repositories only | | `read:org` | Using [`--group-by-team-prefix`](/usage/team-grouping) | +If `GITHUB_TOKEN` isn't set and the [GitHub CLI](https://cli.github.com/) (`gh`) is installed and authenticated, `github-code-search` automatically falls back to the token returned by `gh auth token` — no extra configuration needed. + +## `GCS_DEFAULT_ORG` + +```bash +export GCS_DEFAULT_ORG=my-org +github-code-search "useFeatureFlag" # --org my-org is implied +``` + +Useful when you mostly (or only) search a single organization — set it once in your shell profile and omit `--org` on every call. Passing `--org` explicitly always overrides it. + ## `CI` ```bash diff --git a/github-code-search.ts b/github-code-search.ts index cbee9b3..bfbb69d 100644 --- a/github-code-search.ts +++ b/github-code-search.ts @@ -12,7 +12,7 @@ * GITHUB_TOKEN env var must be set (for search; optional for upgrade). */ -import { Command, program } from "commander"; +import { Command, Option, program } from "commander"; import { writeFileSync } from "node:fs"; import { resolve } from "node:path"; import * as style from "./src/style.ts"; @@ -138,7 +138,15 @@ const helpFormatConfig = { function addSearchOptions(cmd: Command): Command { return cmd .argument("", "Search query") - .requiredOption("--org ", "GitHub organization to search in") + .addOption( + new Option( + "--org ", + [ + "GitHub organization to search in.", + "Falls back to the GCS_DEFAULT_ORG environment variable when omitted.", + ].join("\n"), + ).env("GCS_DEFAULT_ORG"), + ) .option( "--exclude-repositories ", [ @@ -256,7 +264,7 @@ function addSearchOptions(cmd: Command): Command { async function searchAction( query: string, opts: { - org: string; + org?: string; excludeRepositories: string; excludeExtracts: string; interactive: boolean; @@ -279,6 +287,15 @@ async function searchAction( process.exit(1); } + if (!opts.org) { + console.error( + style.red( + "Error: --org is required (set the --org flag or the GCS_DEFAULT_ORG environment variable).", + ), + ); + process.exit(1); + } + // Fail fast on unbalanced quotes rather than surfacing a raw GitHub 422 — see issue #149 const quoteError = validateQuoteBalance(query); if (quoteError) {