Sourcegraph CLI

src is a command line interface to Sourcegraph:

• Search & get results in your terminal
• Search & get JSON for programmatic consumption
• Make GraphQL API requests with auth easily & get JSON back fast
• Execute batch changes
• Manage & administrate repositories, users, and more
• Easily convert src-CLI commands to equivalent curl commands, just add --get-curl!

Installation

Download the latest version from the releases page, or from Sourcegraph.com using the commands below. If the latest version does not work with your Sourcegraph instance, download the version compatible with your Sourcegraph instance, as shown below.

Installation: macOS

Latest version

curl -L https://sourcegraph.com/.api/src-cli/src_darwin_arm64 -o /usr/local/bin/src
chmod +x /usr/local/bin/src

or with Homebrew:

brew install sourcegraph/src-cli/src-cli

or with npm:

npm install -g @sourcegraph/src

Version compatible with your Sourcegraph instance

Replace sourcegraph.example.com with your Sourcegraph instance URL:

curl -L https://sourcegraph.example.com/.api/src-cli/src_darwin_arm64 -o /usr/local/bin/src
chmod +x /usr/local/bin/src

or, if you know the specific version to target:

brew install sourcegraph/src-cli/src-cli@8.1.2687

or with npm/npx:

npx @sourcegraph/src@8.1.2687 version

Installation: Linux

Latest version

curl -L https://sourcegraph.com/.api/src-cli/src_linux_amd64 -o /usr/local/bin/src
chmod +x /usr/local/bin/src

On an ARM host, replace src_linux_amd64 with src_linux_arm64.

or with npm:

npm install -g @sourcegraph/src

Version compatible with your Sourcegraph instance

Replace sourcegraph.example.com with your Sourcegraph instance URL:

curl -L https://sourcegraph.example.com/.api/src-cli/src_linux_amd64 -o /usr/local/bin/src
chmod +x /usr/local/bin/src

or, with npm/npx, if you know the specific version to target:

npx @sourcegraph/src@8.1.2687 version

Installation: Windows

See Sourcegraph CLI for Windows.

Installation: Docker

The sourcegraph/src-cli image on Docker Hub is tagged with latest and with each release version.

docker run --rm=true sourcegraph/src-cli:latest search 'hello world'

Connect to your Sourcegraph instance

src needs the URL of your Sourcegraph instance. Set SRC_ENDPOINT in your shell environment, replacing https://sourcegraph.example.com with your instance URL:

export SRC_ENDPOINT=https://sourcegraph.example.com

For PowerShell on Windows:

$env:SRC_ENDPOINT = 'https://sourcegraph.example.com'

For convenience, add this environment variable to your terminal profile or system environment variables. On macOS and Linux, the terminal profile is typically ~/.zprofile for Zsh or ~/.bash_profile for Bash. On Windows, you can add it through the System Properties window.

If SRC_ENDPOINT is not set, src defaults to https://sourcegraph.com.

OAuth login

Run src login to authenticate interactively with OAuth:

src login

OAuth does not require you to create or export SRC_ACCESS_TOKEN. The OAuth credential is stored in your operating system's native keyring. Keep SRC_ENDPOINT set when running subsequent commands because src uses the endpoint to load the matching OAuth credential.

You can also pass the instance URL directly to src login, but this only selects the endpoint for that login command. You must still set SRC_ENDPOINT when running subsequent commands:

src login https://sourcegraph.example.com

To use the active credential in another command, src auth token prints the raw token and src auth token --header prints a complete Authorization header for the active authentication mode.

Personal access token login

For non-interactive authentication, such as in CI or scripts, create an access token on your Sourcegraph instance under Settings > Access tokens, then set both SRC_ENDPOINT and SRC_ACCESS_TOKEN:

export SRC_ENDPOINT=https://sourcegraph.example.com
export SRC_ACCESS_TOKEN=my-token

For PowerShell on Windows:

$env:SRC_ENDPOINT = 'https://sourcegraph.example.com'
$env:SRC_ACCESS_TOKEN = 'my-token'

When SRC_ACCESS_TOKEN is set, src uses it instead of an OAuth credential and running src login is not necessary. You can also set both variables for a single command:

SRC_ENDPOINT=https://sourcegraph.example.com SRC_ACCESS_TOKEN=my-token src search 'foo'

Is your Sourcegraph instance behind a custom auth proxy? See auth proxy configuration docs.

Usage

src provides different subcommands to interact with different parts of Sourcegraph:

• src abc - manage agentic batch changes
• src api - run Sourcegraph GraphQL API requests
• src auth - print the active authentication token or authorization header
• src batch - execute and manage batch changes
• src code-intel - manage code intelligence data
• src codeowners - manage ingested code ownership data
• src config - manage global, org, and user settings
• src debug - gather and bundle debug data from a Sourcegraph deployment for troubleshooting
• src extsvc - manage external services (repository configuration)
• src login - authenticate to a Sourcegraph instance with your user credentials
• src lsp - run a Language Server Protocol server that proxies requests to Sourcegraph code intelligence
• src orgs - manage organizations
• src repos - manage repositories
• src search - perform searches and get results in your terminal or as JSON
• src search-jobs - manage search jobs
• src serve-git - serve your local git repositories over HTTP for Sourcegraph to pull
• src snapshot - manage snapshots of Sourcegraph instance databases (experimental)
• src users - manage users
• src version - display and compare the src version against the recommended version for your Sourcegraph instance

Run src -h and src <subcommand> -h for more detailed usage information. You can also read the usage docs for the latest version of src-cli online.

Optional: Renaming src

If you have a naming conflict with the src command, such as a Bash alias, you can rename the static binary. For example, on Linux / macOS:

mv /usr/local/bin/src /usr/local/bin/src-cli

You can then invoke it via src-cli.

Timeouts

src waits up to 1 minute for the server to start responding to a request. To change this, set the SRC_RESPONSE_HEADER_TIMEOUT environment variable to a duration such as 30s or 10m, or to 0 to disable the timeout. This timeout only applies until the server sends its response headers — responses that stream data for a long time, such as large search job results, are not interrupted.

Telemetry

src includes the operating system and architecture in the User-Agent header sent to Sourcegraph. For example, running src on an x86-64 Linux host will result in this header:

src-cli/8.1.2687 linux amd64

To disable this and only send the version, you can set -user-agent-telemetry=false for a single command, or set the SRC_DISABLE_USER_AGENT_TELEMETRY environment variable to any non-blank string.

As with other Sourcegraph telemetry, any collected data is only sent to Sourcegraph.com in aggregate form.

Development

Some useful notes on developing src can be found in DEVELOPMENT.md.