CLI
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, 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.
sourcegraph-cli <command> [flags] [arguments]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.
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.
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.
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.
Examples
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>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 — 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.
CLI
sourcegraph-cli 是一个小巧、有边界的 Source Graph 实例 HTTP 客户端。每次调用只向 HTTP 与 MCP 接口 中描述的路由发送一个请求，打印 JSON 响应后退出；它从不克隆仓库，也不安装任何东西。它与服务一起构建到 output/bin/ 中，并包含在容器镜像里。
sourcegraph-cli <command> [flags] [arguments]环境变量
| 变量 | 默认值 | 规则 |
|---|---|---|
SOURCEGRAPH_URL | https://context4ai.org/sourcegraph | 实例的 /sourcegraph 基础地址。必须是 HTTPS URL，且不含用户信息、查询参数或片段 |
SOURCEGRAPH_API_TOKEN | — | 可选的 Bearer 凭据——个人 API Key 或服务令牌。设置时至少 32 个字符 |
由于地址必须是 HTTPS，运行在 http://localhost 上的本地实例需要在前面加一个负责 TLS 终止的代理，才能供 CLI 使用。
命令
| 命令 | 路由 | 使用的参数 |
|---|---|---|
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；之后是 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 |
没有 read_many 命令；请多次调用 read，或使用对应的 MCP 工具。diff 会比较所有已登记的路径，prepare 则作用于所有路径组。prepare 属于管理路由，因此需要服务令牌。
参数
参数采用 Go 语法：前面加一个或两个短横线都可以（-repo 或 --repo），并且所有参数都必须放在位置参数之前。
| 参数 | 默认值 | 含义 |
|---|---|---|
-repo | — | 仓库键，格式为 owner/repository |
-revision | — | 监控分支或完整 SHA；省略时使用默认分支。对 prepare 而言，表示要准备的提交 |
-e | — | 搜索模式，类似 rg -e；不指定时取第一个位置参数 |
-F | false | 将模式作为字面量匹配，类似 rg -F |
-i | false | 忽略大小写，类似 rg -i |
-l | false | 只打印匹配的路径，类似 rg -l |
-g | — | 按 glob 包含文件，或用 ! 排除文件，类似 rg -g；可重复指定 |
-path | — | 相对仓库根目录的文件或目录 |
-start-line | 1 | 读取的起始行 |
-end-line | 100 | 读取的结束行 |
-first | 100 | list（1–1000）和 diff（1–100）的分页大小 |
-after | — | 上一页返回的游标 |
-base、-head | — | diff 比较的两个版本 |
-key | — | prepare 的幂等键，以 Idempotency-Key 发送 |
-kind | index | prepare 的类型：index 或 sync |
搜索模式之后的参数是限定搜索范围的目录，类似 rg 的 PATH 参数。
输出与退出码
CLI 会把响应体（始终是 JSON）原样写到标准输出，上限为 3 MiB，诊断信息则写到标准错误。每个请求的超时时间为 35 秒，并且拒绝重定向。
| 退出码 | 含义 |
|---|---|
0 | 成功 |
1 | 请求失败、超时、返回的响应体无效或过大，或状态码不是 2xx |
2 | 用法错误：未知命令、参数错误、缺少搜索模式、SOURCEGRAPH_URL 或令牌无效 |
3 | 已受理但尚未就绪——202 Accepted 或 409 INDEX_NOT_READY |
超时后无法确定请求是否已送达；重试 prepare 之前，请先用 availability 检查。
示例
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>Git 凭据助手
git-credential-sourcegraph 供服务自身使用，而不是给人使用的。每次执行 Git 拉取时，服务会选择一个凭据——仓库创建者存储的凭据、全局凭据，或旧版的 SOURCEGRAPH_GIT_TOKEN 值，详见 登记仓库——并通过该 Git 进程的 SOURCEGRAPH_GIT_TOKEN 环境变量传给凭据助手。凭据助手只响应 Git 的 get 操作，且只处理发往 github.com 的 HTTPS 请求，把令牌作为密码返回；当令牌为空，或包含换行符或 NUL 字符时，它不输出任何内容。