Files
coder/docs/reference/cli/templates/push.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

3.3 KiB
Generated

title, description
title description
`coder templates push` Create or update a template from the current directory or as specified by flag.

Create or update a template from the current directory or as specified by flag

Usage

coder templates push [flags] [template]

Options

--variables-file

Type string

Specify a file path with values for Terraform-managed variables.

--variable

Type string-array

Specify a set of values for Terraform-managed variables.

--var

Type string-array

Alias of --variable.

--provisioner-tag

Type string-array

Specify a set of tags to target provisioner daemons. If you do not specify any tags, the tags from the active template version will be reused, if available. To remove existing tags, use --provisioner-tag="-".

--name

Type string

Specify a name for the new template version. It will be automatically generated if not provided.

--always-prompt

Type bool

Always prompt all parameters. Does not pull parameter values from active template version.

--activate

Type bool
Default true

Whether the new template will be marked active.

--display-name

Type string

Specify a display name for the template. Takes precedence over display_name in README.md front matter, if present.

--icon

Type string

Specify an icon path or external URL for the template. Takes precedence over icon in README.md front matter, if present.

-y, --yes

Type bool

Bypass confirmation prompts.

-d, --directory

Type string
Default .

Specify the directory to create from, use '-' to read tar from stdin.

--ignore-lockfile

Type bool
Default false

Ignore warnings about not having a .terraform.lock.hcl file present in the template.

-m, --message

Type string

Specify a message describing the changes in this version of the template. Messages longer than 72 characters will be displayed as truncated.

-O, --org

Type string
Environment $CODER_ORGANIZATION

Select which organization (uuid or name) to use.