From 0b41120a1dfd97a9b4b2f83a5f360807fa22a1ed Mon Sep 17 00:00:00 2001 From: Travis Lyons Date: Sun, 16 Feb 2025 17:43:41 -0500 Subject: [PATCH 1/3] docs(cli): add search-jobs command to CLI references navigation --- docs/cli/references/index.mdx | 1 + docs/cli/references/search-jobs.mdx | 27 ++++++++++ docs/cli/references/search-jobs/cancel.mdx | 36 ++++++++++++++ docs/cli/references/search-jobs/create.mdx | 38 ++++++++++++++ docs/cli/references/search-jobs/delete.mdx | 39 +++++++++++++++ docs/cli/references/search-jobs/get.mdx | 45 +++++++++++++++++ docs/cli/references/search-jobs/list.mdx | 58 ++++++++++++++++++++++ 7 files changed, 244 insertions(+) create mode 100644 docs/cli/references/search-jobs.mdx create mode 100644 docs/cli/references/search-jobs/cancel.mdx create mode 100644 docs/cli/references/search-jobs/create.mdx create mode 100644 docs/cli/references/search-jobs/delete.mdx create mode 100644 docs/cli/references/search-jobs/get.mdx create mode 100644 docs/cli/references/search-jobs/list.mdx diff --git a/docs/cli/references/index.mdx b/docs/cli/references/index.mdx index a7c433e00..bd1338247 100644 --- a/docs/cli/references/index.mdx +++ b/docs/cli/references/index.mdx @@ -18,6 +18,7 @@ Most commands require that the user first [authenticate](quickstart#connect-to-s * [`repos`](references/repos) * [`scout`](references/scout) * [`search`](references/search) +* [`search-jobs`](references/search-jobs) * [`serve-git`](references/serve-git) * [`snapshot`](references/snapshot) * [`teams`](references/teams) diff --git a/docs/cli/references/search-jobs.mdx b/docs/cli/references/search-jobs.mdx new file mode 100644 index 000000000..03a862832 --- /dev/null +++ b/docs/cli/references/search-jobs.mdx @@ -0,0 +1,27 @@ +# `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 +``` + +## Sub-Commands + +* [`cancel`](search-jobs/cancel) +* [`create`](search-jobs/create) +* [`delete`](search-jobs/delete) +* [`get`](search-jobs/get) +* [`list`](search-jobs/list) \ No newline at end of file diff --git a/docs/cli/references/search-jobs/cancel.mdx b/docs/cli/references/search-jobs/cancel.mdx new file mode 100644 index 000000000..291bab51e --- /dev/null +++ b/docs/cli/references/search-jobs/cancel.mdx @@ -0,0 +1,36 @@ +# `src search-jobs cancel` + +## 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` | ID of the search job to cancel | | +| `-insecure-skip-verify` | Skip validation of TLS certificates against trusted chains | `false` | +| `-trace` | Log the trace ID for requests. [See 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 cancel': + -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 + ID of the search job to cancel + -insecure-skip-verify + Skip validation of TLS certificates against trusted chains + -trace + 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: + + $ src search-jobs cancel -id=123 +``` diff --git a/docs/cli/references/search-jobs/create.mdx b/docs/cli/references/search-jobs/create.mdx new file mode 100644 index 000000000..e56277baf --- /dev/null +++ b/docs/cli/references/search-jobs/create.mdx @@ -0,0 +1,38 @@ +# `src search-jobs create` + +## Flags + +| Name | Description | Default Value | +|------|-------------|---------------| +| `-dump-requests` | Log GraphQL requests and responses to stdout | `false` | +| `-f` | Format for the output using Go text/template syntax | `\{\{\.ID\}\}: \{\{\.Creator.Username\}\} \{\{\.State\}\} (\{\{\.Query\}\})` | +| `-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` | +| `-query` | Search query (required) | | +| `-trace` | Log the trace ID for requests. [See 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 create': + -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}}: {{.Creator.Username}} ({{.Query}})" or "{{.|json}}") (default "{{.ID}}: {{.Creator.Username}} {{.State}} ({{.Query}})") + -get-curl + 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 + -query string + Search query + -trace + Log the trace ID for requests. See https://docs.sourcegraph.com/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 -query "repo:^github\.com/sourcegraph/sourcegraph$ sort:indexed-desc" +``` \ No newline at end of file diff --git a/docs/cli/references/search-jobs/delete.mdx b/docs/cli/references/search-jobs/delete.mdx new file mode 100644 index 000000000..b7ab1a136 --- /dev/null +++ b/docs/cli/references/search-jobs/delete.mdx @@ -0,0 +1,39 @@ +# `src search-jobs 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` | ID of the search job to delete | | +| `-insecure-skip-verify` | Skip validation of TLS certificates against trusted chains | `false` | +| `-trace` | Log the trace ID for requests. [See docs](https://docs.sourcegraph.com/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': + -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 + ID of the search job to delete + -insecure-skip-verify + Skip validation of TLS certificates against trusted chains + -trace + Log the trace ID for requests. See https://docs.sourcegraph.com/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 + +``` diff --git a/docs/cli/references/search-jobs/get.mdx b/docs/cli/references/search-jobs/get.mdx new file mode 100644 index 000000000..d2672c4a4 --- /dev/null +++ b/docs/cli/references/search-jobs/get.mdx @@ -0,0 +1,45 @@ +# `src search-jobs get` + +## Flags + +| Name | Description | Default Value | +|------|-------------|---------------| +| `-dump-requests` | Log GraphQL requests and responses to stdout | `false` | +| `-f` | Format for the output using Go text/template syntax | `\{\{\.ID\}\}: \{\{\.Creator.Username\}\} \{\{\.State\}\} (\{\{\.Query\}\})` | +| `-get-curl` | Print the curl command for executing this query and exit (WARNING: includes printing your access token!) | `false` | +| `-id` | ID of the search job | | +| `-insecure-skip-verify` | Skip validation of TLS certificates against trusted chains | `false` | +| `-trace` | Log the trace ID for requests. [See 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 + +``` +Usage of 'src search-jobs 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}}: {{.Creator.Username}} ({{.Query}})" or "{{.|json}}") (default "{{.ID}}: {{.Creator.Username}} {{.State}} ({{.Query}})") + -get-curl + Print the curl command for executing this query and exit (WARNING: includes printing your access token!) + -id string + ID of the search job + -insecure-skip-verify + Skip validation of TLS certificates against trusted chains + -trace + Log the trace ID for requests. See https://docs.sourcegraph.com/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 + +``` diff --git a/docs/cli/references/search-jobs/list.mdx b/docs/cli/references/search-jobs/list.mdx new file mode 100644 index 000000000..63f783def --- /dev/null +++ b/docs/cli/references/search-jobs/list.mdx @@ -0,0 +1,58 @@ +# `src search-jobs list` + +## Flags + +| Name | Description | Default Value | +|------|-------------|---------------| +| `-asc` | Sort search jobs in ascending order | `false` | +| `-dump-requests` | Log GraphQL requests and responses to stdout | `false` | +| `-f` | Format for the output using Go text/template syntax | `\{\{\.ID\}\}: \{\{\.Creator.Username\}\} \{\{\.State\}\} (\{\{\.Query\}\})` | +| `-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` | +| `-limit` | Limit the number of search jobs returned | `10` | +| `-order-by` | Sort search jobs by a field | `CREATED_AT` | +| `-trace` | Log the trace ID for requests. [See 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 list': + -asc + Sort search jobs in ascending 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}}: {{.Creator.Username}} ({{.Query}})" or "{{.|json}}") (default "{{.ID}}: {{.Creator.Username}} {{.State}}") + -get-curl + 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 + -limit int + Limit the number of search jobs returned (default 10) + -order-by string + Sort search jobs by a field (default "CREATED_AT") + -trace + Log the trace ID for requests. See https://docs.sourcegraph.com/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 + +``` From 256a8929cb8927747143d15dcf099e4fd1492e4f Mon Sep 17 00:00:00 2001 From: Travis Lyons Date: Wed, 19 Mar 2025 12:51:09 -0400 Subject: [PATCH 2/3] (cli) add src search-jobs documentation --- docs/cli/references/search-jobs.mdx | 46 ++++++++++------ docs/cli/references/search-jobs/cancel.mdx | 42 +++++++-------- docs/cli/references/search-jobs/create.mdx | 46 ++++++++-------- docs/cli/references/search-jobs/delete.mdx | 37 ++++++------- docs/cli/references/search-jobs/get.mdx | 45 ++++++++-------- docs/cli/references/search-jobs/list.mdx | 60 +++++++++++---------- docs/cli/references/search-jobs/logs.mdx | 38 +++++++++++++ docs/cli/references/search-jobs/restart.mdx | 42 +++++++++++++++ docs/cli/references/search-jobs/results.mdx | 39 ++++++++++++++ 9 files changed, 266 insertions(+), 129 deletions(-) create mode 100644 docs/cli/references/search-jobs/logs.mdx create mode 100644 docs/cli/references/search-jobs/restart.mdx create mode 100644 docs/cli/references/search-jobs/results.mdx diff --git a/docs/cli/references/search-jobs.mdx b/docs/cli/references/search-jobs.mdx index 03a862832..04ef84f97 100644 --- a/docs/cli/references/search-jobs.mdx +++ b/docs/cli/references/search-jobs.mdx @@ -1,27 +1,43 @@ -# `src search-jobs` +# src search-jobs + +## Overview + +`src search-jobs` is a tool that manages search jobs in a Sourcegraph instance. ## Usage ``` 'src search-jobs' is a tool that manages search jobs on a Sourcegraph instance. -Usage: + Usage: + + src search-jobs command [command options] + + The commands are: - src search-jobs command [command options] + 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 -The commands are: + Common options for all commands: + -c Select columns to display (e.g., -c id,query,state,username) + -json Output results in JSON format - 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 + Use "src search-jobs [command] -h" for more information about a command. ``` -## Sub-Commands +## Sub-commands -* [`cancel`](search-jobs/cancel) -* [`create`](search-jobs/create) -* [`delete`](search-jobs/delete) -* [`get`](search-jobs/get) -* [`list`](search-jobs/list) \ No newline at end of file +* [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) diff --git a/docs/cli/references/search-jobs/cancel.mdx b/docs/cli/references/search-jobs/cancel.mdx index 291bab51e..315d665fd 100644 --- a/docs/cli/references/search-jobs/cancel.mdx +++ b/docs/cli/references/search-jobs/cancel.mdx @@ -1,36 +1,36 @@ -# `src search-jobs cancel` +# src search-jobs cancel -## Flags +## Overview -| 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` | ID of the search job to cancel | | -| `-insecure-skip-verify` | Skip validation of TLS certificates against trusted chains | `false` | -| `-trace` | Log the trace ID for requests. [See 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 ``` 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") -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!) - -id string - ID of the search job to cancel + 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 -trace - Log the trace ID for requests. See https://sourcegraph.com/docs/admin/observability/tracing + Log the trace ID for requests. See https://docs.sourcegraph.com/admin/observability/tracing -user-agent-telemetry - Include the operating system and architecture in the User-Agent sent with requests to Sourcegraph (default true) + Include the operating system and architecture in the User-Agent sent with requests to Sourcegraph (default true) -Examples: + Examples: - Cancel a search job: + Cancel a search job by ID: - $ src search-jobs cancel -id=123 -``` + $ 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. +``` \ 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 e56277baf..da1a67d39 100644 --- a/docs/cli/references/search-jobs/create.mdx +++ b/docs/cli/references/search-jobs/create.mdx @@ -1,38 +1,42 @@ -# `src search-jobs create` - -## Flags - -| Name | Description | Default Value | -|------|-------------|---------------| -| `-dump-requests` | Log GraphQL requests and responses to stdout | `false` | -| `-f` | Format for the output using Go text/template syntax | `\{\{\.ID\}\}: \{\{\.Creator.Username\}\} \{\{\.State\}\} (\{\{\.Query\}\})` | -| `-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` | -| `-query` | Search query (required) | | -| `-trace` | Log the trace ID for requests. [See 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 + +## Overview + +`src search-jobs create` is a tool that creates a search job on a Sourcegraph instance. + ## Usage ``` 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") -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}}: {{.Creator.Username}} ({{.Query}})" or "{{.|json}}") (default "{{.ID}}: {{.Creator.Username}} {{.State}} ({{.Query}})") -get-curl 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 - -query string - Search query + -json + Output results as JSON for programmatic access -trace Log the trace ID for requests. See https://docs.sourcegraph.com/admin/observability/tracing -user-agent-telemetry Include the operating system and architecture in the User-Agent sent with requests to Sourcegraph (default true) -Examples: + Examples: + + Create a search job: + + $ src search-jobs create "repo:^github\.com/sourcegraph/sourcegraph$ sort:indexed-desc" - Create a search job: + Create a search job and display specific columns: - $ src search-jobs create -query "repo:^github\.com/sourcegraph/sourcegraph$ sort:indexed-desc" -``` \ No newline at end of file + $ 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 +``` diff --git a/docs/cli/references/search-jobs/delete.mdx b/docs/cli/references/search-jobs/delete.mdx index b7ab1a136..bfcd41f61 100644 --- a/docs/cli/references/search-jobs/delete.mdx +++ b/docs/cli/references/search-jobs/delete.mdx @@ -1,39 +1,34 @@ -# `src search-jobs 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` | ID of the search job to delete | | -| `-insecure-skip-verify` | Skip validation of TLS certificates against trusted chains | `false` | -| `-trace` | Log the trace ID for requests. [See docs](https://docs.sourcegraph.com/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 search-jobs delete +## Overview +`src search-jobs delete` is a tool that deletes a search job on a Sourcegraph instance. ``` 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") -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 - ID of the search job to delete -insecure-skip-verify Skip validation of TLS certificates against trusted chains + -json + Output results as JSON for programmatic access -trace Log the trace ID for requests. See https://docs.sourcegraph.com/admin/observability/tracing -user-agent-telemetry Include the operating system and architecture in the User-Agent sent with requests to Sourcegraph (default true) -Examples: + Examples: - Delete a search job by ID: + Delete a search job by ID: - $ src search-jobs delete U2VhcmNoSm9iOjY5 - -``` + $ 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. +``` \ 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 d2672c4a4..1267f6dea 100644 --- a/docs/cli/references/search-jobs/get.mdx +++ b/docs/cli/references/search-jobs/get.mdx @@ -1,45 +1,42 @@ -# `src search-jobs get` - -## Flags - -| Name | Description | Default Value | -|------|-------------|---------------| -| `-dump-requests` | Log GraphQL requests and responses to stdout | `false` | -| `-f` | Format for the output using Go text/template syntax | `\{\{\.ID\}\}: \{\{\.Creator.Username\}\} \{\{\.State\}\} (\{\{\.Query\}\})` | -| `-get-curl` | Print the curl command for executing this query and exit (WARNING: includes printing your access token!) | `false` | -| `-id` | ID of the search job | | -| `-insecure-skip-verify` | Skip validation of TLS certificates against trusted chains | `false` | -| `-trace` | Log the trace ID for requests. [See 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 search-jobs get +## Overview +`src search-jobs get` is a tool that gets details of a single search job on a Sourcegraph instance. ## Usage ``` 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") -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}}: {{.Creator.Username}} ({{.Query}})" or "{{.|json}}") (default "{{.ID}}: {{.Creator.Username}} {{.State}} ({{.Query}})") -get-curl Print the curl command for executing this query and exit (WARNING: includes printing your access token!) - -id string - ID of the search job -insecure-skip-verify Skip validation of TLS certificates against trusted chains + -json + Output results as JSON for programmatic access -trace Log the trace ID for requests. See https://docs.sourcegraph.com/admin/observability/tracing -user-agent-telemetry Include the operating system and architecture in the User-Agent sent with requests to Sourcegraph (default true) -Examples: + Examples: - Get a search job by ID: + Get a search job by ID: - $ src search-jobs get U2VhcmNoSm9iOjY5 + $ 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 +``` \ 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 63f783def..47230264f 100644 --- a/docs/cli/references/search-jobs/list.mdx +++ b/docs/cli/references/search-jobs/list.mdx @@ -1,18 +1,8 @@ -# `src search-jobs list` - -## Flags - -| Name | Description | Default Value | -|------|-------------|---------------| -| `-asc` | Sort search jobs in ascending order | `false` | -| `-dump-requests` | Log GraphQL requests and responses to stdout | `false` | -| `-f` | Format for the output using Go text/template syntax | `\{\{\.ID\}\}: \{\{\.Creator.Username\}\} \{\{\.State\}\} (\{\{\.Query\}\})` | -| `-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` | -| `-limit` | Limit the number of search jobs returned | `10` | -| `-order-by` | Sort search jobs by a field | `CREATED_AT` | -| `-trace` | Log the trace ID for requests. [See 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 + +## Overview + +`src search-jobs list` is a tool that lists search jobs on a Sourcegraph instance. ## Usage @@ -20,39 +10,55 @@ Usage of 'src search-jobs list': -asc 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") -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}}: {{.Creator.Username}} ({{.Query}})" or "{{.|json}}") (default "{{.ID}}: {{.Creator.Username}} {{.State}}") -get-curl 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 + -json + Output results as JSON for programmatic access -limit int Limit the number of search jobs returned (default 10) -order-by string - Sort search jobs by a field (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 -user-agent-telemetry Include the operating system and architecture in the User-Agent sent with requests to Sourcegraph (default true) -Examples: + 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 - List all search jobs: + Order search jobs by a field (must be one of: QUERY, CREATED_AT, STATE): - $ src search-jobs list + $ src search-jobs list --order-by QUERY - List all search jobs in ascending order: + Select specific columns to display: - $ src search-jobs list --asc + $ src search-jobs list -c id,state,username,createdat - Limit the number of search jobs returned: + Output results as JSON: - $ src search-jobs list --limit 5 + $ src search-jobs list -json - Order search jobs by a field (must be one of: QUERY, CREATED_AT, STATE): + Combine options: - $ src search-jobs list --order-by QUERY + $ 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 ``` diff --git a/docs/cli/references/search-jobs/logs.mdx b/docs/cli/references/search-jobs/logs.mdx new file mode 100644 index 000000000..5a077e9b6 --- /dev/null +++ b/docs/cli/references/search-jobs/logs.mdx @@ -0,0 +1,38 @@ +# src search-jobs logs + +## Overview + +`src search-jobs logs` is a tool that gets the logs of a search job on a Sourcegraph instance. + +## Usage + +``` +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") + -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!) + -insecure-skip-verify + Skip validation of TLS certificates against trusted chains + -json + Output results as JSON for programmatic access + -out string + File path to save the logs (optional) + -trace + Log the trace ID for requests. See https://docs.sourcegraph.com/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 + + 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. +``` \ No newline at end of file diff --git a/docs/cli/references/search-jobs/restart.mdx b/docs/cli/references/search-jobs/restart.mdx new file mode 100644 index 000000000..fb1d798f6 --- /dev/null +++ b/docs/cli/references/search-jobs/restart.mdx @@ -0,0 +1,42 @@ +# src search-jobs restart + +## Overview + +`src search-jobs restart` is a tool that restarts a search job on a Sourcegraph instance. + +## Usage + +``` +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") + -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!) + -insecure-skip-verify + Skip validation of TLS certificates against trusted chains + -json + Output results as JSON for programmatic access + -trace + Log the trace ID for requests. See https://docs.sourcegraph.com/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 + + 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 new file mode 100644 index 000000000..694f370e5 --- /dev/null +++ b/docs/cli/references/search-jobs/results.mdx @@ -0,0 +1,39 @@ +# src search-jobs results + +## Overview + +`src search-jobs results` is a tool that gets the results of a search job on a Sourcegraph instance. + +## Usage + +``` +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") + -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!) + -insecure-skip-verify + Skip validation of TLS certificates against trusted chains + -json + Output results as JSON for programmatic access + -out string + File path to save the results (optional) + -trace + Log the trace ID for requests. See https://docs.sourcegraph.com/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 + + 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. +``` \ No newline at end of file From da4057a361b2f7e1361365ab5d5d69abdbcb53f5 Mon Sep 17 00:00:00 2001 From: Maedah Batool Date: Tue, 6 May 2025 11:20:38 -0700 Subject: [PATCH 3/3] Add small tweaks --- docs/cli/references/search-jobs.mdx | 6 ++---- docs/cli/references/search-jobs/cancel.mdx | 8 +++----- docs/cli/references/search-jobs/create.mdx | 6 ++---- docs/cli/references/search-jobs/delete.mdx | 8 +++----- docs/cli/references/search-jobs/get.mdx | 8 +++----- docs/cli/references/search-jobs/list.mdx | 6 ++---- docs/cli/references/search-jobs/logs.mdx | 8 +++----- docs/cli/references/search-jobs/restart.mdx | 8 +++----- docs/cli/references/search-jobs/results.mdx | 8 +++----- 9 files changed, 24 insertions(+), 42 deletions(-) diff --git a/docs/cli/references/search-jobs.mdx b/docs/cli/references/search-jobs.mdx index 04ef84f97..af7c70abc 100644 --- a/docs/cli/references/search-jobs.mdx +++ b/docs/cli/references/search-jobs.mdx @@ -1,12 +1,10 @@ # src search-jobs -## Overview - -`src search-jobs` is a tool that manages search jobs in a Sourcegraph instance. +

`src search-jobs` is a tool that manages search jobs in a Sourcegraph instance.

## Usage -``` +```bash 'src search-jobs' is a tool that manages search jobs on a Sourcegraph instance. Usage: diff --git a/docs/cli/references/search-jobs/cancel.mdx b/docs/cli/references/search-jobs/cancel.mdx index 315d665fd..2573d41a1 100644 --- a/docs/cli/references/search-jobs/cancel.mdx +++ b/docs/cli/references/search-jobs/cancel.mdx @@ -1,12 +1,10 @@ # src search-jobs cancel -## Overview - -`src search-jobs cancel` is a tool that cancels a search job on a Sourcegraph instance. +

`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") @@ -33,4 +31,4 @@ Usage of 'src search-jobs cancel': The ID of the search job to cancel. 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 da1a67d39..30ade86ba 100644 --- a/docs/cli/references/search-jobs/create.mdx +++ b/docs/cli/references/search-jobs/create.mdx @@ -1,12 +1,10 @@ # src search-jobs create -## Overview - -`src search-jobs create` is a tool that creates a search job on a Sourcegraph instance. +

`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") diff --git a/docs/cli/references/search-jobs/delete.mdx b/docs/cli/references/search-jobs/delete.mdx index bfcd41f61..e4c5c5074 100644 --- a/docs/cli/references/search-jobs/delete.mdx +++ b/docs/cli/references/search-jobs/delete.mdx @@ -1,10 +1,8 @@ # src search-jobs delete -## Overview +

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

-`src search-jobs delete` is a tool that deletes a search job on a Sourcegraph instance. - -``` +```bash 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") @@ -31,4 +29,4 @@ Usage of 'src search-jobs delete': The ID of the search job to delete. 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 1267f6dea..3d81730a7 100644 --- a/docs/cli/references/search-jobs/get.mdx +++ b/docs/cli/references/search-jobs/get.mdx @@ -1,12 +1,10 @@ # src search-jobs get -## Overview - -`src search-jobs get` is a tool that gets details of a single search job on a Sourcegraph instance. +

`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") @@ -39,4 +37,4 @@ Usage of 'src search-jobs get': 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/list.mdx b/docs/cli/references/search-jobs/list.mdx index 47230264f..8d48ca178 100644 --- a/docs/cli/references/search-jobs/list.mdx +++ b/docs/cli/references/search-jobs/list.mdx @@ -1,12 +1,10 @@ # src search-jobs list -## Overview - -`src search-jobs list` is a tool that lists search jobs on a Sourcegraph instance. +

`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 diff --git a/docs/cli/references/search-jobs/logs.mdx b/docs/cli/references/search-jobs/logs.mdx index 5a077e9b6..af898e596 100644 --- a/docs/cli/references/search-jobs/logs.mdx +++ b/docs/cli/references/search-jobs/logs.mdx @@ -1,12 +1,10 @@ # src search-jobs logs -## Overview - -`src search-jobs logs` is a tool that gets the logs of a search job on a Sourcegraph instance. +

`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") @@ -35,4 +33,4 @@ Usage of 'src search-jobs logs': 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 fb1d798f6..1849e8a67 100644 --- a/docs/cli/references/search-jobs/restart.mdx +++ b/docs/cli/references/search-jobs/restart.mdx @@ -1,12 +1,10 @@ # src search-jobs restart -## Overview - -`src search-jobs restart` is a tool that restarts a search job on a Sourcegraph instance. +

`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") @@ -39,4 +37,4 @@ Usage of 'src search-jobs restart': 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 694f370e5..1f7e50ac9 100644 --- a/docs/cli/references/search-jobs/results.mdx +++ b/docs/cli/references/search-jobs/results.mdx @@ -1,12 +1,10 @@ # src search-jobs results -## Overview - -`src search-jobs results` is a tool that gets the results of a search job on a Sourcegraph instance. +

`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") @@ -36,4 +34,4 @@ Usage of 'src search-jobs results': 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 +```