doc: add cli documentation (#15906)

This roughs in some top level src-cli documentation, including an
autogenerated reference.

Co-authored-by: Thorsten Ball <mrnugget@gmail.com>

dev/generate.sh

@@ -3,4 +3,6 @@
 set -e
 cd "$(dirname "${BASH_SOURCE[0]}")/.." # cd to repo root dir
 
-go list ./... | xargs go generate -x
+# We'll exclude generating the CLI reference documentation by default due to the
+# relatively high cost of fetching and building src-cli.
+go list ./... | grep -v 'doc/cli/references' | xargs go generate -x

doc/campaigns/quickstart.md

@@ -24,7 +24,7 @@ See ["Code host interactions in campaigns"](explanations/permissions_in_campaign
 
 ## Install the Sourcegraph CLI
 
-In order to create campaigns we need to [install the Sourcegraph CLI](https://github.com/sourcegraph/src-cli) (`src`).
+In order to create campaigns we need to [install the Sourcegraph CLI](../cli/index.md) (`src`).
 
 1. Install the version of `src` that's compatible with your Sourcegraph instance:
 
@@ -38,7 +38,7 @@ In order to create campaigns we need to [install the Sourcegraph CLI](https://gi
     curl -L https://YOUR-SOURCEGRAPH-INSTANCE/.api/src-cli/src_linux_amd64 -o /usr/local/bin/src
     chmod +x /usr/local/bin/src
     ```
-    **Windows**: see ["Sourcegraph CLI for Windows"](https://github.com/sourcegraph/src-cli/blob/main/WINDOWS.md)
+    **Windows**: see ["Sourcegraph CLI for Windows"](../cli/explanations/windows.md)
 2. Authenticate `src` with your Sourcegraph instance by running **`src login`** and following the instructions:
 
     ```

doc/cli/explanations/env.md

@@ -0,0 +1,21 @@
+# Environment variables
+
+## Overview
+
+`src` requires two environment variables to be set to authenticate against your Sourcegraph instance.
+
+## `SRC_ENDPOINT`
+
+`SRC_ENDPOINT` defines the base URL for your Sourcegraph instance. In most cases, this will be a simple HTTPS URL, such as the following:
+
+```
+https://sourcegraph.com
+```
+
+If you're unsure what the URL for your Sourcegraph instance is, please contact your site administrator.
+
+## `SRC_ACCESS_TOKEN`
+
+`src` uses an access token to authenticate as you to your Sourcegraph instance. This token needs to be in the `SRC_ACCESS_TOKEN` environment variable.
+
+To create an access token, please refer to "[Creating an access token](../how-tos/creating_an_access_token.md)".

doc/cli/explanations/index.md

@@ -0,0 +1,6 @@
+# Explanations
+
+The following articles explain different aspects of [the `src` command line interface to Sourcegraph](../index.md) in depth:
+
+- [Environment variables](env.md)
+- [Windows support](windows.md)

doc/cli/explanations/windows.md

@@ -0,0 +1,24 @@
+# Windows support
+
+> NOTE: Windows support is still rough around the edges. If you encounter issues, please let us know by [filing an issue](https://github.com/sourcegraph/src-cli/issues/new).
+
+## Installation
+
+### Install via PowerShell
+
+Run in PowerShell as administrator:
+
+```powershell
+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'
+```
+
+### Install manually
+
+1. Download the latest [src_windows_amd64.exe](https://sourcegraph.com/.api/src-cli/src_windows_amd64.exe)
+2. Place the file under e.g. `C:\Program Files\Sourcegraph\src.exe`
+3. Add that directory to your system PATH to access it from any command prompt

doc/cli/how-tos/creating_an_access_token.md

@@ -0,0 +1,22 @@
+# Creating an access token
+
+Access tokens permit authenticated access to the Sourcegraph API. This is required for [the `src` command line interface to Sourcegraph](../index.md) to operate, and also allows other tools that integrate with Sourcegraph to issue requests on your behalf.
+
+Creating an access token is done through your user settings. This video shows the steps, which are then described below:
+
+<video width="1920" height="1080" autoplay controls loop muted playsinline style="width: 100%; height: auto; max-width: 50rem">
+  <source src="https://sourcegraphstatic.com/docs/images/integration/cli/token.webm type="video/webm">
+  <source src="https://sourcegraphstatic.com/docs/images/integration/cli/token.mp4" type="video/mp4">
+</video>
+
+1. From any Sourcegraph page, click on your avatar at the top right of the page.
+1. Select **Settings** from the dropdown menu.
+1. Select **Access tokens** from the sidebar menu.
+1. Click **Generate new token**.
+1. Enter a description, such as `src`.
+
+    > NOTE: The `user:all` scope that is selected by default is sufficient for all normal `src` usage, and most uses of the GraphQL API. If you're an admin, you should only enable `site-admin:sudo` if you intend to impersonate other users.
+1. Click **Generate token**.
+1. Sourcegraph will now display your access token. You **must copy it from this screen**: once this page is closed, you cannot access the token again, and can only revoke it and issue a new one.
+
+You can then set [the `SRC_ACCESS_TOKEN` environment variable](../explanations/env.md) to the token to use it with `src`.

doc/cli/how-tos/index.md

@@ -0,0 +1,5 @@
+# How-tos
+
+The following how-tos apply to [the `src` command line interface to Sourcegraph](../index.md):
+
+- [Creating an access token](creating_an_access_token.md)

doc/cli/index.md

@@ -0,0 +1,46 @@
+# CLI
+
+<p class="subtitle">Interact with Sourcegraph from the command line</p>
+
+<p class="lead">
+  <code>src</code> is a command line interface to Sourcegraph that allows you to <a href="../code_search">search code</a> from your terminal, <a href="../campaigns">create and apply campaigns</a>, and <a href="../admin">manage and administrate repositories, users, and more</a>.
+</p>
+
+<div class="cta-group">
+  <a class="btn btn-primary" href="quickstart">★ Quickstart</a>
+</div>
+
+## Getting started
+
+<div class="getting-started">
+  <a href="quickstart" class="btn" alt="Run through the Quickstart guide">
+    <span>New to <code>src</code>?</span>
+    <br />
+    Run through the <b>quickstart guide</b> and set up <code>src</code> in minutes.
+  </a>
+
+  <a href="references" class="btn" alt="Read the src reference">
+    <span>Command reference</span>
+    <br />
+    Check the commands available in <code>src</code> and their flags.
+  </a>
+
+  <a href="../campaigns/quickstart" class="btn" alt="Create a campaign">
+    <span>Create a campaign</span>
+    <br />
+    <code>src</code> is the gateway to Sourcegraph's campaign functionality: find out how to create a campaign with it in less than 10 minutes.
+  </a>
+</div>
+
+## Explanations
+
+- [Environment variables](explanations/env.md)
+- [Windows support](explanations/windows.md)
+
+## How-tos
+
+- [Creating an access token](how-tos/creating_an_access_token.md)
+
+## References
+
+- [Command reference](references/index.md)

doc/cli/quickstart.md

@@ -0,0 +1,68 @@
+# Quickstart for `src`
+
+Get started and run your first [code search](../../code_search/index.md) from the command line in 10 minutes or less.
+
+## Introduction
+
+In this guide, you'll install the Sourcegraph CLI, `src`, connect it to your Sourcegraph instance, and use it to run a code search.
+
+## Installation
+
+`src` is shipped as a single, standalone binary. You can get the latest release by following the instructions for your operating system below:
+
+### macOS
+
+```sh
+curl -L https://sourcegraph.com/.api/src-cli/src_darwin_amd64 -o /usr/local/bin/src
+chmod +x /usr/local/bin/src
+```
+
+### Linux
+
+```sh
+curl -L https://sourcegraph.com/.api/src-cli/src_linux_amd64
+chmod +x /usr/local/bin/src
+```
+
+### Windows
+
+You can install using PowerShell as follows:
+
+```powershell
+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'
+```
+
+For other options, please refer to [the Windows specific `src` documentation](explanations/windows.md).
+
+## Connect to Sourcegraph
+
+`src` needs to be authenticated against your Sourcegraph instance. The quickest way to do this is to run `src login https://YOUR-SOURCEGRAPH-INSTANCE` and follow the instructions:
+
+<img src="https://storage.googleapis.com/sourcegraph-assets/docs/images/campaigns/src_login_success.png" class="screenshot" alt="Output from src login showing success">
+
+Once complete, you should have two new environment variables set: `SRC_ENDPOINT` and `SRC_ACCESS_TOKEN`.
+
+## Run a code search
+
+Searching is performed using the [`src search`](references/search.md) command. For example, to search for `ResolveRepositories` in the `src` repository, you can run:
+
+```sh
+src search 'r:github.com/sourcegraph/src-cli ResolveRepositories'
+```
+
+This should result in this output:
+
+<img src="https://sourcegraphstatic.com/docs/images/integration/cli/quickstart-search.png" class="screenshot" alt="Terminal output from the above search">
+
+## Congratulations!
+
+You've run your first search from the command line! 🎉🎉
+
+You can now explore the [range of commands `src` provides](references/index.md), including the extensive support for [campaigns](../../campaigns/index.md).
+
+To learn what else you can do with `src`, see "[CLI](index.md)" in the Sourcegraph documentation.

doc/cli/references/api.md

@@ -0,0 +1,57 @@
+# `src api`
+
+
+## Flags
+
+| Name | Description | Default Value |
+|------|-------------|---------------|
+| `-dump-requests` | Log GraphQL requests and responses to stdout | `false` |
+| `-get-curl` | Print the curl command for executing this query and exit (WARNING: includes printing your access token!) | `false` |
+| `-query` | GraphQL query to execute, e.g. 'query { currentUser { username } }' (stdin otherwise) |  |
+| `-trace` | Log the trace ID for requests. See https://docs.sourcegraph.com/admin/observability/tracing | `false` |
+| `-vars` | GraphQL query variables to include as JSON string, e.g. '{"var": "val", "var2": "val2"}' |  |
+
+
+## Usage
+
+```
+Usage of 'src api':
+  -dump-requests
+    	Log GraphQL requests and responses to stdout
+  -get-curl
+    	Print the curl command for executing this query and exit (WARNING: includes printing your access token!)
+  -query string
+    	GraphQL query to execute, e.g. 'query { currentUser { username } }' (stdin otherwise)
+  -trace
+    	Log the trace ID for requests. See https://docs.sourcegraph.com/admin/observability/tracing
+  -vars string
+    	GraphQL query variables to include as JSON string, e.g. '{"var": "val", "var2": "val2"}'
+
+Exit codes:
+
+  0: Success
+  1: General failures (connection issues, invalid HTTP response, etc.)
+  2: GraphQL error response
+
+Examples:
+
+  Run queries (identical behavior):
+
+    	$ echo 'query { currentUser { username } }' | src api
+    	$ src api -query='query { currentUser { username } }'
+
+  Specify query variables:
+
+    	$ echo '<query>' | src api 'var1=val1' 'var2=val2'
+
+  Searching for "Router" and getting result count:
+
+    	$ echo 'query($query: String!) { search(query: $query) { results { resultCount } } }' | src api 'query=Router'
+
+  Get the curl command for a query (just add '-get-curl' in the flags section):
+
+    	$ src api -get-curl -query='query { currentUser { username } }'
+
+
+```
+	

doc/cli/references/campaigns/apply.md

@@ -0,0 +1,76 @@
+# `src campaigns apply`
+
+
+## Flags
+
+| Name | Description | Default Value |
+|------|-------------|---------------|
+| `-allow-unsupported` | Allow unsupported code hosts. | `false` |
+| `-apply` | Ignored. | `false` |
+| `-cache` | Directory for caching results and repository archives. | `~/.cache/sourcegraph/campaigns` |
+| `-clean-archives` | If true, deletes downloaded repository archives after executing campaign steps. | `true` |
+| `-clear-cache` | If true, clears the execution cache and executes all steps anew. | `false` |
+| `-dump-requests` | Log GraphQL requests and responses to stdout | `false` |
+| `-f` | The campaign spec file to read. |  |
+| `-get-curl` | Print the curl command for executing this query and exit (WARNING: includes printing your access token!) | `false` |
+| `-j` | The maximum number of parallel jobs. (Default: GOMAXPROCS.) | `0` |
+| `-keep-logs` | Retain logs after executing steps. | `false` |
+| `-n` | Alias for -namespace. |  |
+| `-namespace` | The user or organization namespace to place the campaign within. Default is the currently authenticated user. |  |
+| `-timeout` | The maximum duration a single set of campaign steps can take. | `1h0m0s` |
+| `-tmp` | Directory for storing temporary data, such as log files. Default is /tmp. Can also be set with environment variable SRC_CAMPAIGNS_TMP_DIR; if both are set, this flag will be used and not the environment variable. | `/tmp` |
+| `-trace` | Log the trace ID for requests. See https://docs.sourcegraph.com/admin/observability/tracing | `false` |
+
+
+## Usage
+
+```
+Usage of 'src campaigns apply':
+  -allow-unsupported
+    	Allow unsupported code hosts.
+  -apply
+    	Ignored.
+  -cache string
+    	Directory for caching results and repository archives. (default "~/.cache/sourcegraph/campaigns")
+  -clean-archives
+    	If true, deletes downloaded repository archives after executing campaign steps. (default true)
+  -clear-cache
+    	If true, clears the execution cache and executes all steps anew.
+  -dump-requests
+    	Log GraphQL requests and responses to stdout
+  -f string
+    	The campaign spec file to read.
+  -get-curl
+    	Print the curl command for executing this query and exit (WARNING: includes printing your access token!)
+  -j int
+    	The maximum number of parallel jobs. (Default: GOMAXPROCS.)
+  -keep-logs
+    	Retain logs after executing steps.
+  -n string
+    	Alias for -namespace.
+  -namespace string
+    	The user or organization namespace to place the campaign within. Default is the currently authenticated user.
+  -timeout duration
+    	The maximum duration a single set of campaign steps can take. (default 1h0m0s)
+  -tmp string
+    	Directory for storing temporary data, such as log files. Default is /tmp. Can also be set with environment variable SRC_CAMPAIGNS_TMP_DIR; if both are set, this flag will be used and not the environment variable. (default "/tmp")
+  -trace
+    	Log the trace ID for requests. See https://docs.sourcegraph.com/admin/observability/tracing
+
+'src campaigns apply' is used to apply a campaign spec on a Sourcegraph
+instance, creating or updating the described campaign if necessary.
+
+Usage:
+
+    src campaigns apply -f FILE [command options]
+
+Examples:
+
+    $ src campaigns apply -f campaign.spec.yaml
+  
+    $ src campaigns apply -f campaign.spec.yaml -namespace myorg
+
+
+
+```
+	

doc/cli/references/campaigns/index.md

@@ -0,0 +1,11 @@
+# `src campaigns`
+
+## Subcommands
+
+
+* [`apply`](apply.md)
+* [`new`](new.md)
+* [`preview`](preview.md)
+* [`repositories`](repositories.md)
+* [`validate`](validate.md)
+	

doc/cli/references/campaigns/new.md

@@ -0,0 +1,33 @@
+# `src campaigns new`
+
+
+## Flags
+
+| Name | Description | Default Value |
+|------|-------------|---------------|
+| `-f` | The name of campaign spec file to create. | `campaign.yaml` |
+
+
+## Usage
+
+```
+Usage of 'src campaigns new':
+  -f string
+    	The name of campaign spec file to create. (default "campaign.yaml")
+
+'src campaigns new' creates a new campaign spec YAML, prefilled with all
+required fields.
+
+Usage:
+
+    src campaigns new [-f FILE]
+
+Examples:
+
+
+    $ src campaigns new -f campaign.spec.yaml
+
+
+
+```
+	

doc/cli/references/campaigns/preview.md

@@ -0,0 +1,74 @@
+# `src campaigns preview`
+
+
+## Flags
+
+| Name | Description | Default Value |
+|------|-------------|---------------|
+| `-allow-unsupported` | Allow unsupported code hosts. | `false` |
+| `-apply` | Ignored. | `false` |
+| `-cache` | Directory for caching results and repository archives. | `~/.cache/sourcegraph/campaigns` |
+| `-clean-archives` | If true, deletes downloaded repository archives after executing campaign steps. | `true` |
+| `-clear-cache` | If true, clears the execution cache and executes all steps anew. | `false` |
+| `-dump-requests` | Log GraphQL requests and responses to stdout | `false` |
+| `-f` | The campaign spec file to read. |  |
+| `-get-curl` | Print the curl command for executing this query and exit (WARNING: includes printing your access token!) | `false` |
+| `-j` | The maximum number of parallel jobs. (Default: GOMAXPROCS.) | `0` |
+| `-keep-logs` | Retain logs after executing steps. | `false` |
+| `-n` | Alias for -namespace. |  |
+| `-namespace` | The user or organization namespace to place the campaign within. Default is the currently authenticated user. |  |
+| `-timeout` | The maximum duration a single set of campaign steps can take. | `1h0m0s` |
+| `-tmp` | Directory for storing temporary data, such as log files. Default is /tmp. Can also be set with environment variable SRC_CAMPAIGNS_TMP_DIR; if both are set, this flag will be used and not the environment variable. | `/tmp` |
+| `-trace` | Log the trace ID for requests. See https://docs.sourcegraph.com/admin/observability/tracing | `false` |
+
+
+## Usage
+
+```
+Usage of 'src campaigns preview':
+  -allow-unsupported
+    	Allow unsupported code hosts.
+  -apply
+    	Ignored.
+  -cache string
+    	Directory for caching results and repository archives. (default "~/.cache/sourcegraph/campaigns")
+  -clean-archives
+    	If true, deletes downloaded repository archives after executing campaign steps. (default true)
+  -clear-cache
+    	If true, clears the execution cache and executes all steps anew.
+  -dump-requests
+    	Log GraphQL requests and responses to stdout
+  -f string
+    	The campaign spec file to read.
+  -get-curl
+    	Print the curl command for executing this query and exit (WARNING: includes printing your access token!)
+  -j int
+    	The maximum number of parallel jobs. (Default: GOMAXPROCS.)
+  -keep-logs
+    	Retain logs after executing steps.
+  -n string
+    	Alias for -namespace.
+  -namespace string
+    	The user or organization namespace to place the campaign within. Default is the currently authenticated user.
+  -timeout duration
+    	The maximum duration a single set of campaign steps can take. (default 1h0m0s)
+  -tmp string
+    	Directory for storing temporary data, such as log files. Default is /tmp. Can also be set with environment variable SRC_CAMPAIGNS_TMP_DIR; if both are set, this flag will be used and not the environment variable. (default "/tmp")
+  -trace
+    	Log the trace ID for requests. See https://docs.sourcegraph.com/admin/observability/tracing
+
+'src campaigns preview' executes the steps in a campaign spec and uploads it to
+a Sourcegraph instance, ready to be previewed and applied.
+
+Usage:
+
+    src campaigns preview -f FILE [command options]
+
+Examples:
+
+    $ src campaigns preview -f campaign.spec.yaml
+
+
+
+```
+	

doc/cli/references/campaigns/repositories.md

@@ -0,0 +1,41 @@
+# `src campaigns repositories`
+
+
+## Flags
+
+| Name | Description | Default Value |
+|------|-------------|---------------|
+| `-dump-requests` | Log GraphQL requests and responses to stdout | `false` |
+| `-f` | The campaign spec file to read. |  |
+| `-get-curl` | Print the curl command for executing this query and exit (WARNING: includes printing your access token!) | `false` |
+| `-trace` | Log the trace ID for requests. See https://docs.sourcegraph.com/admin/observability/tracing | `false` |
+
+
+## Usage
+
+```
+Usage of 'src campaigns repositories':
+  -dump-requests
+    	Log GraphQL requests and responses to stdout
+  -f string
+    	The campaign spec file to read.
+  -get-curl
+    	Print the curl command for executing this query and exit (WARNING: includes printing your access token!)
+  -trace
+    	Log the trace ID for requests. See https://docs.sourcegraph.com/admin/observability/tracing
+
+'src campaigns repositories' works out the repositories that a campaign spec
+would apply to.
+
+Usage:
+
+    src campaigns repositories -f FILE
+
+Examples:
+
+    $ src campaigns repositories -f campaign.spec.yaml
+
+
+
+```
+	

doc/cli/references/campaigns/validate.md

@@ -0,0 +1,31 @@
+# `src campaigns validate`
+
+
+## Flags
+
+| Name | Description | Default Value |
+|------|-------------|---------------|
+| `-f` | The campaign spec file to read. |  |
+
+
+## Usage
+
+```
+Usage of 'src campaigns validate':
+  -f string
+    	The campaign spec file to read.
+
+'src campaigns validate' validates the given campaign spec.
+
+Usage:
+
+    src campaigns validate -f FILE
+
+Examples:
+
+    $ src campaigns validate -f campaign.spec.yaml
+
+
+
+```
+	

doc/cli/references/config/edit.md

@@ -0,0 +1,64 @@
+# `src config edit`
+
+
+## Flags
+
+| Name | Description | Default Value |
+|------|-------------|---------------|
+| `-dump-requests` | Log GraphQL requests and responses to stdout | `false` |
+| `-get-curl` | Print the curl command for executing this query and exit (WARNING: includes printing your access token!) | `false` |
+| `-overwrite` | Overwrite the entire settings with the value given in -value (not just a single property). | `false` |
+| `-property` | The name of the settings property to set. |  |
+| `-subject` | The ID of the settings subject whose settings to edit. (default: authenticated user) |  |
+| `-trace` | Log the trace ID for requests. See https://docs.sourcegraph.com/admin/observability/tracing | `false` |
+| `-value` | The value for the settings property (when used with -property). |  |
+| `-value-file` | Read the value from this file instead of from the -value command-line option. |  |
+
+
+## Usage
+
+```
+Usage of 'src config edit':
+  -dump-requests
+    	Log GraphQL requests and responses to stdout
+  -get-curl
+    	Print the curl command for executing this query and exit (WARNING: includes printing your access token!)
+  -overwrite
+    	Overwrite the entire settings with the value given in -value (not just a single property).
+  -property string
+    	The name of the settings property to set.
+  -subject string
+    	The ID of the settings subject whose settings to edit. (default: authenticated user)
+  -trace
+    	Log the trace ID for requests. See https://docs.sourcegraph.com/admin/observability/tracing
+  -value string
+    	The value for the settings property (when used with -property).
+  -value-file string
+    	Read the value from this file instead of from the -value command-line option.
+
+Examples:
+
+  Edit settings property for the current user (authenticated by the src CLI's access token, if any):
+
+    	$ src config edit -property motd -value '["Hello!"]'
+
+  Overwrite all settings settings for the current user:
+
+    	$ src config edit -overwrite -value '{"motd":["Hello!"]}'
+
+  Overwrite all settings settings for the current user with the file contents:
+
+    	$ src config edit -overwrite -value-file myconfig.json
+
+  Edit a settings property for the user with username alice:
+
+    	$ src config edit -subject=$(src users get -f '{{.ID}}' -username=alice) -property motd -value '["Hello!"]'
+
+  Overwrite all settings settings for the organization named abc-org:
+
+    	$ src config edit -subject=$(src orgs get -f '{{.ID}}' -name=abc-org) -overwrite -value '{"motd":["Hello!"]}'
+
+
+
+```
+	

doc/cli/references/config/get.md

@@ -0,0 +1,47 @@
+# `src config get`
+
+
+## Flags
+
+| Name | Description | Default Value |
+|------|-------------|---------------|
+| `-dump-requests` | Log GraphQL requests and responses to stdout | `false` |
+| `-f` | Format for the output, using the syntax of Go package text/template. (e.g. "{{.|json}}") | `{{.|jsonIndent}}` |
+| `-get-curl` | Print the curl command for executing this query and exit (WARNING: includes printing your access token!) | `false` |
+| `-subject` | The ID of the settings subject whose settings to get. (default: authenticated user) |  |
+| `-trace` | Log the trace ID for requests. See https://docs.sourcegraph.com/admin/observability/tracing | `false` |
+
+
+## Usage
+
+```
+Usage of 'src config get':
+  -dump-requests
+    	Log GraphQL requests and responses to stdout
+  -f string
+    	Format for the output, using the syntax of Go package text/template. (e.g. "{{.|json}}") (default "{{.|jsonIndent}}")
+  -get-curl
+    	Print the curl command for executing this query and exit (WARNING: includes printing your access token!)
+  -subject string
+    	The ID of the settings subject whose settings to get. (default: authenticated user)
+  -trace
+    	Log the trace ID for requests. See https://docs.sourcegraph.com/admin/observability/tracing
+
+Examples:
+
+  Get settings for the current user (authenticated by the src CLI's access token, if any):
+
+    	$ src config get
+
+  Get settings for the user with username alice:
+
+    	$ src config get -subject=$(src users get -f '{{.ID}}' -username=alice)
+
+  Get settings for the organization named abc-org:
+
+    	$ src config get -subject=$(src orgs get -f '{{.ID}}' -name=abc-org)
+
+
+
+```
+	

doc/cli/references/config/index.md

@@ -0,0 +1,9 @@
+# `src config`
+
+## Subcommands
+
+
+* [`edit`](edit.md)
+* [`get`](get.md)
+* [`list`](list.md)
+	

doc/cli/references/config/list.md

@@ -0,0 +1,43 @@
+# `src config list`
+
+
+## Flags
+
+| Name | Description | Default Value |
+|------|-------------|---------------|
+| `-dump-requests` | Log GraphQL requests and responses to stdout | `false` |
+| `-f` | Format for the output, using the syntax of Go package text/template. (e.g. "{{.|json}}") |  |
+| `-get-curl` | Print the curl command for executing this query and exit (WARNING: includes printing your access token!) | `false` |
+| `-subject` | The ID of the settings subject whose settings to list. (default: authenticated user) |  |
+| `-trace` | Log the trace ID for requests. See https://docs.sourcegraph.com/admin/observability/tracing | `false` |
+
+
+## Usage
+
+```
+Usage of 'src config list':
+  -dump-requests
+    	Log GraphQL requests and responses to stdout
+  -f string
+    	Format for the output, using the syntax of Go package text/template. (e.g. "{{.|json}}")
+  -get-curl
+    	Print the curl command for executing this query and exit (WARNING: includes printing your access token!)
+  -subject string
+    	The ID of the settings subject whose settings to list. (default: authenticated user)
+  -trace
+    	Log the trace ID for requests. See https://docs.sourcegraph.com/admin/observability/tracing
+
+Examples:
+
+  List settings for the current user (authenticated by the src CLI's access token, if any):
+
+    	$ src config list
+
+  List settings for the user with username alice:
+
+    	$ src config list -subject=$(src users get -f '{{.ID}}' -username=alice)
+
+
+
+```
+	

doc/cli/references/doc.go

@@ -0,0 +1,132 @@
+// +build ignore
+
+package main
+
+import (
+	"io/ioutil"
+	"log"
+	"os"
+	"os/exec"
+	"path"
+	"path/filepath"
+	"sort"
+
+	"github.com/pkg/errors"
+)
+
+func clean(base string) error {
+	// Delete every Markdown file that we find, and track the directories that
+	// exist.
+	dirs := []string{}
+	if err := filepath.Walk(base, func(fp string, info os.FileInfo, err error) error {
+		if info.IsDir() {
+			dirs = append(dirs, fp)
+		} else if path.Ext(fp) == ".md" {
+			return os.Remove(fp)
+		}
+
+		return nil
+	}); err != nil {
+		return errors.Wrap(err, "error walking Markdown files")
+	}
+
+	// Now iterate over the directories depth-first, removing the ones that are
+	// empty.
+	sort.Slice(dirs, func(i, j int) bool {
+		return len(dirs[j]) < len(dirs[i])
+	})
+	for _, dir := range dirs {
+		d, err := ioutil.ReadDir(dir)
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		if len(d) == 0 {
+			if err := os.Remove(dir); err != nil {
+				return errors.Wrapf(err, "error removing directory %q", dir)
+			}
+		}
+	}
+
+	return nil
+}
+
+func build(base string) error {
+	// The right way to do this would be to build and run src-cli from git: we
+	// Since we don't want to pollute the local go.mod or go.sum, but we also
+	// need an isolated environment, we're going to set up an isolated directory
+	// to build src-cli. Some day https://github.com/golang/go/issues/40276 will
+	// have its solution merged and we might be able to avoid all of this with a
+	// go:generate one-liner.
+
+	dir, err := ioutil.TempDir("", "src-cli-doc-gen")
+	if err != nil {
+		return errors.Wrap(err, "creating temporary directory")
+	}
+	defer os.RemoveAll(dir)
+
+	if err := os.Chdir(dir); err != nil {
+		return errors.Wrap(err, "changing to temporary directory")
+	}
+
+	// We have a few fun things going on here, but by far the funnest is that
+	// src-cli (and its dependencies) rely on a go.mod replacement of our
+	// upstream YAML library with our own fork. Unfortunately, doing a simple
+	// `go build` (or whatever) with the src-cli URL fails as a result, since
+	// campaignutils will try to call a method that doesn't exist on the
+	// upstream library.
+	//
+	// Since replacements only happen locally, we have to set up the same
+	// replacement in a local go.mod. On the bright side, that means we don't
+	// have to set GO111MODULE explicitly: this just looks like a normal Go
+	// module to Go.
+	//
+	// If this breaks in future with an obscure looking compilation error, the
+	// first thing you'll want to check is that any replacements in
+	// https://github.com/sourcegraph/src-cli/blob/main/go.mod are reproduced
+	// here as well.
+	//
+	// In summary, this is _hilariously_ cursed.
+	if err := ioutil.WriteFile("go.mod", []byte(`module github.com/sourcegraph/sourcegraph/doc/cli/references
+
+replace github.com/gosuri/uilive v0.0.4 => github.com/mrnugget/uilive v0.0.4-fix-escape
+
+// See: https://github.com/ghodss/yaml/pull/65
+replace github.com/ghodss/yaml => github.com/sourcegraph/yaml v1.0.1-0.20200714132230-56936252f152
+	`), 0600); err != nil {
+		return errors.Wrap(err, "setting up go.mod")
+	}
+
+	goGet := exec.Command("go", "get", "github.com/sourcegraph/src-cli/cmd/src")
+	goGet.Env = append(os.Environ(), "GOBIN="+dir)
+	if out, err := goGet.CombinedOutput(); err != nil {
+		return errors.Wrapf(err, "getting src-cli:\n%s\n", string(out))
+	}
+
+	if err := os.Chdir(base); err != nil {
+		return errors.Wrap(err, "returning to the working directory")
+	}
+
+	src := path.Join(dir, "src")
+	srcDoc := exec.Command(src, "doc", "-o", ".")
+	if out, err := srcDoc.CombinedOutput(); err != nil {
+		return errors.Wrapf(err, "running src doc:\n%s\n", string(out))
+	}
+
+	return nil
+}
+
+func main() {
+	wd, err := os.Getwd()
+	if err != nil {
+		log.Fatalf("error getting working directory: %v", err)
+	}
+
+	if err := clean(wd); err != nil {
+		log.Fatalf("error cleaning working directory: %v", err)
+	}
+
+	if err := build(wd); err != nil {
+		log.Fatalf("error building documentation: %v", err)
+	}
+}

doc/cli/references/extensions/copy.md

@@ -0,0 +1,34 @@
+# `src extensions copy`
+
+
+## Flags
+
+| Name | Description | Default Value |
+|------|-------------|---------------|
+| `-current-user` | The current user |  |
+| `-dump-requests` | Log GraphQL requests and responses to stdout | `false` |
+| `-extension-id` | The <extID> in https://sourcegraph.com/extensions/<extID> (e.g. sourcegraph/java) |  |
+| `-get-curl` | Print the curl command for executing this query and exit (WARNING: includes printing your access token!) | `false` |
+| `-trace` | Log the trace ID for requests. See https://docs.sourcegraph.com/admin/observability/tracing | `false` |
+
+
+## Usage
+
+```
+Usage of 'src extensions copy':
+  -current-user string
+    	The current user
+  -dump-requests
+    	Log GraphQL requests and responses to stdout
+  -extension-id string
+    	The <extID> in https://sourcegraph.com/extensions/<extID> (e.g. sourcegraph/java)
+  -get-curl
+    	Print the curl command for executing this query and exit (WARNING: includes printing your access token!)
+  -trace
+    	Log the trace ID for requests. See https://docs.sourcegraph.com/admin/observability/tracing
+
+Copy an extension from Sourcegraph.com to your private registry.
+
+
+```
+	

doc/cli/references/extensions/delete.md

@@ -0,0 +1,40 @@
+# `src extensions delete`
+
+
+## Flags
+
+| Name | Description | Default Value |
+|------|-------------|---------------|
+| `-dump-requests` | Log GraphQL requests and responses to stdout | `false` |
+| `-get-curl` | Print the curl command for executing this query and exit (WARNING: includes printing your access token!) | `false` |
+| `-id` | The ID (GraphQL API ID, not extension ID) of the extension to delete. |  |
+| `-trace` | Log the trace ID for requests. See https://docs.sourcegraph.com/admin/observability/tracing | `false` |
+
+
+## Usage
+
+```
+Usage of 'src extensions delete':
+  -dump-requests
+    	Log GraphQL requests and responses to stdout
+  -get-curl
+    	Print the curl command for executing this query and exit (WARNING: includes printing your access token!)
+  -id string
+    	The ID (GraphQL API ID, not extension ID) of the extension to delete.
+  -trace
+    	Log the trace ID for requests. See https://docs.sourcegraph.com/admin/observability/tracing
+
+Examples:
+
+  Delete the extension by ID (GraphQL API ID, not extension ID):
+
+    	$ src extensions delete -id=UmVnaXN0cnlFeHRlbnNpb246...
+
+  Delete the extension with extension ID "alice/myextension":
+
+    	$ src extensions delete -id=$(src extensions get -f '{{.ID}}' -extension-id=alice/myextension)
+
+
+
+```
+	

doc/cli/references/extensions/get.md

@@ -0,0 +1,40 @@
+# `src extensions get`
+
+
+## Flags
+
+| Name | Description | Default Value |
+|------|-------------|---------------|
+| `-dump-requests` | Log GraphQL requests and responses to stdout | `false` |
+| `-extension-id` | Look up extension by extension ID. (e.g. "alice/myextension") |  |
+| `-f` | Format for the output, using the syntax of Go package text/template. (e.g. "{{.ExtensionID}}: {{.Manifest.Title}} ({{.RemoteURL}})" or "{{.|json}}") | `{{.|json}}` |
+| `-get-curl` | Print the curl command for executing this query and exit (WARNING: includes printing your access token!) | `false` |
+| `-trace` | Log the trace ID for requests. See https://docs.sourcegraph.com/admin/observability/tracing | `false` |
+
+
+## Usage
+
+```
+Usage of 'src extensions get':
+  -dump-requests
+    	Log GraphQL requests and responses to stdout
+  -extension-id string
+    	Look up extension by extension ID. (e.g. "alice/myextension")
+  -f string
+    	Format for the output, using the syntax of Go package text/template. (e.g. "{{.ExtensionID}}: {{.Manifest.Title}} ({{.RemoteURL}})" or "{{.|json}}") (default "{{.|json}}")
+  -get-curl
+    	Print the curl command for executing this query and exit (WARNING: includes printing your access token!)
+  -trace
+    	Log the trace ID for requests. See https://docs.sourcegraph.com/admin/observability/tracing
+
+Examples:
+
+  Get extension with extension ID "alice/myextension":
+
+    	$ src extensions get alice/myextension
+    	$ src extensions get -extension-id=alice/myextension
+
+
+
+```
+	

doc/cli/references/extensions/index.md

@@ -0,0 +1,11 @@
+# `src extensions`
+
+## Subcommands
+
+
+* [`copy`](copy.md)
+* [`delete`](delete.md)
+* [`get`](get.md)
+* [`list`](list.md)
+* [`publish`](publish.md)
+	

doc/cli/references/extensions/list.md

@@ -0,0 +1,50 @@
+# `src extensions list`
+
+
+## Flags
+
+| Name | Description | Default Value |
+|------|-------------|---------------|
+| `-dump-requests` | Log GraphQL requests and responses to stdout | `false` |
+| `-f` | Format for the output, using the syntax of Go package text/template. (e.g. "{{.ExtensionID}}: {{.Manifest.Description}} ({{.RemoteURL}})" or "{{.|json}}") | `{{.ExtensionID}}` |
+| `-first` | Returns the first n extensions from the list. (use -1 for unlimited) | `1000` |
+| `-get-curl` | Print the curl command for executing this query and exit (WARNING: includes printing your access token!) | `false` |
+| `-query` | Returns extensions whose extension IDs match the query. (e.g. "myextension") |  |
+| `-trace` | Log the trace ID for requests. See https://docs.sourcegraph.com/admin/observability/tracing | `false` |
+
+
+## Usage
+
+```
+Usage of 'src extensions list':
+  -dump-requests
+    	Log GraphQL requests and responses to stdout
+  -f string
+    	Format for the output, using the syntax of Go package text/template. (e.g. "{{.ExtensionID}}: {{.Manifest.Description}} ({{.RemoteURL}})" or "{{.|json}}") (default "{{.ExtensionID}}")
+  -first int
+    	Returns the first n extensions from the list. (use -1 for unlimited) (default 1000)
+  -get-curl
+    	Print the curl command for executing this query and exit (WARNING: includes printing your access token!)
+  -query string
+    	Returns extensions whose extension IDs match the query. (e.g. "myextension")
+  -trace
+    	Log the trace ID for requests. See https://docs.sourcegraph.com/admin/observability/tracing
+
+Examples:
+
+  List extensions:
+
+    	$ src extensions list
+
+  List extensions whose names match the query:
+
+    	$ src extensions list -query='myquery'
+
+  List *all* extensions (may be slow!):
+
+    	$ src extensions list -first='-1'
+
+
+
+```
+	

doc/cli/references/extensions/publish.md

@@ -0,0 +1,60 @@
+# `src extensions publish`
+
+
+## Flags
+
+| Name | Description | Default Value |
+|------|-------------|---------------|
+| `-dump-requests` | Log GraphQL requests and responses to stdout | `false` |
+| `-extension-id` | Override the extension ID in the manifest. (default: read from -manifest file) |  |
+| `-force` | Force publish the extension, even if there are validation problems or other warnings. | `false` |
+| `-get-curl` | Print the curl command for executing this query and exit (WARNING: includes printing your access token!) | `false` |
+| `-manifest` | The extension manifest file. | `package.json` |
+| `-trace` | Log the trace ID for requests. See https://docs.sourcegraph.com/admin/observability/tracing | `false` |
+| `-url` | Override the URL for the bundle. (example: set to http://localhost:1234/myext.js for local dev with parcel) |  |
+
+
+## Usage
+
+```
+Usage of 'src extensions publish':
+  -dump-requests
+    	Log GraphQL requests and responses to stdout
+  -extension-id string
+    	Override the extension ID in the manifest. (default: read from -manifest file)
+  -force
+    	Force publish the extension, even if there are validation problems or other warnings.
+  -get-curl
+    	Print the curl command for executing this query and exit (WARNING: includes printing your access token!)
+  -manifest string
+    	The extension manifest file. (default "package.json")
+  -trace
+    	Log the trace ID for requests. See https://docs.sourcegraph.com/admin/observability/tracing
+  -url string
+    	Override the URL for the bundle. (example: set to http://localhost:1234/myext.js for local dev with parcel)
+
+Publish an extension to Sourcegraph, creating it (if necessary).
+
+Examples:
+
+  Publish the "alice/myextension" extension described by package.json in the current directory:
+
+    	$ cat package.json
+        {
+          "name":      "myextension",
+          "publisher": "alice",
+          "title":     "My Extension",
+          "main":      "dist/myext.js",
+          "scripts":   {"sourcegraph:prepublish": "parcel build --out-file dist/myext.js src/myext.ts"}
+        }
+    	$ src extensions publish
+
+Notes:
+
+  Source maps are supported (for easier debugging of extensions). If the main JavaScript bundle is "dist/myext.js",
+  it looks for a source map in "dist/myext.map".
+
+
+
+```
+	

doc/cli/references/extsvc/edit.md

@@ -0,0 +1,53 @@
+# `src extsvc edit`
+
+
+## Flags
+
+| Name | Description | Default Value |
+|------|-------------|---------------|
+| `-dump-requests` | Log GraphQL requests and responses to stdout | `false` |
+| `-exclude-repos` | when specified, add these repositories to the exclusion list |  |
+| `-get-curl` | Print the curl command for executing this query and exit (WARNING: includes printing your access token!) | `false` |
+| `-id` | ID of the external service to edit |  |
+| `-name` | exact name of the external service to edit |  |
+| `-rename` | when specified, renames the external service |  |
+| `-trace` | Log the trace ID for requests. See https://docs.sourcegraph.com/admin/observability/tracing | `false` |
+
+
+## Usage
+
+```
+Usage of 'src extsvc edit':
+  -dump-requests
+    	Log GraphQL requests and responses to stdout
+  -exclude-repos string
+    	when specified, add these repositories to the exclusion list
+  -get-curl
+    	Print the curl command for executing this query and exit (WARNING: includes printing your access token!)
+  -id string
+    	ID of the external service to edit
+  -name string
+    	exact name of the external service to edit
+  -rename string
+    	when specified, renames the external service
+  -trace
+    	Log the trace ID for requests. See https://docs.sourcegraph.com/admin/observability/tracing
+
+Examples:
+
+  Edit an external service configuration on the Sourcegraph instance:
+
+    	$ cat new-config.json | src extsvc edit -id 'RXh0ZXJuYWxTZXJ2aWNlOjQ='
+    	$ src extsvc edit -name 'My GitHub connection' new-config.json
+
+  Edit an external service name on the Sourcegraph instance:
+
+    	$ src extsvc edit -name 'My GitHub connection' -rename 'New name'
+
+  Add some repositories to the exclusion list of the external service:
+
+    	$ src extsvc edit -name 'My GitHub connection' -exclude-repos 'github.com/foo/one' 'github.com/foo/two'
+
+
+```
+	

doc/cli/references/extsvc/index.md

@@ -0,0 +1,8 @@
+# `src extsvc`
+
+## Subcommands
+
+
+* [`edit`](edit.md)
+* [`list`](list.md)
+	

doc/cli/references/extsvc/list.md

@@ -0,0 +1,43 @@
+# `src extsvc list`
+
+
+## Flags
+
+| Name | Description | Default Value |
+|------|-------------|---------------|
+| `-dump-requests` | Log GraphQL requests and responses to stdout | `false` |
+| `-f` | Format for the output, using the syntax of Go package text/template. (e.g. "{{.|json}}") |  |
+| `-first` | Return only the first n external services. (use -1 for unlimited) | `-1` |
+| `-get-curl` | Print the curl command for executing this query and exit (WARNING: includes printing your access token!) | `false` |
+| `-trace` | Log the trace ID for requests. See https://docs.sourcegraph.com/admin/observability/tracing | `false` |
+
+
+## Usage
+
+```
+Usage of 'src extsvc list':
+  -dump-requests
+    	Log GraphQL requests and responses to stdout
+  -f string
+    	Format for the output, using the syntax of Go package text/template. (e.g. "{{.|json}}")
+  -first int
+    	Return only the first n external services. (use -1 for unlimited) (default -1)
+  -get-curl
+    	Print the curl command for executing this query and exit (WARNING: includes printing your access token!)
+  -trace
+    	Log the trace ID for requests. See https://docs.sourcegraph.com/admin/observability/tracing
+
+Examples:
+
+  List external service configurations on the Sourcegraph instance:
+
+    	$ src extsvc list
+
+  List external service configurations and choose output format:
+
+    	$ src extsvc list -f '{{.ID}}'
+
+
+
+```
+	

doc/cli/references/gen.go

@@ -0,0 +1,3 @@
+package main
+
+//go:generate go run ./doc.go

doc/cli/references/index.md

@@ -0,0 +1,20 @@
+# `src`
+
+## Subcommands
+
+
+* [`api`](api.md)
+* [`campaigns`](campaigns/index.md)
+* [`config`](config/index.md)
+* [`extensions`](extensions/index.md)
+* [`extsvc`](extsvc/index.md)
+* [`login`](login.md)
+* [`lsif`](lsif/index.md)
+* [`orgs`](orgs/index.md)
+* [`repos`](repos/index.md)
+* [`search`](search.md)
+* [`serve-git`](serve-git.md)
+* [`users`](users/index.md)
+* [`validate`](validate.md)
+* [`version`](version.md)
+	

doc/cli/references/login.md

@@ -0,0 +1,26 @@
+# `src login`
+
+
+
+## Usage
+
+```
+'src login' helps you authenticate 'src' to access a Sourcegraph instance with your user credentials.
+
+Usage:
+
+    src login SOURCEGRAPH_URL
+
+Examples:
+
+  Authenticate to a Sourcegraph instance at https://sourcegraph.example.com:
+
+    $ src login https://sourcegraph.example.com
+
+  Authenticate to Sourcegraph.com:
+
+    $ src login https://sourcegraph.com
+
+
+```
+	

doc/cli/references/lsif/index.md

@@ -0,0 +1,7 @@
+# `src lsif`
+
+## Subcommands
+
+
+* [`upload`](upload.md)
+	

doc/cli/references/lsif/upload.md

@@ -0,0 +1,71 @@
+# `src lsif upload`
+
+
+## Flags
+
+| Name | Description | Default Value |
+|------|-------------|---------------|
+| `-commit` | The 40-character hash of the commit. Defaults to the currently checked-out commit. |  |
+| `-file` | The path to the LSIF dump file. | `./dump.lsif` |
+| `-github-token` | A GitHub access token with 'public_repo' scope that Sourcegraph uses to verify you have access to the repository. |  |
+| `-ignore-upload-failure` | Exit with status code zero on upload failure. | `false` |
+| `-indexer` | The name of the indexer that generated the dump. This will override the 'toolInfo.name' field in the metadata vertex of the LSIF dump file. This must be supplied if the indexer does not set this field (in which case the upload will fail with an explicit message). |  |
+| `-json` | Output relevant state in JSON on success. | `false` |
+| `-max-payload-size` | The maximum upload size (in megabytes). Indexes exceeding this limit will be uploaded over multiple HTTP requests. | `100` |
+| `-no-progress` | Do not display a progress bar. | `false` |
+| `-open` | Open the LSIF upload page in your browser. | `false` |
+| `-repo` | The name of the repository (e.g. github.com/gorilla/mux). By default, derived from the origin remote. |  |
+| `-root` | The path in the repository that matches the LSIF projectRoot (e.g. cmd/project1). Defaults to the directory where the dump file is located. |  |
+| `-upload-route` | The path of the upload route. | `/.api/lsif/upload` |
+
+
+## Usage
+
+```
+Usage of 'src lsif upload':
+  -commit string
+    	The 40-character hash of the commit. Defaults to the currently checked-out commit.
+  -file string
+    	The path to the LSIF dump file. (default "./dump.lsif")
+  -github-token string
+    	A GitHub access token with 'public_repo' scope that Sourcegraph uses to verify you have access to the repository.
+  -ignore-upload-failure
+    	Exit with status code zero on upload failure.
+  -indexer string
+    	The name of the indexer that generated the dump. This will override the 'toolInfo.name' field in the metadata vertex of the LSIF dump file. This must be supplied if the indexer does not set this field (in which case the upload will fail with an explicit message).
+  -json
+    	Output relevant state in JSON on success.
+  -max-payload-size int
+    	The maximum upload size (in megabytes). Indexes exceeding this limit will be uploaded over multiple HTTP requests. (default 100)
+  -no-progress
+    	Do not display a progress bar.
+  -open
+    	Open the LSIF upload page in your browser.
+  -repo string
+    	The name of the repository (e.g. github.com/gorilla/mux). By default, derived from the origin remote.
+  -root string
+    	The path in the repository that matches the LSIF projectRoot (e.g. cmd/project1). Defaults to the directory where the dump file is located.
+  -upload-route string
+    	The path of the upload route. (default "/.api/lsif/upload")
+
+Examples:
+
+  Upload an LSIF dump with explicit repo, commit, and upload files:
+
+    	$ src lsif upload -repo=FOO -commit=BAR -file=dump.lsif
+
+  Upload an LSIF dump for a subproject:
+
+    	$ src lsif upload -root=cmd/
+
+  Upload an LSIF dump when lsifEnforceAuth is enabled:
+
+    	$ src lsif upload -github-token=BAZ
+
+  Upload an LSIF dump when the LSIF indexer does not not declare a tool name.
+
+    	$ src lsif upload -indexer=lsif-elixir
+
+
+```
+	

doc/cli/references/orgs/create.md

@@ -0,0 +1,39 @@
+# `src orgs create`
+
+
+## Flags
+
+| Name | Description | Default Value |
+|------|-------------|---------------|
+| `-display-name` | The new organization's display name. |  |
+| `-dump-requests` | Log GraphQL requests and responses to stdout | `false` |
+| `-get-curl` | Print the curl command for executing this query and exit (WARNING: includes printing your access token!) | `false` |
+| `-name` | The new organization's name. (required) |  |
+| `-trace` | Log the trace ID for requests. See https://docs.sourcegraph.com/admin/observability/tracing | `false` |
+
+
+## Usage
+
+```
+Usage of 'src orgs create':
+  -display-name string
+    	The new organization's display name.
+  -dump-requests
+    	Log GraphQL requests and responses to stdout
+  -get-curl
+    	Print the curl command for executing this query and exit (WARNING: includes printing your access token!)
+  -name string
+    	The new organization's name. (required)
+  -trace
+    	Log the trace ID for requests. See https://docs.sourcegraph.com/admin/observability/tracing
+
+Examples:
+
+  Create an organization:
+
+    	$ src orgs create -name=abc-org -display-name='ABC Organization'
+
+
+
+```
+	

doc/cli/references/orgs/delete.md

@@ -0,0 +1,44 @@
+# `src orgs delete`
+
+
+## Flags
+
+| Name | Description | Default Value |
+|------|-------------|---------------|
+| `-dump-requests` | Log GraphQL requests and responses to stdout | `false` |
+| `-get-curl` | Print the curl command for executing this query and exit (WARNING: includes printing your access token!) | `false` |
+| `-id` | The ID of the organization to delete. |  |
+| `-trace` | Log the trace ID for requests. See https://docs.sourcegraph.com/admin/observability/tracing | `false` |
+
+
+## Usage
+
+```
+Usage of 'src orgs delete':
+  -dump-requests
+    	Log GraphQL requests and responses to stdout
+  -get-curl
+    	Print the curl command for executing this query and exit (WARNING: includes printing your access token!)
+  -id string
+    	The ID of the organization to delete.
+  -trace
+    	Log the trace ID for requests. See https://docs.sourcegraph.com/admin/observability/tracing
+
+Examples:
+
+  Delete an organization by ID:
+
+    	$ src orgs delete -id=VXNlcjox
+
+  Delete an organization by name:
+
+    	$ src orgs delete -id=$(src orgs get -f='{{.ID}}' -name=abc-org)
+
+  Delete all organizations that match the query
+
+    	$ src orgs list -f='{{.ID}}' -query=abc-org | xargs -n 1 -I ORGID src orgs delete -id=ORGID
+
+
+
+```
+	

doc/cli/references/orgs/get.md

@@ -0,0 +1,43 @@
+# `src orgs get`
+
+
+## Flags
+
+| Name | Description | Default Value |
+|------|-------------|---------------|
+| `-dump-requests` | Log GraphQL requests and responses to stdout | `false` |
+| `-f` | Format for the output, using the syntax of Go package text/template. (e.g. "{{.ID}}: {{.Name}} ({{.DisplayName}})") | `{{.|json}}` |
+| `-get-curl` | Print the curl command for executing this query and exit (WARNING: includes printing your access token!) | `false` |
+| `-name` | Look up organization by name. (e.g. "abc-org") |  |
+| `-trace` | Log the trace ID for requests. See https://docs.sourcegraph.com/admin/observability/tracing | `false` |
+
+
+## Usage
+
+```
+Usage of 'src orgs get':
+  -dump-requests
+    	Log GraphQL requests and responses to stdout
+  -f string
+    	Format for the output, using the syntax of Go package text/template. (e.g. "{{.ID}}: {{.Name}} ({{.DisplayName}})") (default "{{.|json}}")
+  -get-curl
+    	Print the curl command for executing this query and exit (WARNING: includes printing your access token!)
+  -name string
+    	Look up organization by name. (e.g. "abc-org")
+  -trace
+    	Log the trace ID for requests. See https://docs.sourcegraph.com/admin/observability/tracing
+
+Examples:
+
+  Get organization named abc-org:
+
+    	$ src orgs get -name=abc-org
+
+  List usernames of members of organization named abc-org (replace '.Username' with '.ID' to list user IDs):
+
+    	$ src orgs get -f '{{range $i,$ := .Members.Nodes}}{{if ne $i 0}}{{"\n"}}{{end}}{{.Username}}{{end}}' -name=abc-org
+
+
+
+```
+	

doc/cli/references/orgs/index.md

@@ -0,0 +1,11 @@
+# `src orgs`
+
+## Subcommands
+
+
+* [`create`](create.md)
+* [`delete`](delete.md)
+* [`get`](get.md)
+* [`list`](list.md)
+* [`members`](members/index.md)
+	

doc/cli/references/orgs/list.md

@@ -0,0 +1,50 @@
+# `src orgs list`
+
+
+## Flags
+
+| Name | Description | Default Value |
+|------|-------------|---------------|
+| `-dump-requests` | Log GraphQL requests and responses to stdout | `false` |
+| `-f` | Format for the output, using the syntax of Go package text/template. (e.g. "{{.ID}}: {{.Name}} ({{.DisplayName}})" or "{{.|json}}") | `{{.Name}}` |
+| `-first` | Returns the first n organizations from the list. (use -1 for unlimited) | `1000` |
+| `-get-curl` | Print the curl command for executing this query and exit (WARNING: includes printing your access token!) | `false` |
+| `-query` | Returns organizations whose names match the query. (e.g. "alice") |  |
+| `-trace` | Log the trace ID for requests. See https://docs.sourcegraph.com/admin/observability/tracing | `false` |
+
+
+## Usage
+
+```
+Usage of 'src orgs list':
+  -dump-requests
+    	Log GraphQL requests and responses to stdout
+  -f string
+    	Format for the output, using the syntax of Go package text/template. (e.g. "{{.ID}}: {{.Name}} ({{.DisplayName}})" or "{{.|json}}") (default "{{.Name}}")
+  -first int
+    	Returns the first n organizations from the list. (use -1 for unlimited) (default 1000)
+  -get-curl
+    	Print the curl command for executing this query and exit (WARNING: includes printing your access token!)
+  -query string
+    	Returns organizations whose names match the query. (e.g. "alice")
+  -trace
+    	Log the trace ID for requests. See https://docs.sourcegraph.com/admin/observability/tracing
+
+Examples:
+
+  List organizations:
+
+    	$ src orgs list
+
+  List *all* organizations (may be slow!):
+
+    	$ src orgs list -first='-1'
+
+  List organizations whose names match the query:
+
+    	$ src orgs list -query='myquery'
+
+
+
+```
+	

doc/cli/references/orgs/members/add.md

@@ -0,0 +1,39 @@
+# `src orgs members add`
+
+
+## Flags
+
+| Name | Description | Default Value |
+|------|-------------|---------------|
+| `-dump-requests` | Log GraphQL requests and responses to stdout | `false` |
+| `-get-curl` | Print the curl command for executing this query and exit (WARNING: includes printing your access token!) | `false` |
+| `-org-id` | ID of organization to which to add member. (required) |  |
+| `-trace` | Log the trace ID for requests. See https://docs.sourcegraph.com/admin/observability/tracing | `false` |
+| `-username` | Username of user to add as member. (required) |  |
+
+
+## Usage
+
+```
+Usage of 'src orgs members add':
+  -dump-requests
+    	Log GraphQL requests and responses to stdout
+  -get-curl
+    	Print the curl command for executing this query and exit (WARNING: includes printing your access token!)
+  -org-id string
+    	ID of organization to which to add member. (required)
+  -trace
+    	Log the trace ID for requests. See https://docs.sourcegraph.com/admin/observability/tracing
+  -username string
+    	Username of user to add as member. (required)
+
+Examples:
+
+  Add a member (alice) to an organization (abc-org):
+
+    	$ src orgs members add -org-id=$(src org get -f '{{.ID}}' -name=abc-org) -username=alice
+
+
+
+```
+	

doc/cli/references/orgs/members/index.md

@@ -0,0 +1,8 @@
+# `src orgs members`
+
+## Subcommands
+
+
+* [`add`](add.md)
+* [`remove`](remove.md)
+	

doc/cli/references/orgs/members/remove.md

@@ -0,0 +1,38 @@
+# `src orgs members remove`
+
+
+## Flags
+
+| Name | Description | Default Value |
+|------|-------------|---------------|
+| `-dump-requests` | Log GraphQL requests and responses to stdout | `false` |
+| `-get-curl` | Print the curl command for executing this query and exit (WARNING: includes printing your access token!) | `false` |
+| `-org-id` | ID of organization from which to remove member. (required) |  |
+| `-trace` | Log the trace ID for requests. See https://docs.sourcegraph.com/admin/observability/tracing | `false` |
+| `-user-id` | ID of user to remove as member. (required) |  |
+
+
+## Usage
+
+```
+Usage of 'src orgs members remove':
+  -dump-requests
+    	Log GraphQL requests and responses to stdout
+  -get-curl
+    	Print the curl command for executing this query and exit (WARNING: includes printing your access token!)
+  -org-id string
+    	ID of organization from which to remove member. (required)
+  -trace
+    	Log the trace ID for requests. See https://docs.sourcegraph.com/admin/observability/tracing
+  -user-id string
+    	ID of user to remove as member. (required)
+
+Examples:
+
+  Remove a member (alice) from an organization (abc-org):
+
+    	$ src orgs members remove -org-id=$(src org get -f '{{.ID}}' -name=abc-org) -user-id=$(src users get -f '{{.ID}}' -username=alice)
+
+
+```
+	

doc/cli/references/repos/delete.md

@@ -0,0 +1,31 @@
+# `src repos delete`
+
+
+## Flags
+
+| Name | Description | Default Value |
+|------|-------------|---------------|
+| `-dump-requests` | Log GraphQL requests and responses to stdout | `false` |
+| `-get-curl` | Print the curl command for executing this query and exit (WARNING: includes printing your access token!) | `false` |
+| `-trace` | Log the trace ID for requests. See https://docs.sourcegraph.com/admin/observability/tracing | `false` |
+
+
+## Usage
+
+```
+Usage of 'src repos delete'
+  -dump-requests
+    	Log GraphQL requests and responses to stdout
+  -get-curl
+    	Print the curl command for executing this query and exit (WARNING: includes printing your access token!)
+  -trace
+    	Log the trace ID for requests. See https://docs.sourcegraph.com/admin/observability/tracing
+
+Examples:
+
+   Delete one or more repositories:
+
+    	$ src repos delete github.com/my/repo github.com/my/repo2
+
+```
+	

doc/cli/references/repos/disable.md

@@ -0,0 +1,33 @@
+# `src repos disable`
+
+
+## Flags
+
+| Name | Description | Default Value |
+|------|-------------|---------------|
+| `-dump-requests` | Log GraphQL requests and responses to stdout | `false` |
+| `-get-curl` | Print the curl command for executing this query and exit (WARNING: includes printing your access token!) | `false` |
+| `-trace` | Log the trace ID for requests. See https://docs.sourcegraph.com/admin/observability/tracing | `false` |
+
+
+## Usage
+
+```
+Usage of 'src repos disable':
+  -dump-requests
+    	Log GraphQL requests and responses to stdout
+  -get-curl
+    	Print the curl command for executing this query and exit (WARNING: includes printing your access token!)
+  -trace
+    	Log the trace ID for requests. See https://docs.sourcegraph.com/admin/observability/tracing
+
+Examples:
+
+  Disable one or more repositories:
+
+    	$ src repos disable github.com/my/repo github.com/my/repo2
+
+
+
+```
+	

doc/cli/references/repos/enable.md

@@ -0,0 +1,33 @@
+# `src repos enable`
+
+
+## Flags
+
+| Name | Description | Default Value |
+|------|-------------|---------------|
+| `-dump-requests` | Log GraphQL requests and responses to stdout | `false` |
+| `-get-curl` | Print the curl command for executing this query and exit (WARNING: includes printing your access token!) | `false` |
+| `-trace` | Log the trace ID for requests. See https://docs.sourcegraph.com/admin/observability/tracing | `false` |
+
+
+## Usage
+
+```
+Usage of 'src repos enable':
+  -dump-requests
+    	Log GraphQL requests and responses to stdout
+  -get-curl
+    	Print the curl command for executing this query and exit (WARNING: includes printing your access token!)
+  -trace
+    	Log the trace ID for requests. See https://docs.sourcegraph.com/admin/observability/tracing
+
+Examples:
+
+  Enable one or more repositories:
+
+    	$ src repos enable github.com/my/repo github.com/my/repo2
+
+
+
+```
+	

doc/cli/references/repos/get.md

@@ -0,0 +1,39 @@
+# `src repos get`
+
+
+## Flags
+
+| Name | Description | Default Value |
+|------|-------------|---------------|
+| `-dump-requests` | Log GraphQL requests and responses to stdout | `false` |
+| `-f` | Format for the output, using the syntax of Go package text/template. (e.g. "{{.ID}}: {{.Name}}") or "{{.|json}}") | `{{.ID}}` |
+| `-get-curl` | Print the curl command for executing this query and exit (WARNING: includes printing your access token!) | `false` |
+| `-name` | The name of the repository. (required) |  |
+| `-trace` | Log the trace ID for requests. See https://docs.sourcegraph.com/admin/observability/tracing | `false` |
+
+
+## Usage
+
+```
+Usage of 'src repos get':
+  -dump-requests
+    	Log GraphQL requests and responses to stdout
+  -f string
+    	Format for the output, using the syntax of Go package text/template. (e.g. "{{.ID}}: {{.Name}}") or "{{.|json}}") (default "{{.ID}}")
+  -get-curl
+    	Print the curl command for executing this query and exit (WARNING: includes printing your access token!)
+  -name string
+    	The name of the repository. (required)
+  -trace
+    	Log the trace ID for requests. See https://docs.sourcegraph.com/admin/observability/tracing
+
+Examples:
+
+  Look up a repository by name:
+
+    	$ src repos get -name=github.com/sourcegraph/src-cli
+
+
+
+```
+	

doc/cli/references/repos/index.md

@@ -0,0 +1,11 @@
+# `src repos`
+
+## Subcommands
+
+
+* [`delete`](delete.md)
+* [`disable`](disable.md)
+* [`enable`](enable.md)
+* [`get`](get.md)
+* [`list`](list.md)
+	

doc/cli/references/repos/list.md

@@ -0,0 +1,75 @@
+# `src repos list`
+
+
+## Flags
+
+| Name | Description | Default Value |
+|------|-------------|---------------|
+| `-cloned` | Include cloned repositories. | `true` |
+| `-descending` | Whether or not results should be in descending order. | `false` |
+| `-dump-requests` | Log GraphQL requests and responses to stdout | `false` |
+| `-f` | Format for the output, using the syntax of Go package text/template. (e.g. "{{.ID}}: {{.Name}}") or "{{.|json}}") | `{{.Name}}` |
+| `-first` | Returns the first n repositories from the list. (use -1 for unlimited) | `1000` |
+| `-get-curl` | Print the curl command for executing this query and exit (WARNING: includes printing your access token!) | `false` |
+| `-indexed` | Include repositories that have a text search index. | `true` |
+| `-names-without-host` | Whether or not repository names should be printed without the hostname (or other first path component). If set, -f is ignored. | `false` |
+| `-not-cloned` | Include repositories that are not yet cloned and for which cloning is not in progress. | `true` |
+| `-not-indexed` | Include repositories that do not have a text search index. | `true` |
+| `-order-by` | How to order the results; possible choices are: "name", "created-at" | `name` |
+| `-query` | Returns repositories whose names match the query. (e.g. "myorg/") |  |
+| `-trace` | Log the trace ID for requests. See https://docs.sourcegraph.com/admin/observability/tracing | `false` |
+
+
+## Usage
+
+```
+Usage of 'src repos list':
+  -cloned
+    	Include cloned repositories. (default true)
+  -descending
+    	Whether or not results should be in descending order.
+  -dump-requests
+    	Log GraphQL requests and responses to stdout
+  -f string
+    	Format for the output, using the syntax of Go package text/template. (e.g. "{{.ID}}: {{.Name}}") or "{{.|json}}") (default "{{.Name}}")
+  -first int
+    	Returns the first n repositories from the list. (use -1 for unlimited) (default 1000)
+  -get-curl
+    	Print the curl command for executing this query and exit (WARNING: includes printing your access token!)
+  -indexed
+    	Include repositories that have a text search index. (default true)
+  -names-without-host
+    	Whether or not repository names should be printed without the hostname (or other first path component). If set, -f is ignored.
+  -not-cloned
+    	Include repositories that are not yet cloned and for which cloning is not in progress. (default true)
+  -not-indexed
+    	Include repositories that do not have a text search index. (default true)
+  -order-by string
+    	How to order the results; possible choices are: "name", "created-at" (default "name")
+  -query string
+    	Returns repositories whose names match the query. (e.g. "myorg/")
+  -trace
+    	Log the trace ID for requests. See https://docs.sourcegraph.com/admin/observability/tracing
+
+Examples:
+
+  List repositories:
+
+    	$ src repos list
+
+  Print JSON description of repositories list:
+
+    	$ src repos list -f '{{.|json}}'
+
+  List *all* repositories (may be slow!):
+
+    	$ src repos list -first='-1'
+
+  List repositories whose names match the query:
+
+    	$ src repos list -query='myquery'
+
+
+
+```
+	

doc/cli/references/search.md

@@ -0,0 +1,58 @@
+# `src search`
+
+
+## Flags
+
+| Name | Description | Default Value |
+|------|-------------|---------------|
+| `-dump-requests` | Log GraphQL requests and responses to stdout | `false` |
+| `-explain-json` | Explain the JSON output schema and exit. | `false` |
+| `-get-curl` | Print the curl command for executing this query and exit (WARNING: includes printing your access token!) | `false` |
+| `-json` | Whether or not to output results as JSON | `false` |
+| `-less` | Pipe output to 'less -R' (only if stdout is terminal, and not json flag) | `true` |
+| `-trace` | Log the trace ID for requests. See https://docs.sourcegraph.com/admin/observability/tracing | `false` |
+
+
+## Usage
+
+```
+Usage of 'src search':
+  -dump-requests
+    	Log GraphQL requests and responses to stdout
+  -explain-json
+    	Explain the JSON output schema and exit.
+  -get-curl
+    	Print the curl command for executing this query and exit (WARNING: includes printing your access token!)
+  -json
+    	Whether or not to output results as JSON
+  -less
+    	Pipe output to 'less -R' (only if stdout is terminal, and not json flag) (default true)
+  -trace
+    	Log the trace ID for requests. See https://docs.sourcegraph.com/admin/observability/tracing
+
+Examples:
+
+  Perform a search and get results:
+
+    	$ src search 'repogroup:sample error'
+
+  Perform a search and get results as JSON:
+
+    	$ src search -json 'repogroup:sample error'
+
+Other tips:
+
+  Make 'type:diff' searches have colored diffs by installing https://colordiff.org
+    - Ubuntu/Debian: $ sudo apt-get install colordiff
+    - Mac OS:        $ brew install colordiff
+    - Windows:       $ npm install -g colordiff
+
+  Disable color output by setting NO_COLOR=t (see https://no-color.org).
+
+  Force color output on (not on by default when piped to other programs) by setting COLOR=t
+
+  Query syntax: https://about.sourcegraph.com/docs/search/query-syntax/
+
+
+```
+	

doc/cli/references/serve-git.md

@@ -0,0 +1,28 @@
+# `src serve-git`
+
+
+## Flags
+
+| Name | Description | Default Value |
+|------|-------------|---------------|
+| `-addr` | Address on which to serve (end with : for unused port) | `:3434` |
+| `-list` | list found repository names | `false` |
+
+
+## Usage
+
+```
+'src serve-git' serves your local git repositories over HTTP for Sourcegraph to pull.
+
+USAGE
+  src [-v] serve-git [-list] [-addr :3434] [path/to/dir]
+
+By default 'src serve-git' will recursively serve your current directory on the address ':3434'.
+
+'src serve-git -list' will not start up the server. Instead it will write to stdout a list of
+repository names it would serve.
+
+Documentation at https://docs.sourcegraph.com/admin/external_service/src_serve_git
+
+```
+	

doc/cli/references/users/create.md

@@ -0,0 +1,42 @@
+# `src users create`
+
+
+## Flags
+
+| Name | Description | Default Value |
+|------|-------------|---------------|
+| `-dump-requests` | Log GraphQL requests and responses to stdout | `false` |
+| `-email` | The new user's email address. (required) |  |
+| `-get-curl` | Print the curl command for executing this query and exit (WARNING: includes printing your access token!) | `false` |
+| `-reset-password-url` | Print the reset password URL to manually send to the new user. | `false` |
+| `-trace` | Log the trace ID for requests. See https://docs.sourcegraph.com/admin/observability/tracing | `false` |
+| `-username` | The new user's username. (required) |  |
+
+
+## Usage
+
+```
+Usage of 'src users create':
+  -dump-requests
+    	Log GraphQL requests and responses to stdout
+  -email string
+    	The new user's email address. (required)
+  -get-curl
+    	Print the curl command for executing this query and exit (WARNING: includes printing your access token!)
+  -reset-password-url
+    	Print the reset password URL to manually send to the new user.
+  -trace
+    	Log the trace ID for requests. See https://docs.sourcegraph.com/admin/observability/tracing
+  -username string
+    	The new user's username. (required)
+
+Examples:
+
+  Create a user account:
+
+    	$ src users create -username=alice -email=alice@example.com
+
+
+
+```
+	

doc/cli/references/users/delete.md

@@ -0,0 +1,44 @@
+# `src users delete`
+
+
+## Flags
+
+| Name | Description | Default Value |
+|------|-------------|---------------|
+| `-dump-requests` | Log GraphQL requests and responses to stdout | `false` |
+| `-get-curl` | Print the curl command for executing this query and exit (WARNING: includes printing your access token!) | `false` |
+| `-id` | The ID of the user to delete. |  |
+| `-trace` | Log the trace ID for requests. See https://docs.sourcegraph.com/admin/observability/tracing | `false` |
+
+
+## Usage
+
+```
+Usage of 'src users delete':
+  -dump-requests
+    	Log GraphQL requests and responses to stdout
+  -get-curl
+    	Print the curl command for executing this query and exit (WARNING: includes printing your access token!)
+  -id string
+    	The ID of the user to delete.
+  -trace
+    	Log the trace ID for requests. See https://docs.sourcegraph.com/admin/observability/tracing
+
+Examples:
+
+  Delete a user account by ID:
+
+    	$ src users delete -id=VXNlcjox
+
+  Delete a user account by username:
+
+    	$ src users delete -id=$(src users get -f='{{.ID}}' -username=alice)
+
+  Delete all user accounts that match the query:
+
+    	$ src users list -f='{{.ID}}' -query=alice | xargs -n 1 -I USERID src users delete -id=USERID
+
+
+
+```
+	

doc/cli/references/users/get.md

@@ -0,0 +1,39 @@
+# `src users get`
+
+
+## Flags
+
+| Name | Description | Default Value |
+|------|-------------|---------------|
+| `-dump-requests` | Log GraphQL requests and responses to stdout | `false` |
+| `-f` | Format for the output, using the syntax of Go package text/template. (e.g. "{{.ID}}: {{.Username}} ({{.DisplayName}})") | `{{.|json}}` |
+| `-get-curl` | Print the curl command for executing this query and exit (WARNING: includes printing your access token!) | `false` |
+| `-trace` | Log the trace ID for requests. See https://docs.sourcegraph.com/admin/observability/tracing | `false` |
+| `-username` | Look up user by username. (e.g. "alice") |  |
+
+
+## Usage
+
+```
+Usage of 'src users get':
+  -dump-requests
+    	Log GraphQL requests and responses to stdout
+  -f string
+    	Format for the output, using the syntax of Go package text/template. (e.g. "{{.ID}}: {{.Username}} ({{.DisplayName}})") (default "{{.|json}}")
+  -get-curl
+    	Print the curl command for executing this query and exit (WARNING: includes printing your access token!)
+  -trace
+    	Log the trace ID for requests. See https://docs.sourcegraph.com/admin/observability/tracing
+  -username string
+    	Look up user by username. (e.g. "alice")
+
+Examples:
+
+  Get user with username alice:
+
+    	$ src users get -username=alice
+
+
+
+```
+	

doc/cli/references/users/index.md

@@ -0,0 +1,11 @@
+# `src users`
+
+## Subcommands
+
+
+* [`create`](create.md)
+* [`delete`](delete.md)
+* [`get`](get.md)
+* [`list`](list.md)
+* [`tag`](tag.md)
+	

doc/cli/references/users/list.md

@@ -0,0 +1,57 @@
+# `src users list`
+
+
+## Flags
+
+| Name | Description | Default Value |
+|------|-------------|---------------|
+| `-dump-requests` | Log GraphQL requests and responses to stdout | `false` |
+| `-f` | Format for the output, using the syntax of Go package text/template. (e.g. "{{.ID}}: {{.Username}} ({{.DisplayName}})" or "{{.|json}}") | `{{.Username}}` |
+| `-first` | Returns the first n users from the list. (use -1 for unlimited) | `1000` |
+| `-get-curl` | Print the curl command for executing this query and exit (WARNING: includes printing your access token!) | `false` |
+| `-query` | Returns users whose names match the query. (e.g. "alice") |  |
+| `-tag` | Returns users with the given tag. |  |
+| `-trace` | Log the trace ID for requests. See https://docs.sourcegraph.com/admin/observability/tracing | `false` |
+
+
+## Usage
+
+```
+Usage of 'src users list':
+  -dump-requests
+    	Log GraphQL requests and responses to stdout
+  -f string
+    	Format for the output, using the syntax of Go package text/template. (e.g. "{{.ID}}: {{.Username}} ({{.DisplayName}})" or "{{.|json}}") (default "{{.Username}}")
+  -first int
+    	Returns the first n users from the list. (use -1 for unlimited) (default 1000)
+  -get-curl
+    	Print the curl command for executing this query and exit (WARNING: includes printing your access token!)
+  -query string
+    	Returns users whose names match the query. (e.g. "alice")
+  -tag string
+    	Returns users with the given tag.
+  -trace
+    	Log the trace ID for requests. See https://docs.sourcegraph.com/admin/observability/tracing
+
+Examples:
+
+  List users:
+
+    	$ src users list
+
+  List *all* users (may be slow!):
+
+    	$ src users list -first='-1'
+
+  List users whose names match the query:
+
+    	$ src users list -query='myquery'
+
+  List all users with the "foo" tag:
+
+    	$ src users list -tag=foo
+
+
+
+```
+	

doc/cli/references/users/tag.md

@@ -0,0 +1,52 @@
+# `src users tag`
+
+
+## Flags
+
+| Name | Description | Default Value |
+|------|-------------|---------------|
+| `-dump-requests` | Log GraphQL requests and responses to stdout | `false` |
+| `-get-curl` | Print the curl command for executing this query and exit (WARNING: includes printing your access token!) | `false` |
+| `-remove` | Remove the tag. (default: add the tag | `false` |
+| `-tag` | The tag to set on the user. (required) |  |
+| `-trace` | Log the trace ID for requests. See https://docs.sourcegraph.com/admin/observability/tracing | `false` |
+| `-user-id` | The ID of the user to tag. (required) |  |
+
+
+## Usage
+
+```
+Usage of 'src users tag':
+  -dump-requests
+    	Log GraphQL requests and responses to stdout
+  -get-curl
+    	Print the curl command for executing this query and exit (WARNING: includes printing your access token!)
+  -remove
+    	Remove the tag. (default: add the tag
+  -tag string
+    	The tag to set on the user. (required)
+  -trace
+    	Log the trace ID for requests. See https://docs.sourcegraph.com/admin/observability/tracing
+  -user-id string
+    	The ID of the user to tag. (required)
+
+Examples:
+
+  Add a tag "foo" to a user:
+
+    	$ src users tag -user-id=$(src users get -f '{{.ID}}' -username=alice) -tag=foo
+
+  Remove a tag "foo" to a user:
+
+    	$ src users tag -user-id=$(src users get -f '{{.ID}}' -username=alice) -remove -tag=foo
+
+Related examples:
+
+  List all users with the "foo" tag:
+
+    	$ src users list -tag=foo
+
+
+
+```
+	

doc/cli/references/validate.md

@@ -0,0 +1,43 @@
+# `src validate`
+
+
+## Flags
+
+| Name | Description | Default Value |
+|------|-------------|---------------|
+| `-context` | Comma-separated list of key=value pairs to add to the script execution context |  |
+| `-dump-requests` | Log GraphQL requests and responses to stdout | `false` |
+| `-get-curl` | Print the curl command for executing this query and exit (WARNING: includes printing your access token!) | `false` |
+| `-secrets` | Path to a file containing key=value lines. The key value pairs will be added to the script context |  |
+| `-trace` | Log the trace ID for requests. See https://docs.sourcegraph.com/admin/observability/tracing | `false` |
+
+
+## Usage
+
+```
+Usage of 'src validate validate':
+  -context string
+    	Comma-separated list of key=value pairs to add to the script execution context
+  -dump-requests
+    	Log GraphQL requests and responses to stdout
+  -get-curl
+    	Print the curl command for executing this query and exit (WARNING: includes printing your access token!)
+  -secrets string
+    	Path to a file containing key=value lines. The key value pairs will be added to the script context
+  -trace
+    	Log the trace ID for requests. See https://docs.sourcegraph.com/admin/observability/tracing
+'src validate' is a tool that validates a Sourcegraph instance.
+
+EXPERIMENTAL: 'validate' is an experimental command in the 'src' tool.
+
+Usage:
+
+	src validate [options] src-validate.yml
+or
+    cat src-validate.yml | src validate [options]
+
+Please visit https://docs.sourcegraph.com/admin/validation for documentation of the validate command.
+
+
+```
+	

doc/cli/references/version.md

@@ -0,0 +1,18 @@
+# `src version`
+
+
+
+## Usage
+
+```
+Usage of 'src version':
+
+Examples:
+
+  Get the src-cli version and the Sourcegraph instance's recommended version:
+
+    	$ src version
+
+
+```
+	

doc/sidebar.md

@@ -34,6 +34,11 @@ Keep it as a single list with at most 2 levels. (Anything else may not render co
   - [Editors](integration/editor.md)
   - [Browser search engine](integration/browser_search_engine.md)
 - [Extensions](extensions/index.md)
+- [CLI](cli/index.md)
+  - [Quickstart](cli/quickstart.md)
+  - [Explanations](cli/explanations/index.md)
+  - [How-to guides](cli/how-tos/index.md)
+  - [References](cli/references/index.md)
 - [Adopting](adopt/index.md)
 - [Administration](admin/index.md)
   - [Install](admin/install/index.md)