Files
Nick Vigilante 6e51c66a97 docs: give every table header cell text and fail lint on empty ones (#30879)
## Summary

axe reports `empty-table-header` on 116 generated CLI reference pages
and several hand-written pages: a header cell with no text is announced
by screen readers as an unnamed column. This PR gives every table header
cell in `docs/` text, and adds a lint check so empty header cells can't
come back.

## How to review this PR

- `docs/reference/cli/`: 116 files, these all generate identically, so I
would only spot check 2-3 of them and skip the rest
- `docs/*` outside of `docs/reference/cli/`: 6 files, normal review of
these
- `scripts`: 5 files, code review of the Bash and Go files to make sure
we're properly inserting headers into each table

## What changed

**Generator.** `scripts/clidocgen` wrote an empty header row (`| | |`)
over each option's metadata table (Type, Environment, YAML, Default). It
now writes `| Property | Value |`. Subcommand tables already had `Name |
Purpose` and are unchanged. Regenerated with `make
docs/reference/cli/index.md`: 116 files under `docs/reference/cli/`
change. The header rows change, and the body rows of each option table
are re-padded to the wider first column; the content is otherwise
identical. Every option on those 116 pages now shows a visible `Property
| Value` header row above Type, Environment, YAML, and Default, so this
is a visual change on the docs site as well as a screen reader one. The
CLI's own `--help` output doesn't use this template, so it's unchanged.

**Audit logs.** `docs/admin/security/audit-logs.md` already has `Field |
Tracked` headers on `main` (the generator writes them), so there was
nothing to change there; the live-site finding predates that.

**Hand-written tables.**
- `docs/admin/networking/port-forwarding.md`: the CORS matrix had three
empty spanning corner cells. The corner now reads `From user` and `From
workspace` (spanning the three row-header columns, beside the Alice/Bob
and Workspace rows) and `To user`, `To workspace`, `To app` (over the
three row-header columns). The grid is still 3 header rows by 7 columns.
The From cells have `scope="row"` and the other header-row cells
`scope="col"`, so the From labels don't become column headers for the
body's label columns; the body's user, workspace, and app labels are
`<th scope="row">`; and a `<caption>` says columns are the origin and
rows the destination.
- `groups-roles.md`, `airgap.md`, `scale-testing.md`,
`workspace-tags.md`: these four corner cells are already filled by
#30873. The new check would fail CI without them, so this PR carries the
same four lines, byte-identical to #30873 (`Permission`, `Component`,
`Scenario`, `Input`), so whichever PR merges second rebases without
conflict. If #30873 merges first, these hunks drop out.

**New check.** `scripts/docshtmlcheck` (`make lint/docs-html`, part of
`make lint`) now also reports `empty-table-header`. I put it there
because that checker already parses every Markdown file under `docs/`,
generated pages included, with goldmark and tokenizes raw HTML with
`golang.org/x/net/html`, and it already runs in CI. A markdownlint
custom rule would have needed a new JS rule and HTML parsing there.
- Markdown pipe tables: the header row, via goldmark's GFM table
extension.
- Raw HTML tables: every `<th>`, tracked across HTML blocks, with
entities decoded and whitespace trimmed, so `<th></th>`,
`<th>&nbsp;</th>`, and `<th><br></th>` are all reported. Markdown
between the HTML blocks of an open `<th>` counts as its text. Tables in
code blocks are ignored.
- Output: `docs/x.md:29: empty-table-header: header cell 1 has no text
(table's first header "Auditor")`, plus a summary footer.
- The tokenizer loop moved out of `scanNode` into a shared
`tokenizeSegments` helper so both checks use it; `scanNode`'s behavior
is unchanged.
- The style guide's checks table gets one row; the README for the
checker describes the rule.

## Testing

- Tests first: `TestCheckTables` (now 22 cases) and
`TestRunEmptyTableHeader` failed against a stub, then pass. The existing
`docshtmlcheck` tests pass unchanged.
- `go run ./scripts/docshtmlcheck` on `main` reports 1,561 empty header
cells (116 CLI pages, port-forwarding, and the four #30873 tables); on
this branch it reports none.
- `go test ./scripts/docshtmlcheck/ ./scripts/clidocgen/
./scripts/docgenenv/`, golangci-lint on the changed packages, `make
lint/docs-html lint/docs-manifest lint/docs-gen-filter lint/emdash`,
`pnpm run check-docs`, and Vale on the changed hand-written pages all
pass.
- `make gen` couldn't run to completion locally (no `protoc-gen-go`);
CI's gen check covers it. The CLI pages were regenerated with the repo's
own target.

Review feedback applied in cfd29a2160 (entities decoded in Markdown
text, image alt text and autolinks count as text), 709a58f603 (per-kind
counts, finding order, CLI generator note), 8e61ff3afa (CORS matrix
scopes and caption), and b807bcbbc7 and 2871f89bdf (style guide rule
section, `make lint/docs-html` in the checks table, coverage counts).

Linear: DOCS-1308

---

🤖 Built with AI assistance.
2026-10-21 10:58:04 -07:00

17 KiB
Generated

title, description, icon_path
title description icon_path
Command Line Reference for the Coder command-line interface, with usage and flags for every command. ./images/icons/terminal.svg

Usage

coder [global-flags] <subcommand>

Description

Coder — A tool for provisioning self-hosted development environments with Terraform.
  - Start a Coder server:

     $ coder server

  - Get started by creating a template from an example:

     $ coder templates init

Subcommands

Name Purpose
completion Install or update shell completion scripts for the detected or chosen shell.
dotfiles Personalize your workspace by applying a canonical dotfiles repository
external-auth Manage external authentication
login Authenticate with Coder deployment
logout Unauthenticate your local session
netcheck Print network debug information for DERP and STUN
notifications Manage Coder notifications
oauth2-provider Manage Coder OAuth2 provider settings
organizations Organization related commands
port-forward Forward ports from a workspace to the local machine. For reverse port forwarding, use "coder ssh -R".
publickey Output your Coder public key used for Git operations
reset-password Directly connect to the database to reset a user's password
secret Manage secrets
sharing Commands for managing shared workspaces
state Manually manage Terraform state to fix broken workspaces
templates Manage templates
tokens Manage personal access tokens
users Manage users
version Show coder version
autoupdate Toggle auto-update policy for a workspace
config-ssh Add an SSH Host entry for your workspaces "ssh workspace.coder"
create Create a workspace
delete Delete a workspace
favorite Add a workspace to your favorites
list List workspaces
logs View logs for a workspace
open Open a workspace
ping Ping a workspace
rename Rename a workspace
restart Restart a workspace
schedule Schedule automated start and stop times for workspaces
show Display details of a workspace's resources and agents
speedtest Run upload and download tests from your machine to a workspace
ssh Start a shell into a workspace or run a command
start Start a workspace
stat Show resource usage for the current workspace.
stop Stop a workspace
unfavorite Remove a workspace from your favorites
update Will update and start a given workspace if it is out of date. If the workspace is already running, it will be stopped first.
whoami Fetch authenticated user info for Coder deployment
support Commands for troubleshooting issues with a Coder deployment.
server Start a Coder server
provisioner View and manage provisioner daemons and jobs
ai-gateway Manage AI Gateway
agent-firewall Network isolation tool for monitoring and restricting HTTP/HTTPS requests
workspace-proxy Workspace proxies provide low-latency experiences for geo-distributed teams.
features List license features and entitlements
licenses Add, delete, and list licenses
groups Manage groups
prebuilds Manage Coder prebuilds
external-workspaces Create or manage external workspaces

Options

--url

Property Value
Type url
Environment $CODER_URL

URL to a deployment.

--debug-options

Property Value
Type bool

Print all options, how they're set, then exit.

--token

Property Value
Type string
Environment $CODER_SESSION_TOKEN

Specify an authentication token. For security reasons setting CODER_SESSION_TOKEN is preferred.

--no-version-warning

Property Value
Type bool
Environment $CODER_NO_VERSION_WARNING

Suppress warning when client and server versions do not match.

--no-feature-warning

Property Value
Type bool
Environment $CODER_NO_FEATURE_WARNING

Suppress warnings about unlicensed features.

--allow-redirects

Property Value
Type bool
Environment $CODER_ALLOW_REDIRECTS

Follow HTTP redirects from the server instead of returning an error. Following redirects may alter the request method and/or drop its body.

--header

Property Value
Type string-array
Environment $CODER_HEADER

Additional HTTP headers added to all requests. Provide as key=value. Can be specified multiple times.

--header-command

Property Value
Type string
Environment $CODER_HEADER_COMMAND

An external command that outputs additional HTTP headers added to all requests. The command must output each header as key=value on its own line. If a header value is a JWT, it will be refreshed based on the value in its exp field.

--force-tty

Property Value
Type bool
Environment $CODER_FORCE_TTY

Force the use of a TTY.

-v, --verbose

Property Value
Type bool
Environment $CODER_VERBOSE

Enable verbose output.

--flight-recorder-size

Property Value
Type int
Environment $CODER_FLIGHT_RECORDER_SIZE
Default 10

Number of log entries below the current log level to keep in memory and emit on errors. Set to 0 to disable the flight recorder.

--disable-direct-connections

Property Value
Type bool
Environment $CODER_DISABLE_DIRECT_CONNECTIONS

Disable direct (P2P) connections to workspaces.

--disable-network-telemetry

Property Value
Type bool
Environment $CODER_DISABLE_NETWORK_TELEMETRY

Disable network telemetry. Network telemetry is collected when connecting to workspaces using the CLI, and is forwarded to the server. If telemetry is also enabled on the server, it may be sent to Coder. Network telemetry is used to measure network quality and detect regressions.

--client-tls-ca-file

Property Value
Type string
Environment $CODER_CLIENT_TLS_CA_FILE

Path to a CA certificate file to trust for API and DERP connections.

--client-tls-cert-file

Property Value
Type string
Environment $CODER_CLIENT_TLS_CERT_FILE

Path to a client certificate file for mTLS authentication with API and DERP. Requires --client-tls-key-file.

--client-tls-key-file

Property Value
Type string
Environment $CODER_CLIENT_TLS_KEY_FILE

Path to a client private key file for mTLS authentication with API and DERP. Requires --client-tls-cert-file.

--use-keyring

Property Value
Type bool
Environment $CODER_USE_KEYRING
Default true

Store and retrieve session tokens using the operating system keyring. This flag is ignored and file-based storage is used when --global-config is set or keyring usage is not supported on the current platform. Set to false to force file-based storage on supported platforms.

--global-config

Property Value
Type string
Environment $CODER_CONFIG_DIR
Default ~/.config/coderv2

Path to the global coder config directory.