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!
Note: Using Sourcegraph 3.12 or earlier? See the older README.
Installation
Binary downloads are available on the releases tab, and through Sourcegraph.com. If the latest version does not work for you, consider using the version compatible with your Sourcegraph instance instead.
Installation: Mac OS
Latest version
curl -L https://sourcegraph.com/.api/src-cli/src_darwin_amd64 -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_amd64 -o /usr/local/bin/src
chmod +x /usr/local/bin/src
or, if you know the specific version to target, for example 3.43.2:
brew install sourcegraph/src-cli/[email protected]
or with npm/npx:
npx @sourcegraph/[email protected] version
Note: Versioned formulas are available on Homebrew for Sourcegraph versions 3.43.2 and later.
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
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, for example 3.43.2:
npx @sourcegraph/[email protected] version
Installation: Windows
See Sourcegraph CLI for Windows.
Installation: Docker
sourcegraph/src-cli
is published to Docker Hub. You can use the latest
tag or a specific version such as 3.43
. To see all versions view sourcegraph/src-cli tags.
docker run --rm=true sourcegraph/src-cli:latest search 'hello world'
Log into your Sourcegraph instance
Run src login SOURCEGRAPH-URL
to authenticate src
to access your Sourcegraph instance with your user credentials.
Examples
src login https://sourcegraph.example.com
src login https://sourcegraph.com
src
consults the following environment variables:
SRC_ENDPOINT
: the URL to your Sourcegraph instance (such ashttps://sourcegraph.example.com
)SRC_ACCESS_TOKEN
: your Sourcegraph access token (on your Sourcegraph instance, click your user menu in the top right, then select Settings > Access tokens to create one)
For convenience, you can add these environment variables persistently.
Configuration: Mac OS / Linux
Add the following to your terminal profile file, typically accessible at ~/.bash_profile
(if using Bash) or ~/.zprofile
(if using Zsh):
export SRC_ACCESS_TOKEN=my-token
export SRC_ENDPOINT=https://sourcegraph.example.com
Replace my-token
and https://sourcegraph.example.com
with the appropriate values for your account and instance.
You can also inline them in a single command with:
SRC_ENDPOINT=https://sourcegraph.example.com SRC_ACCESS_TOKEN=my-token src search 'foo'
Configuration: Windows
Type the following on your PowerShell terminal:
$env.SRC_ENDPOINT = 'https://sourcegraph.example.com'
$env.SRC_ACCESS_TOKEN = 'my-token'
Replace my-token
and https://sourcegraph.example.com
with the appropriate values for your account and instance.
You can also manually add them via the System Properties windows. Check this post for details.
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 login
- authenticate to a Sourcegraph instance with your user credentialssrc search
- perform searches and get results in your terminal or as JSONsrc api
- run Sourcegraph GraphQL API requestssrc batch
- execute and manage batch changessrc repos
- manage repositoriessrc users
- manage userssrc orgs
- manages organizationsrc config
- manage global, org, and user settingssrc extsvc
- manage external services (repository configuration)src extensions
- manage extensionssrc code-intel
- manages Code Intelligence data (deprecated alias:src lsif
)src serve-git
- serves your local git repositories over HTTP for Sourcegraph to pullsrc version
- check version and guaranteed-compatible 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.
src
Optional: Renaming 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 / Mac OS:
mv /usr/local/bin/src /usr/local/bin/src-cli
You can then invoke it via src-cli
.
Telemetry
src
includes the operating system and architecture in the User-Agent
header sent to Sourcegraph. For example, running src
version 3.21.10 on an x86-64 Linux host will result in this header:
src-cli/3.21.10 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.