DOCSEARCHbyAlgolia
Submit Docs

Sourcegraph CLI (src)

repository·main·Indexed 43 days ago

https://github.com/sourcegraph/src-cli

A command-line interface for interacting with Sourcegraph instances. It allows developers to perform searches, execute GraphQL API requests via `src api`, manage repositories and users, and run batch changes directly from the terminal.

Tokens
51.9K
Snippets
210
Records
248
Agent score
54%

What's inside Sourcegraph CLI

  1. Understand the `src` volume workspace base image

    main

    When Sourcegraph src executes batch changes using a volume workspace (the default behavior on macOS), it uses the src-batch-change-volume-workspace Docker image.

    This image performs two primary tasks:

    1. Initializes the volume workspace within Docker.
    2. Extracts the diff required to create the changeset.

    The image is based on Alpine Linux and includes the following essential tools:

    • curl
    • git
    • unzip

  2. Connect to a Sourcegraph instance

    main

    The src CLI requires the URL of your Sourcegraph instance, which is provided via the SRC_ENDPOINT environment variable. If not set, it defaults to https://sourcegraph.com.

    Set the Endpoint

    Bash (Mac/Linux):

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

    PowerShell (Windows):

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

    Authentication Methods

    1. OAuth Login (Interactive)

    Use src login to authenticate via a browser. Credentials are stored in your operating system's native keyring. You can specify an endpoint during login, but you must still set SRC_ENDPOINT for subsequent commands:

    src login https://sourcegraph.example.com

    2. Personal Access Token (Non-interactive/CI)

    For scripts or CI/CD, create an access token in Sourcegraph (Settings > Access tokens) and set the SRC_ACCESS_TOKEN environment variable:

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

    You can also provide both variables inline for a single command:

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

  3. Install a version of the Sourcegraph CLI compatible with your instance

    main

    If you are using a self-hosted Sourcegraph instance, you should install the CLI version compatible with that instance. Run the following commands in PowerShell as an Administrator, replacing sourcegraph.example.com with your actual Sourcegraph instance URL.

    New-Item -ItemType Directory 'C:\Program Files\Sourcegraph'

Invoke-WebRequest https://sourcegraph.example.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'

  4. Install the Sourcegraph CLI on Windows (Latest Version)

    main

    To install the latest version of the Sourcegraph CLI on Windows, run the following commands in PowerShell with Administrator privileges. This script creates the installation directory, downloads the executable, and adds the directory to your system PATH.

    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'

  5. Build and install the `src` CLI for development

    main

    To develop the CLI, clone the repository and use go install to build and install the binary to your $GOPATH/bin. Alternatively, you can run the CLI directly from the source without installing it.

    # Install the CLI
cd src-cli/
go install ./cmd/src

# Run without installation
go run ./cmd/src

  6. Debug batch changes using the `debug` build tag

    main

    Commands like src batch apply and src batch preview use a TUI (Terminal User Interface) that can overwrite or hide standard printf debug output. To debug these, compile the binary with the debug build tag. This includes ./internal/batches/debug.go, which configures the standard log package to write to ~/.sourcegraph/src-cli.debug.log instead of stdout. You can then monitor this file using tail -f.

    # Compile with debug tags
go build -tags debug -o ~/src ./cmd/src

# Monitor the debug log
tail -f ~/.sourcegraph/src-cli.debug.log

  8. Update vendored lib packages

    main

    The lib directory contains vendored packages from the main Sourcegraph repository. To update these packages to the latest version from the main branch, run the provided vendor script.

    Note: The script requires that the ../sourcegraph directory is on the main branch and has no uncommitted changes before it can run successfully.

    ./dev/vendor-lib.sh

  9. Install the Sourcegraph CLI (src)

    main

    You can install the src CLI via binary downloads, Homebrew, npm, or Docker. If you are using a self-hosted Sourcegraph instance, it is recommended to install a version compatible with your instance.

    Mac OS

    Latest version:

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

# Via Homebrew
brew install sourcegraph/src-cli/src-cli

# Via npm
npm install -g @sourcegraph/src

    Compatible version: Replace sourcegraph.example.com with your 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

    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

# Via npm
npm install -g @sourcegraph/src

    Compatible version:

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

    Docker

    Use the latest tag or a specific version:

    docker run --rm=true sourcegraph/src-cli:latest search 'hello world'
    # Mac OS Latest
curl -L https://sourcegraph.com/.api/src-cli/src_darwin_amd64 -o /usr/local/bin/src
chmod +x /usr/local/bin/src

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

  10. Build and test the `src-cli` Docker image

    main

    The project uses a multi-stage Dockerfile to ensure the src binary is built without runtime libc dependencies, allowing it to run in a scratch image. To test changes to the Dockerfile locally, build and run a local image.

    # Build a local image
docker build -t local-src-cli .

# Run the local image
docker run --rm local-src-cli

  11. Run manual smoke tests

    main

    For quick end-to-end sanity checks against a live Sourcegraph instance, use the provided smoke test script. This script uses your currently exported SRC_* environment variables and is intended for manual regression checks (e.g., verifying src users list still works).

    ./dev/smoke.sh

  12. Manually install the Sourcegraph CLI on Windows

    main

    You can install the Sourcegraph CLI manually by following these steps:

    1. Download the src_windows_amd64.exe binary from either https://sourcegraph.com/.api/src-cli/src_windows_amd64.exe (for the latest version) or from your own instance at https://<your-instance>/.api/src-cli/src_windows_amd64.exe.
    2. Place the downloaded file in a directory, for example: C:\Program Files\Sourcegraph\src.exe.
    3. Add that directory to your system PATH environment variable to ensure you can run src from any command prompt.