diff --git a/docs/cli/references/debug.mdx b/docs/cli/references/debug.mdx deleted file mode 100644 index 07cd0797b..000000000 --- a/docs/cli/references/debug.mdx +++ /dev/null @@ -1,27 +0,0 @@ -# `src debug` - - - -## Usage - -``` -'src debug' gathers and bundles debug data from a Sourcegraph deployment for troubleshooting. - -Usage: - - src debug command [command options] - -The commands are: - - kube dumps context from k8s deployments - compose dumps context from docker-compose deployments - server dumps context from single-container deployments - - -Use "src debug command -h" for more information about a subcommands. -src debug has access to flags on src -- Ex: src -v kube -o foo.zip - - - -``` - \ No newline at end of file diff --git a/docs/cli/references/debug/compose.mdx b/docs/cli/references/debug/compose.mdx new file mode 100644 index 000000000..2000a4d70 --- /dev/null +++ b/docs/cli/references/debug/compose.mdx @@ -0,0 +1,37 @@ +# `src debug compose` + + +## Flags + +| Name | Description | Default Value | +|------|-------------|---------------| +| `-no-configs` | If true, exclude Sourcegraph configuration files. Defaults to false. | `false` | +| `-o` | The name of the output zip archive | `debug.zip` | + + +## Usage + +``` + +'src debug compose' invokes docker cli diagnostic commands targeting a set of containers that are members of a docker-compose network, +writing an archive file from their returns. + +Usage: + + src debug compose [command options] + +Flags: + + -o Specify the name of the output zip archive. + --no-configs Don't include Sourcegraph configuration json. + +Examples: + + $ src debug compose -o debug.zip + + $ src -v debug compose -no-configs -o foo.zip + + + +``` + \ No newline at end of file diff --git a/docs/cli/references/debug/index.mdx b/docs/cli/references/debug/index.mdx new file mode 100644 index 000000000..d2fdcaac4 --- /dev/null +++ b/docs/cli/references/debug/index.mdx @@ -0,0 +1,9 @@ +# `src debug` + +## Subcommands + + +* [`compose`](debug/compose) +* [`kube`](debug/kube) +* [`server`](debug/server) + \ No newline at end of file diff --git a/docs/cli/references/debug/kube.mdx b/docs/cli/references/debug/kube.mdx new file mode 100644 index 000000000..5c8203d1b --- /dev/null +++ b/docs/cli/references/debug/kube.mdx @@ -0,0 +1,40 @@ +# `src debug kube` + + +## Flags + +| Name | Description | Default Value | +|------|-------------|---------------| +| `-n` | The namespace passed to kubectl commands, if not specified the 'default' namespace is used | `default` | +| `-no-configs` | If true, exclude Sourcegraph configuration files. Defaults to false. | `false` | +| `-o` | The name of the output zip archive | `debug.zip` | + + +## Usage + +``` + +'src debug kube' invokes kubectl diagnostic commands targeting kubectl's current-context, writing returns to an archive. + +Usage: + + src debug kube [command options] + +Flags: + + -o Specify the name of the output zip archive. + -n Specify the namespace passed to kubectl commands. If not specified the 'default' namespace is used. + --no-config Don't include Sourcegraph configuration json. + +Examples: + + $ src debug kube -o debug.zip + + $ src -v debug kube -n ns-sourcegraph -o foo + + $ src debug kube -no-configs -o bar.zip + + + +``` + \ No newline at end of file diff --git a/docs/cli/references/debug/server.mdx b/docs/cli/references/debug/server.mdx new file mode 100644 index 000000000..caf960806 --- /dev/null +++ b/docs/cli/references/debug/server.mdx @@ -0,0 +1,38 @@ +# `src debug server` + + +## Flags + +| Name | Description | Default Value | +|------|-------------|---------------| +| `-c` | The container to target | | +| `-no-configs` | If true, exclude Sourcegraph configuration files. Defaults to false. | `false` | +| `-o` | The name of the output zip archive | `debug.zip` | + + +## Usage + +``` + +'src debug server' invokes docker cli diagnostic commands targeting a Sourcegraph server container, +and writes an archive file from their returns. + +Usage: + + src debug server [command options] + +Flags: + + -o Specify the name of the output zip archive. + -no-config Don't include Sourcegraph configuration json. + +Examples: + + $ src debug server -c foo -o debug.zip + + $ src -v debug server --no-configs -c ViktorVaughn -o foo.zip + + + +``` + \ No newline at end of file diff --git a/docs/cli/references/index.mdx b/docs/cli/references/index.mdx index fb7a86720..ce45deb1d 100644 --- a/docs/cli/references/index.mdx +++ b/docs/cli/references/index.mdx @@ -6,9 +6,20 @@ * [`abc`](references/abc) * [`api`](references/api) * [`auth`](references/auth) +* [`batch`](references/batch) +* [`code-intel`](references/code-intel) * [`codeowners`](references/codeowners) +* [`config`](references/config) +* [`debug`](references/debug) +* [`extsvc`](references/extsvc) * [`login`](references/login) +* [`lsp`](references/lsp) * [`orgs`](references/orgs) +* [`repos`](references/repos) +* [`search`](references/search) +* [`search-jobs`](references/search-jobs) +* [`serve-git`](references/serve-git) +* [`snapshot`](references/snapshot) * [`users`](references/users) * [`version`](references/version) \ No newline at end of file diff --git a/docs/cli/references/search-jobs.mdx b/docs/cli/references/search-jobs.mdx deleted file mode 100644 index 1cfb311bb..000000000 --- a/docs/cli/references/search-jobs.mdx +++ /dev/null @@ -1,33 +0,0 @@ -# `src search-jobs` - - - -## Usage - -``` -'src search-jobs' is a tool that manages search jobs on a Sourcegraph instance. - - Usage: - - src search-jobs command [command options] - - The commands are: - - cancel cancels a search job by ID - create creates a search job - delete deletes a search job by ID - get gets a search job by ID - list lists search jobs - logs fetches logs for a search job by ID - restart restarts a search job by ID - results fetches results for a search job by ID - - Common options for all commands: - -c Select columns to display (e.g., -c id,query,state,username) - -json Output results in JSON format - - Use "src search-jobs [command] -h" for more information about a command. - - -``` - \ No newline at end of file diff --git a/docs/cli/references/search-jobs/cancel.mdx b/docs/cli/references/search-jobs/cancel.mdx index f8a9dded8..5f39fd539 100644 --- a/docs/cli/references/search-jobs/cancel.mdx +++ b/docs/cli/references/search-jobs/cancel.mdx @@ -1,37 +1,49 @@ -# src search-jobs cancel +# `src search-jobs cancel` + + +## Flags + +| Name | Description | Default Value | +|------|-------------|---------------| +| `-c` | Comma-separated list of columns to display. Available: id,query,state,username,createdat,startedat,finishedat,url,logurl,total,completed,failed,inprogress | `id,username,state,query` | +| `-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` | +| `-insecure-skip-verify` | Skip validation of TLS certificates against trusted chains | `false` | +| `-json` | Output results as JSON for programmatic access | `false` | +| `-trace` | Log the trace ID for requests. See https://sourcegraph.com/docs/admin/observability/tracing | `false` | +| `-user-agent-telemetry` | Include the operating system and architecture in the User-Agent sent with requests to Sourcegraph | `true` | -

- `src search-jobs cancel` is a tool that cancels a search job on a - Sourcegraph instance. -

## Usage -```bash +``` Usage of 'src search-jobs cancel': -c string - Comma-separated list of columns to display. Available: id,query,state,username,createdat,startedat,finishedat,url,logurl,total,completed,failed,inprogress (default "id,username,state,query") + Comma-separated list of columns to display. Available: id,query,state,username,createdat,startedat,finishedat,url,logurl,total,completed,failed,inprogress (default "id,username,state,query") -dump-requests - Log GraphQL requests and responses to stdout + 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!) + Print the curl command for executing this query and exit (WARNING: includes printing your access token!) -insecure-skip-verify - Skip validation of TLS certificates against trusted chains + Skip validation of TLS certificates against trusted chains -json - Output results as JSON for programmatic access + Output results as JSON for programmatic access -trace - Log the trace ID for requests. See https://docs.sourcegraph.com/admin/observability/tracing + Log the trace ID for requests. See https://sourcegraph.com/docs/admin/observability/tracing -user-agent-telemetry - Include the operating system and architecture in the User-Agent sent with requests to Sourcegraph (default true) - - Examples: - - Cancel a search job by ID: - - $ src search-jobs cancel U2VhcmNoSm9iOjY5 - - Arguments: - The ID of the search job to cancel. + Include the operating system and architecture in the User-Agent sent with requests to Sourcegraph (default true) + + Examples: + + Cancel a search job by ID: + + $ src search-jobs cancel U2VhcmNoSm9iOjY5 + + Arguments: + The ID of the search job to cancel. + + The cancel command stops a running search job and outputs a confirmation message. + - The cancel command stops a running search job and outputs a confirmation message. ``` + \ No newline at end of file diff --git a/docs/cli/references/search-jobs/create.mdx b/docs/cli/references/search-jobs/create.mdx index b63fb061f..098a6e442 100644 --- a/docs/cli/references/search-jobs/create.mdx +++ b/docs/cli/references/search-jobs/create.mdx @@ -1,43 +1,55 @@ -# src search-jobs create +# `src search-jobs create` + + +## Flags + +| Name | Description | Default Value | +|------|-------------|---------------| +| `-c` | Comma-separated list of columns to display. Available: id,query,state,username,createdat,startedat,finishedat,url,logurl,total,completed,failed,inprogress | `id,username,state,query` | +| `-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` | +| `-insecure-skip-verify` | Skip validation of TLS certificates against trusted chains | `false` | +| `-json` | Output results as JSON for programmatic access | `false` | +| `-trace` | Log the trace ID for requests. See https://sourcegraph.com/docs/admin/observability/tracing | `false` | +| `-user-agent-telemetry` | Include the operating system and architecture in the User-Agent sent with requests to Sourcegraph | `true` | -

- `src search-jobs create` is a tool that creates a search job on a - Sourcegraph instance. -

## Usage -```bash +``` Usage of 'src search-jobs create': -c string - Comma-separated list of columns to display. Available: id,query,state,username,createdat,startedat,finishedat,url,logurl,total,completed,failed,inprogress (default "id,username,state,query") + Comma-separated list of columns to display. Available: id,query,state,username,createdat,startedat,finishedat,url,logurl,total,completed,failed,inprogress (default "id,username,state,query") -dump-requests - Log GraphQL requests and responses to stdout + 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!) + Print the curl command for executing this query and exit (WARNING: includes printing your access token!) -insecure-skip-verify - Skip validation of TLS certificates against trusted chains + Skip validation of TLS certificates against trusted chains -json - Output results as JSON for programmatic access + Output results as JSON for programmatic access -trace - Log the trace ID for requests. See https://docs.sourcegraph.com/admin/observability/tracing + Log the trace ID for requests. See https://sourcegraph.com/docs/admin/observability/tracing -user-agent-telemetry - Include the operating system and architecture in the User-Agent sent with requests to Sourcegraph (default true) - - Examples: - - Create a search job: - - $ src search-jobs create "repo:^github\.com/sourcegraph/sourcegraph$ sort:indexed-desc" - - Create a search job and display specific columns: - - $ src search-jobs create "repo:sourcegraph" -c id,state,username - - Create a search job and output in JSON format: - - $ src search-jobs create "repo:sourcegraph" -json + Include the operating system and architecture in the User-Agent sent with requests to Sourcegraph (default true) + + Examples: + + Create a search job: + + $ src search-jobs create "repo:^github\.com/sourcegraph/sourcegraph$ sort:indexed-desc" + + Create a search job and display specific columns: + + $ src search-jobs create "repo:sourcegraph" -c id,state,username + + Create a search job and output in JSON format: + + $ src search-jobs create "repo:sourcegraph" -json + + Available columns are: id, query, state, username, createdat, startedat, finishedat, + url, logurl, total, completed, failed, inprogress + - Available columns are: id, query, state, username, createdat, startedat, finishedat, - url, logurl, total, completed, failed, inprogress ``` + \ No newline at end of file diff --git a/docs/cli/references/search-jobs/delete.mdx b/docs/cli/references/search-jobs/delete.mdx index dfd48683b..14032f563 100644 --- a/docs/cli/references/search-jobs/delete.mdx +++ b/docs/cli/references/search-jobs/delete.mdx @@ -1,35 +1,49 @@ -# src search-jobs delete +# `src search-jobs delete` -

- `src search-jobs delete` is a tool that deletes a search job on a - Sourcegraph instance. -

-```bash +## Flags + +| Name | Description | Default Value | +|------|-------------|---------------| +| `-c` | Comma-separated list of columns to display. Available: id,query,state,username,createdat,startedat,finishedat,url,logurl,total,completed,failed,inprogress | `id,username,state,query` | +| `-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` | +| `-insecure-skip-verify` | Skip validation of TLS certificates against trusted chains | `false` | +| `-json` | Output results as JSON for programmatic access | `false` | +| `-trace` | Log the trace ID for requests. See https://sourcegraph.com/docs/admin/observability/tracing | `false` | +| `-user-agent-telemetry` | Include the operating system and architecture in the User-Agent sent with requests to Sourcegraph | `true` | + + +## Usage + +``` Usage of 'src search-jobs delete': -c string - Comma-separated list of columns to display. Available: id,query,state,username,createdat,startedat,finishedat,url,logurl,total,completed,failed,inprogress (default "id,username,state,query") + Comma-separated list of columns to display. Available: id,query,state,username,createdat,startedat,finishedat,url,logurl,total,completed,failed,inprogress (default "id,username,state,query") -dump-requests - Log GraphQL requests and responses to stdout + 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!) + Print the curl command for executing this query and exit (WARNING: includes printing your access token!) -insecure-skip-verify - Skip validation of TLS certificates against trusted chains + Skip validation of TLS certificates against trusted chains -json - Output results as JSON for programmatic access + Output results as JSON for programmatic access -trace - Log the trace ID for requests. See https://docs.sourcegraph.com/admin/observability/tracing + Log the trace ID for requests. See https://sourcegraph.com/docs/admin/observability/tracing -user-agent-telemetry - Include the operating system and architecture in the User-Agent sent with requests to Sourcegraph (default true) - - Examples: - - Delete a search job by ID: - - $ src search-jobs delete U2VhcmNoSm9iOjY5 + Include the operating system and architecture in the User-Agent sent with requests to Sourcegraph (default true) - Arguments: - The ID of the search job to delete. + Examples: + + Delete a search job by ID: + + $ src search-jobs delete U2VhcmNoSm9iOjY5 + + Arguments: + The ID of the search job to delete. + + The delete command permanently removes a search job and outputs a confirmation message. + - The delete command permanently removes a search job and outputs a confirmation message. ``` + \ No newline at end of file diff --git a/docs/cli/references/search-jobs/get.mdx b/docs/cli/references/search-jobs/get.mdx index 17db0d0a4..4d1301b8e 100644 --- a/docs/cli/references/search-jobs/get.mdx +++ b/docs/cli/references/search-jobs/get.mdx @@ -1,43 +1,55 @@ -# src search-jobs get +# `src search-jobs get` + + +## Flags + +| Name | Description | Default Value | +|------|-------------|---------------| +| `-c` | Comma-separated list of columns to display. Available: id,query,state,username,createdat,startedat,finishedat,url,logurl,total,completed,failed,inprogress | `id,username,state,query` | +| `-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` | +| `-insecure-skip-verify` | Skip validation of TLS certificates against trusted chains | `false` | +| `-json` | Output results as JSON for programmatic access | `false` | +| `-trace` | Log the trace ID for requests. See https://sourcegraph.com/docs/admin/observability/tracing | `false` | +| `-user-agent-telemetry` | Include the operating system and architecture in the User-Agent sent with requests to Sourcegraph | `true` | -

- `src search-jobs get` is a tool that gets details of a single search job on - a Sourcegraph instance. -

## Usage -```bash +``` Usage of 'src search-jobs get': -c string - Comma-separated list of columns to display. Available: id,query,state,username,createdat,startedat,finishedat,url,logurl,total,completed,failed,inprogress (default "id,username,state,query") + Comma-separated list of columns to display. Available: id,query,state,username,createdat,startedat,finishedat,url,logurl,total,completed,failed,inprogress (default "id,username,state,query") -dump-requests - Log GraphQL requests and responses to stdout + 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!) + Print the curl command for executing this query and exit (WARNING: includes printing your access token!) -insecure-skip-verify - Skip validation of TLS certificates against trusted chains + Skip validation of TLS certificates against trusted chains -json - Output results as JSON for programmatic access + Output results as JSON for programmatic access -trace - Log the trace ID for requests. See https://docs.sourcegraph.com/admin/observability/tracing + Log the trace ID for requests. See https://sourcegraph.com/docs/admin/observability/tracing -user-agent-telemetry - Include the operating system and architecture in the User-Agent sent with requests to Sourcegraph (default true) - - Examples: - - Get a search job by ID: - - $ src search-jobs get U2VhcmNoSm9iOjY5 - - Get a search job with specific columns: - - $ src search-jobs get U2VhcmNoSm9iOjY5 -c id,state,username - - Get a search job in JSON format: - - $ src search-jobs get U2VhcmNoSm9iOjY5 -json + Include the operating system and architecture in the User-Agent sent with requests to Sourcegraph (default true) + + Examples: + + Get a search job by ID: + + $ src search-jobs get U2VhcmNoSm9iOjY5 + + Get a search job with specific columns: + + $ src search-jobs get U2VhcmNoSm9iOjY5 -c id,state,username + + Get a search job in JSON format: + + $ src search-jobs get U2VhcmNoSm9iOjY5 -json + + Available columns are: id, query, state, username, createdat, startedat, finishedat, + url, logurl, total, completed, failed, inprogress + - Available columns are: id, query, state, username, createdat, startedat, finishedat, - url, logurl, total, completed, failed, inprogress ``` + \ No newline at end of file diff --git a/docs/cli/references/search-jobs/index.mdx b/docs/cli/references/search-jobs/index.mdx new file mode 100644 index 000000000..c4aad2c9c --- /dev/null +++ b/docs/cli/references/search-jobs/index.mdx @@ -0,0 +1,14 @@ +# `src search-jobs` + +## Subcommands + + +* [`cancel`](search-jobs/cancel) +* [`create`](search-jobs/create) +* [`delete`](search-jobs/delete) +* [`get`](search-jobs/get) +* [`list`](search-jobs/list) +* [`logs`](search-jobs/logs) +* [`restart`](search-jobs/restart) +* [`results`](search-jobs/results) + \ No newline at end of file diff --git a/docs/cli/references/search-jobs/list.mdx b/docs/cli/references/search-jobs/list.mdx index 3e959717f..9075168a6 100644 --- a/docs/cli/references/search-jobs/list.mdx +++ b/docs/cli/references/search-jobs/list.mdx @@ -1,65 +1,80 @@ -# src search-jobs list +# `src search-jobs list` + + +## Flags + +| Name | Description | Default Value | +|------|-------------|---------------| +| `-asc` | Sort search jobs in ascending order | `false` | +| `-c` | Comma-separated list of columns to display. Available: id,query,state,username,createdat,startedat,finishedat,url,logurl,total,completed,failed,inprogress | `id,username,state,query` | +| `-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` | +| `-insecure-skip-verify` | Skip validation of TLS certificates against trusted chains | `false` | +| `-json` | Output results as JSON for programmatic access | `false` | +| `-limit` | Limit the number of search jobs returned | `10` | +| `-order-by` | Sort search jobs by a sortable field (QUERY, CREATED_AT, STATE) | `CREATED_AT` | +| `-trace` | Log the trace ID for requests. See https://sourcegraph.com/docs/admin/observability/tracing | `false` | +| `-user-agent-telemetry` | Include the operating system and architecture in the User-Agent sent with requests to Sourcegraph | `true` | -

- `src search-jobs list` is a tool that lists search jobs on a Sourcegraph - instance. -

## Usage -```bash +``` Usage of 'src search-jobs list': -asc - Sort search jobs in ascending order + Sort search jobs in ascending order -c string - Comma-separated list of columns to display. Available: id,query,state,username,createdat,startedat,finishedat,url,logurl,total,completed,failed,inprogress (default "id,username,state,query") + Comma-separated list of columns to display. Available: id,query,state,username,createdat,startedat,finishedat,url,logurl,total,completed,failed,inprogress (default "id,username,state,query") -dump-requests - Log GraphQL requests and responses to stdout + 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!) + Print the curl command for executing this query and exit (WARNING: includes printing your access token!) -insecure-skip-verify - Skip validation of TLS certificates against trusted chains + Skip validation of TLS certificates against trusted chains -json - Output results as JSON for programmatic access + Output results as JSON for programmatic access -limit int - Limit the number of search jobs returned (default 10) + Limit the number of search jobs returned (default 10) -order-by string - Sort search jobs by a sortable field (QUERY, CREATED_AT, STATE) (default "CREATED_AT") + Sort search jobs by a sortable field (QUERY, CREATED_AT, STATE) (default "CREATED_AT") -trace - Log the trace ID for requests. See https://docs.sourcegraph.com/admin/observability/tracing + Log the trace ID for requests. See https://sourcegraph.com/docs/admin/observability/tracing -user-agent-telemetry - Include the operating system and architecture in the User-Agent sent with requests to Sourcegraph (default true) - - Examples: - - List all search jobs: - - $ src search-jobs list - - List all search jobs in ascending order: - - $ src search-jobs list --asc - - Limit the number of search jobs returned: - - $ src search-jobs list --limit 5 - - Order search jobs by a field (must be one of: QUERY, CREATED_AT, STATE): - - $ src search-jobs list --order-by QUERY - - Select specific columns to display: - - $ src search-jobs list -c id,state,username,createdat - - Output results as JSON: - - $ src search-jobs list -json - - Combine options: - - $ src search-jobs list --limit 10 --order-by STATE --asc -c id,query,state + Include the operating system and architecture in the User-Agent sent with requests to Sourcegraph (default true) + + Examples: + + List all search jobs: + + $ src search-jobs list + + List all search jobs in ascending order: + + $ src search-jobs list --asc + + Limit the number of search jobs returned: + + $ src search-jobs list --limit 5 + + Order search jobs by a field (must be one of: QUERY, CREATED_AT, STATE): + + $ src search-jobs list --order-by QUERY + + Select specific columns to display: + + $ src search-jobs list -c id,state,username,createdat + + Output results as JSON: + + $ src search-jobs list -json + + Combine options: + + $ src search-jobs list --limit 10 --order-by STATE --asc -c id,query,state + + Available columns are: id, query, state, username, createdat, startedat, finishedat, + url, logurl, total, completed, failed, inprogress + - Available columns are: id, query, state, username, createdat, startedat, finishedat, - url, logurl, total, completed, failed, inprogress ``` + \ No newline at end of file diff --git a/docs/cli/references/search-jobs/logs.mdx b/docs/cli/references/search-jobs/logs.mdx index 95898a47e..caaf1025f 100644 --- a/docs/cli/references/search-jobs/logs.mdx +++ b/docs/cli/references/search-jobs/logs.mdx @@ -1,39 +1,52 @@ -# src search-jobs logs +# `src search-jobs logs` + + +## Flags + +| Name | Description | Default Value | +|------|-------------|---------------| +| `-c` | Comma-separated list of columns to display. Available: id,query,state,username,createdat,startedat,finishedat,url,logurl,total,completed,failed,inprogress | `id,username,state,query` | +| `-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` | +| `-insecure-skip-verify` | Skip validation of TLS certificates against trusted chains | `false` | +| `-json` | Output results as JSON for programmatic access | `false` | +| `-out` | File path to save the logs (optional) | | +| `-trace` | Log the trace ID for requests. See https://sourcegraph.com/docs/admin/observability/tracing | `false` | +| `-user-agent-telemetry` | Include the operating system and architecture in the User-Agent sent with requests to Sourcegraph | `true` | -

- `src search-jobs logs` is a tool that gets the logs of a search job on a - Sourcegraph instance. -

## Usage -```bash +``` Usage of 'src search-jobs logs': -c string - Comma-separated list of columns to display. Available: id,query,state,username,createdat,startedat,finishedat,url,logurl,total,completed,failed,inprogress (default "id,username,state,query") + Comma-separated list of columns to display. Available: id,query,state,username,createdat,startedat,finishedat,url,logurl,total,completed,failed,inprogress (default "id,username,state,query") -dump-requests - Log GraphQL requests and responses to stdout + 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!) + Print the curl command for executing this query and exit (WARNING: includes printing your access token!) -insecure-skip-verify - Skip validation of TLS certificates against trusted chains + Skip validation of TLS certificates against trusted chains -json - Output results as JSON for programmatic access + Output results as JSON for programmatic access -out string - File path to save the logs (optional) + File path to save the logs (optional) -trace - Log the trace ID for requests. See https://docs.sourcegraph.com/admin/observability/tracing + Log the trace ID for requests. See https://sourcegraph.com/docs/admin/observability/tracing -user-agent-telemetry - Include the operating system and architecture in the User-Agent sent with requests to Sourcegraph (default true) - - Examples: - - View the logs of a search job: - $ src search-jobs logs U2VhcmNoSm9iOjY5 + Include the operating system and architecture in the User-Agent sent with requests to Sourcegraph (default true) - Save the logs to a file: - $ src search-jobs logs U2VhcmNoSm9iOjY5 -out logs.csv + Examples: + + View the logs of a search job: + $ src search-jobs logs U2VhcmNoSm9iOjY5 + + Save the logs to a file: + $ src search-jobs logs U2VhcmNoSm9iOjY5 -out logs.csv + + The logs command retrieves the raw log data in CSV format. The data will be + displayed on stdout or written to the file specified with -out. + - The logs command retrieves the raw log data in CSV format. The data will be - displayed on stdout or written to the file specified with -out. ``` + \ No newline at end of file diff --git a/docs/cli/references/search-jobs/restart.mdx b/docs/cli/references/search-jobs/restart.mdx index 45298a7e6..d42bf17c4 100644 --- a/docs/cli/references/search-jobs/restart.mdx +++ b/docs/cli/references/search-jobs/restart.mdx @@ -1,43 +1,55 @@ -# src search-jobs restart +# `src search-jobs restart` + + +## Flags + +| Name | Description | Default Value | +|------|-------------|---------------| +| `-c` | Comma-separated list of columns to display. Available: id,query,state,username,createdat,startedat,finishedat,url,logurl,total,completed,failed,inprogress | `id,username,state,query` | +| `-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` | +| `-insecure-skip-verify` | Skip validation of TLS certificates against trusted chains | `false` | +| `-json` | Output results as JSON for programmatic access | `false` | +| `-trace` | Log the trace ID for requests. See https://sourcegraph.com/docs/admin/observability/tracing | `false` | +| `-user-agent-telemetry` | Include the operating system and architecture in the User-Agent sent with requests to Sourcegraph | `true` | -

- `src search-jobs restart` is a tool that restarts a search job on a - Sourcegraph instance. -

## Usage -```bash +``` Usage of 'src search-jobs restart': -c string - Comma-separated list of columns to display. Available: id,query,state,username,createdat,startedat,finishedat,url,logurl,total,completed,failed,inprogress (default "id,username,state,query") + Comma-separated list of columns to display. Available: id,query,state,username,createdat,startedat,finishedat,url,logurl,total,completed,failed,inprogress (default "id,username,state,query") -dump-requests - Log GraphQL requests and responses to stdout + 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!) + Print the curl command for executing this query and exit (WARNING: includes printing your access token!) -insecure-skip-verify - Skip validation of TLS certificates against trusted chains + Skip validation of TLS certificates against trusted chains -json - Output results as JSON for programmatic access + Output results as JSON for programmatic access -trace - Log the trace ID for requests. See https://docs.sourcegraph.com/admin/observability/tracing + Log the trace ID for requests. See https://sourcegraph.com/docs/admin/observability/tracing -user-agent-telemetry - Include the operating system and architecture in the User-Agent sent with requests to Sourcegraph (default true) - - Examples: - - Restart a search job by ID: - - $ src search-jobs restart U2VhcmNoSm9iOjY5 - - Restart a search job and display specific columns: - - $ src search-jobs restart U2VhcmNoSm9iOjY5 -c id,state,query - - Restart a search job and output in JSON format: - - $ src search-jobs restart U2VhcmNoSm9iOjY5 -json + Include the operating system and architecture in the User-Agent sent with requests to Sourcegraph (default true) + + Examples: + + Restart a search job by ID: + + $ src search-jobs restart U2VhcmNoSm9iOjY5 + + Restart a search job and display specific columns: + + $ src search-jobs restart U2VhcmNoSm9iOjY5 -c id,state,query + + Restart a search job and output in JSON format: + + $ src search-jobs restart U2VhcmNoSm9iOjY5 -json + + Available columns are: id, query, state, username, createdat, startedat, finishedat, + url, logurl, total, completed, failed, inprogress + - Available columns are: id, query, state, username, createdat, startedat, finishedat, - url, logurl, total, completed, failed, inprogress ``` + \ No newline at end of file diff --git a/docs/cli/references/search-jobs/results.mdx b/docs/cli/references/search-jobs/results.mdx index bf440909f..bbe049bd9 100644 --- a/docs/cli/references/search-jobs/results.mdx +++ b/docs/cli/references/search-jobs/results.mdx @@ -1,40 +1,53 @@ -# src search-jobs results +# `src search-jobs results` + + +## Flags + +| Name | Description | Default Value | +|------|-------------|---------------| +| `-c` | Comma-separated list of columns to display. Available: id,query,state,username,createdat,startedat,finishedat,url,logurl,total,completed,failed,inprogress | `id,username,state,query` | +| `-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` | +| `-insecure-skip-verify` | Skip validation of TLS certificates against trusted chains | `false` | +| `-json` | Output results as JSON for programmatic access | `false` | +| `-out` | File path to save the results (optional) | | +| `-trace` | Log the trace ID for requests. See https://sourcegraph.com/docs/admin/observability/tracing | `false` | +| `-user-agent-telemetry` | Include the operating system and architecture in the User-Agent sent with requests to Sourcegraph | `true` | -

- `src search-jobs results` is a tool that gets the results of a search job on - a Sourcegraph instance. -

## Usage -```bash +``` Usage of 'src search-jobs results': -c string - Comma-separated list of columns to display. Available: id,query,state,username,createdat,startedat,finishedat,url,logurl,total,completed,failed,inprogress (default "id,username,state,query") + Comma-separated list of columns to display. Available: id,query,state,username,createdat,startedat,finishedat,url,logurl,total,completed,failed,inprogress (default "id,username,state,query") -dump-requests - Log GraphQL requests and responses to stdout + 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!) + Print the curl command for executing this query and exit (WARNING: includes printing your access token!) -insecure-skip-verify - Skip validation of TLS certificates against trusted chains + Skip validation of TLS certificates against trusted chains -json - Output results as JSON for programmatic access + Output results as JSON for programmatic access -out string - File path to save the results (optional) + File path to save the results (optional) -trace - Log the trace ID for requests. See https://docs.sourcegraph.com/admin/observability/tracing + Log the trace ID for requests. See https://sourcegraph.com/docs/admin/observability/tracing -user-agent-telemetry - Include the operating system and architecture in the User-Agent sent with requests to Sourcegraph (default true) - - Examples: - - Get the results of a search job: - $ src search-jobs results U2VhcmNoSm9iOjY5 + Include the operating system and architecture in the User-Agent sent with requests to Sourcegraph (default true) - Save search results to a file: - $ src search-jobs results U2VhcmNoSm9iOjY5 -out results.jsonl + Examples: + + Get the results of a search job: + $ src search-jobs results U2VhcmNoSm9iOjY5 + + Save search results to a file: + $ src search-jobs results U2VhcmNoSm9iOjY5 -out results.jsonl + + The results command retrieves the raw search results in JSON Lines format. + Each line contains a single JSON object representing a search result. The data + will be displayed on stdout or written to the file specified with -out. + - The results command retrieves the raw search results in JSON Lines format. - Each line contains a single JSON object representing a search result. The data - will be displayed on stdout or written to the file specified with -out. ``` + \ No newline at end of file diff --git a/docs/cli/references/snapshot.mdx b/docs/cli/references/snapshot.mdx deleted file mode 100644 index b4e7228a8..000000000 --- a/docs/cli/references/snapshot.mdx +++ /dev/null @@ -1,27 +0,0 @@ -# `src snapshot` - - - -## Usage - -``` -'src snapshot' manages snapshots of Sourcegraph instance databases. All subcommands are currently EXPERIMENTAL. - -Usage: - - src snapshot - -The commands are: - - databases export databases from a Sourcegraph instance - restore restore databases from an export - upload upload exported databases and summary file when migrating to Sourcegraph Cloud - - summary export summary data about an instance for acceptance testing of a restored Sourcegraph instance - test use exported summary data and instance health indicators to validate a restored and upgraded instance - -Use "src snapshot [command] -h" for more information about a command. - - -``` - \ No newline at end of file diff --git a/docs/cli/references/snapshot/databases.mdx b/docs/cli/references/snapshot/databases.mdx new file mode 100644 index 000000000..add94ff5c --- /dev/null +++ b/docs/cli/references/snapshot/databases.mdx @@ -0,0 +1,38 @@ +# `src snapshot databases` + + +## Flags + +| Name | Description | Default Value | +|------|-------------|---------------| +| `-run` | Automatically run the commands | `false` | +| `-targets` | predefined targets ('docker' or 'k8s'), or a custom targets.yaml file | `auto` | + + +## Usage + +``` +'src snapshot databases' generates commands to export Sourcegraph database dumps. +Note that these commands are intended for use as reference - you may need to adjust the commands for your deployment. + +USAGE + src [-v] snapshot databases [--targets=] [--run] + +TARGETS FILES + Predefined targets are available based on default Sourcegraph configurations ('docker', 'k8s'). + Custom targets configuration can be provided in YAML format with '--targets=target.yaml', e.g. + + pgsql: + target: ... # the DSN of the database deployment, e.g. in docker, the name of the database container + dbname: ... # name of database + username: ... # username for database access + password: ... # password for database access - only include password if it is non-sensitive + codeintel: + # same as above + codeinsights: + # same as above + + See the pgdump.Targets type for more details. + +``` + \ No newline at end of file diff --git a/docs/cli/references/snapshot/index.mdx b/docs/cli/references/snapshot/index.mdx new file mode 100644 index 000000000..2800134e6 --- /dev/null +++ b/docs/cli/references/snapshot/index.mdx @@ -0,0 +1,11 @@ +# `src snapshot` + +## Subcommands + + +* [`databases`](snapshot/databases) +* [`restore`](snapshot/restore) +* [`summary`](snapshot/summary) +* [`test`](snapshot/test) +* [`upload`](snapshot/upload) + \ No newline at end of file diff --git a/docs/cli/references/snapshot/restore.mdx b/docs/cli/references/snapshot/restore.mdx new file mode 100644 index 000000000..27e3d7c3b --- /dev/null +++ b/docs/cli/references/snapshot/restore.mdx @@ -0,0 +1,38 @@ +# `src snapshot restore` + + +## Flags + +| Name | Description | Default Value | +|------|-------------|---------------| +| `-run` | Automatically run the commands | `false` | +| `-targets` | predefined targets ('docker' or 'k8s'), or a custom targets.yaml file | `auto` | + + +## Usage + +``` +'src snapshot restore' restores a Sourcegraph instance using Sourcegraph database dumps. +Note that these commands are intended for use as reference - you may need to adjust the commands for your deployment. + +USAGE + src [-v] snapshot restore [--targets] [--run] + +TARGETS FILES + Predefined targets are available based on default Sourcegraph configurations ('docker', 'k8s'). + Custom targets configuration can be provided in YAML format with '--targets=target.yaml', e.g. + + pgsql: + target: ... # the DSN of the database deployment, e.g. in docker, the name of the database container + dbname: ... # name of database + username: ... # username for database access + password: ... # password for database access - only include password if it is non-sensitive + codeintel: + # same as above + codeinsights: + # same as above + + See the pgdump.Targets type for more details. + +``` + \ No newline at end of file diff --git a/docs/cli/references/snapshot/summary.mdx b/docs/cli/references/snapshot/summary.mdx new file mode 100644 index 000000000..db568e9ac --- /dev/null +++ b/docs/cli/references/snapshot/summary.mdx @@ -0,0 +1,28 @@ +# `src snapshot summary` + + +## 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` | +| `-insecure-skip-verify` | Skip validation of TLS certificates against trusted chains | `false` | +| `-trace` | Log the trace ID for requests. See https://sourcegraph.com/docs/admin/observability/tracing | `false` | +| `-user-agent-telemetry` | Include the operating system and architecture in the User-Agent sent with requests to Sourcegraph | `true` | + + +## Usage + +``` +'src snapshot summary' generates summary data for acceptance testing of a restored Sourcegraph instance with 'src snapshot test'. + +USAGE + src login # site-admin authentication required + src [-v] snapshot summary + +SUMMARY DATA + Use '-dump-requests' to see what data is requested, or open the generated summary at "src-snapshot/summary.json". + +``` + \ No newline at end of file diff --git a/docs/cli/references/snapshot/test.mdx b/docs/cli/references/snapshot/test.mdx new file mode 100644 index 000000000..333790a4e --- /dev/null +++ b/docs/cli/references/snapshot/test.mdx @@ -0,0 +1,38 @@ +# `src snapshot test` + + +## 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` | +| `-insecure-skip-verify` | Skip validation of TLS certificates against trusted chains | `false` | +| `-since` | duration ago to look for healthcheck data | `1h0m0s` | +| `-summary-path` | path to read snapshot summary from | `src-snapshot/summary.json` | +| `-trace` | Log the trace ID for requests. See https://sourcegraph.com/docs/admin/observability/tracing | `false` | +| `-user-agent-telemetry` | Include the operating system and architecture in the User-Agent sent with requests to Sourcegraph | `true` | + + +## Usage + +``` +'src snapshot test' uses exported summary data to validate a restored and upgraded instance. + +USAGE + src login # site-admin authentication required + src [-v] snapshot test [-summary-path="./src-snapshot-summary.json"] + +ASSESSING RESULTS + The outputs of the test is supposed to be used only as a reference indicator of whether or not the instance is in a healthy state. + + It generally does not give a definitive result, though if an issue is found that the test deems may be critical, the command will exit with status 1. + +SNAPSHOT SUMMARY + The snapshot summary to assert against ('-summary-path') should be generated by 'src snapshot summary'. + +TEST DATA + Use '-dump-requests' to see what data is requested to perform tests. + +``` + \ No newline at end of file diff --git a/docs/cli/references/snapshot/upload.mdx b/docs/cli/references/snapshot/upload.mdx new file mode 100644 index 000000000..99c945565 --- /dev/null +++ b/docs/cli/references/snapshot/upload.mdx @@ -0,0 +1,52 @@ +# `src snapshot upload` + + +## Flags + +| Name | Description | Default Value | +|------|-------------|---------------| +| `-bucket` | Name of the Google Cloud Storage bucket provided by Sourcegraph | | +| `-credentials` | File path to the credentials file provided by Sourcegraph | | +| `-file` | Specify which files from the ./src-snapshot directory to upload | `codeinsights.sql,codeintel.sql,pgsql.sql,summary.json` | +| `-filter-sql` | Filter incompatible SQL statements from database snapshots which break the import into Google Cloud SQL | `true` | + + +## Usage + +``` +'src snapshot upload' uploads the files generated by 'src snapshot databases' and 'src snapshot summary' to the specified GCS bucket, for self-hosted Sourcegraph customers migrating to Sourcegraph Cloud. + +Usage: + + src snapshot upload -bucket=$MIGRATION_BUCKET_NAME -credentials=$CREDENTIALS_FILE_PATH [-file] + +Examples: + + src snapshot upload -bucket=example-bucket-name -credentials=path/to/migration_private_key.json + + src snapshot upload -bucket=example-bucket-name -credentials=./migration_private_key.json -file=pgsql.sql + + src snapshot upload -bucket=example-bucket-name -credentials=./migration_private_key.json -file="codeinsights.sql, codeintel.sql, pgsql.sql" + +Args: + + -bucket + Name of the Google Cloud Storage bucket provided by Sourcegraph + Required + Type: string + + -credentials + File path to the credentials file provided by Sourcegraph + Required + Type: file path, as string + + -file + Specify which files from the ./src-snapshot directory to upload + Optional + Type: comma-delimited list of file names, with file-type extensions, as a string + Valid values: codeinsights.sql, codeintel.sql, pgsql.sql, summary.json + Default: All valid values + + +``` + \ No newline at end of file diff --git a/docs/cli/references/teams.mdx b/docs/cli/references/teams.mdx deleted file mode 100644 index 5abc51d07..000000000 --- a/docs/cli/references/teams.mdx +++ /dev/null @@ -1,26 +0,0 @@ -# `src teams` - - - -## Usage - -``` -'src teams' is a tool that manages teams in a Sourcegraph instance. - -Usage: - - src teams command [command options] - -The commands are: - - list lists teams - create create a team - update update a team - delete delete a team - members manage team members, use "src teams members [command] -h" for more information. - -Use "src teams [command] -h" for more information about a command. - - -``` - \ No newline at end of file