Quick links: Installation, Setup (Authentication), Usage

The Sourcegraph src CLI provides access to Sourcegraph via a command-line interface.

It currently provides the ability to:

• Execute search queries from the command line and get nice colorized output back (or JSON, optionally).
• Execute GraphQL queries against a Sourcegraph instance, and get JSON results back (src api).
  • You can provide your API access token via an environment variable or file on disk.
  • You can easily convert a src api command into a curl command with src api -get-curl.
• Manage repositories, users, and organizations using the src repos, src users, and src orgs commands.

If there is something you'd like to see Sourcegraph be able to do from the CLI, let us know! :)

NOTE: To get the best version for your Sourcegraph instance, simply replace sourcegraph.com in the commands below with your own Sourcegraph URL and the latest version compatible with your instance will be provided. If you are running a Sourcegraph version older than 3.13, run the commands below instead.

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

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

NOTE: Windows support is still rough around the edges, but is available. If you encounter issues, please let us know by filing an issue :)

Run in PowerShell as administrator:

New-Item -ItemType Directory 'C:\Program Files\Sourcegraph'
Invoke-WebRequest https://sourcegraph.com/.api/src-cli/src_windows_amd64.exe -OutFile 'C:\Program Files\Sourcegraph\src.exe'
[Environment]::SetEnvironmentVariable('Path', [Environment]::GetEnvironmentVariable('Path', [EnvironmentVariableTarget]::Machine) + ';C:\Program Files\Sourcegraph', [EnvironmentVariableTarget]::Machine)
$env:Path += ';C:\Program Files\Sourcegraph'

Or manually:

• Download the latest src_windows_amd64.exe: https://sourcegraph.com/.api/src-cli/src_windows_amd64.exe and rename to src.exe.
• Place the file under e.g. C:\Program Files\Sourcegraph\src.exe
• Add that directory to your system path to access it from any command prompt

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/sourcegraph-cli

You can then invoke it via sourcegraph-cli.

If you want to use src with your own Sourcegraph instance set the SRC_ENDPOINT environment variable:

SRC_ENDPOINT=https://sourcegraph.example.com src search

Some Sourcegraph instances will be configured to require authentication. You can do so via the environment:

SRC_ENDPOINT=https://sourcegraph.example.com SRC_ACCESS_TOKEN="secret" src ...

Or via the configuration file (~/src-config.json):

	{"accessToken": "secret", "endpoint": "https://sourcegraph.example.com"}

See src -h for more information on specifying access tokens.

To acquire the access token, visit your Sourcegraph instance (or https://sourcegraph.com), click your username in the top right to open the user menu, select Settings, and then select Access tokens in the left hand menu.

Consult src -h and src api -h for usage information.

If you want to develop the CLI, you can install it with go get:

go get -u github.com/sourcegraph/src-cli/cmd/src

1. Find the latest version (either via the releases tab on GitHub or via git tags) to determine which version you are releasing.
2. VERSION=9.9.9 ./release.sh (replace 9.9.9 with the version you are releasing)
3. Travis will automatically perform the release. Once it has finished, confirm that the curl commands fetch the latest version above.
4. Update the MinimumVersion constant in the src-cli package.

Note: The version recommended by a Sourcegraph instance will be the highest patch version with the same major and minor version as the set minimum. This means that patch versions are reserved solely for non-breaking changes and minor bug fixes. This allows us to dynamically release fixes for older versions of src-cli without having to update the instance.