From 603ba0bdfa486f2855fd895e27f9860fe060483b Mon Sep 17 00:00:00 2001 From: Eugenio Date: Wed, 29 Jul 2026 11:03:40 -0700 Subject: [PATCH] docs/auth: clarify OAuth and access token setup Explain endpoint configuration, OAuth keyring credentials, and personal access token authentication for non-interactive use. Document the src auth token commands and preserve the previous section anchor. Amp-Thread-ID: https://ampcode.com/threads/T-019faf06-8fb0-77ce-b64c-706d253bba28 Co-authored-by: Amp --- README.md | 58 +++++++++++++++++++++++++++++++++---------------------- 1 file changed, 35 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index 46ee3f42d1..415b56caf6 100644 --- a/README.md +++ b/README.md @@ -103,54 +103,65 @@ See [Sourcegraph CLI for Windows](WINDOWS.md). 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. +## 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: -**Examples** -`src login https://sourcegraph.example.com` -`src login https://sourcegraph.com` +```sh +export SRC_ENDPOINT=https://sourcegraph.example.com +``` -
+For PowerShell on Windows: -`src` consults the following environment variables: +```powershell +$env:SRC_ENDPOINT = 'https://sourcegraph.example.com' +``` -- `SRC_ENDPOINT`: the URL to your Sourcegraph instance (such as `https://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, add this environment variable to your terminal profile or system environment variables. On Mac OS and Linux, the terminal profile is typically `~/.bash_profile` for Bash or `~/.zprofile` for Zsh. On Windows, you can add it through the *System Properties* window. See [these instructions](https://www.computerhope.com/issues/ch000549.htm) for details. -For convenience, you can add these environment variables persistently. +If `SRC_ENDPOINT` is not set, `src` defaults to `https://sourcegraph.com`. -### Configuration: Mac OS / Linux +### OAuth login -Add the following to your terminal profile file, typically accessible at `~/.bash_profile` (if using Bash) or `~/.zprofile` (if using Zsh): +Run `src login` to authenticate interactively with OAuth: -``` -export SRC_ACCESS_TOKEN=my-token -export SRC_ENDPOINT=https://sourcegraph.example.com +```sh +src login ``` -Replace `my-token` and `https://sourcegraph.example.com` with the appropriate values for your account and instance. +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 inline them in a single command with: +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: ```sh -SRC_ENDPOINT=https://sourcegraph.example.com SRC_ACCESS_TOKEN=my-token src search 'foo' +src login https://sourcegraph.example.com ``` -### Configuration: Windows +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. -Type the following on your PowerShell terminal: +### 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`: + +```sh +export SRC_ENDPOINT=https://sourcegraph.example.com +export SRC_ACCESS_TOKEN=my-token ``` + +For PowerShell on Windows: + +```powershell $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. +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: -You can also manually add them via the *System Properties* windows. Check [this post](https://www.computerhope.com/issues/ch000549.htm) for details. +```sh +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](./AUTH_PROXY.md) docs. @@ -159,6 +170,7 @@ Is your Sourcegraph instance behind a custom auth proxy? See [auth proxy configu `src` provides different subcommands to interact with different parts of Sourcegraph: - `src login` - authenticate to a Sourcegraph instance with your user credentials + - `src auth` - print the active authentication token or authorization header - `src search` - perform searches and get results in your terminal or as JSON - `src api` - run Sourcegraph GraphQL API requests - `src batch` - execute and manage [batch changes](https://docs.sourcegraph.com/batch_changes)