Files
coder/docs/reference/cli/create.md
T
Nick Vigilante d187dea338 docs: end every page description with a period and lint for it (#30863)
## Summary

Page descriptions in the docs were inconsistent about ending with a
period. This makes every page description end with one and adds a lint
so it stays that way.

A page description can come from three places, and the docs site reads
front matter first and falls back to the manifest:

- the hand-written YAML sidebar sources under `docs/manifest/`
(including `children_from` overlays),
- the generated fragments (`docs/manifest/generated/cli.json`,
`rest-api.json`), compiled into `docs/manifest.json`,
- a page's own front matter (today only the generated CLI and API
reference pages carry one).

The check covers all three. For the CLI, the description comes from each
command's `Short`, which stays unpunctuated by CLI-help convention, so
`clidocgen` adds the period when it writes the docs description instead
of changing 120 `Short` strings and the CLI golden files.

## What the lint checks

`make lint/docs-manifest` (`docsmanifestgen check`, already part of
`make lint` in CI) now fails when a non-empty description doesn't end
with `.`. No description in the tree ends with `?` or `!`, so the rule
allows only a period. Errors name the source file, the sidebar
breadcrumb, and the description, for example:

```
install/plan/sizing.yml: Install > Plan your deployment > Coder Validated Architecture > Up to 1,000 users: description must end with a period: "Hardware specifications and architecture guidance for Coder deployments that support up to 1,000 users"
generated/api.json: General: description must end with a period: "General endpoints"
reference/cli/ping.md: Reference > Command Line > `ping`: front matter description must end with a period: "Ping a workspace"
```

The style guide's page-description rule now lists the requirement and
cites the checker, and `styleclaims` recognises
`scripts/docsmanifestgen` so the coverage table counts it as
tool-checked.

## Count of descriptions fixed

147 descriptions in `docs/manifest.json`:

- 27 hand-written descriptions in 15 sidebar source files,
- 120 generated CLI descriptions, which also update the front matter of
120 CLI reference pages.

The REST API descriptions already ended with a period. No description is
otherwise reworded.

## Testing

- New table cases in `scripts/docgenenv` (section route, child route,
overlay, generated fragment, front matter, and a `?` ending) and
`scripts/clidocgen`, written first and failing before the change.
- `docsmanifestgen check` on the unfixed tree reported the 27 source
descriptions; after the fixes and regeneration it passes.
- `go test ./scripts/docgenenv/ ./scripts/clidocgen/
./scripts/docsmanifestgen/ ./scripts/styleclaims/
./scripts/apidocgen/...`
- `golangci-lint run` on the changed packages, `pnpm run check-docs`,
`go run ./scripts/styleclaims`, `scripts/check_emdash.sh`, and
`docsmanifestgen fmt` (no changes).

Linear: [DOCS-1304](https://linear.app/codercom/issue/DOCS-1304)

---

🤖 Built with AI assistance.
2026-10-20 18:51:44 -04:00

195 lines
6.2 KiB
Markdown
Generated

---
# Code generated by make gen. DO NOT EDIT.
title: "`coder create`"
description: Create a workspace.
---
<!-- DO NOT EDIT | GENERATED CONTENT -->
Create a workspace
## Usage
```console
coder create [flags] [workspace]
```
## Description
```console
- Create a workspace for another user (if you have permission):
$ coder create <username>/<workspace_name>
```
## Options
### -t, --template
| | |
|-------------|-----------------------------------|
| Type | <code>string</code> |
| Environment | <code>$CODER_TEMPLATE_NAME</code> |
Specify a template name.
### --template-version
| | |
|-------------|--------------------------------------|
| Type | <code>string</code> |
| Environment | <code>$CODER_TEMPLATE_VERSION</code> |
Specify a template version name or ID.
### --preset
| | |
|-------------|---------------------------------|
| Type | <code>string</code> |
| Environment | <code>$CODER_PRESET_NAME</code> |
Specify the name of a template version preset. Use 'none' to explicitly indicate that no preset should be used.
### --start-at
| | |
|-------------|----------------------------------------|
| Type | <code>string</code> |
| Environment | <code>$CODER_WORKSPACE_START_AT</code> |
Specify the workspace autostart schedule. Check coder schedule start --help for the syntax.
### --stop-after
| | |
|-------------|------------------------------------------|
| Type | <code>duration</code> |
| Environment | <code>$CODER_WORKSPACE_STOP_AFTER</code> |
Specify a duration after which the workspace should shut down (e.g. 8h).
### --automatic-updates
| | |
|-------------|-------------------------------------------------|
| Type | <code>string</code> |
| Environment | <code>$CODER_WORKSPACE_AUTOMATIC_UPDATES</code> |
| Default | <code>never</code> |
Specify automatic updates setting for the workspace (accepts 'always' or 'never').
### --copy-parameters-from
| | |
|-------------|----------------------------------------------------|
| Type | <code>string</code> |
| Environment | <code>$CODER_WORKSPACE_COPY_PARAMETERS_FROM</code> |
Specify the source workspace name to copy parameters from.
### --no-wait
| | |
|-------------|------------------------------------|
| Type | <code>bool</code> |
| Environment | <code>$CODER_CREATE_NO_WAIT</code> |
Return immediately after creating the workspace. The build will run in the background.
### -y, --yes
| | |
|------|-------------------|
| Type | <code>bool</code> |
Bypass confirmation prompts.
### --build-option
| | |
|-------------|----------------------------------|
| Type | <code>string-array</code> |
| Environment | <code>$CODER_BUILD_OPTION</code> |
Build option value in the format "name=value".
### --build-options
| | |
|------|-------------------|
| Type | <code>bool</code> |
Prompt for one-time build options defined with ephemeral parameters.
### --ephemeral-parameter
| | |
|-------------|-----------------------------------------|
| Type | <code>string-array</code> |
| Environment | <code>$CODER_EPHEMERAL_PARAMETER</code> |
Set the value of ephemeral parameters defined in the template. The format is "name=value".
### --prompt-ephemeral-parameters
| | |
|-------------|-------------------------------------------------|
| Type | <code>bool</code> |
| Environment | <code>$CODER_PROMPT_EPHEMERAL_PARAMETERS</code> |
Prompt to set values of ephemeral parameters defined in the template. If a value has been set via --ephemeral-parameter, it will not be prompted for.
### --parameter
| | |
|-------------|------------------------------------|
| Type | <code>string-array</code> |
| Environment | <code>$CODER_RICH_PARAMETER</code> |
Rich parameter value in the format "name=value".
### --rich-parameter-file
| | |
|-------------|-----------------------------------------|
| Type | <code>string</code> |
| Environment | <code>$CODER_RICH_PARAMETER_FILE</code> |
Specify a file path with values for rich parameters defined in the template. The file should be in YAML format, containing key-value pairs for the parameters.
### --parameter-default
| | |
|-------------|--------------------------------------------|
| Type | <code>string-array</code> |
| Environment | <code>$CODER_RICH_PARAMETER_DEFAULT</code> |
Rich parameter default values in the format "name=value".
### --use-parameter-defaults
| | |
|-------------|------------------------------------------------------|
| Type | <code>bool</code> |
| Environment | <code>$CODER_WORKSPACE_USE_PARAMETER_DEFAULTS</code> |
Automatically accept parameter defaults when no value is provided.
### --always-prompt
| | |
|------|-------------------|
| Type | <code>bool</code> |
Always prompt all parameters. Does not pull parameter values from existing workspace.
### -O, --org
| | |
|-------------|----------------------------------|
| Type | <code>string</code> |
| Environment | <code>$CODER_ORGANIZATION</code> |
Select which organization (uuid or name) to use.