Skip to content

Commit f6a8c36

Browse files
ammarioammario
authored
feat(docs): rework CLI docs (#6312)
1 parent 43e8ba0 commit f6a8c36

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

71 files changed

+2340
-2085
lines changed

‎Makefile

+3-2
Original file line numberDiff line numberDiff line change
@@ -501,9 +501,10 @@ docs/admin/prometheus.md: scripts/metricsdocgen/main.go scripts/metricsdocgen/me
501501
yarn run format:write:only ../docs/admin/prometheus.md
502502

503503
docs/cli/coder.md: scripts/clidocgen/main.go $(GO_SRC_FILES) docs/manifest.json
504-
BASE_PATH="." go run scripts/clidocgen/main.go
504+
rm -rf ./docs/cli/*.md
505+
BASE_PATH="." go run ./scripts/clidocgen
505506
cd site
506-
yarn run format:write:only ../docs/cli/*.md ../docs/manifest.json
507+
yarn run format:write:only ../docs/cli.md ../docs/cli/*.md ../docs/manifest.json
507508

508509
docs/admin/audit-logs.md: scripts/auditdocgen/main.go enterprise/audit/table.go
509510
go run scripts/auditdocgen/main.go

‎cli/state.go

+6-4
Original file line numberDiff line numberDiff line change
@@ -27,8 +27,9 @@ func state() *cobra.Command {
2727
func statePull() *cobra.Command {
2828
var buildNumber int
2929
cmd := &cobra.Command{
30-
Use: "pull <workspace> [file]",
31-
Args: cobra.MinimumNArgs(1),
30+
Use: "pull <workspace> [file]",
31+
Short: "Pull a Terraform state file from a workspace.",
32+
Args: cobra.MinimumNArgs(1),
3233
RunE: func(cmd *cobra.Command, args []string) error {
3334
client, err := CreateClient(cmd)
3435
if err != nil {
@@ -68,8 +69,9 @@ func statePull() *cobra.Command {
6869
func statePush() *cobra.Command {
6970
var buildNumber int
7071
cmd := &cobra.Command{
71-
Use: "push <workspace> <file>",
72-
Args: cobra.ExactArgs(2),
72+
Use: "push <workspace> <file>",
73+
Args: cobra.ExactArgs(2),
74+
Short: "Push a Terraform state file to a workspace.",
7375
RunE: func(cmd *cobra.Command, args []string) error {
7476
client, err := CreateClient(cmd)
7577
if err != nil {

‎cli/templatepull_test.go

+1
Original file line numberDiff line numberDiff line change
@@ -73,6 +73,7 @@ func TestTemplatePull(t *testing.T) {
7373
// and writes it to the correct directory.
7474
t.Run("ToDir", func(t *testing.T) {
7575
t.Parallel()
76+
t.Skip("FLAKE: @ammario to fix imminently")
7677

7778
client := coderdtest.New(t, &coderdtest.Options{IncludeProvisionerDaemon: true})
7879
user := coderdtest.CreateFirstUser(t, client)

‎cli/testdata/coder_state_--help.golden

+2-2
Original file line numberDiff line numberDiff line change
@@ -6,8 +6,8 @@ Usage:
66
coder state [command]
77

88
Commands:
9-
pull
10-
push
9+
pull Pull a Terraform state file from a workspace.
10+
push Push a Terraform state file to a workspace.
1111

1212
Flags:
1313
-h, --help help for state

‎cli/testdata/coder_state_pull_--help.golden

+2
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
Pull a Terraform state file from a workspace.
2+
13
Usage:
24
coder state pull <workspace> [file] [flags]
35

‎cli/testdata/coder_state_push_--help.golden

+2
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
Push a Terraform state file to a workspace.
2+
13
Usage:
24
coder state push <workspace> <file> [flags]
35

‎docs/cli.md

+55
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
<!-- DO NOT EDIT | GENERATED CONTENT -->
2+
3+
# coder
4+
5+
Coder — A tool for provisioning self-hosted development environments with Terraform.
6+
7+
## Usage
8+
9+
```console
10+
coder [flags]
11+
```
12+
13+
## Examples
14+
15+
```console
16+
- Start a Coder server:
17+
18+
$ coder server
19+
20+
- Get started by creating a template from an example:
21+
22+
$ coder templates init
23+
```
24+
25+
## Subcommands
26+
27+
| Name | Purpose |
28+
| --------------------------------------------------------- | --------------------------------------------------------------- |
29+
| [<code>config-ssh</code>](./cli/coder_config-ssh) | Add an SSH Host entry for your workspaces "ssh coder.workspace" |
30+
| [<code>create</code>](./cli/coder_create) | Create a workspace |
31+
| [<code>delete</code>](./cli/coder_delete) | Delete a workspace |
32+
| [<code>dotfiles</code>](./cli/coder_dotfiles) | Checkout and install a dotfiles repository from a Git URL |
33+
| [<code>list</code>](./cli/coder_list) | List workspaces |
34+
| [<code>login</code>](./cli/coder_login) | Authenticate with Coder deployment |
35+
| [<code>logout</code>](./cli/coder_logout) | Unauthenticate your local session |
36+
| [<code>ping</code>](./cli/coder_ping) | Ping a workspace |
37+
| [<code>port-forward</code>](./cli/coder_port-forward) | Forward ports from machine to a workspace |
38+
| [<code>publickey</code>](./cli/coder_publickey) | Output your Coder public key used for Git operations |
39+
| [<code>rename</code>](./cli/coder_rename) | Rename a workspace |
40+
| [<code>reset-password</code>](./cli/coder_reset-password) | Directly connect to the database to reset a user's password |
41+
| [<code>restart</code>](./cli/coder_restart) | Restart a workspace |
42+
| [<code>scaletest</code>](./cli/coder_scaletest) | Run a scale test against the Coder API |
43+
| [<code>schedule</code>](./cli/coder_schedule) | Schedule automated start and stop times for workspaces |
44+
| [<code>server</code>](./cli/coder_server) | Start a Coder server |
45+
| [<code>show</code>](./cli/coder_show) | Display details of a workspace's resources and agents |
46+
| [<code>speedtest</code>](./cli/coder_speedtest) | Run upload and download tests from your machine to a workspace |
47+
| [<code>ssh</code>](./cli/coder_ssh) | Start a shell into a workspace |
48+
| [<code>start</code>](./cli/coder_start) | Start a workspace |
49+
| [<code>state</code>](./cli/coder_state) | Manually manage Terraform state to fix broken workspaces |
50+
| [<code>stop</code>](./cli/coder_stop) | Stop a workspace |
51+
| [<code>templates</code>](./cli/coder_templates) | Manage templates |
52+
| [<code>tokens</code>](./cli/coder_tokens) | Manage personal access tokens |
53+
| [<code>update</code>](./cli/coder_update) | Update a workspace |
54+
| [<code>users</code>](./cli/coder_users) | Manage users |
55+
| [<code>version</code>](./cli/coder_version) | Show coder version |

‎docs/cli/coder.md

-71
This file was deleted.

‎docs/cli/coder_config-ssh.md

+46-34
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,18 @@
1-
## coder config-ssh
1+
<!-- DO NOT EDIT | GENERATED CONTENT -->
2+
3+
# coder config-ssh
24

35
Add an SSH Host entry for your workspaces "ssh coder.workspace"
46

5-
```
7+
## Usage
8+
9+
```console
610
coder config-ssh [flags]
711
```
812

9-
### Examples
13+
## Examples
1014

11-
```
15+
```console
1216
- You can use -o (or --ssh-option) so set SSH options to be used for all your
1317
workspaces:
1418

@@ -19,38 +23,46 @@ coder config-ssh [flags]
1923
$ coder config-ssh --dry-run
2024
```
2125

22-
### Options
26+
## Flags
2327

24-
```
25-
-n, --dry-run Perform a trial run with no changes made, showing a diff at the end.
26-
-h, --help help for config-ssh
27-
--ssh-config-file string Specifies the path to an SSH config.
28-
Consumes $CODER_SSH_CONFIG_FILE (default "~/.ssh/config")
29-
-o, --ssh-option stringArray Specifies additional SSH options to embed in each host stanza.
30-
--use-previous-options Specifies whether or not to keep options from previous run of config-ssh.
31-
Consumes $CODER_SSH_USE_PREVIOUS_OPTIONS
32-
-y, --yes Bypass prompts
33-
```
28+
### --dry-run, -n
3429

35-
### Options inherited from parent commands
30+
Perform a trial run with no changes made, showing a diff at the end.
31+
<br/>
32+
| | |
33+
| --- | --- |
34+
| Default | <code>false</code> |
3635

37-
```
38-
--global-config coder Path to the global coder config directory.
39-
Consumes $CODER_CONFIG_DIR (default "~/.config/coderv2")
40-
--header stringArray HTTP headers added to all requests. Provide as "Key=Value".
41-
Consumes $CODER_HEADER
42-
--no-feature-warning Suppress warnings about unlicensed features.
43-
Consumes $CODER_NO_FEATURE_WARNING
44-
--no-version-warning Suppress warning when client and server versions do not match.
45-
Consumes $CODER_NO_VERSION_WARNING
46-
--token string Specify an authentication token. For security reasons setting CODER_SESSION_TOKEN is preferred.
47-
Consumes $CODER_SESSION_TOKEN
48-
--url string URL to a deployment.
49-
Consumes $CODER_URL
50-
-v, --verbose Enable verbose output.
51-
Consumes $CODER_VERBOSE
52-
```
36+
### --ssh-config-file
37+
38+
Specifies the path to an SSH config.
39+
<br/>
40+
| | |
41+
| --- | --- |
42+
| Consumes | <code>$CODER_SSH_CONFIG_FILE</code> |
43+
| Default | <code>~/.ssh/config</code> |
44+
45+
### --ssh-option, -o
46+
47+
Specifies additional SSH options to embed in each host stanza.
48+
<br/>
49+
| | |
50+
| --- | --- |
51+
| Default | <code>[]</code> |
52+
53+
### --use-previous-options
54+
55+
Specifies whether or not to keep options from previous run of config-ssh.
56+
<br/>
57+
| | |
58+
| --- | --- |
59+
| Consumes | <code>$CODER_SSH_USE_PREVIOUS_OPTIONS</code> |
60+
| Default | <code>false</code> |
5361

54-
### SEE ALSO
62+
### --yes, -y
5563

56-
- [coder](coder.md) -
64+
Bypass prompts
65+
<br/>
66+
| | |
67+
| --- | --- |
68+
| Default | <code>false</code> |

‎docs/cli/coder_create.md

+51-36
Original file line numberDiff line numberDiff line change
@@ -1,47 +1,62 @@
1-
## coder create
1+
<!-- DO NOT EDIT | GENERATED CONTENT -->
2+
3+
# coder create
24

35
Create a workspace
46

5-
```
7+
## Usage
8+
9+
```console
610
coder create [name] [flags]
711
```
812

9-
### Options
13+
## Flags
1014

11-
```
12-
-h, --help help for create
13-
--parameter-file string Specify a file path with parameter values.
14-
Consumes $CODER_PARAMETER_FILE
15-
--rich-parameter-file string Specify a file path with values for rich parameters defined in the template.
16-
Consumes $CODER_RICH_PARAMETER_FILE
17-
--start-at coder schedule start --help Specify the workspace autostart schedule. Check coder schedule start --help for the syntax.
18-
Consumes $CODER_WORKSPACE_START_AT
19-
--stop-after duration Specify a duration after which the workspace should shut down (e.g. 8h).
20-
Consumes $CODER_WORKSPACE_STOP_AFTER (default 8h0m0s)
21-
-t, --template string Specify a template name.
22-
Consumes $CODER_TEMPLATE_NAME
23-
-y, --yes Bypass prompts
24-
```
15+
### --parameter-file
2516

26-
### Options inherited from parent commands
17+
Specify a file path with parameter values.
18+
<br/>
19+
| | |
20+
| --- | --- |
21+
| Consumes | <code>$CODER_PARAMETER_FILE</code> |
2722

28-
```
29-
--global-config coder Path to the global coder config directory.
30-
Consumes $CODER_CONFIG_DIR (default "~/.config/coderv2")
31-
--header stringArray HTTP headers added to all requests. Provide as "Key=Value".
32-
Consumes $CODER_HEADER
33-
--no-feature-warning Suppress warnings about unlicensed features.
34-
Consumes $CODER_NO_FEATURE_WARNING
35-
--no-version-warning Suppress warning when client and server versions do not match.
36-
Consumes $CODER_NO_VERSION_WARNING
37-
--token string Specify an authentication token. For security reasons setting CODER_SESSION_TOKEN is preferred.
38-
Consumes $CODER_SESSION_TOKEN
39-
--url string URL to a deployment.
40-
Consumes $CODER_URL
41-
-v, --verbose Enable verbose output.
42-
Consumes $CODER_VERBOSE
43-
```
23+
### --rich-parameter-file
24+
25+
Specify a file path with values for rich parameters defined in the template.
26+
<br/>
27+
| | |
28+
| --- | --- |
29+
| Consumes | <code>$CODER_RICH_PARAMETER_FILE</code> |
30+
31+
### --start-at
32+
33+
Specify the workspace autostart schedule. Check `coder schedule start --help` for the syntax.
34+
<br/>
35+
| | |
36+
| --- | --- |
37+
| Consumes | <code>$CODER_WORKSPACE_START_AT</code> |
38+
39+
### --stop-after
40+
41+
Specify a duration after which the workspace should shut down (e.g. 8h).
42+
<br/>
43+
| | |
44+
| --- | --- |
45+
| Consumes | <code>$CODER_WORKSPACE_STOP_AFTER</code> |
46+
| Default | <code>8h0m0s</code> |
47+
48+
### --template, -t
49+
50+
Specify a template name.
51+
<br/>
52+
| | |
53+
| --- | --- |
54+
| Consumes | <code>$CODER_TEMPLATE_NAME</code> |
4455

45-
### SEE ALSO
56+
### --yes, -y
4657

47-
- [coder](coder.md) -
58+
Bypass prompts
59+
<br/>
60+
| | |
61+
| --- | --- |
62+
| Default | <code>false</code> |

0 commit comments

Comments
 (0)