Skip to content

Commit 8a391e5

Browse files
marcleblanc2ampagent
marcleblanc2
and
ampagent
committed
cli: add reference pages for search-jobs, debug, snapshot subcommands; list all commands in index
Pre-seeds the output of the fixed `src doc` generator (sourcegraph/src-cli#1375) so the CLI reference is correct now rather than after the next src-cli release and docs sync: - index.mdx lists all 20 top-level commands again (was only the 8 urfave/cli ones since src-cli#1304). - debug/, snapshot/: new index + subcommand pages (9 files). - search-jobs/: new index; the 8 hand-written subcommand pages are replaced by the generated equivalents (same usage text, plus a flags table). - Delete the flat debug.mdx, search-jobs.mdx, snapshot.mdx. The sync job never deletes, and these would shadow the new <group>/index.mdx in contentlayer routing. Files were produced with the same md2mdx conversion the sync uses; the sync/generated-docs PR that follows sourcegraph/sourcegraph#15528 should be a no-op for these paths. Part of https://linear.app/sourcegraph/issue/FE-502 Co-authored-by: Amp <amp@ampcode.com> Amp-Thread-ID: https://ampcode.com/threads/T-01a08410-86ca-72be-9928-2810e837fae1
1 parent 2f8832a commit 8a391e5

23 files changed

Lines changed: 685 additions & 314 deletions

‎docs/cli/references/debug.mdx‎

Lines changed: 0 additions & 27 deletions
This file was deleted.

‎docs/cli/references/debug/compose.mdx‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# `src debug compose`
2+
3+
4+
## Flags
5+
6+
| Name | Description | Default Value |
7+
|------|-------------|---------------|
8+
| `-no-configs` | If true, exclude Sourcegraph configuration files. Defaults to false. | `false` |
9+
| `-o` | The name of the output zip archive | `debug.zip` |
10+
11+
12+
## Usage
13+
14+
```
15+
16+
'src debug compose' invokes docker cli diagnostic commands targeting a set of containers that are members of a docker-compose network,
17+
writing an archive file from their returns.
18+
19+
Usage:
20+
21+
src debug compose [command options]
22+
23+
Flags:
24+
25+
-o Specify the name of the output zip archive.
26+
--no-configs Don't include Sourcegraph configuration json.
27+
28+
Examples:
29+
30+
$ src debug compose -o debug.zip
31+
32+
$ src -v debug compose -no-configs -o foo.zip
33+
34+
35+
36+
```
37+

‎docs/cli/references/debug/index.mdx‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# `src debug`
2+
3+
## Subcommands
4+
5+
6+
* [`compose`](debug/compose)
7+
* [`kube`](debug/kube)
8+
* [`server`](debug/server)
9+

‎docs/cli/references/debug/kube.mdx‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
# `src debug kube`
2+
3+
4+
## Flags
5+
6+
| Name | Description | Default Value |
7+
|------|-------------|---------------|
8+
| `-n` | The namespace passed to kubectl commands, if not specified the 'default' namespace is used | `default` |
9+
| `-no-configs` | If true, exclude Sourcegraph configuration files. Defaults to false. | `false` |
10+
| `-o` | The name of the output zip archive | `debug.zip` |
11+
12+
13+
## Usage
14+
15+
```
16+
17+
'src debug kube' invokes kubectl diagnostic commands targeting kubectl's current-context, writing returns to an archive.
18+
19+
Usage:
20+
21+
src debug kube [command options]
22+
23+
Flags:
24+
25+
-o Specify the name of the output zip archive.
26+
-n Specify the namespace passed to kubectl commands. If not specified the 'default' namespace is used.
27+
--no-config Don't include Sourcegraph configuration json.
28+
29+
Examples:
30+
31+
$ src debug kube -o debug.zip
32+
33+
$ src -v debug kube -n ns-sourcegraph -o foo
34+
35+
$ src debug kube -no-configs -o bar.zip
36+
37+
38+
39+
```
40+

‎docs/cli/references/debug/server.mdx‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# `src debug server`
2+
3+
4+
## Flags
5+
6+
| Name | Description | Default Value |
7+
|------|-------------|---------------|
8+
| `-c` | The container to target | |
9+
| `-no-configs` | If true, exclude Sourcegraph configuration files. Defaults to false. | `false` |
10+
| `-o` | The name of the output zip archive | `debug.zip` |
11+
12+
13+
## Usage
14+
15+
```
16+
17+
'src debug server' invokes docker cli diagnostic commands targeting a Sourcegraph server container,
18+
and writes an archive file from their returns.
19+
20+
Usage:
21+
22+
src debug server [command options]
23+
24+
Flags:
25+
26+
-o Specify the name of the output zip archive.
27+
-no-config Don't include Sourcegraph configuration json.
28+
29+
Examples:
30+
31+
$ src debug server -c foo -o debug.zip
32+
33+
$ src -v debug server --no-configs -c ViktorVaughn -o foo.zip
34+
35+
36+
37+
```
38+

‎docs/cli/references/index.mdx‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,21 @@
66
* [`abc`](references/abc)
77
* [`api`](references/api)
88
* [`auth`](references/auth)
9+
* [`batch`](references/batch)
10+
* [`code-intel`](references/code-intel)
911
* [`codeowners`](references/codeowners)
12+
* [`config`](references/config)
13+
* [`debug`](references/debug)
14+
* [`extsvc`](references/extsvc)
1015
* [`login`](references/login)
16+
* [`lsp`](references/lsp)
1117
* [`orgs`](references/orgs)
18+
* [`repos`](references/repos)
19+
* [`search`](references/search)
20+
* [`search-jobs`](references/search-jobs)
21+
* [`serve-git`](references/serve-git)
22+
* [`snapshot`](references/snapshot)
23+
* [`teams`](references/teams)
1224
* [`users`](references/users)
1325
* [`version`](references/version)
1426

‎docs/cli/references/search-jobs.mdx‎

Lines changed: 0 additions & 33 deletions
This file was deleted.

‎docs/cli/references/search-jobs/cancel.mdx‎

Lines changed: 35 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -1,37 +1,49 @@
1-
# src search-jobs cancel
1+
# `src search-jobs cancel`
2+
3+
4+
## Flags
5+
6+
| Name | Description | Default Value |
7+
|------|-------------|---------------|
8+
| `-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` |
9+
| `-dump-requests` | Log GraphQL requests and responses to stdout | `false` |
10+
| `-get-curl` | Print the curl command for executing this query and exit (WARNING: includes printing your access token!) | `false` |
11+
| `-insecure-skip-verify` | Skip validation of TLS certificates against trusted chains | `false` |
12+
| `-json` | Output results as JSON for programmatic access | `false` |
13+
| `-trace` | Log the trace ID for requests. See https://sourcegraph.com/docs/admin/observability/tracing | `false` |
14+
| `-user-agent-telemetry` | Include the operating system and architecture in the User-Agent sent with requests to Sourcegraph | `true` |
215

3-
<p className="subtitle">
4-
`src search-jobs cancel` is a tool that cancels a search job on a
5-
Sourcegraph instance.
6-
</p>
716

817
## Usage
918

10-
```bash
19+
```
1120
Usage of 'src search-jobs cancel':
1221
-c string
13-
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")
22+
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")
1423
-dump-requests
15-
Log GraphQL requests and responses to stdout
24+
Log GraphQL requests and responses to stdout
1625
-get-curl
17-
Print the curl command for executing this query and exit (WARNING: includes printing your access token!)
26+
Print the curl command for executing this query and exit (WARNING: includes printing your access token!)
1827
-insecure-skip-verify
19-
Skip validation of TLS certificates against trusted chains
28+
Skip validation of TLS certificates against trusted chains
2029
-json
21-
Output results as JSON for programmatic access
30+
Output results as JSON for programmatic access
2231
-trace
23-
Log the trace ID for requests. See https://docs.sourcegraph.com/admin/observability/tracing
32+
Log the trace ID for requests. See https://sourcegraph.com/docs/admin/observability/tracing
2433
-user-agent-telemetry
25-
Include the operating system and architecture in the User-Agent sent with requests to Sourcegraph (default true)
26-
27-
Examples:
28-
29-
Cancel a search job by ID:
30-
31-
$ src search-jobs cancel U2VhcmNoSm9iOjY5
32-
33-
Arguments:
34-
The ID of the search job to cancel.
34+
Include the operating system and architecture in the User-Agent sent with requests to Sourcegraph (default true)
35+
36+
Examples:
37+
38+
Cancel a search job by ID:
39+
40+
$ src search-jobs cancel U2VhcmNoSm9iOjY5
41+
42+
Arguments:
43+
The ID of the search job to cancel.
44+
45+
The cancel command stops a running search job and outputs a confirmation message.
46+
3547
36-
The cancel command stops a running search job and outputs a confirmation message.
3748
```
49+

‎docs/cli/references/search-jobs/create.mdx‎

Lines changed: 41 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -1,43 +1,55 @@
1-
# src search-jobs create
1+
# `src search-jobs create`
2+
3+
4+
## Flags
5+
6+
| Name | Description | Default Value |
7+
|------|-------------|---------------|
8+
| `-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` |
9+
| `-dump-requests` | Log GraphQL requests and responses to stdout | `false` |
10+
| `-get-curl` | Print the curl command for executing this query and exit (WARNING: includes printing your access token!) | `false` |
11+
| `-insecure-skip-verify` | Skip validation of TLS certificates against trusted chains | `false` |
12+
| `-json` | Output results as JSON for programmatic access | `false` |
13+
| `-trace` | Log the trace ID for requests. See https://sourcegraph.com/docs/admin/observability/tracing | `false` |
14+
| `-user-agent-telemetry` | Include the operating system and architecture in the User-Agent sent with requests to Sourcegraph | `true` |
215

3-
<p className="subtitle">
4-
`src search-jobs create` is a tool that creates a search job on a
5-
Sourcegraph instance.
6-
</p>
716

817
## Usage
918

10-
```bash
19+
```
1120
Usage of 'src search-jobs create':
1221
-c string
13-
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")
22+
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")
1423
-dump-requests
15-
Log GraphQL requests and responses to stdout
24+
Log GraphQL requests and responses to stdout
1625
-get-curl
17-
Print the curl command for executing this query and exit (WARNING: includes printing your access token!)
26+
Print the curl command for executing this query and exit (WARNING: includes printing your access token!)
1827
-insecure-skip-verify
19-
Skip validation of TLS certificates against trusted chains
28+
Skip validation of TLS certificates against trusted chains
2029
-json
21-
Output results as JSON for programmatic access
30+
Output results as JSON for programmatic access
2231
-trace
23-
Log the trace ID for requests. See https://docs.sourcegraph.com/admin/observability/tracing
32+
Log the trace ID for requests. See https://sourcegraph.com/docs/admin/observability/tracing
2433
-user-agent-telemetry
25-
Include the operating system and architecture in the User-Agent sent with requests to Sourcegraph (default true)
26-
27-
Examples:
28-
29-
Create a search job:
30-
31-
$ src search-jobs create "repo:^github\.com/sourcegraph/sourcegraph$ sort:indexed-desc"
32-
33-
Create a search job and display specific columns:
34-
35-
$ src search-jobs create "repo:sourcegraph" -c id,state,username
36-
37-
Create a search job and output in JSON format:
38-
39-
$ src search-jobs create "repo:sourcegraph" -json
34+
Include the operating system and architecture in the User-Agent sent with requests to Sourcegraph (default true)
35+
36+
Examples:
37+
38+
Create a search job:
39+
40+
$ src search-jobs create "repo:^github\.com/sourcegraph/sourcegraph$ sort:indexed-desc"
41+
42+
Create a search job and display specific columns:
43+
44+
$ src search-jobs create "repo:sourcegraph" -c id,state,username
45+
46+
Create a search job and output in JSON format:
47+
48+
$ src search-jobs create "repo:sourcegraph" -json
49+
50+
Available columns are: id, query, state, username, createdat, startedat, finishedat,
51+
url, logurl, total, completed, failed, inprogress
52+
4053
41-
Available columns are: id, query, state, username, createdat, startedat, finishedat,
42-
url, logurl, total, completed, failed, inprogress
4354
```
55+

0 commit comments

Comments
 (0)