# CLI



<a id="section-goal"></a>

`sourcegraph-cli` is a small, bounded HTTP client for a Source Graph instance. It sends one request per invocation to the routes described in [HTTP and MCP](</context/llms/pages/a8fe02c341a72e370f653228d71e9982.txt>), prints the JSON response and exits; it never clones repositories or installs anything. It is built with the service into `output/bin/` and is included in the container image.

```text
sourcegraph-cli <command> [flags] [arguments]
```


<a id="section-env"></a>

## Environment

| Variable | Default | Rules |
| --- | --- | --- |
| `SOURCEGRAPH_URL` | `https://context4ai.org/sourcegraph` | The instance's `/sourcegraph` base address. Must be an HTTPS URL without user information, query or fragment |
| `SOURCEGRAPH_API_TOKEN` | — | Optional bearer credential — a personal API key or the service token. At least 32 characters when set |

Because the address must be HTTPS, a local instance on `http://localhost` needs a TLS-terminating proxy in front of it for CLI use.


<a id="section-commands"></a>

## Commands

| Command | Route | Flags used |
| --- | --- | --- |
| `repositories` | `GET /v1/repos` | `-after` |
| `availability` | `GET /v1/repo/availability` | `-repo` |
| `resolve` | `POST /v1/repo/resolve` | `-repo`, `-revision` |
| `search` | `POST /api/search` | `-repo`, `-revision`, `-e`, `-F`, `-i`, `-l`, `-g`; then `PATTERN [PATH...]` |
| `read` | `POST /v1/repo/read` | `-repo`, `-revision`, `-path`, `-start-line`, `-end-line` |
| `list` | `POST /v1/repo/list` | `-repo`, `-revision`, `-path`, `-first`, `-after` |
| `diff` | `POST /v1/repo/diff` | `-repo`, `-base`, `-head`, `-first`, `-after` |
| `prepare` | `POST /api/admin/v1/repo/prepare` | `-repo`, `-revision`, `-kind`, `-key` |

There is no `read_many` command; use several `read` calls or the MCP tool. `diff` compares all registered paths, and `prepare` targets all path groups. `prepare` is a management route, so it needs the service token.


<a id="section-flags"></a>

## Flags

Flags use Go syntax: one or two leading dashes both work (`-repo` or `--repo`), and every flag must come before positional arguments.

| Flag | Default | Meaning |
| --- | --- | --- |
| `-repo` | — | Repository key, `owner/repository` |
| `-revision` | — | A monitored branch or a full SHA; omitted means the default branch. For `prepare`, the commit to prepare |
| `-e` | — | Search pattern, like `rg -e`; otherwise the first positional argument |
| `-F` | `false` | Match the pattern as literal text, like `rg -F` |
| `-i` | `false` | Ignore case, like `rg -i` |
| `-l` | `false` | Print only matching paths, like `rg -l` |
| `-g` | — | Include, or `!`-exclude, files by glob, like `rg -g`; repeatable |
| `-path` | — | Repository-relative file or directory |
| `-start-line` | `1` | First line to read |
| `-end-line` | `100` | Last line to read |
| `-first` | `100` | Page size for `list` (1–1000) and `diff` (1–100) |
| `-after` | — | Cursor from the previous page |
| `-base`, `-head` | — | The two revisions for `diff` |
| `-key` | — | Idempotency key sent as `Idempotency-Key` for `prepare` |
| `-kind` | `index` | `index` or `sync`, for `prepare` |

Search arguments after the pattern are directories to search within, like `rg`'s `PATH` arguments.


<a id="section-output"></a>

## Output and exit codes

The CLI writes the response body — always JSON — to standard output unchanged, up to 3 MiB, and diagnostics to standard error. Each request has a 35-second timeout, and redirects are refused.

| Exit code | Meaning |
| --- | --- |
| `0` | Success |
| `1` | Request failed, timed out, returned an invalid or oversized body, or a non-2xx status |
| `2` | Usage error: unknown command, bad flags, missing pattern, invalid `SOURCEGRAPH_URL` or token |
| `3` | Accepted but not ready yet — `202 Accepted`, or `409 INDEX_NOT_READY` |

After a timeout, delivery is unknown; inspect `availability` before retrying a `prepare`.


<a id="section-examples"></a>

## Examples

```bash
export SOURCEGRAPH_URL="https://context4ai.org/sourcegraph"

# Literal search in TypeScript files under packages/
sourcegraph-cli search -repo context4ai/context -F -g '*.ts' 'defineProject' packages

# Read lines 1–40 at the commit returned in Meta.Commit
sourcegraph-cli read -repo context4ai/context -revision <commit> -path README.md -end-line 40

# List the repository root
sourcegraph-cli list -repo context4ai/context -first 50

# Ask an instance you administer to index a commit (service token required)
SOURCEGRAPH_API_TOKEN=... sourcegraph-cli prepare -repo acme/app -revision <full-sha> -key index-<full-sha>
```


<a id="section-helper"></a>

## Git credential helper

`git-credential-sourcegraph` is used by the service itself, not by people. For every Git fetch, the service selects a credential — the repository creator's stored credential, the global one, or the legacy `SOURCEGRAPH_GIT_TOKEN` value, as described in [Registering Repositories](</context/llms/pages/aa50227a56841f0d42fe08e9dfa4cd53.txt>) — and passes it to the helper through the `SOURCEGRAPH_GIT_TOKEN` environment variable of that Git process. The helper answers only Git's `get` action and only for HTTPS requests to `github.com`, returning the token as the password; it prints nothing when the token is empty or contains line breaks or NUL characters.

---

## Sources

- [sourcegraph/cmd/sourcegraph-cli/main.go L1–L28 · 4e5c555](<https://github.com/context4ai/sourcegraph/blob/4e5c5552394f4c16e050ae3185aad585fb07785d/cmd/sourcegraph-cli/main.go#L1-L28>)
- [sourcegraph/DEVELOPMENT.md L24–L24 · 4e5c555](<https://github.com/context4ai/sourcegraph/blob/4e5c5552394f4c16e050ae3185aad585fb07785d/DEVELOPMENT.md#L24-L24>)
- [sourcegraph/Dockerfile L20–L28 · 4e5c555](<https://github.com/context4ai/sourcegraph/blob/4e5c5552394f4c16e050ae3185aad585fb07785d/Dockerfile#L20-L28>)
- [sourcegraph/cmd/sourcegraph-cli/main.go L50–L63 · 4e5c555](<https://github.com/context4ai/sourcegraph/blob/4e5c5552394f4c16e050ae3185aad585fb07785d/cmd/sourcegraph-cli/main.go#L50-L63>)
- [sourcegraph/cmd/sourcegraph-cli/main.go L64–L125 · 4e5c555](<https://github.com/context4ai/sourcegraph/blob/4e5c5552394f4c16e050ae3185aad585fb07785d/cmd/sourcegraph-cli/main.go#L64-L125>)
- [sourcegraph/cmd/sourcegraph-cli/main.go L29–L49 · 4e5c555](<https://github.com/context4ai/sourcegraph/blob/4e5c5552394f4c16e050ae3185aad585fb07785d/cmd/sourcegraph-cli/main.go#L29-L49>)
- [sourcegraph/cmd/sourcegraph-cli/main.go L78–L99 · 4e5c555](<https://github.com/context4ai/sourcegraph/blob/4e5c5552394f4c16e050ae3185aad585fb07785d/cmd/sourcegraph-cli/main.go#L78-L99>)
- [sourcegraph/cmd/sourcegraph-cli/main.go L126–L162 · 4e5c555](<https://github.com/context4ai/sourcegraph/blob/4e5c5552394f4c16e050ae3185aad585fb07785d/cmd/sourcegraph-cli/main.go#L126-L162>)
- [sourcegraph/web/assets/clients.js L1–L21 · 4e5c555](<https://github.com/context4ai/sourcegraph/blob/4e5c5552394f4c16e050ae3185aad585fb07785d/web/assets/clients.js#L1-L21>)
- [sourcegraph/cmd/git-credential-sourcegraph/main.go L1–L36 · 4e5c555](<https://github.com/context4ai/sourcegraph/blob/4e5c5552394f4c16e050ae3185aad585fb07785d/cmd/git-credential-sourcegraph/main.go#L1-L36>)
- [sourcegraph/internal/gitstore/fetch.go L146–L152 · 4e5c555](<https://github.com/context4ai/sourcegraph/blob/4e5c5552394f4c16e050ae3185aad585fb07785d/internal/gitstore/fetch.go#L146-L152>)
- [sourcegraph/internal/codecredentials/manager.go L203–L240 · 4e5c555](<https://github.com/context4ai/sourcegraph/blob/4e5c5552394f4c16e050ae3185aad585fb07785d/internal/codecredentials/manager.go#L203-L240>)