fix(provisionersdk): allow .terraform.lock.hcl files to be archived (#7604)

* chore(dogfood): update keys, add script to do so

* chore(dogfood): fix urls in Dockerfile

* fmt

.devcontainer/Dockerfile

@@ -3,30 +3,30 @@ SHELL ["/bin/bash", "-o", "pipefail", "-c"]
 
 ENV EDITOR=vim
 
-RUN apt-get update && apt-get upgrade
+RUN apt-get update && apt-get upgrade --yes
 
 RUN apt-get install --yes \
-        ca-certificates \
-        bash-completion \
-        build-essential \
-        curl \
-        cmake \
-        direnv \
-        emacs-nox \
-        gnupg \
-        htop \
-        jq \
-        less \
-        lsb-release \
-        lsof \
-        man-db \
-        nano \
-        neovim \
-        ssl-cert \
-        sudo \
-        unzip \
-        xz-utils \
-        zip
+	ca-certificates \
+	bash-completion \
+	build-essential \
+	curl \
+	cmake \
+	direnv \
+	emacs-nox \
+	gnupg \
+	htop \
+	jq \
+	less \
+	lsb-release \
+	lsof \
+	man-db \
+	nano \
+	neovim \
+	ssl-cert \
+	sudo \
+	unzip \
+	xz-utils \
+	zip
 
 # configure locales to UTF8
 RUN apt-get install locales && locale-gen en_US.UTF-8
@@ -39,25 +39,25 @@ RUN direnv hook bash >> $HOME/.bashrc
 RUN sh <(curl -L https://nixos.org/nix/install) --daemon
 
 RUN mkdir -p $HOME/.config/nix $HOME/.config/nixpkgs \
-        && echo 'sandbox = false' >> $HOME/.config/nix/nix.conf \
-        && echo '{ allowUnfree = true; }' >> $HOME/.config/nixpkgs/config.nix \
-        && echo '. $HOME/.nix-profile/etc/profile.d/nix.sh' >> $HOME/.bashrc
+	&& echo 'sandbox = false' >> $HOME/.config/nix/nix.conf \
+	&& echo '{ allowUnfree = true; }' >> $HOME/.config/nixpkgs/config.nix \
+	&& echo '. $HOME/.nix-profile/etc/profile.d/nix.sh' >> $HOME/.bashrc
 
 
 # install docker and configure daemon to use vfs as GitHub codespaces requires vfs
 # https://github.com/moby/moby/issues/13742#issuecomment-725197223
 RUN mkdir -p /etc/apt/keyrings \
-        && curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg \
-        && echo \
-  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
-  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null \
-        && apt-get update \
-        && apt-get install --yes docker-ce docker-ce-cli containerd.io docker-compose-plugin \
-        && mkdir -p /etc/docker \
-        && echo '{"cgroup-parent":"/actions_job","storage-driver":"vfs"}' >> /etc/docker/daemon.json
+	&& curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg \
+	&& echo \
+	"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
+	$(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null \
+	&& apt-get update \
+	&& apt-get install --yes docker-ce docker-ce-cli containerd.io docker-compose-plugin \
+	&& mkdir -p /etc/docker \
+	&& echo '{"cgroup-parent":"/actions_job","storage-driver":"vfs"}' >> /etc/docker/daemon.json
 
 # install golang and language tooling
-ENV GO_VERSION=1.19
+ENV GO_VERSION=1.20
 ENV GOPATH=$HOME/go-packages
 ENV GOROOT=$HOME/go
 ENV PATH=$GOROOT/bin:$GOPATH/bin:$PATH
@@ -67,6 +67,7 @@ RUN echo 'export PATH=$GOPATH/bin:$PATH' >> $HOME/.bashrc
 RUN bash -c ". $HOME/.bashrc \
 	go install -v golang.org/x/tools/gopls@latest \
 	&& go install -v mvdan.cc/sh/v3/cmd/shfmt@latest \
+	&& go install -v github.com/mikefarah/yq/v4@v4.30.6 \
 	"
 
 # install nodejs
@@ -80,4 +81,3 @@ RUN bash -c "$(curl -fsSL https://raw.githubusercontent.com/horta/zstd.install/m
 RUN echo 'deb [trusted=yes] https://repo.goreleaser.com/apt/ /' | sudo tee /etc/apt/sources.list.d/goreleaser.list \
 	&& apt update \
 	&& apt install nfpm
-

.devcontainer/devcontainer.json

@@ -1,18 +1,24 @@
 // For format details, see https://aka.ms/devcontainer.json
 {
-	"name": "Development environments on your infrastructure",
+  "name": "Development environments on your infrastructure",
 
-	// Sets the run context to one level up instead of the .devcontainer folder.
-	"context": ".",
+  // Sets the run context to one level up instead of the .devcontainer folder.
+  "context": ".",
 
-	// Update the 'dockerFile' property if you aren't using the standard 'Dockerfile' filename.
-	"dockerFile": "Dockerfile",
+  // Update the 'dockerFile' property if you aren't using the standard 'Dockerfile' filename.
+  "dockerFile": "Dockerfile",
 
-	// Use 'forwardPorts' to make a list of ports inside the container available locally.
-	// "forwardPorts": [],
-	
-	"postStartCommand": "dockerd",
+  // Use 'forwardPorts' to make a list of ports inside the container available locally.
+  // "forwardPorts": [],
 
-	// privileged is required by GitHub codespaces - https://github.com/microsoft/vscode-dev-containers/issues/727
-	"runArgs": [ "--cap-add=SYS_PTRACE", "--security-opt", "seccomp=unconfined", "--privileged", "--init" ]	
+  "postStartCommand": "dockerd",
+
+  // privileged is required by GitHub codespaces - https://github.com/microsoft/vscode-dev-containers/issues/727
+  "runArgs": [
+    "--cap-add=SYS_PTRACE",
+    "--security-opt",
+    "seccomp=unconfined",
+    "--privileged",
+    "--init"
+  ]
 }

.editorconfig

@@ -7,7 +7,7 @@ trim_trailing_whitespace = true
 insert_final_newline = true
 indent_style = tab
 
-[*.{md,json,yaml,yml,tf,tfvars}]
+[*.{md,json,yaml,yml,tf,tfvars,nix}]
 indent_style = space
 indent_size = 2
 

.gitattributes

@@ -1,4 +1,6 @@
 # Generated files
+coderd/apidoc/docs.go linguist-generated=true
+coderd/apidoc/swagger.json linguist-generated=true
 coderd/database/dump.sql linguist-generated=true
 peerbroker/proto/*.go linguist-generated=true
 provisionerd/proto/*.go linguist-generated=true

.github/CODEOWNERS

@@ -1,4 +1,3 @@
-site/ @coder/frontend
 docs/ @coder/docs
 README.md @coder/docs
 ADOPTERS.md @coder/docs

.github/ISSUE_TEMPLATE/external_bug_report.md

@@ -1,9 +0,0 @@
-<!--- Provide a general summary of the issue in the Title above -->
-
-## Expected Behavior
-
-<!--- Tell us what should happen -->
-
-## Current Behavior
-
-<!--- Tell us what happens instead of the expected behavior -->

.github/dependabot.yaml

@@ -3,7 +3,7 @@ updates:
   - package-ecosystem: "github-actions"
     directory: "/"
     schedule:
-      interval: "monthly"
+      interval: "weekly"
       time: "06:00"
       timezone: "America/Chicago"
     labels: []
@@ -28,7 +28,7 @@ updates:
   - package-ecosystem: "gomod"
     directory: "/"
     schedule:
-      interval: "monthly"
+      interval: "weekly"
       time: "06:00"
       timezone: "America/Chicago"
     commit-message:
@@ -38,7 +38,19 @@ updates:
       # Ignore patch updates for all dependencies
       - dependency-name: "*"
         update-types:
-        - version-update:semver-patch
+          - version-update:semver-patch
+
+  # Update our Dockerfile.
+  - package-ecosystem: "docker"
+    directory: "/scripts/"
+    schedule:
+      interval: "weekly"
+      time: "06:00"
+      timezone: "America/Chicago"
+    ignore:
+      # We need to coordinate terraform updates with the version hardcoded in
+      # our Go code.
+      - dependency-name: "terraform"
 
   - package-ecosystem: "npm"
     directory: "/site/"
@@ -53,7 +65,7 @@ updates:
       # Ignore patch updates for all dependencies
       - dependency-name: "*"
         update-types:
-        - version-update:semver-patch
+          - version-update:semver-patch
       # Ignore major updates to Node.js types, because they need to
       # correspond to the Node.js engine version
       - dependency-name: "@types/node"

.github/pull_request_template.md

@@ -1,3 +0,0 @@
-<!--
-Check if your change requires documentation edits before merging: https://coder.com/docs/coder. Make edits in `docs/`.
--->

.github/semantic.yaml

@@ -1,56 +0,0 @@
-###############################################################################
-# This file configures "Semantic Pull Requests", which is documented here:
-# https://github.com/zeke/semantic-pull-requests
-#
-# This action/spec implements the "Conventional Commits" RFC which is
-# available here:
-# https://www.notion.so/coderhq/Conventional-commits-1d51287f58b64026bb29393f277734ed
-###############################################################################
-
-# We have no valid scopes right now.
-# A scope should be added when commits aren't aligning with associated change anymore.
-scopes:
-
-# We only check that the PR title is semantic. The PR title is automatically
-# applied to the "Squash & Merge" flow as the suggested commit message, so this
-# should suffice unless someone drastically alters the message in that flow.
-titleOnly: true
-
-# Types are the 'tag' types in a commit or PR title. For example, in
-#
-# chore: fix thing
-#
-# 'chore' is the type.
-types:
-  # A build of any kind.
-  - build
-
-  # Any code task that operates outside of CI, docs, or the product. Examples
-  # include configurations, linters etc.
-  - chore
-
-  # Any work performed on CI.
-  - ci
-  
-  - example
-
-  # Work that directly implements or supports the implementation of a feature.
-  - feat
-
-  # A fix for either a released or unrelesed bug.
-  - fix
-
-  # A fix for a released bug (regression fix) that is intended for patch-release
-  # purposes.
-  - hotfix
-
-  # A refactor changes code structure without any behavioral change.
-  - refactor
-
-  # A git revert for any style of commit.
-  - revert
-
-  # Adding tests of any kind. Should be separate from feature or fix
-  # implementations. For example, if a commit adds a fix + test, it's a fix
-  # commit. If a commit is simply bumping coverage, it's a test commit.
-  - test

.github/workflows/ci.yaml

@@ -1,4 +1,4 @@
-name: coder
+name: ci
 
 on:
   push:
@@ -28,22 +28,73 @@ concurrency:
   cancel-in-progress: ${{ github.event_name == 'pull_request' }}
 
 jobs:
-  typos:
-    runs-on: ubuntu-latest
+  lint:
+    runs-on: ${{ github.repository_owner == 'coder' && 'ubuntu-latest-8-cores' || 'ubuntu-latest' }}
     steps:
       - name: Checkout
-        uses: actions/checkout@v2
-      - name: typos-action
-        uses: crate-ci/typos@v1.12.8
+        uses: actions/checkout@v3
+
+      # Install Go!
+      - uses: actions/setup-go@v4
+        with:
+          go-version: "~1.20"
+
+      # Check for any typos!
+      - name: Check for typos
+        uses: crate-ci/typos@v1.14.9
         with:
           config: .github/workflows/typos.toml
-      - name: Fix Helper
+      - name: Fix the typos
         if: ${{ failure() }}
         run: |
           echo "::notice:: you can automatically fix typos from your CLI:
           cargo install typos-cli
           typos -c .github/workflows/typos.toml -w"
 
+      # Check for Go linting errors!
+      - name: Lint Go
+        uses: golangci/golangci-lint-action@v3.3.1
+        with:
+          version: v1.51.0
+
+      - name: Lint shell scripts
+        uses: ludeeus/action-shellcheck@2.0.0
+        env:
+          SHELLCHECK_OPTS: --external-sources
+        with:
+          ignore: node_modules
+
+      # Lint our dashboard!
+      - name: Cache node_modules
+        id: cache-node
+        uses: actions/cache@v3
+        with:
+          path: |
+            **/node_modules
+            .eslintcache
+          key: js-${{ runner.os }}-test-${{ hashFiles('**/yarn.lock') }}
+          restore-keys: |
+            js-${{ runner.os }}-
+      - name: Install node_modules
+        run: ./scripts/yarn_install.sh
+      - name: Lint TypeScript
+        run: yarn lint
+        working-directory: site
+
+      # Make sure the Helm chart is linted!
+      - name: Install helm
+        uses: azure/setup-helm@v3
+        with:
+          version: v3.9.2
+      - name: Lint Helm chart
+        run: |
+          cd helm
+          make lint
+
+      # Ensure AGPL and Enterprise are separated!
+      - name: Check for AGPL code importing Enterprise...
+        run: ./scripts/check_enterprise_imports.sh
+
   changes:
     runs-on: ubuntu-latest
     outputs:
@@ -70,108 +121,16 @@ jobs:
               - 'site/**'
             k8s:
               - 'helm/**'
-              - Dockerfile
+              - scripts/Dockerfile
+              - scripts/Dockerfile.base
               - scripts/helm.sh
       - id: debug
         run: |
           echo "${{ toJSON(steps.filter )}}"
 
-  # Debug step
-  debug-inputs:
-    needs:
-      - changes
-    runs-on: ubuntu-latest
-    steps:
-      - id: log
-        run: |
-          echo "${{ toJSON(needs) }}"
-
-  style-lint-golangci:
-    name: style/lint/golangci
-    timeout-minutes: 5
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-      - uses: actions/setup-go@v3
-        with:
-          go-version: "~1.19"
-      - name: golangci-lint
-        uses: golangci/golangci-lint-action@v3.2.0
-        with:
-          version: v1.48.0
-
-  check-enterprise-imports:
-    name: check/enterprise-imports
-    timeout-minutes: 5
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-      - name: Check imports of enterprise code
-        run: ./scripts/check_enterprise_imports.sh
-
-  style-lint-shellcheck:
-    name: style/lint/shellcheck
-    timeout-minutes: 5
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-      - name: Run ShellCheck
-        uses: ludeeus/action-shellcheck@1.1.0
-        env:
-          SHELLCHECK_OPTS: --external-sources
-        with:
-          ignore: node_modules
-
-  style-lint-typescript:
-    name: "style/lint/typescript"
-    timeout-minutes: 5
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v3
-
-      - name: Cache Node
-        id: cache-node
-        uses: actions/cache@v3
-        with:
-          path: |
-            **/node_modules
-            .eslintcache
-          key: js-${{ runner.os }}-test-${{ hashFiles('**/yarn.lock') }}
-          restore-keys: |
-            js-${{ runner.os }}-
-
-      - name: Install node_modules
-        run: ./scripts/yarn_install.sh
-
-      - name: "yarn lint"
-        run: yarn lint
-        working-directory: site
-
-  style-lint-k8s:
-    name: "style/lint/k8s"
-    timeout-minutes: 5
-    needs: changes
-    if: needs.changes.outputs.k8s == 'true'
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v3
-
-      - name: Install helm
-        uses: azure/setup-helm@v3
-        with:
-          version: v3.9.2
-
-      - name: cd helm && make lint
-        run: |
-          cd helm
-          make lint
-
   gen:
-    name: "style/gen"
     timeout-minutes: 8
-    runs-on: ubuntu-latest
+    runs-on: ${{ github.repository_owner == 'coder' && 'ubuntu-latest-8-cores' || 'ubuntu-latest' }}
     needs: changes
     if: needs.changes.outputs.docs-only == 'false'
     steps:
@@ -191,42 +150,46 @@ jobs:
       - name: Install node_modules
         run: ./scripts/yarn_install.sh
 
-      - uses: actions/setup-go@v3
+      - uses: actions/setup-go@v4
         with:
-          go-version: "~1.19"
+          cache: false
+          go-version: "~1.20"
 
       - name: Echo Go Cache Paths
         id: go-cache-paths
         run: |
-          echo "::set-output name=go-build::$(go env GOCACHE)"
-          echo "::set-output name=go-mod::$(go env GOMODCACHE)"
+          echo "GOCACHE=$(go env GOCACHE)" >> $GITHUB_OUTPUT
+          echo "GOMODCACHE=$(go env GOMODCACHE)" >> $GITHUB_OUTPUT
 
       - name: Go Build Cache
         uses: actions/cache@v3
         with:
-          path: ${{ steps.go-cache-paths.outputs.go-build }}
+          path: ${{ steps.go-cache-paths.outputs.GOCACHE }}
           key: ${{ github.job }}-go-build-${{ hashFiles('**/go.sum', '**/**.go') }}
 
       - name: Go Mod Cache
         uses: actions/cache@v3
         with:
-          path: ${{ steps.go-cache-paths.outputs.go-mod }}
+          path: ${{ steps.go-cache-paths.outputs.GOMODCACHE }}
           key: ${{ github.job }}-go-mod-${{ hashFiles('**/go.sum') }}
 
       - name: Install sqlc
         run: |
-          curl -sSL https://github.com/kyleconroy/sqlc/releases/download/v1.13.0/sqlc_1.13.0_linux_amd64.tar.gz | sudo tar -C /usr/bin -xz sqlc
+          curl -sSL https://github.com/kyleconroy/sqlc/releases/download/v1.17.2/sqlc_1.17.2_linux_amd64.tar.gz | sudo tar -C /usr/bin -xz sqlc
       - name: Install protoc-gen-go
         run: go install google.golang.org/protobuf/cmd/protoc-gen-go@v1.26
       - name: Install protoc-gen-go-drpc
         run: go install storj.io/drpc/cmd/protoc-gen-go-drpc@v0.0.26
       - name: Install goimports
         run: go install golang.org/x/tools/cmd/goimports@latest
+      - name: Install yq
+        run: go run github.com/mikefarah/yq/v4@v4.30.6
 
       - name: Install Protoc
         run: |
-          # protoc must be in lockstep with our dogfood Dockerfile
-          # or the version in the comments will differ.
+          # protoc must be in lockstep with our dogfood Dockerfile or the
+          # version in the comments will differ. This is also defined in
+          # security.yaml
           set -x
           cd dogfood
           DOCKER_BUILDKIT=1 docker build . --target proto -t protoc
@@ -241,8 +204,7 @@ jobs:
       - name: Check for unstaged files
         run: ./scripts/check_unstaged.sh
 
-  style-fmt:
-    name: "style/fmt"
+  fmt:
     runs-on: ubuntu-latest
     timeout-minutes: 5
     steps:
@@ -274,9 +236,11 @@ jobs:
           export PATH=${PATH}:$(go env GOPATH)/bin
           make --output-sync -j -B fmt
 
+      - name: Check for unstaged files
+        run: ./scripts/check_unstaged.sh
+
   test-go:
-    name: "test/go"
-    runs-on: ${{ matrix.os }}
+    runs-on: ${{ matrix.os == 'ubuntu-latest' && github.repository_owner == 'coder' && 'ubuntu-latest-8-cores' ||  matrix.os == 'windows-2022' && github.repository_owner == 'coder' && 'windows-latest-8-cores'|| matrix.os }}
     timeout-minutes: 20
     strategy:
       matrix:
@@ -287,35 +251,36 @@ jobs:
     steps:
       - uses: actions/checkout@v3
 
-      - uses: actions/setup-go@v3
+      - uses: actions/setup-go@v4
         with:
-          go-version: "~1.19"
+          cache: false
+          go-version: "~1.20"
 
       - name: Echo Go Cache Paths
         id: go-cache-paths
         run: |
-          echo "::set-output name=go-build::$(go env GOCACHE)"
-          echo "::set-output name=go-mod::$(go env GOMODCACHE)"
+          echo "GOCACHE=$(go env GOCACHE)" >> ${{ runner.os == 'Windows' && '$env:' || '$' }}GITHUB_OUTPUT
+          echo "GOMODCACHE=$(go env GOMODCACHE)" >> ${{ runner.os == 'Windows' && '$env:' || '$' }}GITHUB_OUTPUT
 
       - name: Go Build Cache
         uses: actions/cache@v3
         with:
-          path: ${{ steps.go-cache-paths.outputs.go-build }}
+          path: ${{ steps.go-cache-paths.outputs.GOCACHE }}
           key: ${{ runner.os }}-go-build-${{ hashFiles('**/go.**', '**.go') }}
 
       - name: Go Mod Cache
         uses: actions/cache@v3
         with:
-          path: ${{ steps.go-cache-paths.outputs.go-mod }}
+          path: ${{ steps.go-cache-paths.outputs.GOMODCACHE }}
           key: ${{ runner.os }}-go-mod-${{ hashFiles('**/go.sum') }}
 
       - name: Install gotestsum
-        uses: jaxxstorm/action-install-gh-release@v1.7.1
+        uses: jaxxstorm/action-install-gh-release@v1.10.0
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         with:
           repo: gotestyourself/gotestsum
-          tag: v1.7.0
+          tag: v1.9.0
 
       - uses: hashicorp/setup-terraform@v2
         with:
@@ -330,17 +295,28 @@ jobs:
           # prevents test caching, so we disable it on alternate operating
           # systems.
           if [ "${{ matrix.os }}" == "ubuntu-latest" ]; then
-            echo ::set-output name=cover::true
+            echo "cover=true" >> $GITHUB_OUTPUT
             export COVERAGE_FLAGS='-covermode=atomic -coverprofile="gotests.coverage" -coverpkg=./...'
           else
-            echo ::set-output name=cover::false
+            echo "cover=false" >> $GITHUB_OUTPUT
           fi
-          set -x
-          test_timeout=5m
-          if [[ "${{ matrix.os }}" == windows* ]]; then
-            test_timeout=10m
-          fi
-          gotestsum --junitfile="gotests.xml" --packages="./..." -- -parallel=8 -timeout=$test_timeout -short -failfast $COVERAGE_FLAGS
+
+          export TS_DEBUG_DISCO=true
+          gotestsum --junitfile="gotests.xml" --jsonfile="gotests.json" --packages="./..." -- -parallel=8 -timeout=7m -short -failfast $COVERAGE_FLAGS
+
+      - name: Print test stats
+        if: success() || failure()
+        run: |
+          # Artifacts are not available after rerunning a job,
+          # so we need to print the test stats to the log.
+          go run ./scripts/ci-report/main.go gotests.json | tee gotests_stats.json
+
+      - uses: actions/upload-artifact@v3
+        if: success() || failure()
+        with:
+          name: gotests-${{ matrix.os }}.xml
+          path: ./gotests.xml
+          retention-days: 30
 
       - uses: codecov/codecov-action@v3
         # This action has a tendency to error out unexpectedly, it has
@@ -354,9 +330,8 @@ jobs:
           files: ./gotests.coverage
           flags: unittest-go-${{ matrix.os }}
 
-  test-go-postgres:
-    name: "test/go/postgres"
-    runs-on: ubuntu-latest
+  test-go-psql:
+    runs-on: ${{ github.repository_owner == 'coder' && 'ubuntu-latest-8-cores' || 'ubuntu-latest' }}
     # This timeout must be greater than the timeout set by `go test` in
     # `make test-postgres` to ensure we receive a trace of running
     # goroutines. Setting this to the timeout +5m should work quite well
@@ -365,35 +340,36 @@ jobs:
     steps:
       - uses: actions/checkout@v3
 
-      - uses: actions/setup-go@v3
+      - uses: actions/setup-go@v4
         with:
-          go-version: "~1.19"
+          cache: false
+          go-version: "~1.20"
 
       - name: Echo Go Cache Paths
         id: go-cache-paths
         run: |
-          echo "::set-output name=go-build::$(go env GOCACHE)"
-          echo "::set-output name=go-mod::$(go env GOMODCACHE)"
+          echo "GOCACHE=$(go env GOCACHE)" >> $GITHUB_OUTPUT
+          echo "GOMODCACHE=$(go env GOMODCACHE)" >> $GITHUB_OUTPUT
 
       - name: Go Build Cache
         uses: actions/cache@v3
         with:
-          path: ${{ steps.go-cache-paths.outputs.go-build }}
+          path: ${{ steps.go-cache-paths.outputs.GOCACHE }}
           key: ${{ runner.os }}-go-build-${{ hashFiles('**/go.sum', '**/**.go') }}
 
       - name: Go Mod Cache
         uses: actions/cache@v3
         with:
-          path: ${{ steps.go-cache-paths.outputs.go-mod }}
+          path: ${{ steps.go-cache-paths.outputs.GOMODCACHE }}
           key: ${{ runner.os }}-go-mod-${{ hashFiles('**/go.sum') }}
 
       - name: Install gotestsum
-        uses: jaxxstorm/action-install-gh-release@v1.7.1
+        uses: jaxxstorm/action-install-gh-release@v1.10.0
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         with:
           repo: gotestyourself/gotestsum
-          tag: v1.7.0
+          tag: v1.9.0
 
       - uses: hashicorp/setup-terraform@v2
         with:
@@ -401,7 +377,23 @@ jobs:
           terraform_wrapper: false
 
       - name: Test with PostgreSQL Database
-        run: make test-postgres
+        run: |
+          export TS_DEBUG_DISCO=true
+          make test-postgres
+
+      - name: Print test stats
+        if: success() || failure()
+        run: |
+          # Artifacts are not available after rerunning a job,
+          # so we need to print the test stats to the log.
+          go run ./scripts/ci-report/main.go gotests.json | tee gotests_stats.json
+
+      - uses: actions/upload-artifact@v3
+        if: success() || failure()
+        with:
+          name: gotests-postgres.xml
+          path: ./gotests.xml
+          retention-days: 30
 
       - uses: codecov/codecov-action@v3
         # This action has a tendency to error out unexpectedly, it has
@@ -413,11 +405,11 @@ jobs:
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
           files: ./gotests.coverage
-          flags: unittest-go-postgres-${{ matrix.os }}
+          flags: unittest-go-postgres-linux
 
   deploy:
     name: "deploy"
-    runs-on: ubuntu-latest
+    runs-on: ${{ github.repository_owner == 'coder' && 'ubuntu-latest-8-cores' || 'ubuntu-latest' }}
     timeout-minutes: 30
     needs: changes
     if: |
@@ -432,34 +424,35 @@ jobs:
           fetch-depth: 0
 
       - name: Authenticate to Google Cloud
-        uses: google-github-actions/auth@v0
+        uses: google-github-actions/auth@v1
         with:
           workload_identity_provider: projects/573722524737/locations/global/workloadIdentityPools/github/providers/github
           service_account: coder-ci@coder-dogfood.iam.gserviceaccount.com
 
       - name: Set up Google Cloud SDK
-        uses: google-github-actions/setup-gcloud@v0
+        uses: google-github-actions/setup-gcloud@v1
 
-      - uses: actions/setup-go@v3
+      - uses: actions/setup-go@v4
         with:
-          go-version: "~1.19"
+          cache: false
+          go-version: "~1.20"
 
       - name: Echo Go Cache Paths
         id: go-cache-paths
         run: |
-          echo "::set-output name=go-build::$(go env GOCACHE)"
-          echo "::set-output name=go-mod::$(go env GOMODCACHE)"
+          echo "GOCACHE=$(go env GOCACHE)" >> $GITHUB_OUTPUT
+          echo "GOMODCACHE=$(go env GOMODCACHE)" >> $GITHUB_OUTPUT
 
       - name: Go Build Cache
         uses: actions/cache@v3
         with:
-          path: ${{ steps.go-cache-paths.outputs.go-build }}
+          path: ${{ steps.go-cache-paths.outputs.GOCACHE }}
           key: ${{ runner.os }}-release-go-build-${{ hashFiles('**/go.sum') }}
 
       - name: Go Mod Cache
         uses: actions/cache@v3
         with:
-          path: ${{ steps.go-cache-paths.outputs.go-mod }}
+          path: ${{ steps.go-cache-paths.outputs.GOMODCACHE }}
           key: ${{ runner.os }}-release-go-mod-${{ hashFiles('**/go.sum') }}
 
       - name: Cache Node
@@ -494,14 +487,36 @@ jobs:
 
       - name: Install Release
         run: |
-          gcloud config set project coder-dogfood
-          gcloud config set compute/zone us-central1-a
-          gcloud compute scp ./build/coder_*_linux_amd64.deb coder:/tmp/coder.deb
-          gcloud compute ssh coder -- sudo dpkg -i --force-confdef /tmp/coder.deb
-          gcloud compute ssh coder -- sudo systemctl daemon-reload
+          set -euo pipefail
 
-      - name: Start
-        run: gcloud compute ssh coder -- sudo service coder restart
+          regions=(
+            # gcp-region-id instance-name systemd-service-name
+            "us-central1-a coder coder"
+            "australia-southeast1-b coder-sydney coder-workspace-proxy"
+            "europe-west3-c coder-europe coder-workspace-proxy"
+            "southamerica-east1-b coder-brazil coder-workspace-proxy"
+          )
+
+          deb_pkg="./build/coder_$(./scripts/version.sh)_linux_amd64.deb"
+          if [ ! -f "$deb_pkg" ]; then
+            echo "deb package not found: $deb_pkg"
+            ls -l ./build
+            exit 1
+          fi
+
+          gcloud config set project coder-dogfood
+          for region in "${regions[@]}"; do
+            echo "::group::$region"
+            set -- $region
+
+            set -x
+            gcloud config set compute/zone "$1"
+            gcloud compute scp "$deb_pkg" "${2}:/tmp/coder.deb"
+            gcloud compute ssh "$2" -- /bin/sh -c "set -eux; sudo dpkg -i --force-confdef /tmp/coder.deb; sudo systemctl daemon-reload; sudo service '$3' restart"
+            set +x
+
+            echo "::endgroup::"
+          done
 
       - uses: actions/upload-artifact@v3
         with:
@@ -513,8 +528,7 @@ jobs:
           retention-days: 7
 
   test-js:
-    name: "test/js"
-    runs-on: ubuntu-latest
+    runs-on: ${{ github.repository_owner == 'coder' && 'ubuntu-latest-8-cores' || 'ubuntu-latest' }}
     timeout-minutes: 20
     steps:
       - uses: actions/checkout@v3
@@ -532,12 +546,12 @@ jobs:
 
       - uses: actions/setup-node@v3
         with:
-          node-version: "14"
+          node-version: "16.16.0"
 
       - name: Install node_modules
         run: ./scripts/yarn_install.sh
 
-      - run: yarn test:coverage
+      - run: yarn test:ci --max-workers ${{ steps.cpu-cores.outputs.count }}
         working-directory: site
 
       - uses: codecov/codecov-action@v3
@@ -553,16 +567,11 @@ jobs:
           flags: unittest-js
 
   test-e2e:
-    name: "test/e2e/${{ matrix.os }}"
     needs:
       - changes
     if: needs.changes.outputs.docs-only == 'false'
-    runs-on: ${{ matrix.os }}
+    runs-on: ${{ github.repository_owner == 'coder' && 'ubuntu-latest-8-cores' || 'ubuntu-latest' }}
     timeout-minutes: 20
-    strategy:
-      matrix:
-        os:
-          - ubuntu-latest
     steps:
       - uses: actions/checkout@v3
 
@@ -575,9 +584,10 @@ jobs:
             .eslintcache
           key: js-${{ runner.os }}-e2e-${{ hashFiles('**/yarn.lock') }}
 
-      - uses: actions/setup-go@v3
+      - uses: actions/setup-go@v4
         with:
-          go-version: "~1.19"
+          cache: false
+          go-version: "~1.20"
 
       - uses: hashicorp/setup-terraform@v2
         with:
@@ -586,24 +596,24 @@ jobs:
 
       - uses: actions/setup-node@v3
         with:
-          node-version: "14"
+          node-version: "16.16.0"
 
       - name: Echo Go Cache Paths
         id: go-cache-paths
         run: |
-          echo "::set-output name=go-build::$(go env GOCACHE)"
-          echo "::set-output name=go-mod::$(go env GOMODCACHE)"
+          echo "GOCACHE=$(go env GOCACHE)" >> $GITHUB_OUTPUT
+          echo "GOMODCACHE=$(go env GOMODCACHE)" >> $GITHUB_OUTPUT
 
       - name: Go Build Cache
         uses: actions/cache@v3
         with:
-          path: ${{ steps.go-cache-paths.outputs.go-build }}
+          path: ${{ steps.go-cache-paths.outputs.GOCACHE }}
           key: ${{ runner.os }}-go-build-${{ hashFiles('**/go.sum') }}
 
       - name: Go Mod Cache
         uses: actions/cache@v3
         with:
-          path: ${{ steps.go-cache-paths.outputs.go-mod }}
+          path: ${{ steps.go-cache-paths.outputs.GOMODCACHE }}
           key: ${{ runner.os }}-go-mod-${{ hashFiles('**/go.sum') }}
 
       - name: Build
@@ -614,9 +624,6 @@ jobs:
       - run: yarn playwright:install
         working-directory: site
 
-      - run: yarn playwright:install-deps
-        working-directory: site
-
       - run: yarn playwright:test
         env:
           DEBUG: pw:api
@@ -628,7 +635,7 @@ jobs:
         with:
           name: failed-test-videos
           path: ./site/test-results/**/*.webm
-          retention:days: 7
+          retention-days: 7
 
   chromatic:
     # REMARK: this is only used to build storybook and deploy it to Chromatic.
@@ -643,6 +650,10 @@ jobs:
           # only get 1 commit on shallow checkout.
           fetch-depth: 0
 
+      - uses: actions/setup-node@v3
+        with:
+          node-version: "16.16.0"
+
       - name: Install dependencies
         run: cd site && yarn
 
@@ -652,6 +663,9 @@ jobs:
       - name: Publish to Chromatic (non-mainline)
         if: github.ref != 'refs/heads/main' && github.repository_owner == 'coder'
         uses: chromaui/action@v1
+        env:
+          NODE_OPTIONS: "--max_old_space_size=4096"
+          STORYBOOK: true
         with:
           buildScriptName: "storybook:build"
           exitOnceUploaded: true
@@ -669,6 +683,9 @@ jobs:
       - name: Publish to Chromatic (mainline)
         if: github.ref == 'refs/heads/main' && github.repository_owner == 'coder'
         uses: chromaui/action@v1
+        env:
+          NODE_OPTIONS: "--max_old_space_size=4096"
+          STORYBOOK: true
         with:
           autoAcceptChanges: true
           buildScriptName: "storybook:build"

.github/workflows/contrib.yaml

@@ -0,0 +1,169 @@
+name: contrib
+
+on:
+  issue_comment:
+    types: [created]
+  pull_request_target:
+    types:
+      - opened
+      - closed
+      - synchronize
+      - labeled
+      - unlabeled
+      - opened
+      - reopened
+      - edited
+
+# Only run one instance per PR to ensure in-order execution.
+concurrency: pr-${{ github.ref }}
+
+jobs:
+  # Dependabot is annoying, but this makes it a bit less so.
+  auto-approve-dependabot:
+    runs-on: ubuntu-latest
+    if: github.event_name == 'pull_request_target'
+    permissions:
+      pull-requests: write
+    steps:
+      - uses: hmarr/auto-approve-action@v3
+        if: github.actor == 'dependabot[bot]'
+
+  cla:
+    runs-on: ubuntu-latest
+    steps:
+      - name: cla
+        if: (github.event.comment.body == 'recheck' || github.event.comment.body == 'I have read the CLA Document and I hereby sign the CLA') || github.event_name == 'pull_request_target'
+        uses: contributor-assistant/github-action@v2.3.0
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          # the below token should have repo scope and must be manually added by you in the repository's secret
+          PERSONAL_ACCESS_TOKEN: ${{ secrets.CDRCOMMUNITY_GITHUB_TOKEN }}
+        with:
+          remote-organization-name: "coder"
+          remote-repository-name: "cla"
+          path-to-signatures: "v2022-09-04/signatures.json"
+          path-to-document: "https://github.com/coder/cla/blob/main/README.md"
+          # branch should not be protected
+          branch: "main"
+          allowlist: dependabot*
+
+  title:
+    runs-on: ubuntu-latest
+    if: github.event_name == 'pull_request_target'
+    steps:
+      - name: Validate PR title
+        uses: amannn/action-semantic-pull-request@v5
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          requireScope: false
+
+  release-labels:
+    runs-on: ubuntu-latest
+    # Depend on lint so that title is Conventional Commits-compatible.
+    needs: [title]
+    # Skip tagging for draft PRs.
+    if: ${{ github.event_name == 'pull_request_target' && success() && !github.event.pull_request.draft }}
+    steps:
+      - uses: actions/github-script@v6
+        with:
+          # This script ensures PR title and labels are in sync:
+          #
+          # When release/breaking label is:
+          # - Added, rename PR title to include ! (e.g. feat!:)
+          # - Removed, rename PR title to strip ! (e.g. feat:)
+          #
+          # When title is:
+          # - Renamed (+!), add the release/breaking label
+          # - Renamed (-!), remove the release/breaking label
+          script: |
+            const releaseLabels = {
+              breaking: "release/breaking",
+            }
+
+            const { action, changes, label, pull_request } = context.payload
+            const { title } = pull_request
+            const labels = pull_request.labels.map((label) => label.name)
+            const isBreakingTitle = isBreaking(title)
+
+            // Debug information.
+            console.log("Action: %s", action)
+            console.log("Title: %s", title)
+            console.log("Labels: %s", labels.join(", "))
+
+            const params = {
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+            }
+
+            if (action === "opened" || action === "reopened") {
+              if (isBreakingTitle && !labels.includes(releaseLabels.breaking)) {
+                console.log('Add "%s" label', releaseLabels.breaking)
+                await github.rest.issues.addLabels({
+                  ...params,
+                  labels: [releaseLabels.breaking],
+                })
+              }
+            }
+
+            if (action === "edited" && changes.title) {
+              if (isBreakingTitle && !labels.includes(releaseLabels.breaking)) {
+                console.log('Add "%s" label', releaseLabels.breaking)
+                await github.rest.issues.addLabels({
+                  ...params,
+                  labels: [releaseLabels.breaking],
+                })
+              }
+
+              if (!isBreakingTitle && labels.includes(releaseLabels.breaking)) {
+                const wasBreakingTitle = isBreaking(changes.title.from)
+                if (wasBreakingTitle) {
+                  console.log('Remove "%s" label', releaseLabels.breaking)
+                  await github.rest.issues.removeLabel({
+                    ...params,
+                    name: releaseLabels.breaking,
+                  })
+                } else {
+                  console.log('Rename title from "%s" to "%s"', title, toBreaking(title))
+                  await github.rest.issues.update({
+                    ...params,
+                    title: toBreaking(title),
+                  })
+                }
+              }
+            }
+
+            if (action === "labeled") {
+              if (label.name === releaseLabels.breaking && !isBreakingTitle) {
+                console.log('Rename title from "%s" to "%s"', title, toBreaking(title))
+                await github.rest.issues.update({
+                  ...params,
+                  title: toBreaking(title),
+                })
+              }
+            }
+
+            if (action === "unlabeled") {
+              if (label.name === releaseLabels.breaking && isBreakingTitle) {
+                console.log('Rename title from "%s" to "%s"', title, fromBreaking(title))
+                await github.rest.issues.update({
+                  ...params,
+                  title: fromBreaking(title),
+                })
+              }
+            }
+
+            function isBreaking(t) {
+              return t.split(" ")[0].endsWith("!:")
+            }
+
+            function toBreaking(t) {
+              const parts = t.split(" ")
+              return [parts[0].replace(/:$/, "!:"), ...parts.slice(1)].join(" ")
+            }
+
+            function fromBreaking(t) {
+              const parts = t.split(" ")
+              return [parts[0].replace(/!:$/, ":"), ...parts.slice(1)].join(" ")
+            }

.github/workflows/cron-weekly.yaml

@@ -0,0 +1,32 @@
+name: Weekly Cron
+# runs every monday at 9 am
+on:
+  schedule:
+    - cron: "0 9 * * 1"
+  workflow_dispatch: # allows to run manually for testing
+
+jobs:
+  check-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@master
+
+      - name: Check Markdown links
+        uses: gaurav-nelson/github-action-markdown-link-check@v1
+        id: markdown-link-check
+        # checks all markdown files from /docs including all subfolders
+        with:
+          use-quiet-mode: "yes"
+          use-verbose-mode: "yes"
+          config-file: ".github/workflows/mlc_config.json"
+          folder-path: "docs/"
+          file-path: "./README.md"
+
+      - name: Send Slack notification
+        if: failure()
+        run: |
+          curl -X POST -H 'Content-type: application/json' -d '{"msg":"Broken links found in the documentation. Please check the logs at ${{ env.LOGS_URL }}"}' ${{ secrets.DOCS_LINK_SLACK_WEBHOOK }}
+          echo "Sent Slack notification"
+        env:
+          LOGS_URL: https://github.com/coder/coder/actions/runs/${{ github.run_id }}

.github/workflows/dependabot.yaml

@@ -1,13 +0,0 @@
-# Dependabot is annoying, but this makes it a bit less so.
-name: Auto Approve Dependabot
-
-on: pull_request_target
-
-jobs:
-  auto-approve:
-    runs-on: ubuntu-latest
-    permissions:
-      pull-requests: write
-    steps:
-      - uses: hmarr/auto-approve-action@v2
-        if: github.actor == 'dependabot[bot]'

.github/workflows/docker-base.yaml

@@ -0,0 +1,90 @@
+name: docker-base
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - scripts/Dockerfile.base
+      - scripts/Dockerfile
+
+  schedule:
+    # Run every week at 09:43 on Monday, Wednesday and Friday. We build this
+    # frequently to ensure that packages are up-to-date.
+    - cron: "43 9 * * 1,3,5"
+
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  # Necessary to push docker images to ghcr.io.
+  packages: write
+  # Necessary for depot.dev authentication.
+  id-token: write
+
+# Avoid running multiple jobs for the same commit.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}-docker-base
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    if: github.repository_owner == 'coder'
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Docker login
+        uses: docker/login-action@v2
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Create empty base-build-context directory
+        run: mkdir base-build-context
+
+      - name: Install depot.dev CLI
+        uses: depot/setup-action@v1
+
+      # This uses OIDC authentication, so no auth variables are required.
+      - name: Build base Docker image via depot.dev
+        uses: depot/build-push-action@v1
+        with:
+          project: wl5hnrrkns
+          context: base-build-context
+          file: scripts/Dockerfile.base
+          platforms: linux/amd64,linux/arm64,linux/arm/v7
+          pull: true
+          no-cache: true
+          push: true
+          tags: |
+            ghcr.io/coder/coder-base:latest
+
+      - name: Verify that images are pushed properly
+        run: |
+          # retry 10 times with a 5 second delay as the images may not be
+          # available immediately
+          for i in {1..10}; do
+            rc=0
+            raw_manifests=$(docker buildx imagetools inspect --raw ghcr.io/coder/coder-base:latest) || rc=$?
+            if [[ "$rc" -eq 0 ]]; then
+              break
+            fi
+            if [[ "$i" -eq 10 ]]; then
+              echo "Failed to pull manifests after 10 retries"
+              exit 1
+            fi
+            echo "Failed to pull manifests, retrying in 5 seconds"
+            sleep 5
+          done
+
+          manifests=$(
+            echo "$raw_manifests" | \
+              jq -r '.manifests[].platform | .os + "/" + .architecture + (if .variant then "/" + .variant else "" end)'
+          )
+
+          # Verify all 3 platforms are present.
+          set -euxo pipefail
+          echo "$manifests" | grep -q linux/amd64
+          echo "$manifests" | grep -q linux/arm64
+          echo "$manifests" | grep -q linux/arm/v7

.github/workflows/dogfood.yaml

@@ -6,18 +6,19 @@ on:
       - main
     paths:
       - "dogfood/**"
-  pull_request:
-    paths:
-      - "dogfood/**"
+  # Uncomment these lines when testing with CI.
+  # pull_request:
+  #   paths:
+  #     - "dogfood/**"
   workflow_dispatch:
 
 jobs:
-  deploy:
+  deploy_image:
     runs-on: ubuntu-latest
     steps:
       - name: Get branch name
         id: branch-name
-        uses: tj-actions/branch-names@v6.1
+        uses: tj-actions/branch-names@v6.5
 
       - name: "Branch name to Docker tag name"
         id: docker-tag-name
@@ -25,7 +26,7 @@ jobs:
           tag=${{ steps.branch-name.outputs.current_branch }}
           # Replace / with --, e.g. user/feature => user--feature.
           tag=${tag//\//--}
-          echo "::set-output name=tag::${tag}"
+          echo "tag=${tag}" >> $GITHUB_OUTPUT
 
       - name: Set up QEMU
         uses: docker/setup-qemu-action@v2
@@ -40,10 +41,34 @@ jobs:
           password: ${{ secrets.DOCKERHUB_PASSWORD }}
 
       - name: Build and push
-        uses: docker/build-push-action@v3
+        uses: docker/build-push-action@v4
         with:
           context: "{{defaultContext}}:dogfood"
           push: true
           tags: "codercom/oss-dogfood:${{ steps.docker-tag-name.outputs.tag }},codercom/oss-dogfood:latest"
           cache-from: type=registry,ref=codercom/oss-dogfood:latest
           cache-to: type=inline
+  deploy_template:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+      - name: Get short commit SHA
+        id: vars
+        run: echo "sha_short=$(git rev-parse --short HEAD)" >> $GITHUB_OUTPUT
+      - name: "Install latest Coder"
+        run: |
+          curl -L https://coder.com/install.sh | sh
+        # env:
+        #   VERSION: 0.x
+      - name: "Push template"
+        run: |
+          coder templates push $CODER_TEMPLATE_NAME --directory $CODER_TEMPLATE_DIR --yes --name=$CODER_TEMPLATE_VERSION
+        env:
+          # Consumed by Coder CLI
+          CODER_URL: https://dev.coder.com
+          CODER_SESSION_TOKEN: ${{ secrets.CODER_SESSION_TOKEN }}
+          # Template source & details
+          CODER_TEMPLATE_NAME: ${{ secrets.CODER_TEMPLATE_NAME }}
+          CODER_TEMPLATE_VERSION: ${{ steps.vars.outputs.sha_short }}
+          CODER_TEMPLATE_DIR: ./dogfood

.github/workflows/mlc_config.json

@@ -0,0 +1,23 @@
+{
+  "ignorePatterns": [
+    {
+      "pattern": "://localhost"
+    },
+    {
+      "pattern": "://.*.?example\\.com"
+    },
+    {
+      "pattern": "developer.github.com"
+    },
+    {
+      "pattern": "docs.github.com"
+    },
+    {
+      "pattern": "support.google.com"
+    },
+    {
+      "pattern": "tailscale.com"
+    }
+  ],
+  "aliveStatusCodes": [200, 0]
+}

.github/workflows/pr-auto-assign.yaml

@@ -0,0 +1,16 @@
+# Filtering pull requests is much easier when we can reliably guarantee
+# that the "Assignee" field is populated.
+name: PR Auto Assign
+
+on:
+  pull_request_target:
+    types: [opened]
+
+permissions:
+  pull-requests: write
+
+jobs:
+  assign-author:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: toshimaru/auto-author-assign@v1.6.2

.github/workflows/release.yaml

@@ -1,35 +1,43 @@
 # GitHub release workflow.
-name: release
+name: Release
 on:
   push:
     tags:
       - "v*"
   workflow_dispatch:
     inputs:
-      snapshot:
-        description: Force a dev version to be generated, implies dry_run.
-        type: boolean
-        required: true
       dry_run:
-        description: Perform a dry-run release.
+        description: Perform a dry-run release (devel). Note that ref must be an annotated tag when run without dry-run.
         type: boolean
         required: true
+        default: false
 
 permissions:
   # Required to publish a release
   contents: write
   # Necessary to push docker images to ghcr.io.
   packages: write
+  # Necessary for GCP authentication (https://github.com/google-github-actions/setup-gcloud#usage)
+  id-token: write
+
+concurrency: ${{ github.workflow }}-${{ github.ref }}
 
 env:
-  CODER_RELEASE: ${{ github.event.inputs.snapshot && 'false' || 'true' }}
+  # Use `inputs` (vs `github.event.inputs`) to ensure that booleans are actual
+  # booleans, not strings.
+  # https://github.blog/changelog/2022-06-10-github-actions-inputs-unified-across-manual-and-reusable-workflows/
+  CODER_RELEASE: ${{ !inputs.dry_run }}
+  CODER_DRY_RUN: ${{ inputs.dry_run }}
 
 jobs:
   release:
-    runs-on: ubuntu-latest
+    name: Build and publish
+    runs-on: ${{ github.repository_owner == 'coder' && 'ubuntu-latest-8-cores' || 'ubuntu-latest' }}
     env:
       # Necessary for Docker manifest
       DOCKER_CLI_EXPERIMENTAL: "enabled"
+    outputs:
+      version: ${{ steps.version.outputs.version }}
     steps:
       - uses: actions/checkout@v3
         with:
@@ -43,6 +51,38 @@ jobs:
       - name: Fetch git tags
         run: git fetch --tags --force
 
+      - name: Print version
+        id: version
+        run: |
+          set -euo pipefail
+          version="$(./scripts/version.sh)"
+          echo "version=$version" >> $GITHUB_OUTPUT
+          # Speed up future version.sh calls.
+          echo "CODER_FORCE_VERSION=$version" >> $GITHUB_ENV
+          echo "$version"
+
+      - name: Create release notes
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          # We always have to set this since there might be commits on
+          # main that didn't have a PR.
+          CODER_IGNORE_MISSING_COMMIT_METADATA: "1"
+        run: |
+          set -euo pipefail
+          ref=HEAD
+          old_version="$(git describe --abbrev=0 "$ref^1")"
+          version="$(./scripts/version.sh)"
+
+          # Generate notes.
+          release_notes_file="$(mktemp -t release_notes.XXXXXX)"
+          ./scripts/release/generate_release_notes.sh --old-version "$old_version" --new-version "$version" --ref "$ref" >> "$release_notes_file"
+          echo CODER_RELEASE_NOTES_FILE="$release_notes_file" >> $GITHUB_ENV
+
+      - name: Show release notes
+        run: |
+          set -euo pipefail
+          cat "$CODER_RELEASE_NOTES_FILE"
+
       - name: Docker Login
         uses: docker/login-action@v2
         with:
@@ -50,9 +90,9 @@ jobs:
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
-      - uses: actions/setup-go@v3
+      - uses: actions/setup-go@v4
         with:
-          go-version: "~1.19"
+          go-version: "~1.20"
 
       - name: Cache Node
         id: cache-node
@@ -65,24 +105,25 @@ jobs:
           restore-keys: |
             js-${{ runner.os }}-
 
+      - name: Install nsis and zstd
+        run: sudo apt-get install -y nsis zstd
+
       - name: Install nfpm
         run: |
           set -euo pipefail
           wget -O /tmp/nfpm.deb https://github.com/goreleaser/nfpm/releases/download/v2.18.1/nfpm_amd64.deb
           sudo dpkg -i /tmp/nfpm.deb
-      - name: Install zstd
-        run: sudo apt-get install -y zstd
+          rm /tmp/nfpm.deb
 
       - name: Install rcodesign
         run: |
           set -euo pipefail
-
-          # Install a prebuilt binary of rcodesign for linux amd64. Once the
-          # following PR is merged and released upstream, we can download
-          # directly from GitHub releases instead:
-          #   https://github.com/indygreg/PyOxidizer/pull/635
-          wget -O /tmp/rcodesign https://cdn.discordapp.com/attachments/283356472258199552/1016767245717872700/rcodesign
-          sudo install --mode 755 /tmp/rcodesign /usr/local/bin/rcodesign
+          wget -O /tmp/rcodesign.tar.gz https://github.com/indygreg/apple-platform-rs/releases/download/apple-codesign%2F0.22.0/apple-codesign-0.22.0-x86_64-unknown-linux-musl.tar.gz
+          sudo tar -xzf /tmp/rcodesign.tar.gz \
+            -C /usr/bin \
+            --strip-components=1 \
+            apple-codesign-0.22.0-x86_64-unknown-linux-musl/rcodesign
+          rm /tmp/rcodesign.tar.gz
 
       - name: Setup Apple Developer certificate and API key
         run: |
@@ -107,6 +148,7 @@ jobs:
           make -j \
             build/coder_"$version"_linux_{amd64,armv7,arm64}.{tar.gz,apk,deb,rpm} \
             build/coder_"$version"_{darwin,windows}_{amd64,arm64}.zip \
+            build/coder_"$version"_windows_amd64_installer.exe \
             build/coder_helm_"$version".tgz
         env:
           CODER_SIGN_DARWIN: "1"
@@ -119,6 +161,69 @@ jobs:
       - name: Delete Apple Developer certificate and API key
         run: rm -f /tmp/{apple_cert.p12,apple_cert_password.txt,apple_apikey.p8}
 
+      - name: Determine base image tag
+        id: image-base-tag
+        run: |
+          set -euo pipefail
+          if [[ "${CODER_RELEASE:-}" != *t* ]] || [[ "${CODER_DRY_RUN:-}" == *t* ]]; then
+            # Empty value means use the default and avoid building a fresh one.
+            echo "tag=" >> $GITHUB_OUTPUT
+          else
+            echo "tag=$(CODER_IMAGE_BASE=ghcr.io/coder/coder-base ./scripts/image_tag.sh)" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Create empty base-build-context directory
+        if: steps.image-base-tag.outputs.tag != ''
+        run: mkdir base-build-context
+
+      - name: Install depot.dev CLI
+        if: steps.image-base-tag.outputs.tag != ''
+        uses: depot/setup-action@v1
+
+      # This uses OIDC authentication, so no auth variables are required.
+      - name: Build base Docker image via depot.dev
+        if: steps.image-base-tag.outputs.tag != ''
+        uses: depot/build-push-action@v1
+        with:
+          project: wl5hnrrkns
+          context: base-build-context
+          file: scripts/Dockerfile.base
+          platforms: linux/amd64,linux/arm64,linux/arm/v7
+          pull: true
+          no-cache: true
+          push: true
+          tags: |
+            ${{ steps.image-base-tag.outputs.tag }}
+
+      - name: Verify that images are pushed properly
+        run: |
+          # retry 10 times with a 5 second delay as the images may not be
+          # available immediately
+          for i in {1..10}; do
+            rc=0
+            raw_manifests=$(docker buildx imagetools inspect --raw "${{ steps.image-base-tag.outputs.tag }}") || rc=$?
+            if [[ "$rc" -eq 0 ]]; then
+              break
+            fi
+            if [[ "$i" -eq 10 ]]; then
+              echo "Failed to pull manifests after 10 retries"
+              exit 1
+            fi
+            echo "Failed to pull manifests, retrying in 5 seconds"
+            sleep 5
+          done
+
+          manifests=$(
+            echo "$raw_manifests" | \
+              jq -r '.manifests[].platform | .os + "/" + .architecture + (if .variant then "/" + .variant else "" end)'
+          )
+
+          # Verify all 3 platforms are present.
+          set -euxo pipefail
+          echo "$manifests" | grep -q linux/amd64
+          echo "$manifests" | grep -q linux/arm64
+          echo "$manifests" | grep -q linux/arm/v7
+
       - name: Build Linux Docker images
         run: |
           set -euxo pipefail
@@ -147,14 +252,26 @@ jobs:
               --target "$(./scripts/image_tag.sh --version latest)" \
               $(cat build/coder_"$version"_linux_{amd64,arm64,armv7}.tag)
           fi
+        env:
+          CODER_BASE_IMAGE_TAG: ${{ steps.image-base-tag.outputs.tag }}
 
       - name: ls build
         run: ls -lh build
 
       - name: Publish release
         run: |
-          ./scripts/publish_release.sh \
-            ${{ (github.event.inputs.dry_run || github.event.inputs.snapshot) && '--dry-run' }} \
+          set -euo pipefail
+
+          publish_args=()
+          if [[ $CODER_DRY_RUN == *t* ]]; then
+            publish_args+=(--dry-run)
+          fi
+          declare -p publish_args
+
+          ./scripts/release/publish.sh \
+            "${publish_args[@]}" \
+            --release-notes-file "$CODER_RELEASE_NOTES_FILE" \
+            ./build/*_installer.exe \
             ./build/*.zip \
             ./build/*.tar.gz \
             ./build/*.tgz \
@@ -163,13 +280,37 @@ jobs:
             ./build/*.rpm
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          CODER_GPG_RELEASE_KEY_BASE64: ${{ secrets.GPG_RELEASE_KEY_BASE64 }}
 
-      - name: Upload artifacts to actions (if dry-run or snapshot)
-        if: ${{ github.event.inputs.dry_run || github.event.inputs.snapshot }}
-        uses: actions/upload-artifact@v2
+      - name: Authenticate to Google Cloud
+        uses: google-github-actions/auth@v1
+        with:
+          workload_identity_provider: ${{ secrets.GCP_WORKLOAD_ID_PROVIDER }}
+          service_account: ${{ secrets.GCP_SERVICE_ACCOUNT }}
+
+      - name: Setup GCloud SDK
+        uses: "google-github-actions/setup-gcloud@v1"
+
+      - name: Publish Helm Chart
+        if: ${{ !inputs.dry_run }}
+        run: |
+          set -euo pipefail
+          version="$(./scripts/version.sh)"
+          mkdir -p build/helm
+          cp "build/coder_helm_${version}.tgz" build/helm
+          gsutil cp gs://helm.coder.com/v2/index.yaml build/helm/index.yaml
+          helm repo index build/helm --url https://helm.coder.com/v2 --merge build/helm/index.yaml
+          gsutil -h "Cache-Control:no-cache,max-age=0" cp build/helm/coder_helm_${version}.tgz gs://helm.coder.com/v2
+          gsutil -h "Cache-Control:no-cache,max-age=0" cp build/helm/index.yaml gs://helm.coder.com/v2
+          gsutil -h "Cache-Control:no-cache,max-age=0" cp helm/artifacthub-repo.yml gs://helm.coder.com/v2
+
+      - name: Upload artifacts to actions (if dry-run)
+        if: ${{ inputs.dry_run }}
+        uses: actions/upload-artifact@v3
         with:
           name: release-artifacts
           path: |
+            ./build/*_installer.exe
             ./build/*.zip
             ./build/*.tar.gz
             ./build/*.tgz
@@ -177,3 +318,94 @@ jobs:
             ./build/*.deb
             ./build/*.rpm
           retention-days: 7
+
+      - name: Start Packer builds
+        if: ${{ !inputs.dry_run }}
+        uses: peter-evans/repository-dispatch@v2
+        with:
+          token: ${{ secrets.CDRCI_GITHUB_TOKEN }}
+          repository: coder/packages
+          event-type: coder-release
+          client-payload: '{"coder_version": "${{ steps.version.outputs.version }}"}'
+
+  publish-winget:
+    name: Publish to winget-pkgs
+    runs-on: windows-latest
+    needs: release
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+
+      # If the event that triggered the build was an annotated tag (which our
+      # tags are supposed to be), actions/checkout has a bug where the tag in
+      # question is only a lightweight tag and not a full annotated tag. This
+      # command seems to fix it.
+      # https://github.com/actions/checkout/issues/290
+      - name: Fetch git tags
+        run: git fetch --tags --force
+
+      - name: Install wingetcreate
+        run: |
+          Invoke-WebRequest https://aka.ms/wingetcreate/latest -OutFile wingetcreate.exe
+
+      - name: Submit updated manifest to winget-pkgs
+        run: |
+          # The package version is the same as the tag minus the leading "v".
+          # The version in this output already has the leading "v" removed but
+          # we do it again to be safe.
+          $version = "${{ needs.release.outputs.version }}".Trim('v')
+
+          $release_assets = gh release view --repo coder/coder "v${version}" --json assets | `
+            ConvertFrom-Json
+          # Get the installer URL from the release assets.
+          $installer_url = $release_assets.assets | `
+            Where-Object name -Match ".*_windows_amd64_installer.exe$" | `
+            Select -ExpandProperty url
+
+          echo "Installer URL: ${installer_url}"
+          echo "Package version: ${version}"
+
+          # Bail if dry-run.
+          if ($env:CODER_DRY_RUN -match "t") {
+            echo "Skipping submission due to dry-run."
+            exit 0
+          }
+
+          # The URL "|X64" suffix forces the architecture as it cannot be
+          # sniffed properly from the URL. wingetcreate checks both the URL and
+          # binary magic bytes for the architecture and they need to both match,
+          # but they only check for `x64`, `win64` and `_64` in the URL. Our URL
+          # contains `amd64` which doesn't match sadly.
+          #
+          # wingetcreate will still do the binary magic bytes check, so if we
+          # accidentally change the architecture of the installer, it will fail
+          # submission.
+          .\wingetcreate.exe update Coder.Coder `
+            --submit `
+            --version "${version}" `
+            --urls "${installer_url}|X64" `
+            --token "$env:WINGET_GH_TOKEN"
+
+        env:
+          # For gh CLI:
+          GH_TOKEN: ${{ github.token }}
+          # For wingetcreate. We need a real token since we're pushing a commit
+          # to GitHub and then making a PR in a different repo.
+          WINGET_GH_TOKEN: ${{ secrets.CDRCI_GITHUB_TOKEN }}
+
+      - name: Comment on PR
+        if: ${{ !inputs.dry_run }}
+        run: |
+          # Find the PR that wingetcreate just made.
+          $version = "${{ needs.release.outputs.version }}".Trim('v')
+          $pr_list = gh pr list --repo microsoft/winget-pkgs --search "author:cdrci Coder.Coder version ${version}" --limit 1 --json number | `
+            ConvertFrom-Json
+          $pr_number = $pr_list[0].number
+
+          gh pr comment --repo microsoft/winget-pkgs "${pr_number}" --body "🤖 cc: @deansheather @matifali"
+
+        env:
+          # For gh CLI. We need a real token since we're commenting on a PR in a
+          # different repo.
+          GH_TOKEN: ${{ secrets.CDRCI_GITHUB_TOKEN }}

.github/workflows/security.yaml

@@ -0,0 +1,172 @@
+name: "security"
+
+permissions:
+  actions: read
+  contents: read
+  security-events: write
+
+on:
+  workflow_dispatch:
+
+  schedule:
+    # Run every 6 hours Monday-Friday!
+    - cron: "0 0,6,12,18 * * 1-5"
+
+# Cancel in-progress runs for pull requests when developers push
+# additional changes
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}-security
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  codeql:
+    runs-on: ${{ github.repository_owner == 'coder' && 'ubuntu-latest-8-cores' || 'ubuntu-latest' }}
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v2
+        with:
+          languages: go, javascript
+
+      - name: Setup Go
+        uses: actions/setup-go@v4
+        with:
+          go-version: "~1.20"
+
+      - name: Go Cache Paths
+        id: go-cache-paths
+        run: |
+          echo "GOMODCACHE=$(go env GOMODCACHE)" >> $GITHUB_OUTPUT
+
+      - name: Go Mod Cache
+        uses: actions/cache@v3
+        with:
+          path: ${{ steps.go-cache-paths.outputs.GOMODCACHE }}
+          key: ${{ runner.os }}-release-go-mod-${{ hashFiles('**/go.sum') }}
+
+      # Workaround to prevent CodeQL from building the dashboard.
+      - name: Remove Makefile
+        run: |
+          rm Makefile
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v2
+
+      - name: Send Slack notification on failure
+        if: ${{ failure() }}
+        run: |
+          msg="❌ CodeQL Failed\n\nhttps://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}"
+          curl \
+            -qfsSL \
+            -X POST \
+            -H "Content-Type: application/json" \
+            --data "{\"content\": \"$msg\"}" \
+            "${{ secrets.SLACK_SECURITY_FAILURE_WEBHOOK_URL }}"
+
+  trivy:
+    runs-on: ${{ github.repository_owner == 'coder' && 'ubuntu-latest-8-cores' || 'ubuntu-latest' }}
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-go@v4
+        with:
+          go-version: "~1.20"
+
+      - name: Go Cache Paths
+        id: go-cache-paths
+        run: |
+          echo "GOMODCACHE=$(go env GOMODCACHE)" >> $GITHUB_OUTPUT
+
+      - name: Go Mod Cache
+        uses: actions/cache@v3
+        with:
+          path: ${{ steps.go-cache-paths.outputs.GOMODCACHE }}
+          key: ${{ runner.os }}-release-go-mod-${{ hashFiles('**/go.sum') }}
+
+      - name: Cache Node
+        id: cache-node
+        uses: actions/cache@v3
+        with:
+          path: |
+            **/node_modules
+            .eslintcache
+          key: js-${{ runner.os }}-test-${{ hashFiles('**/yarn.lock') }}
+          restore-keys: |
+            js-${{ runner.os }}-
+
+      - name: Install sqlc
+        run: |
+          curl -sSL https://github.com/kyleconroy/sqlc/releases/download/v1.17.2/sqlc_1.17.2_linux_amd64.tar.gz | sudo tar -C /usr/bin -xz sqlc
+      - name: Install yq
+        run: go run github.com/mikefarah/yq/v4@v4.30.6
+      - name: Install protoc-gen-go
+        run: go install google.golang.org/protobuf/cmd/protoc-gen-go@v1.26
+      - name: Install protoc-gen-go-drpc
+        run: go install storj.io/drpc/cmd/protoc-gen-go-drpc@v0.0.26
+      - name: Install Protoc
+        run: |
+          # protoc must be in lockstep with our dogfood Dockerfile or the
+          # version in the comments will differ. This is also defined in
+          # ci.yaml.
+          set -x
+          cd dogfood
+          DOCKER_BUILDKIT=1 docker build . --target proto -t protoc
+          protoc_path=/usr/local/bin/protoc
+          docker run --rm --entrypoint cat protoc /tmp/bin/protoc > $protoc_path
+          chmod +x $protoc_path
+          protoc --version
+
+      - name: Build Coder linux amd64 Docker image
+        id: build
+        run: |
+          set -euo pipefail
+
+          version="$(./scripts/version.sh)"
+          image_job="build/coder_${version}_linux_amd64.tag"
+
+          # This environment variable force make to not build packages and
+          # archives (which the Docker image depends on due to technical reasons
+          # related to concurrent FS writes).
+          export DOCKER_IMAGE_NO_PREREQUISITES=true
+          # This environment variables forces scripts/build_docker.sh to build
+          # the base image tag locally instead of using the cached version from
+          # the registry.
+          export CODER_IMAGE_BUILD_BASE_TAG="$(CODER_IMAGE_BASE=coder-base ./scripts/image_tag.sh --version "$version")"
+
+          make -j "$image_job"
+          echo "image=$(cat "$image_job")" >> $GITHUB_OUTPUT
+
+      - name: Run Trivy vulnerability scanner
+        uses: aquasecurity/trivy-action@e5f43133f6e8736992c9f3c1b3296e24b37e17f2
+        with:
+          image-ref: ${{ steps.build.outputs.image }}
+          format: sarif
+          output: trivy-results.sarif
+          severity: "CRITICAL,HIGH"
+
+      - name: Upload Trivy scan results to GitHub Security tab
+        uses: github/codeql-action/upload-sarif@v2
+        with:
+          sarif_file: trivy-results.sarif
+          category: "Trivy"
+
+      - name: Upload Trivy scan results as an artifact
+        uses: actions/upload-artifact@v3
+        with:
+          name: trivy
+          path: trivy-results.sarif
+          retention-days: 7
+
+      - name: Send Slack notification on failure
+        if: ${{ failure() }}
+        run: |
+          msg="❌ Trivy Failed\n\nhttps://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}"
+          curl \
+            -qfsSL \
+            -X POST \
+            -H "Content-Type: application/json" \
+            --data "{\"content\": \"$msg\"}" \
+            "${{ secrets.SLACK_SECURITY_FAILURE_WEBHOOK_URL }}"

.github/workflows/stale.yaml

@@ -1,35 +1,48 @@
-name: Stale Issue Cron
+name: Stale Issue and Branch Cleanup
 on:
   schedule:
     # Every day at midnight
     - cron: "0 0 * * *"
   workflow_dispatch:
 jobs:
-  stale:
+  issues:
     runs-on: ubuntu-latest
     permissions:
       issues: write
       pull-requests: write
     steps:
-      # v5.1.0 has a weird bug that makes stalebot add then remove its own label
-      # https://github.com/actions/stale/pull/775
-      - uses: actions/stale@v6.0.0
+      - uses: actions/stale@v8.0.0
         with:
-          stale-issue-label: stale
-          stale-pr-label: stale
+          stale-issue-label: "stale"
+          stale-pr-label: "stale"
+          days-before-stale: 90
           # Pull Requests become stale more quickly due to merge conflicts.
           # Also, we promote minimizing WIP.
           days-before-pr-stale: 7
           days-before-pr-close: 3
           stale-pr-message: >
-            This Pull Request is becoming stale. In order to minimize WIP, 
+            This Pull Request is becoming stale. In order to minimize WIP,
             prevent merge conflicts and keep the tracker readable, I'm going
             close to this PR in 3 days if there isn't more activity.
           stale-issue-message: >
             This issue is becoming stale. In order to keep the tracker readable
-            and actionable, I'm going close to this issue in 7 days if there 
+            and actionable, I'm going close to this issue in 7 days if there
             isn't more activity.
           # Upped from 30 since we have a big tracker and was hitting the limit.
           operations-per-run: 60
           # Start with the oldest issues, always.
           ascending: true
+  branches:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v2
+      - name: Run delete-old-branches-action
+        uses: beatlabs/delete-old-branches-action@v0.0.10
+        with:
+          repo_token: ${{ github.token }}
+          date: "6 months ago"
+          dry_run: false
+          delete_tags: false
+          # extra_protected_branch_regex: ^(foo|bar)$
+          exclude_open_pr_branches: true

.github/workflows/typos.toml

@@ -3,8 +3,16 @@ alog = "alog"
 Jetbrains = "JetBrains"
 IST = "IST"
 MacOS = "macOS"
+AKS = "AKS"
 
 [default.extend-words]
+AKS = "AKS"
+# do as sudo replacement
+doas = "doas"
+darcula = "darcula"
+Hashi = "Hashi"
+trialer = "trialer"
+encrypter = "encrypter"
 
 [files]
 extend-exclude = [
@@ -16,4 +24,5 @@ extend-exclude = [
     # These files contain base64 strings that confuse the detector
     "**XService**.ts",
     "**identity.go",
+    "scripts/ci-report/testdata/**",
 ]

.github/workflows/welcome.yaml

@@ -1,18 +0,0 @@
-name: Welcome
-on:
-  pull_request:
-    types: [opened]
-jobs:
-  test:
-    runs-on: ubuntu-latest
-    permissions:
-      pull-requests: write
-    steps:
-      - uses: wow-actions/welcome@v1
-        with:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          FIRST_PR_REACTIONS: '+1, hooray, rocket, heart'
-          FIRST_PR_COMMENT: |
-            👋 Welcome @{{ author }} to Coder! Yo @coder/docs this is @{{ author }}'s first pull-request here! 
-          FIRST_PR_MERGED: |
-            🎉 Thanks for the contribution @{{ author }}! Yo @coder/docs @{{ author }}'s first contribution has been merged! 👀👀👀

.gitignore

@@ -1,48 +1,61 @@
-###############################################################################
-#                                 NOTICE                                      #
-# If you change this file, kindly copy-pasta your change into .prettierignore #
-# and .eslintignore as well. See the following discussions to understand why  #
-# we have to resort to this duplication (at least for now):                   #
-#                                                                             #
-# https://github.com/prettier/prettier/issues/8048                            #
-# https://github.com/prettier/prettier/issues/8506                            #
-# https://github.com/prettier/prettier/issues/8679                            #
-###############################################################################
-
-node_modules
-vendor
-.eslintcache
-yarn-error.log
-gotests.coverage
-.idea
-.gitpod.yml
+# Common ignore patterns, these rules applies in both root and subdirectories.
 .DS_Store
+.eslintcache
+.gitpod.yml
+.idea
+**/*.swp
+gotests.coverage
+gotests.xml
+gotests_stats.json
+gotests.json
+node_modules/
+vendor/
+yarn-error.log
 
-# Front-end ignore
+# VSCode settings.
+**/.vscode/*
+# Allow VSCode recommendations and default settings in project root.
+!/.vscode/extensions.json
+!/.vscode/settings.json
+
+# Front-end ignore patterns.
 .next/
-site/.eslintcache
-site/.next/
-site/node_modules/
-site/storybook-static/
-site/test-results/
-site/yarn-error.log
-coverage/
 site/**/*.typegen.ts
 site/build-storybook.log
+site/coverage/
+site/storybook-static/
+site/test-results/*
+site/e2e/test-results/*
+site/e2e/states/*.json
+site/playwright-report/*
+site/.swc
+site/dist/
+
+# Make target for updating golden files (any dir).
+.gen-golden
 
 # Build
 /build/
 /dist/
 site/out/
 
+# Bundle analysis
+site/stats/
+
 *.tfstate
 *.tfstate.backup
 *.tfplan
 *.lock.hcl
 .terraform/
 
-.vscode/*.log
-.vscode/launch.json
-**/*.swp
-.coderv2/*
+**/.coderv2/*
 **/__debug_bin
+
+# direnv
+.envrc
+*.test
+
+# Loadtesting
+./scaletest/terraform/.terraform
+./scaletest/terraform/.terraform.lock.hcl
+terraform.tfstate.*

.golangci.yaml

@@ -103,7 +103,7 @@ linters-settings:
     settings:
       ruleguard:
         failOn: all
-        rules: '${configDir}/scripts/rules.go'
+        rules: "${configDir}/scripts/rules.go"
 
   staticcheck:
     # https://staticcheck.io/docs/options#checks
@@ -123,6 +123,8 @@ linters-settings:
 
   misspell:
     locale: US
+    ignore-words:
+      - trialer
 
   nestif:
     min-complexity: 4 # Min complexity of if statements (def 5, goal 4)
@@ -192,6 +194,7 @@ issues:
       linters:
         # We use assertions rather than explicitly checking errors in tests
         - errcheck
+        - forcetypeassert
 
   fix: true
   max-issues-per-linter: 0
@@ -213,7 +216,6 @@ linters:
     - asciicheck
     - bidichk
     - bodyclose
-    - deadcode
     - dogsled
     - errcheck
     - errname
@@ -235,10 +237,15 @@ linters:
     - noctx
     - paralleltest
     - revive
-    - rowserrcheck
-    - sqlclosecheck
+
+    # These don't work until the following issue is solved.
+    # https://github.com/golangci/golangci-lint/issues/2649
+    # - rowserrcheck
+    # - sqlclosecheck
+    # - structcheck
+    # - wastedassign
+
     - staticcheck
-    - structcheck
     - tenv
     # In Go, it's possible for a package to test it's internal functionality
     # without testing any exported functions. This is enabled to promote
@@ -252,5 +259,3 @@ linters:
     - typecheck
     - unconvert
     - unused
-    - varcheck
-    - wastedassign

.prettierignore

@@ -0,0 +1,75 @@
+# Code generated by Makefile (.gitignore .prettierignore.include). DO NOT EDIT.
+
+# .gitignore:
+# Common ignore patterns, these rules applies in both root and subdirectories.
+.DS_Store
+.eslintcache
+.gitpod.yml
+.idea
+**/*.swp
+gotests.coverage
+gotests.xml
+gotests_stats.json
+gotests.json
+node_modules/
+vendor/
+yarn-error.log
+
+# VSCode settings.
+**/.vscode/*
+# Allow VSCode recommendations and default settings in project root.
+!/.vscode/extensions.json
+!/.vscode/settings.json
+
+# Front-end ignore patterns.
+.next/
+site/**/*.typegen.ts
+site/build-storybook.log
+site/coverage/
+site/storybook-static/
+site/test-results/*
+site/e2e/test-results/*
+site/e2e/states/*.json
+site/playwright-report/*
+site/.swc
+site/dist/
+
+# Make target for updating golden files (any dir).
+.gen-golden
+
+# Build
+/build/
+/dist/
+site/out/
+
+# Bundle analysis
+site/stats/
+
+*.tfstate
+*.tfstate.backup
+*.tfplan
+*.lock.hcl
+.terraform/
+
+**/.coderv2/*
+**/__debug_bin
+
+# direnv
+.envrc
+*.test
+
+# Loadtesting
+./scaletest/terraform/.terraform
+./scaletest/terraform/.terraform.lock.hcl
+terraform.tfstate.*
+# .prettierignore.include:
+# Helm templates contain variables that are invalid YAML and can't be formatted
+# by Prettier.
+helm/templates/*.yaml
+
+# Terraform state files used in tests, these are automatically generated.
+# Example: provisioner/terraform/testdata/instance-id/instance-id.tfstate.json
+**/testdata/**/*.tf*.json
+
+# Testdata shouldn't be formatted.
+scripts/apitypings/testdata/**/*.ts

.prettierignore.include

@@ -0,0 +1,10 @@
+# Helm templates contain variables that are invalid YAML and can't be formatted
+# by Prettier.
+helm/templates/*.yaml
+
+# Terraform state files used in tests, these are automatically generated.
+# Example: provisioner/terraform/testdata/instance-id/instance-id.tfstate.json
+**/testdata/**/*.tf*.json
+
+# Testdata shouldn't be formatted.
+scripts/apitypings/testdata/**/*.ts

.prettierrc.yaml

@@ -0,0 +1,16 @@
+# This config file is used in conjunction with `.editorconfig` to specify
+# formatting for prettier-supported files. See `.editorconfig` and
+# `site/.editorconfig`for whitespace formatting options.
+printWidth: 80
+semi: false
+trailingComma: all
+overrides:
+  - files:
+      - README.md
+    options:
+      proseWrap: preserve
+  - files:
+      - "site/**/*.yaml"
+      - "site/**/*.yml"
+    options:
+      proseWrap: always

.swaggo

@@ -0,0 +1,8 @@
+// Replace all NullTime with string
+replace github.com/coder/coder/codersdk.NullTime string
+// Prevent swaggo from rendering enums for time.Duration
+replace time.Duration int64
+// Do not expose "echo" provider
+replace github.com/coder/coder/codersdk.ProvisionerType string
+// Do not render netip.Addr
+replace netip.Addr string

.vscode/extensions.json

@@ -1,5 +1,6 @@
 {
   "recommendations": [
+    "github.vscode-codeql",
     "golang.go",
     "hashicorp.terraform",
     "esbenp.prettier-vscode",

.vscode/settings.json

@@ -1,6 +1,11 @@
 {
   "cSpell.words": [
+    "afero",
+    "agentsdk",
     "apps",
+    "ASKPASS",
+    "authcheck",
+    "autostop",
     "awsidentity",
     "bodyclose",
     "buildinfo",
@@ -15,18 +20,29 @@
     "codersdk",
     "cronstrue",
     "databasefake",
+    "dbfake",
+    "dbgen",
+    "dbtype",
     "DERP",
     "derphttp",
     "derpmap",
     "devel",
+    "devtunnel",
+    "dflags",
     "drpc",
     "drpcconn",
     "drpcmux",
     "drpcserver",
     "Dsts",
+    "embeddedpostgres",
     "enablements",
+    "enterprisemeta",
+    "errgroup",
+    "eventsourcemock",
+    "Failf",
     "fatih",
     "Formik",
+    "gitauth",
     "gitsshkey",
     "goarch",
     "gographviz",
@@ -76,32 +92,38 @@
     "parameterscopeid",
     "pqtype",
     "prometheusmetrics",
-    "promptui",
+    "promhttp",
     "protobuf",
     "provisionerd",
+    "provisionerdserver",
     "provisionersdk",
     "ptty",
     "ptys",
     "ptytest",
     "quickstart",
     "reconfig",
+    "replicasync",
     "retrier",
     "rpty",
+    "SCIM",
     "sdkproto",
     "sdktrace",
     "Signup",
     "slogtest",
     "sourcemapped",
     "Srcs",
+    "stdbuf",
     "stretchr",
     "STTY",
     "stuntest",
+    "tanstack",
     "tailbroker",
     "tailcfg",
     "tailexchange",
     "tailnet",
     "tailnettest",
     "Tailscale",
+    "tbody",
     "TCGETS",
     "tcpip",
     "TCSETS",
@@ -113,8 +135,12 @@
     "tfjson",
     "tfplan",
     "tfstate",
+    "thead",
     "tios",
+    "tmpdir",
+    "tokenconfig",
     "tparallel",
+    "trialer",
     "trimprefix",
     "tsdial",
     "tslogger",
@@ -146,10 +172,7 @@
     "xstate",
     "yamux"
   ],
-  "cSpell.ignorePaths": [
-    "site/package.json",
-    ".vscode/settings.json"
-  ],
+  "cSpell.ignorePaths": ["site/package.json", ".vscode/settings.json"],
   "emeraldwalk.runonsave": {
     "commands": [
       {
@@ -166,6 +189,10 @@
   "files.exclude": {
     "**/node_modules": true
   },
+  "search.exclude": {
+    "scripts/metricsdocgen/metrics": true,
+    "docs/api/*.md": true
+  },
   // Ensure files always have a newline.
   "files.insertFinalNewline": true,
   "go.lintTool": "golangci-lint",
@@ -181,11 +208,15 @@
   // To reduce redundancy in tests, it's covered by other packages.
   // Since package coverage pairing can't be defined, all packages cover
   // all other packages.
-  "go.testFlags": [
-    "-short",
-    "-coverpkg=./..."
-  ],
+  "go.testFlags": ["-short", "-coverpkg=./..."],
   // We often use a version of TypeScript that's ahead of the version shipped
   // with VS Code.
-  "typescript.tsdk": "./site/node_modules/typescript/lib"
+  "typescript.tsdk": "./site/node_modules/typescript/lib",
+  "grammarly.selectors": [
+    {
+      "language": "markdown",
+      "scheme": "file",
+      "pattern": "docs/contributing/frontend.md"
+    }
+  ]
 }

ADOPTERS.md

@@ -1,12 +0,0 @@
-# Adopters 
-[!["Join us on
-Discord"](https://img.shields.io/badge/join-us%20on%20Discord-gray.svg?longCache=true&logo=discord&colorB=green)](https://coder.com/chat?utm_source=github.com/coder/coder&utm_medium=github&utm_campaign=adopters.md) [![Twitter
-Follow](https://img.shields.io/twitter/follow/coderhq?label=%40coderhq&style=social)](https://twitter.com/coderhq)
-
-🦩 _If you're using Coder in your organization, please try to add your company name to this list. It really helps the project to gain momentum and credibility. It's a small contribution back to the project with a big impact. You can do this by by editing this file and contributing your changes via a pull-request on GitHub._
-
-> 👋 _If you are considering using Coder in your organization please introduce yourself via https://coder.com/demo_ 🙇🏻‍♂️
-
-| Organization                                                                | Contact                                                                                                                                                                                                                                                          | Description of Use                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [Coder](https://www.coder.com)                                              | [@coderhq](https://twitter.com/coderhq)                                                                                                                                                                                                                     | Coder builds coder with Coder.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |

Makefile

@@ -44,6 +44,18 @@ else
 ZSTDFLAGS := -6
 endif
 
+# Common paths to exclude from find commands, this rule is written so
+# that it can be it can be used in a chain of AND statements (meaning
+# you can simply write `find . $(FIND_EXCLUSIONS) -name thing-i-want`).
+# Note, all find statements should be written with `.` or `./path` as
+# the search path so that these exclusions match.
+FIND_EXCLUSIONS= \
+	-not \( \( -path '*/.git/*' -o -path './build/*' -o -path './vendor/*' -o -path './.coderv2/*' -o -path '*/node_modules/*' -o -path './site/out/*' \) -prune \)
+# Source files used for make targets, evaluated on use.
+GO_SRC_FILES = $(shell find . $(FIND_EXCLUSIONS) -type f -name '*.go')
+# All the shell files in the repo, excluding ignored files.
+SHELL_SRC_FILES = $(shell find . $(FIND_EXCLUSIONS) -type f -name '*.sh')
+
 # All ${OS}_${ARCH} combos we build for. Windows binaries have the .exe suffix.
 OS_ARCHES := \
 	linux_amd64 linux_arm64 linux_armv7 \
@@ -80,6 +92,19 @@ CODER_FAT_NOVERSION_BINARIES      := $(addprefix build/coder_,$(OS_ARCHES))
 CODER_ALL_NOVERSION_IMAGES        := $(foreach arch, $(DOCKER_ARCHES), build/coder_linux_$(arch).tag) build/coder_linux.tag
 CODER_ALL_NOVERSION_IMAGES_PUSHED := $(addprefix push/, $(CODER_ALL_NOVERSION_IMAGES))
 
+# If callers are only building Docker images and not the packages and archives,
+# we can skip those prerequisites as they are not actually required and only
+# specified to avoid concurrent write failures.
+ifdef DOCKER_IMAGE_NO_PREREQUISITES
+CODER_ARCH_IMAGE_PREREQUISITES :=
+else
+CODER_ARCH_IMAGE_PREREQUISITES := \
+	build/coder_$(VERSION)_%.apk \
+	build/coder_$(VERSION)_%.deb \
+	build/coder_$(VERSION)_%.rpm \
+	build/coder_$(VERSION)_%.tar.gz
+endif
+
 
 clean:
 	rm -rf build site/out
@@ -96,19 +121,26 @@ build-fat build-full build: $(CODER_FAT_BINARIES)
 release: $(CODER_FAT_BINARIES) $(CODER_ALL_ARCHIVES) $(CODER_ALL_PACKAGES) $(CODER_ARCH_IMAGES) build/coder_helm_$(VERSION).tgz
 .PHONY: release
 
-build/coder-slim_$(VERSION)_checksums.sha1 site/out/bin/coder.sha1: $(CODER_SLIM_BINARIES)
+build/coder-slim_$(VERSION)_checksums.sha1: site/out/bin/coder.sha1
+	cp "$<" "$@"
+
+site/out/bin/coder.sha1: $(CODER_SLIM_BINARIES)
 	pushd ./site/out/bin
 		openssl dgst -r -sha1 coder-* | tee coder.sha1
 	popd
 
-	cp "site/out/bin/coder.sha1" "build/coder-slim_$(VERSION)_checksums.sha1"
-
 build/coder-slim_$(VERSION).tar: build/coder-slim_$(VERSION)_checksums.sha1 $(CODER_SLIM_BINARIES)
 	pushd ./site/out/bin
 		tar cf "../../../build/$(@F)" coder-*
 	popd
 
-build/coder-slim_$(VERSION).tar.zst site/out/bin/coder.tar.zst: build/coder-slim_$(VERSION).tar
+	# delete the uncompressed binaries from the embedded dir
+	rm -f site/out/bin/coder-*
+
+site/out/bin/coder.tar.zst: build/coder-slim_$(VERSION).tar.zst
+	cp "$<" "$@"
+
+build/coder-slim_$(VERSION).tar.zst: build/coder-slim_$(VERSION).tar
 	zstd $(ZSTDFLAGS) \
 		--force \
 		--long \
@@ -116,10 +148,6 @@ build/coder-slim_$(VERSION).tar.zst site/out/bin/coder.tar.zst: build/coder-slim
 		-o "build/coder-slim_$(VERSION).tar.zst" \
 		"build/coder-slim_$(VERSION).tar"
 
-	cp "build/coder-slim_$(VERSION).tar.zst" "site/out/bin/coder.tar.zst"
-	# delete the uncompressed binaries from the embedded dir
-	rm site/out/bin/coder-*
-
 # Redirect from version-less targets to the versioned ones. There is a similar
 # target for slim binaries below.
 #
@@ -171,7 +199,7 @@ endef
 # You should probably use the non-version targets above instead if you're
 # calling this manually.
 $(CODER_ALL_BINARIES): go.mod go.sum \
-	$(shell find . -not -path './vendor/*' -type f -name '*.go') \
+	$(GO_SRC_FILES) \
 	$(shell find ./examples/templates)
 
 	$(get-mode-os-arch-ext)
@@ -252,6 +280,13 @@ $(CODER_ALL_PACKAGES): $(CODER_PACKAGE_DEPS)
 		--output "$@" \
 		"build/coder_$(VERSION)_$${os}_$${arch}"
 
+# This task builds a Windows amd64 installer. Depends on makensis.
+build/coder_$(VERSION)_windows_amd64_installer.exe: build/coder_$(VERSION)_windows_amd64.exe
+	./scripts/build_windows_installer.sh \
+		--version "$(VERSION)" \
+		--output "$@" \
+		"$<"
+
 # Redirect from version-less Docker image targets to the versioned ones.
 #
 # Called like this:
@@ -274,13 +309,7 @@ $(CODER_ALL_NOVERSION_IMAGES_PUSHED): push/build/coder_%: push/build/coder_$(VER
 #
 # Images need to run after the archives and packages are built, otherwise they
 # cause errors like "file changed as we read it".
-$(CODER_ARCH_IMAGES): build/coder_$(VERSION)_%.tag: \
-	build/coder_$(VERSION)_% \
-	build/coder_$(VERSION)_%.apk \
-	build/coder_$(VERSION)_%.deb \
-	build/coder_$(VERSION)_%.rpm \
-	build/coder_$(VERSION)_%.tar.gz
-
+$(CODER_ARCH_IMAGES): build/coder_$(VERSION)_%.tag: build/coder_$(VERSION)_% $(CODER_ARCH_IMAGE_PREREQUISITES)
 	$(get-mode-os-arch-ext)
 
 	image_tag="$$(./scripts/image_tag.sh --arch "$$arch" --version "$(VERSION)")"
@@ -326,7 +355,7 @@ build/coder_helm_$(VERSION).tgz:
 		--version "$(VERSION)" \
 		--output "$@"
 
-site/out/index.html: $(shell find ./site -not -path './site/node_modules/*' -type f -name '*.tsx') $(shell find ./site -not -path './site/node_modules/*' -type f -name '*.ts') site/package.json
+site/out/index.html: site/package.json $(shell find ./site $(FIND_EXCLUSIONS) -type f \( -name '*.ts' -o -name '*.tsx' \))
 	./scripts/yarn_install.sh
 	cd site
 	yarn build
@@ -339,9 +368,15 @@ install: build/coder_$(VERSION)_$(GOOS)_$(GOARCH)$(GOOS_BIN_EXT)
 	cp "$<" "$$output_file"
 .PHONY: install
 
-fmt: fmt/prettier fmt/terraform fmt/shfmt
+fmt: fmt/prettier fmt/terraform fmt/shfmt fmt/go
 .PHONY: fmt
 
+fmt/go:
+	# VS Code users should check out
+	# https://github.com/mvdan/gofumpt#visual-studio-code
+	go run mvdan.cc/gofumpt@v0.4.0 -w -l .
+.PHONY: fmt/go
+
 fmt/prettier:
 	echo "--- prettier"
 	cd site
@@ -357,13 +392,13 @@ fmt/terraform: $(wildcard *.tf)
 	terraform fmt -recursive
 .PHONY: fmt/terraform
 
-fmt/shfmt: $(shell shfmt -f .)
+fmt/shfmt: $(SHELL_SRC_FILES)
 	echo "--- shfmt"
 # Only do diff check in CI, errors on diff.
 ifdef CI
-	shfmt -d $(shell shfmt -f .)
+	shfmt -d $(SHELL_SRC_FILES)
 else
-	shfmt -w $(shell shfmt -f .)
+	shfmt -w $(SHELL_SRC_FILES)
 endif
 .PHONY: fmt/shfmt
 
@@ -376,9 +411,9 @@ lint/go:
 .PHONY: lint/go
 
 # Use shfmt to determine the shell files, takes editorconfig into consideration.
-lint/shellcheck: $(shell shfmt -f .)
+lint/shellcheck: $(SHELL_SRC_FILES)
 	echo "--- shellcheck"
-	shellcheck --external-sources $(shell shfmt -f .)
+	shellcheck --external-sources $(SHELL_SRC_FILES)
 .PHONY: lint/shellcheck
 
 # all gen targets should be added here and to gen/mark-fresh
@@ -387,13 +422,39 @@ gen: \
 	coderd/database/querier.go \
 	provisionersdk/proto/provisioner.pb.go \
 	provisionerd/proto/provisionerd.pb.go \
-	site/src/api/typesGenerated.ts
+	site/src/api/typesGenerated.ts \
+	coderd/rbac/object_gen.go \
+	docs/admin/prometheus.md \
+	docs/cli.md \
+	docs/admin/audit-logs.md \
+	coderd/apidoc/swagger.json \
+	.prettierignore.include \
+	.prettierignore \
+	site/.prettierrc.yaml \
+	site/.prettierignore \
+	site/.eslintignore
 .PHONY: gen
 
 # Mark all generated files as fresh so make thinks they're up-to-date. This is
 # used during releases so we don't run generation scripts.
 gen/mark-fresh:
-	files="coderd/database/dump.sql coderd/database/querier.go provisionersdk/proto/provisioner.pb.go provisionerd/proto/provisionerd.pb.go site/src/api/typesGenerated.ts"
+	files="\
+		coderd/database/dump.sql \
+		coderd/database/querier.go \
+		provisionersdk/proto/provisioner.pb.go \
+		provisionerd/proto/provisionerd.pb.go \
+		site/src/api/typesGenerated.ts \
+		coderd/rbac/object_gen.go \
+		docs/admin/prometheus.md \
+		docs/cli.md \
+		docs/admin/audit-logs.md \
+		coderd/apidoc/swagger.json \
+		.prettierignore.include \
+		.prettierignore \
+		site/.prettierrc.yaml \
+		site/.prettierignore \
+		site/.eslintignore \
+	"
 	for file in $$files; do
 		echo "$$file"
 		if [ ! -f "$$file" ]; then
@@ -431,22 +492,124 @@ provisionerd/proto/provisionerd.pb.go: provisionerd/proto/provisionerd.proto
 		--go-drpc_opt=paths=source_relative \
 		./provisionerd/proto/provisionerd.proto
 
-site/src/api/typesGenerated.ts: scripts/apitypings/main.go $(shell find codersdk -type f -name '*.go')
+site/src/api/typesGenerated.ts: scripts/apitypings/main.go $(shell find ./codersdk $(FIND_EXCLUSIONS) -type f -name '*.go')
 	go run scripts/apitypings/main.go > site/src/api/typesGenerated.ts
 	cd site
 	yarn run format:types
 
+coderd/rbac/object_gen.go: scripts/rbacgen/main.go coderd/rbac/object.go
+	go run scripts/rbacgen/main.go ./coderd/rbac > coderd/rbac/object_gen.go
+
+docs/admin/prometheus.md: scripts/metricsdocgen/main.go scripts/metricsdocgen/metrics
+	go run scripts/metricsdocgen/main.go
+	cd site
+	yarn run format:write:only ../docs/admin/prometheus.md
+
+docs/cli.md: scripts/clidocgen/main.go $(GO_SRC_FILES) docs/manifest.json
+	BASE_PATH="." go run ./scripts/clidocgen
+	cd site
+	yarn run format:write:only ../docs/cli.md ../docs/cli/*.md ../docs/manifest.json
+
+docs/admin/audit-logs.md: scripts/auditdocgen/main.go enterprise/audit/table.go coderd/rbac/object_gen.go
+	go run scripts/auditdocgen/main.go
+	cd site
+	yarn run format:write:only ../docs/admin/audit-logs.md
+
+coderd/apidoc/swagger.json: $(shell find ./scripts/apidocgen $(FIND_EXCLUSIONS) -type f) $(wildcard coderd/*.go) $(wildcard enterprise/coderd/*.go) $(wildcard codersdk/*.go) $(wildcard enterprise/wsproxy/wsproxysdk/*.go) coderd/database/querier.go .swaggo docs/manifest.json coderd/rbac/object_gen.go
+	./scripts/apidocgen/generate.sh
+	yarn run --cwd=site format:write:only ../docs/api ../docs/manifest.json ../coderd/apidoc/swagger.json
+
+update-golden-files: cli/testdata/.gen-golden helm/tests/testdata/.gen-golden scripts/ci-report/testdata/.gen-golden
+.PHONY: update-golden-files
+
+cli/testdata/.gen-golden: $(wildcard cli/testdata/*.golden) $(wildcard cli/*.tpl) $(GO_SRC_FILES)
+	go test ./cli -run="Test(CommandHelp|ServerYAML)" -update
+	touch "$@"
+
+helm/tests/testdata/.gen-golden: $(wildcard helm/tests/testdata/*.yaml) $(wildcard helm/tests/testdata/*.golden) $(GO_SRC_FILES)
+	go test ./helm/tests -run=TestUpdateGoldenFiles -update
+	touch "$@"
+
+scripts/ci-report/testdata/.gen-golden: $(wildcard scripts/ci-report/testdata/*) $(wildcard scripts/ci-report/*.go)
+	go test ./scripts/ci-report -run=TestOutputMatchesGoldenFile -update
+	touch "$@"
+
+# Generate a prettierrc for the site package that uses relative paths for
+# overrides. This allows us to share the same prettier config between the
+# site and the root of the repo.
+site/.prettierrc.yaml: .prettierrc.yaml
+	. ./scripts/lib.sh
+	dependencies yq
+
+	echo "# Code generated by Makefile (../$<). DO NOT EDIT." > "$@"
+	echo "" >> "$@"
+
+	# Replace all listed override files with relative paths inside site/.
+	# - ./ -> ../
+	# - ./site -> ./
+	yq \
+		'.overrides[].files |= map(. | sub("^./"; "") | sub("^"; "../") | sub("../site/"; "./"))' \
+		"$<" >> "$@"
+
+# Combine .gitignore with .prettierignore.include to generate .prettierignore.
+.prettierignore: .gitignore .prettierignore.include
+	echo "# Code generated by Makefile ($^). DO NOT EDIT." > "$@"
+	echo "" >> "$@"
+	for f in $^; do
+		echo "# $${f}:" >> "$@"
+		cat "$$f" >> "$@"
+	done
+
+# Generate ignore files based on gitignore into the site directory. We turn all
+# rules into relative paths for the `site/` directory (where applicable),
+# following the pattern format defined by git:
+# https://git-scm.com/docs/gitignore#_pattern_format
+#
+# This is done for compatibility reasons, see:
+# https://github.com/prettier/prettier/issues/8048
+# https://github.com/prettier/prettier/issues/8506
+# https://github.com/prettier/prettier/issues/8679
+site/.eslintignore site/.prettierignore: .prettierignore Makefile
+	rm -f "$@"
+	touch "$@"
+	# Skip generated by header, inherit `.prettierignore` header as-is.
+	while read -r rule; do
+		# Remove leading ! if present to simplify rule, added back at the end.
+		tmp="$${rule#!}"
+		ignore="$${rule%"$$tmp"}"
+		rule="$$tmp"
+		case "$$rule" in
+			# Comments or empty lines (include).
+			\#*|'') ;;
+			# Generic rules (include).
+			\*\**) ;;
+			# Site prefixed rules (include).
+			site/*) rule="$${rule#site/}";;
+			./site/*) rule="$${rule#./site/}";;
+			# Rules that are non-generic and don't start with site (rewrite).
+			/*) rule=.."$$rule";;
+			*/?*) rule=../"$$rule";;
+			*) ;;
+		esac
+		echo "$${ignore}$${rule}" >> "$@"
+	done < "$<"
+
 test: test-clean
-	gotestsum -- -v -short ./...
+	gotestsum --format standard-quiet -- -v -short ./...
 .PHONY: test
 
 # When updating -timeout for this test, keep in sync with
 # test-go-postgres (.github/workflows/coder.yaml).
 test-postgres: test-clean test-postgres-docker
-	DB=ci DB_FROM=$(shell go run scripts/migrate-ci/main.go) gotestsum --junitfile="gotests.xml" --packages="./..." -- \
+	# The postgres test is prone to failure, so we limit parallelism for
+	# more consistent execution.
+	DB=ci DB_FROM=$(shell go run scripts/migrate-ci/main.go) gotestsum \
+		--junitfile="gotests.xml" \
+		--jsonfile="gotests.json" \
+		--packages="./..." -- \
 		-covermode=atomic -coverprofile="gotests.coverage" -timeout=20m \
 		-coverpkg=./... \
-		-count=1 -race -failfast
+		-race -failfast
 .PHONY: test-postgres
 
 test-postgres-docker:
@@ -463,10 +626,13 @@ test-postgres-docker:
 		--detach \
 		postgres:13 \
 		-c shared_buffers=1GB \
+		-c work_mem=1GB \
+		-c effective_cache_size=1GB \
 		-c max_connections=1000 \
 		-c fsync=off \
 		-c synchronous_commit=off \
-		-c full_page_writes=off
+		-c full_page_writes=off \
+		-c log_statement=all
 	while ! pg_isready -h 127.0.0.1
 	do
 		echo "$(date) - waiting for database to start"

README.md

@@ -1,102 +1,125 @@
-# Coder
+<div align="center">
+  <a href="https://coder.com#gh-light-mode-only">
+    <img src="./docs/images/logo-black.png" style="width: 128px">
+  </a>
+  <a href="https://coder.com#gh-dark-mode-only">
+    <img src="./docs/images/logo-white.png" style="width: 128px">
+  </a>
 
-[!["Join us on
-Discord"](https://img.shields.io/badge/join-us%20on%20Discord-gray.svg?longCache=true&logo=discord&colorB=green)](https://coder.com/chat?utm_source=github.com/coder/coder&utm_medium=github&utm_campaign=readme.md)
+  <h1>
+  Self-Hosted Remote Development Environments
+  </h1>
+
+  <a href="https://coder.com#gh-light-mode-only">
+    <img src="./docs/images/banner-black.png" style="width: 650px">
+  </a>
+  <a href="https://coder.com#gh-dark-mode-only">
+    <img src="./docs/images/banner-white.png" style="width: 650px">
+  </a>
+
+  <br>
+  <br>
+
+[Quickstart](#quickstart) | [Docs](https://coder.com/docs) | [Why Coder](https://coder.com/why) | [Enterprise](https://coder.com/docs/v2/latest/enterprise)
+
+[![discord](https://img.shields.io/discord/747933592273027093?label=discord)](https://discord.gg/coder)
 [![codecov](https://codecov.io/gh/coder/coder/branch/main/graph/badge.svg?token=TNLW3OAP6G)](https://codecov.io/gh/coder/coder)
-[![Go Reference](https://pkg.go.dev/badge/github.com/coder/coder.svg)](https://pkg.go.dev/github.com/coder/coder)
-[![Twitter
-Follow](https://img.shields.io/twitter/follow/coderhq?label=%40coderhq&style=social)](https://twitter.com/coderhq)
+[![release](https://img.shields.io/github/v/release/coder/coder)](https://github.com/coder/coder/releases/latest)
+[![godoc](https://pkg.go.dev/badge/github.com/coder/coder.svg)](https://pkg.go.dev/github.com/coder/coder)
+[![Go Report Card](https://goreportcard.com/badge/github.com/coder/coder)](https://goreportcard.com/report/github.com/coder/coder)
+[![license](https://img.shields.io/github/license/coder/coder)](./LICENSE)
 
-Coder creates remote development machines so your team can develop from anywhere.
+</div>
+
+[Coder](https://coder.com) enables organizations to set up development environments in the cloud. Environments are defined with Terraform, connected through a secure high-speed Wireguard® tunnel, and are automatically shut down when not in use to save on costs. Coder gives engineering teams the flexibility to use the cloud for workloads that are most beneficial to them.
+
+- Define development environments in Terraform
+  - EC2 VMs, Kubernetes Pods, Docker Containers, etc.
+- Automatically shutdown idle resources to save on costs
+- Onboard developers in seconds instead of days
 
 <p align="center">
   <img src="./docs/images/hero-image.png">
 </p>
 
-**Manage less**
+## Quickstart
 
-- Ensure your entire team is using the same tools and resources
-  - Rollout critical updates to your developers with one command
-- Automatically shut down expensive cloud resources
-- Keep your source code and data behind your firewall
+The most convenient way to try Coder is to install it on your local machine and experiment with provisioning development environments using Docker (works on Linux, macOS, and Windows).
 
-**Code more**
+```
+# First, install Coder
+curl -L https://coder.com/install.sh | sh
 
-- Build and test faster
-  - Leveraging cloud CPUs, RAM, network speeds, etc.
-- Access your environment from any place on any client (even an iPad)
-- Onboard instantly then stay up to date continuously
+# Start the Coder server (caches data in ~/.cache/coder)
+coder server
 
-## Getting Started
+# Navigate to http://localhost:3000 to create your initial user
+# Create a Docker template, and provision a workspace
+```
 
-> **Note**:
-> Coder is in a beta state. [Report issues here](https://github.com/coder/coder/issues/new).
+## Install
 
-The easiest way to install Coder is to use our [install script](https://github.com/coder/coder/blob/main/install.sh) for Linux and macOS.
-
-To install, run:
+The easiest way to install Coder is to use our
+[install script](https://github.com/coder/coder/blob/main/install.sh) for Linux
+and macOS. For Windows, use the latest `..._installer.exe` file from GitHub
+Releases.
 
 ```bash
 curl -L https://coder.com/install.sh | sh
 ```
 
-You can preview what occurs during the install process:
-
-```bash
-curl -L https://coder.com/install.sh | sh -s -- --dry-run
-```
-
-You can modify the installation process by including flags. Run the help command for reference:
-
-```bash
-curl -L https://coder.com/install.sh | sh -s -- --help
-```
+You can run the install script with `--dry-run` to see the commands that will be used to install without executing them. You can modify the installation process by including flags. Run the install script with `--help` for reference.
 
 > See [install](docs/install) for additional methods.
 
 Once installed, you can start a production deployment<sup>1</sup> with a single command:
 
-```sh
+```console
 # Automatically sets up an external access URL on *.try.coder.app
-coder server --tunnel
+coder server
 
-# Requires a PostgreSQL instance and external access URL
+# Requires a PostgreSQL instance (version 13 or higher) and external access URL
 coder server --postgres-url <url> --access-url <url>
 ```
 
-> <sup>1</sup> The embedded database is great for trying out Coder with small deployments, but do consider using an external database for increased assurance and control.
+> <sup>1</sup> For production deployments, set up an external PostgreSQL instance for reliability.
 
-Use `coder --help` to get a complete list of flags and environment variables. Use our [quickstart guide](https://coder.com/docs/coder-oss/latest/quickstart) for a full walkthrough.
+Use `coder --help` to get a list of flags and environment variables. Use our [install guides](https://coder.com/docs/v2/latest/install) for a full walkthrough.
 
 ## Documentation
 
-Visit our docs [here](https://coder.com/docs/coder-oss).
+Browse our docs [here](https://coder.com/docs/v2) or visit a specific section below:
 
-## Comparison
-
-Please file [an issue](https://github.com/coder/coder/issues/new) if any information is out of date. Also refer to: [What Coder is not](https://coder.com/docs/coder-oss/latest/index#what-coder-is-not).
-
-| Tool                                                        | Type     | Delivery Model     | Cost                          | Environments                                                                                                                                               |
-| :---------------------------------------------------------- | :------- | :----------------- | :---------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [Coder](https://github.com/coder/coder)                     | Platform | OSS + Self-Managed | Pay your cloud                | All [Terraform](https://www.terraform.io/registry/providers) resources, all clouds, multi-architecture: Linux, Mac, Windows, containers, VMs, amd64, arm64 |
-| [code-server](https://github.com/cdr/code-server)           | Web IDE  | OSS + Self-Managed | Pay your cloud                | Linux, Mac, Windows, containers, VMs, amd64, arm64                                                                                                         |
-| [Coder (Classic)](https://coder.com/docs)                   | Platform | Self-Managed       | Pay your cloud + license fees | Kubernetes Linux Containers                                                                                                                                |
-| [GitHub Codespaces](https://github.com/features/codespaces) | Platform | SaaS               | 2x Azure Compute              | Linux containers                                                                                                                                           |
-
----
-
-_Last updated: 5/27/22_
+- [**Templates**](https://coder.com/docs/v2/latest/templates): Templates are written in Terraform and describe the infrastructure for workspaces
+- [**Workspaces**](https://coder.com/docs/v2/latest/workspaces): Workspaces contain the IDEs, dependencies, and configuration information needed for software development
+- [**IDEs**](https://coder.com/docs/v2/latest/ides): Connect your existing editor to a workspace
+- [**Administration**](https://coder.com/docs/v2/latest/admin): Learn how to operate Coder
+- [**Enterprise**](https://coder.com/docs/v2/latest/enterprise): Learn about our paid features built for large teams
 
 ## Community and Support
 
-Join our community on [Discord](https://coder.com/chat?utm_source=github.com/coder/coder&utm_medium=github&utm_campaign=readme.md) and [Twitter](https://twitter.com/coderhq)!
+Feel free to [open an issue](https://github.com/coder/coder/issues/new) if you have questions, run into bugs, or have a feature request.
 
-[Suggest improvements and report problems](https://github.com/coder/coder/issues/new/choose)
+[Join our Discord](https://discord.gg/coder) to provide feedback on in-progress features, and chat with the community using Coder!
 
 ## Contributing
 
-If you're using Coder in your organization, please try to add your company name to the [ADOPTERS.md](./ADOPTERS.md). It really helps the project to gain momentum and credibility. It's a small contribution back to the project with a big impact. 
-
-Read the [contributing docs](https://coder.com/docs/coder-oss/latest/CONTRIBUTING).
+Contributions are welcome! Read the [contributing docs](https://coder.com/docs/v2/latest/CONTRIBUTING) to get started.
 
 Find our list of contributors [here](https://github.com/coder/coder/graphs/contributors).
+
+## Related
+
+We are always working on new integrations. Feel free to open an issue to request an integration. Contributions are welcome in any official or community repositories.
+
+### Official
+
+- [**VS Code Extension**](https://marketplace.visualstudio.com/items?itemName=coder.coder-remote): Open any Coder workspace in VS Code with a single click
+- [**JetBrains Gateway Extension**](https://plugins.jetbrains.com/plugin/19620-coder): Open any Coder workspace in JetBrains Gateway with a single click
+- [**Self-Hosted VS Code Extension Marketplace**](https://github.com/coder/code-marketplace): A private extension marketplace that works in restricted or airgapped networks integrating with [code-server](https://github.com/coder/code-server).
+
+### Community
+
+- [**Provision Coder with Terraform**](https://github.com/ElliotG/coder-oss-tf): Provision Coder on Google GKE, Azure AKS, AWS EKS, DigitalOcean DOKS, IBMCloud K8s, OVHCloud K8s, and Scaleway K8s Kapsule with Terraform
+- [**Coder GitHub Action**](https://github.com/marketplace/actions/update-coder-template): A GitHub Action that updates Coder templates
+- [**Various Templates**](./examples/templates/community-templates.md): Hetzner Cloud, Docker in Docker, and other templates the community has built.

SECURITY.md

@@ -0,0 +1,73 @@
+# Coder Security
+
+Coder welcomes feedback from security researchers and the general public
+to help improve our security. If you believe you have discovered a vulnerability,
+privacy issue, exposed data, or other security issues in any of our assets, we
+want to hear from you. This policy outlines steps for reporting vulnerabilities
+to us, what we expect, what you can expect from us.
+
+You can see the pretty version [here](https://coder.com/security/policy)
+
+# Why Coder's security matters
+
+If an attacker could fully compromise a Coder installation, they could spin
+up expensive workstations, steal valuable credentials, or steal proprietary
+source code. We take this risk very seriously and employ routine pen testing,
+vulnerability scanning, and code reviews. We also welcome the contributions
+from the community that helped make this product possible.
+
+# Where should I report security issues?
+
+Please report security issues to security@coder.com, providing
+all relevant information. The more details you provide, the easier it will be
+for us to triage and fix the issue.
+
+# Out of Scope
+
+Our primary concern is around an abuse of the Coder application that allows
+an attacker to gain access to another users workspace, or spin up unwanted
+workspaces.
+
+- DOS/DDOS attacks affecting availability --> While we do support rate limiting
+  of requests, we primarily leave this to the owner of the Coder installation. Our
+  rationale is that a DOS attack only affecting availability is not a valuable
+  target for attackers.
+- Abuse of a compromised user credential --> If a user credential is compromised
+  outside of the Coder ecosystem, then we consider it beyond the scope of our application.
+  However, if an unprivileged user could escalate their permissions or gain access
+  to another workspace, that is a cause for concern.
+- Vulnerabilities in third party systems --> Vulnerabilities discovered in
+  out-of-scope systems should be reported to the appropriate vendor or applicable authority.
+
+# Our Commitments
+
+When working with us, according to this policy, you can expect us to:
+
+- Respond to your report promptly, and work with you to understand and validate your report;
+- Strive to keep you informed about the progress of a vulnerability as it is processed;
+- Work to remediate discovered vulnerabilities in a timely manner, within our operational constraints; and
+- Extend Safe Harbor for your vulnerability research that is related to this policy.
+
+# Our Expectations
+
+In participating in our vulnerability disclosure program in good faith, we ask that you:
+
+- Play by the rules, including following this policy and any other relevant agreements.
+  If there is any inconsistency between this policy and any other applicable terms, the
+  terms of this policy will prevail;
+- Report any vulnerability you’ve discovered promptly;
+- Avoid violating the privacy of others, disrupting our systems, destroying data, and/or
+  harming user experience;
+- Use only the Official Channels to discuss vulnerability information with us;
+- Provide us a reasonable amount of time (at least 90 days from the initial report) to
+  resolve the issue before you disclose it publicly;
+- Perform testing only on in-scope systems, and respect systems and activities which
+  are out-of-scope;
+- If a vulnerability provides unintended access to data: Limit the amount of data you
+  access to the minimum required for effectively demonstrating a Proof of Concept; and
+  cease testing and submit a report immediately if you encounter any user data during testing,
+  such as Personally Identifiable Information (PII), Personal Healthcare Information (PHI),
+  credit card data, or proprietary information;
+- You should only interact with test accounts you own or with explicit permission from
+- the account holder; and
+- Do not engage in extortion.

agent/agentssh/agentssh.go

@@ -0,0 +1,740 @@
+package agentssh
+
+import (
+	"bufio"
+	"context"
+	"crypto/rand"
+	"crypto/rsa"
+	"errors"
+	"fmt"
+	"io"
+	"net"
+	"os"
+	"os/exec"
+	"os/user"
+	"path/filepath"
+	"runtime"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/gliderlabs/ssh"
+	"github.com/pkg/sftp"
+	"github.com/spf13/afero"
+	"go.uber.org/atomic"
+	gossh "golang.org/x/crypto/ssh"
+	"golang.org/x/xerrors"
+
+	"cdr.dev/slog"
+
+	"github.com/coder/coder/agent/usershell"
+	"github.com/coder/coder/codersdk/agentsdk"
+	"github.com/coder/coder/pty"
+)
+
+const (
+	// MagicSessionErrorCode indicates that something went wrong with the session, rather than the
+	// command just returning a nonzero exit code, and is chosen as an arbitrary, high number
+	// unlikely to shadow other exit codes, which are typically 1, 2, 3, etc.
+	MagicSessionErrorCode = 229
+
+	// MagicSessionTypeEnvironmentVariable is used to track the purpose behind an SSH connection.
+	// This is stripped from any commands being executed, and is counted towards connection stats.
+	MagicSessionTypeEnvironmentVariable = "CODER_SSH_SESSION_TYPE"
+	// MagicSessionTypeVSCode is set in the SSH config by the VS Code extension to identify itself.
+	MagicSessionTypeVSCode = "vscode"
+	// MagicSessionTypeJetBrains is set in the SSH config by the JetBrains extension to identify itself.
+	MagicSessionTypeJetBrains = "jetbrains"
+)
+
+type Server struct {
+	mu        sync.RWMutex // Protects following.
+	fs        afero.Fs
+	listeners map[net.Listener]struct{}
+	conns     map[net.Conn]struct{}
+	sessions  map[ssh.Session]struct{}
+	closing   chan struct{}
+	// Wait for goroutines to exit, waited without
+	// a lock on mu but protected by closing.
+	wg sync.WaitGroup
+
+	logger       slog.Logger
+	srv          *ssh.Server
+	x11SocketDir string
+
+	Env        map[string]string
+	AgentToken func() string
+	Manifest   *atomic.Pointer[agentsdk.Manifest]
+
+	connCountVSCode     atomic.Int64
+	connCountJetBrains  atomic.Int64
+	connCountSSHSession atomic.Int64
+}
+
+func NewServer(ctx context.Context, logger slog.Logger, fs afero.Fs, maxTimeout time.Duration, x11SocketDir string) (*Server, error) {
+	// Clients' should ignore the host key when connecting.
+	// The agent needs to authenticate with coderd to SSH,
+	// so SSH authentication doesn't improve security.
+	randomHostKey, err := rsa.GenerateKey(rand.Reader, 2048)
+	if err != nil {
+		return nil, err
+	}
+	randomSigner, err := gossh.NewSignerFromKey(randomHostKey)
+	if err != nil {
+		return nil, err
+	}
+	if x11SocketDir == "" {
+		x11SocketDir = filepath.Join(os.TempDir(), ".X11-unix")
+	}
+
+	forwardHandler := &ssh.ForwardedTCPHandler{}
+	unixForwardHandler := &forwardedUnixHandler{log: logger}
+
+	s := &Server{
+		listeners:    make(map[net.Listener]struct{}),
+		fs:           fs,
+		conns:        make(map[net.Conn]struct{}),
+		sessions:     make(map[ssh.Session]struct{}),
+		logger:       logger,
+		x11SocketDir: x11SocketDir,
+	}
+
+	s.srv = &ssh.Server{
+		ChannelHandlers: map[string]ssh.ChannelHandler{
+			"direct-tcpip":                   ssh.DirectTCPIPHandler,
+			"direct-streamlocal@openssh.com": directStreamLocalHandler,
+			"session":                        ssh.DefaultSessionHandler,
+		},
+		ConnectionFailedCallback: func(_ net.Conn, err error) {
+			s.logger.Info(ctx, "ssh connection ended", slog.Error(err))
+		},
+		Handler:     s.sessionHandler,
+		HostSigners: []ssh.Signer{randomSigner},
+		LocalPortForwardingCallback: func(ctx ssh.Context, destinationHost string, destinationPort uint32) bool {
+			// Allow local port forwarding all!
+			s.logger.Debug(ctx, "local port forward",
+				slog.F("destination-host", destinationHost),
+				slog.F("destination-port", destinationPort))
+			return true
+		},
+		PtyCallback: func(ctx ssh.Context, pty ssh.Pty) bool {
+			return true
+		},
+		ReversePortForwardingCallback: func(ctx ssh.Context, bindHost string, bindPort uint32) bool {
+			// Allow reverse port forwarding all!
+			s.logger.Debug(ctx, "local port forward",
+				slog.F("bind-host", bindHost),
+				slog.F("bind-port", bindPort))
+			return true
+		},
+		RequestHandlers: map[string]ssh.RequestHandler{
+			"tcpip-forward":                          forwardHandler.HandleSSHRequest,
+			"cancel-tcpip-forward":                   forwardHandler.HandleSSHRequest,
+			"streamlocal-forward@openssh.com":        unixForwardHandler.HandleSSHRequest,
+			"cancel-streamlocal-forward@openssh.com": unixForwardHandler.HandleSSHRequest,
+		},
+		X11Callback: s.x11Callback,
+		ServerConfigCallback: func(ctx ssh.Context) *gossh.ServerConfig {
+			return &gossh.ServerConfig{
+				NoClientAuth: true,
+			}
+		},
+		SubsystemHandlers: map[string]ssh.SubsystemHandler{
+			"sftp": s.sessionHandler,
+		},
+		MaxTimeout: maxTimeout,
+	}
+
+	return s, nil
+}
+
+type ConnStats struct {
+	Sessions  int64
+	VSCode    int64
+	JetBrains int64
+}
+
+func (s *Server) ConnStats() ConnStats {
+	return ConnStats{
+		Sessions:  s.connCountSSHSession.Load(),
+		VSCode:    s.connCountVSCode.Load(),
+		JetBrains: s.connCountJetBrains.Load(),
+	}
+}
+
+func (s *Server) sessionHandler(session ssh.Session) {
+	if !s.trackSession(session, true) {
+		// See (*Server).Close() for why we call Close instead of Exit.
+		_ = session.Close()
+		return
+	}
+	defer s.trackSession(session, false)
+
+	ctx := session.Context()
+
+	extraEnv := make([]string, 0)
+	x11, hasX11 := session.X11()
+	if hasX11 {
+		handled := s.x11Handler(session.Context(), x11)
+		if !handled {
+			_ = session.Exit(1)
+			return
+		}
+		extraEnv = append(extraEnv, fmt.Sprintf("DISPLAY=:%d.0", x11.ScreenNumber))
+	}
+
+	switch ss := session.Subsystem(); ss {
+	case "":
+	case "sftp":
+		s.sftpHandler(session)
+		return
+	default:
+		s.logger.Debug(ctx, "unsupported subsystem", slog.F("subsystem", ss))
+		_ = session.Exit(1)
+		return
+	}
+
+	err := s.sessionStart(session, extraEnv)
+	var exitError *exec.ExitError
+	if xerrors.As(err, &exitError) {
+		s.logger.Debug(ctx, "ssh session returned", slog.Error(exitError))
+		_ = session.Exit(exitError.ExitCode())
+		return
+	}
+	if err != nil {
+		s.logger.Warn(ctx, "ssh session failed", slog.Error(err))
+		// This exit code is designed to be unlikely to be confused for a legit exit code
+		// from the process.
+		_ = session.Exit(MagicSessionErrorCode)
+		return
+	}
+	_ = session.Exit(0)
+}
+
+func (s *Server) sessionStart(session ssh.Session, extraEnv []string) (retErr error) {
+	ctx := session.Context()
+	env := append(session.Environ(), extraEnv...)
+	var magicType string
+	for index, kv := range env {
+		if !strings.HasPrefix(kv, MagicSessionTypeEnvironmentVariable) {
+			continue
+		}
+		magicType = strings.TrimPrefix(kv, MagicSessionTypeEnvironmentVariable+"=")
+		env = append(env[:index], env[index+1:]...)
+	}
+	switch magicType {
+	case MagicSessionTypeVSCode:
+		s.connCountVSCode.Add(1)
+		defer s.connCountVSCode.Add(-1)
+	case MagicSessionTypeJetBrains:
+		s.connCountJetBrains.Add(1)
+		defer s.connCountJetBrains.Add(-1)
+	case "":
+		s.connCountSSHSession.Add(1)
+		defer s.connCountSSHSession.Add(-1)
+	default:
+		s.logger.Warn(ctx, "invalid magic ssh session type specified", slog.F("type", magicType))
+	}
+
+	cmd, err := s.CreateCommand(ctx, session.RawCommand(), env)
+	if err != nil {
+		return err
+	}
+
+	if ssh.AgentRequested(session) {
+		l, err := ssh.NewAgentListener()
+		if err != nil {
+			return xerrors.Errorf("new agent listener: %w", err)
+		}
+		defer l.Close()
+		go ssh.ForwardAgentConnections(l, session)
+		cmd.Env = append(cmd.Env, fmt.Sprintf("%s=%s", "SSH_AUTH_SOCK", l.Addr().String()))
+	}
+
+	sshPty, windowSize, isPty := session.Pty()
+	if isPty {
+		return s.startPTYSession(session, cmd, sshPty, windowSize)
+	}
+	return startNonPTYSession(session, cmd.AsExec())
+}
+
+func startNonPTYSession(session ssh.Session, cmd *exec.Cmd) error {
+	cmd.Stdout = session
+	cmd.Stderr = session.Stderr()
+	// This blocks forever until stdin is received if we don't
+	// use StdinPipe. It's unknown what causes this.
+	stdinPipe, err := cmd.StdinPipe()
+	if err != nil {
+		return xerrors.Errorf("create stdin pipe: %w", err)
+	}
+	go func() {
+		_, _ = io.Copy(stdinPipe, session)
+		_ = stdinPipe.Close()
+	}()
+	err = cmd.Start()
+	if err != nil {
+		return xerrors.Errorf("start: %w", err)
+	}
+	return cmd.Wait()
+}
+
+// ptySession is the interface to the ssh.Session that startPTYSession uses
+// we use an interface here so that we can fake it in tests.
+type ptySession interface {
+	io.ReadWriter
+	Context() ssh.Context
+	DisablePTYEmulation()
+	RawCommand() string
+}
+
+func (s *Server) startPTYSession(session ptySession, cmd *pty.Cmd, sshPty ssh.Pty, windowSize <-chan ssh.Window) (retErr error) {
+	ctx := session.Context()
+	// Disable minimal PTY emulation set by gliderlabs/ssh (NL-to-CRNL).
+	// See https://github.com/coder/coder/issues/3371.
+	session.DisablePTYEmulation()
+
+	if !isQuietLogin(session.RawCommand()) {
+		manifest := s.Manifest.Load()
+		if manifest != nil {
+			err := showMOTD(session, manifest.MOTDFile)
+			if err != nil {
+				s.logger.Error(ctx, "show MOTD", slog.Error(err))
+			}
+		} else {
+			s.logger.Warn(ctx, "metadata lookup failed, unable to show MOTD")
+		}
+	}
+
+	cmd.Env = append(cmd.Env, fmt.Sprintf("TERM=%s", sshPty.Term))
+
+	// The pty package sets `SSH_TTY` on supported platforms.
+	ptty, process, err := pty.Start(cmd, pty.WithPTYOption(
+		pty.WithSSHRequest(sshPty),
+		pty.WithLogger(slog.Stdlib(ctx, s.logger, slog.LevelInfo)),
+	))
+	if err != nil {
+		return xerrors.Errorf("start command: %w", err)
+	}
+	defer func() {
+		closeErr := ptty.Close()
+		if closeErr != nil {
+			s.logger.Warn(ctx, "failed to close tty", slog.Error(closeErr))
+			if retErr == nil {
+				retErr = closeErr
+			}
+		}
+	}()
+	go func() {
+		for win := range windowSize {
+			resizeErr := ptty.Resize(uint16(win.Height), uint16(win.Width))
+			// If the pty is closed, then command has exited, no need to log.
+			if resizeErr != nil && !errors.Is(resizeErr, pty.ErrClosed) {
+				s.logger.Warn(ctx, "failed to resize tty", slog.Error(resizeErr))
+			}
+		}
+	}()
+
+	go func() {
+		_, _ = io.Copy(ptty.InputWriter(), session)
+	}()
+
+	// We need to wait for the command output to finish copying.  It's safe to
+	// just do this copy on the main handler goroutine because one of two things
+	// will happen:
+	//
+	// 1. The command completes & closes the TTY, which then triggers an error
+	//    after we've Read() all the buffered data from the PTY.
+	// 2. The client hangs up, which cancels the command's Context, and go will
+	//    kill the command's process.  This then has the same effect as (1).
+	n, err := io.Copy(session, ptty.OutputReader())
+	s.logger.Debug(ctx, "copy output done", slog.F("bytes", n), slog.Error(err))
+	if err != nil {
+		return xerrors.Errorf("copy error: %w", err)
+	}
+	// We've gotten all the output, but we need to wait for the process to
+	// complete so that we can get the exit code.  This returns
+	// immediately if the TTY was closed as part of the command exiting.
+	err = process.Wait()
+	var exitErr *exec.ExitError
+	// ExitErrors just mean the command we run returned a non-zero exit code, which is normal
+	// and not something to be concerned about.  But, if it's something else, we should log it.
+	if err != nil && !xerrors.As(err, &exitErr) {
+		s.logger.Warn(ctx, "wait error", slog.Error(err))
+	}
+	if err != nil {
+		return xerrors.Errorf("process wait: %w", err)
+	}
+	return nil
+}
+
+func (s *Server) sftpHandler(session ssh.Session) {
+	ctx := session.Context()
+
+	// Typically sftp sessions don't request a TTY, but if they do,
+	// we must ensure the gliderlabs/ssh CRLF emulation is disabled.
+	// Otherwise sftp will be broken. This can happen if a user sets
+	// `RequestTTY force` in their SSH config.
+	session.DisablePTYEmulation()
+
+	var opts []sftp.ServerOption
+	// Change current working directory to the users home
+	// directory so that SFTP connections land there.
+	homedir, err := userHomeDir()
+	if err != nil {
+		s.logger.Warn(ctx, "get sftp working directory failed, unable to get home dir", slog.Error(err))
+	} else {
+		opts = append(opts, sftp.WithServerWorkingDirectory(homedir))
+	}
+
+	server, err := sftp.NewServer(session, opts...)
+	if err != nil {
+		s.logger.Debug(ctx, "initialize sftp server", slog.Error(err))
+		return
+	}
+	defer server.Close()
+
+	err = server.Serve()
+	if errors.Is(err, io.EOF) {
+		// Unless we call `session.Exit(0)` here, the client won't
+		// receive `exit-status` because `(*sftp.Server).Close()`
+		// calls `Close()` on the underlying connection (session),
+		// which actually calls `channel.Close()` because it isn't
+		// wrapped. This causes sftp clients to receive a non-zero
+		// exit code. Typically sftp clients don't echo this exit
+		// code but `scp` on macOS does (when using the default
+		// SFTP backend).
+		_ = session.Exit(0)
+		return
+	}
+	s.logger.Warn(ctx, "sftp server closed with error", slog.Error(err))
+	_ = session.Exit(1)
+}
+
+// CreateCommand processes raw command input with OpenSSH-like behavior.
+// If the script provided is empty, it will default to the users shell.
+// This injects environment variables specified by the user at launch too.
+func (s *Server) CreateCommand(ctx context.Context, script string, env []string) (*pty.Cmd, error) {
+	currentUser, err := user.Current()
+	if err != nil {
+		return nil, xerrors.Errorf("get current user: %w", err)
+	}
+	username := currentUser.Username
+
+	shell, err := usershell.Get(username)
+	if err != nil {
+		return nil, xerrors.Errorf("get user shell: %w", err)
+	}
+
+	manifest := s.Manifest.Load()
+	if manifest == nil {
+		return nil, xerrors.Errorf("no metadata was provided")
+	}
+
+	// OpenSSH executes all commands with the users current shell.
+	// We replicate that behavior for IDE support.
+	caller := "-c"
+	if runtime.GOOS == "windows" {
+		caller = "/c"
+	}
+	args := []string{caller, script}
+
+	// gliderlabs/ssh returns a command slice of zero
+	// when a shell is requested.
+	if len(script) == 0 {
+		args = []string{}
+		if runtime.GOOS != "windows" {
+			// On Linux and macOS, we should start a login
+			// shell to consume juicy environment variables!
+			args = append(args, "-l")
+		}
+	}
+
+	cmd := pty.CommandContext(ctx, shell, args...)
+	cmd.Dir = manifest.Directory
+
+	// If the metadata directory doesn't exist, we run the command
+	// in the users home directory.
+	_, err = os.Stat(cmd.Dir)
+	if cmd.Dir == "" || err != nil {
+		// Default to user home if a directory is not set.
+		homedir, err := userHomeDir()
+		if err != nil {
+			return nil, xerrors.Errorf("get home dir: %w", err)
+		}
+		cmd.Dir = homedir
+	}
+	cmd.Env = append(os.Environ(), env...)
+	executablePath, err := os.Executable()
+	if err != nil {
+		return nil, xerrors.Errorf("getting os executable: %w", err)
+	}
+	// Set environment variables reliable detection of being inside a
+	// Coder workspace.
+	cmd.Env = append(cmd.Env, "CODER=true")
+	cmd.Env = append(cmd.Env, fmt.Sprintf("USER=%s", username))
+	// Git on Windows resolves with UNIX-style paths.
+	// If using backslashes, it's unable to find the executable.
+	unixExecutablePath := strings.ReplaceAll(executablePath, "\\", "/")
+	cmd.Env = append(cmd.Env, fmt.Sprintf(`GIT_SSH_COMMAND=%s gitssh --`, unixExecutablePath))
+
+	// Specific Coder subcommands require the agent token exposed!
+	cmd.Env = append(cmd.Env, fmt.Sprintf("CODER_AGENT_TOKEN=%s", s.AgentToken()))
+
+	// Set SSH connection environment variables (these are also set by OpenSSH
+	// and thus expected to be present by SSH clients). Since the agent does
+	// networking in-memory, trying to provide accurate values here would be
+	// nonsensical. For now, we hard code these values so that they're present.
+	srcAddr, srcPort := "0.0.0.0", "0"
+	dstAddr, dstPort := "0.0.0.0", "0"
+	cmd.Env = append(cmd.Env, fmt.Sprintf("SSH_CLIENT=%s %s %s", srcAddr, srcPort, dstPort))
+	cmd.Env = append(cmd.Env, fmt.Sprintf("SSH_CONNECTION=%s %s %s %s", srcAddr, srcPort, dstAddr, dstPort))
+
+	// This adds the ports dialog to code-server that enables
+	// proxying a port dynamically.
+	cmd.Env = append(cmd.Env, fmt.Sprintf("VSCODE_PROXY_URI=%s", manifest.VSCodePortProxyURI))
+
+	// Hide Coder message on code-server's "Getting Started" page
+	cmd.Env = append(cmd.Env, "CS_DISABLE_GETTING_STARTED_OVERRIDE=true")
+
+	// Load environment variables passed via the agent.
+	// These should override all variables we manually specify.
+	for envKey, value := range manifest.EnvironmentVariables {
+		// Expanding environment variables allows for customization
+		// of the $PATH, among other variables. Customers can prepend
+		// or append to the $PATH, so allowing expand is required!
+		cmd.Env = append(cmd.Env, fmt.Sprintf("%s=%s", envKey, os.ExpandEnv(value)))
+	}
+
+	// Agent-level environment variables should take over all!
+	// This is used for setting agent-specific variables like "CODER_AGENT_TOKEN".
+	for envKey, value := range s.Env {
+		cmd.Env = append(cmd.Env, fmt.Sprintf("%s=%s", envKey, value))
+	}
+
+	return cmd, nil
+}
+
+func (s *Server) Serve(l net.Listener) error {
+	defer l.Close()
+
+	s.trackListener(l, true)
+	defer s.trackListener(l, false)
+	for {
+		conn, err := l.Accept()
+		if err != nil {
+			return err
+		}
+		go s.handleConn(l, conn)
+	}
+}
+
+func (s *Server) handleConn(l net.Listener, c net.Conn) {
+	defer c.Close()
+
+	if !s.trackConn(l, c, true) {
+		// Server is closed or we no longer want
+		// connections from this listener.
+		s.logger.Debug(context.Background(), "received connection after server closed")
+		return
+	}
+	defer s.trackConn(l, c, false)
+
+	s.srv.HandleConn(c)
+}
+
+// trackListener registers the listener with the server. If the server is
+// closing, the function will block until the server is closed.
+//
+//nolint:revive
+func (s *Server) trackListener(l net.Listener, add bool) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	if add {
+		for s.closing != nil {
+			closing := s.closing
+			// Wait until close is complete before
+			// serving a new listener.
+			s.mu.Unlock()
+			<-closing
+			s.mu.Lock()
+		}
+		s.wg.Add(1)
+		s.listeners[l] = struct{}{}
+		return
+	}
+	s.wg.Done()
+	delete(s.listeners, l)
+}
+
+// trackConn registers the connection with the server. If the server is
+// closed or the listener is closed, the connection is not registered
+// and should be closed.
+//
+//nolint:revive
+func (s *Server) trackConn(l net.Listener, c net.Conn, add bool) (ok bool) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	if add {
+		found := false
+		for ll := range s.listeners {
+			if l == ll {
+				found = true
+				break
+			}
+		}
+		if s.closing != nil || !found {
+			// Server or listener closed.
+			return false
+		}
+		s.wg.Add(1)
+		s.conns[c] = struct{}{}
+		return true
+	}
+	s.wg.Done()
+	delete(s.conns, c)
+	return true
+}
+
+// trackSession registers the session with the server. If the server is
+// closing, the session is not registered and should be closed.
+//
+//nolint:revive
+func (s *Server) trackSession(ss ssh.Session, add bool) (ok bool) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	if add {
+		if s.closing != nil {
+			// Server closed.
+			return false
+		}
+		s.sessions[ss] = struct{}{}
+		return true
+	}
+	delete(s.sessions, ss)
+	return true
+}
+
+// Close the server and all active connections. Server can be re-used
+// after Close is done.
+func (s *Server) Close() error {
+	s.mu.Lock()
+
+	// Guard against multiple calls to Close and
+	// accepting new connections during close.
+	if s.closing != nil {
+		s.mu.Unlock()
+		return xerrors.New("server is closing")
+	}
+	s.closing = make(chan struct{})
+
+	// Close all active sessions to gracefully
+	// terminate client connections.
+	for ss := range s.sessions {
+		// We call Close on the underlying channel here because we don't
+		// want to send an exit status to the client (via Exit()).
+		// Typically OpenSSH clients will return 255 as the exit status.
+		_ = ss.Close()
+	}
+
+	// Close all active listeners and connections.
+	for l := range s.listeners {
+		_ = l.Close()
+	}
+	for c := range s.conns {
+		_ = c.Close()
+	}
+
+	// Close the underlying SSH server.
+	err := s.srv.Close()
+
+	s.mu.Unlock()
+	s.wg.Wait() // Wait for all goroutines to exit.
+
+	s.mu.Lock()
+	close(s.closing)
+	s.closing = nil
+	s.mu.Unlock()
+
+	return err
+}
+
+// Shutdown gracefully closes all active SSH connections and stops
+// accepting new connections.
+//
+// Shutdown is not implemented.
+func (*Server) Shutdown(_ context.Context) error {
+	// TODO(mafredri): Implement shutdown, SIGHUP running commands, etc.
+	return nil
+}
+
+// isQuietLogin checks if the SSH server should perform a quiet login or not.
+//
+// https://github.com/openssh/openssh-portable/blob/25bd659cc72268f2858c5415740c442ee950049f/session.c#L816
+func isQuietLogin(rawCommand string) bool {
+	// We are always quiet unless this is a login shell.
+	if len(rawCommand) != 0 {
+		return true
+	}
+
+	// Best effort, if we can't get the home directory,
+	// we can't lookup .hushlogin.
+	homedir, err := userHomeDir()
+	if err != nil {
+		return false
+	}
+
+	_, err = os.Stat(filepath.Join(homedir, ".hushlogin"))
+	return err == nil
+}
+
+// showMOTD will output the message of the day from
+// the given filename to dest, if the file exists.
+//
+// https://github.com/openssh/openssh-portable/blob/25bd659cc72268f2858c5415740c442ee950049f/session.c#L784
+func showMOTD(dest io.Writer, filename string) error {
+	if filename == "" {
+		return nil
+	}
+
+	f, err := os.Open(filename)
+	if err != nil {
+		if xerrors.Is(err, os.ErrNotExist) {
+			// This is not an error, there simply isn't a MOTD to show.
+			return nil
+		}
+		return xerrors.Errorf("open MOTD: %w", err)
+	}
+	defer f.Close()
+
+	s := bufio.NewScanner(f)
+	for s.Scan() {
+		// Carriage return ensures each line starts
+		// at the beginning of the terminal.
+		_, err = fmt.Fprint(dest, s.Text()+"\r\n")
+		if err != nil {
+			return xerrors.Errorf("write MOTD: %w", err)
+		}
+	}
+	if err := s.Err(); err != nil {
+		return xerrors.Errorf("read MOTD: %w", err)
+	}
+
+	return nil
+}
+
+// userHomeDir returns the home directory of the current user, giving
+// priority to the $HOME environment variable.
+func userHomeDir() (string, error) {
+	// First we check the environment.
+	homedir, err := os.UserHomeDir()
+	if err == nil {
+		return homedir, nil
+	}
+
+	// As a fallback, we try the user information.
+	u, err := user.Current()
+	if err != nil {
+		return "", xerrors.Errorf("current user: %w", err)
+	}
+	return u.HomeDir, nil
+}

agent/agentssh/agentssh_internal_test.go

@@ -0,0 +1,190 @@
+//go:build !windows
+
+package agentssh
+
+import (
+	"bufio"
+	"context"
+	"io"
+	"net"
+	"testing"
+
+	gliderssh "github.com/gliderlabs/ssh"
+	"github.com/spf13/afero"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/coder/coder/pty"
+	"github.com/coder/coder/testutil"
+
+	"cdr.dev/slog/sloggers/slogtest"
+)
+
+const longScript = `
+echo "started"
+sleep 30
+echo "done"
+`
+
+// Test_sessionStart_orphan tests running a command that takes a long time to
+// exit normally, and terminate the SSH session context early to verify that we
+// return quickly and don't leave the command running as an "orphan" with no
+// active SSH session.
+func Test_sessionStart_orphan(t *testing.T) {
+	t.Parallel()
+
+	ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitMedium)
+	defer cancel()
+	logger := slogtest.Make(t, nil)
+	s, err := NewServer(ctx, logger, afero.NewMemMapFs(), 0, "")
+	require.NoError(t, err)
+
+	// Here we're going to call the handler directly with a faked SSH session
+	// that just uses io.Pipes instead of a network socket.  There is a large
+	// variation in the time between closing the socket from the client side and
+	// the SSH server canceling the session Context, which would lead to a flaky
+	// test if we did it that way.  So instead, we directly cancel the context
+	// in this test.
+	sessionCtx, sessionCancel := context.WithCancel(ctx)
+	toClient, fromClient, sess := newTestSession(sessionCtx)
+	ptyInfo := gliderssh.Pty{}
+	windowSize := make(chan gliderssh.Window)
+	close(windowSize)
+	// the command gets the session context so that Go will terminate it when
+	// the session expires.
+	cmd := pty.CommandContext(sessionCtx, "sh", "-c", longScript)
+
+	done := make(chan struct{})
+	go func() {
+		defer close(done)
+		// we don't really care what the error is here.  In the larger scenario,
+		// the client has disconnected, so we can't return any error information
+		// to them.
+		_ = s.startPTYSession(sess, cmd, ptyInfo, windowSize)
+	}()
+
+	readDone := make(chan struct{})
+	go func() {
+		defer close(readDone)
+		s := bufio.NewScanner(toClient)
+		assert.True(t, s.Scan())
+		txt := s.Text()
+		assert.Equal(t, "started", txt, "output corrupted")
+	}()
+
+	waitForChan(ctx, t, readDone, "read timeout")
+	// process is started, and should be sleeping for ~30 seconds
+
+	sessionCancel()
+
+	// now, we wait for the handler to complete.  If it does so before the
+	// main test timeout, we consider this a pass.  If not, it indicates
+	// that the server isn't properly shutting down sessions when they are
+	// disconnected client side, which could lead to processes hanging around
+	// indefinitely.
+	waitForChan(ctx, t, done, "handler timeout")
+
+	err = fromClient.Close()
+	require.NoError(t, err)
+}
+
+func waitForChan(ctx context.Context, t *testing.T, c <-chan struct{}, msg string) {
+	t.Helper()
+	select {
+	case <-c:
+		// OK!
+	case <-ctx.Done():
+		t.Fatal(msg)
+	}
+}
+
+type testSession struct {
+	ctx testSSHContext
+
+	// c2p is the client -> pty buffer
+	toPty *io.PipeReader
+	// p2c is the pty -> client buffer
+	fromPty *io.PipeWriter
+}
+
+type testSSHContext struct {
+	context.Context
+}
+
+func newTestSession(ctx context.Context) (toClient *io.PipeReader, fromClient *io.PipeWriter, s ptySession) {
+	toClient, fromPty := io.Pipe()
+	toPty, fromClient := io.Pipe()
+
+	return toClient, fromClient, &testSession{
+		ctx:     testSSHContext{ctx},
+		toPty:   toPty,
+		fromPty: fromPty,
+	}
+}
+
+func (s *testSession) Context() gliderssh.Context {
+	return s.ctx
+}
+
+func (*testSession) DisablePTYEmulation() {}
+
+// RawCommand returns "quiet logon" so that the PTY handler doesn't attempt to
+// write the message of the day, which will interfere with our tests.  It writes
+// the message of the day if it's a shell login (zero length RawCommand()).
+func (*testSession) RawCommand() string { return "quiet logon" }
+
+func (s *testSession) Read(p []byte) (n int, err error) {
+	return s.toPty.Read(p)
+}
+
+func (s *testSession) Write(p []byte) (n int, err error) {
+	return s.fromPty.Write(p)
+}
+
+func (testSSHContext) Lock() {
+	panic("not implemented")
+}
+
+func (testSSHContext) Unlock() {
+	panic("not implemented")
+}
+
+// User returns the username used when establishing the SSH connection.
+func (testSSHContext) User() string {
+	panic("not implemented")
+}
+
+// SessionID returns the session hash.
+func (testSSHContext) SessionID() string {
+	panic("not implemented")
+}
+
+// ClientVersion returns the version reported by the client.
+func (testSSHContext) ClientVersion() string {
+	panic("not implemented")
+}
+
+// ServerVersion returns the version reported by the server.
+func (testSSHContext) ServerVersion() string {
+	panic("not implemented")
+}
+
+// RemoteAddr returns the remote address for this connection.
+func (testSSHContext) RemoteAddr() net.Addr {
+	panic("not implemented")
+}
+
+// LocalAddr returns the local address for this connection.
+func (testSSHContext) LocalAddr() net.Addr {
+	panic("not implemented")
+}
+
+// Permissions returns the Permissions object used for this connection.
+func (testSSHContext) Permissions() *gliderssh.Permissions {
+	panic("not implemented")
+}
+
+// SetValue allows you to easily write new values into the underlying context.
+func (testSSHContext) SetValue(_, _ interface{}) {
+	panic("not implemented")
+}

agent/agentssh/agentssh_test.go

@@ -0,0 +1,141 @@
+// Package agentssh_test provides tests for basic functinoality of the agentssh
+// package, more test coverage can be found in the `agent` and `cli` package(s).
+package agentssh_test
+
+import (
+	"bytes"
+	"context"
+	"net"
+	"strings"
+	"sync"
+	"testing"
+
+	"github.com/spf13/afero"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"go.uber.org/atomic"
+	"go.uber.org/goleak"
+	"golang.org/x/crypto/ssh"
+
+	"cdr.dev/slog/sloggers/slogtest"
+
+	"github.com/coder/coder/agent/agentssh"
+	"github.com/coder/coder/codersdk/agentsdk"
+	"github.com/coder/coder/pty/ptytest"
+)
+
+func TestMain(m *testing.M) {
+	goleak.VerifyTestMain(m)
+}
+
+func TestNewServer_ServeClient(t *testing.T) {
+	t.Parallel()
+
+	ctx := context.Background()
+	logger := slogtest.Make(t, nil)
+	s, err := agentssh.NewServer(ctx, logger, afero.NewMemMapFs(), 0, "")
+	require.NoError(t, err)
+
+	// The assumption is that these are set before serving SSH connections.
+	s.AgentToken = func() string { return "" }
+	s.Manifest = atomic.NewPointer(&agentsdk.Manifest{})
+
+	ln, err := net.Listen("tcp", "127.0.0.1:0")
+	require.NoError(t, err)
+
+	done := make(chan struct{})
+	go func() {
+		defer close(done)
+		err := s.Serve(ln)
+		assert.Error(t, err) // Server is closed.
+	}()
+
+	c := sshClient(t, ln.Addr().String())
+
+	var b bytes.Buffer
+	sess, err := c.NewSession()
+	sess.Stdout = &b
+	require.NoError(t, err)
+	err = sess.Start("echo hello")
+	require.NoError(t, err)
+
+	err = sess.Wait()
+	require.NoError(t, err)
+
+	require.Equal(t, "hello", strings.TrimSpace(b.String()))
+
+	err = s.Close()
+	require.NoError(t, err)
+	<-done
+}
+
+func TestNewServer_CloseActiveConnections(t *testing.T) {
+	t.Parallel()
+
+	ctx := context.Background()
+	logger := slogtest.Make(t, &slogtest.Options{IgnoreErrors: true})
+	s, err := agentssh.NewServer(ctx, logger, afero.NewMemMapFs(), 0, "")
+	require.NoError(t, err)
+
+	// The assumption is that these are set before serving SSH connections.
+	s.AgentToken = func() string { return "" }
+	s.Manifest = atomic.NewPointer(&agentsdk.Manifest{})
+
+	ln, err := net.Listen("tcp", "127.0.0.1:0")
+	require.NoError(t, err)
+
+	var wg sync.WaitGroup
+	wg.Add(2)
+	go func() {
+		defer wg.Done()
+		err := s.Serve(ln)
+		assert.Error(t, err) // Server is closed.
+	}()
+
+	pty := ptytest.New(t)
+
+	doClose := make(chan struct{})
+	go func() {
+		defer wg.Done()
+		c := sshClient(t, ln.Addr().String())
+		sess, err := c.NewSession()
+		sess.Stdin = pty.Input()
+		sess.Stdout = pty.Output()
+		sess.Stderr = pty.Output()
+
+		assert.NoError(t, err)
+		err = sess.Start("")
+		assert.NoError(t, err)
+
+		close(doClose)
+		err = sess.Wait()
+		assert.Error(t, err)
+	}()
+
+	<-doClose
+	err = s.Close()
+	require.NoError(t, err)
+
+	wg.Wait()
+}
+
+func sshClient(t *testing.T, addr string) *ssh.Client {
+	conn, err := net.Dial("tcp", addr)
+	require.NoError(t, err)
+	t.Cleanup(func() {
+		_ = conn.Close()
+	})
+
+	sshConn, channels, requests, err := ssh.NewClientConn(conn, "localhost:22", &ssh.ClientConfig{
+		HostKeyCallback: ssh.InsecureIgnoreHostKey(), //nolint:gosec // This is a test.
+	})
+	require.NoError(t, err)
+	t.Cleanup(func() {
+		_ = sshConn.Close()
+	})
+	c := ssh.NewClient(sshConn, channels, requests)
+	t.Cleanup(func() {
+		_ = c.Close()
+	})
+	return c
+}

agent/agentssh/bicopy.go

@@ -0,0 +1,47 @@
+package agentssh
+
+import (
+	"context"
+	"io"
+	"sync"
+)
+
+// Bicopy copies all of the data between the two connections and will close them
+// after one or both of them are done writing. If the context is canceled, both
+// of the connections will be closed.
+func Bicopy(ctx context.Context, c1, c2 io.ReadWriteCloser) {
+	ctx, cancel := context.WithCancel(ctx)
+	defer cancel()
+
+	defer func() {
+		_ = c1.Close()
+		_ = c2.Close()
+	}()
+
+	var wg sync.WaitGroup
+	copyFunc := func(dst io.WriteCloser, src io.Reader) {
+		defer func() {
+			wg.Done()
+			// If one side of the copy fails, ensure the other one exits as
+			// well.
+			cancel()
+		}()
+		_, _ = io.Copy(dst, src)
+	}
+
+	wg.Add(2)
+	go copyFunc(c1, c2)
+	go copyFunc(c2, c1)
+
+	// Convert waitgroup to a channel so we can also wait on the context.
+	done := make(chan struct{})
+	go func() {
+		defer close(done)
+		wg.Wait()
+	}()
+
+	select {
+	case <-ctx.Done():
+	case <-done:
+	}
+}

agent/agentssh/forward.go

@@ -0,0 +1,203 @@
+package agentssh
+
+import (
+	"context"
+	"fmt"
+	"net"
+	"os"
+	"path/filepath"
+	"sync"
+
+	"github.com/gliderlabs/ssh"
+	gossh "golang.org/x/crypto/ssh"
+	"golang.org/x/xerrors"
+
+	"cdr.dev/slog"
+)
+
+// streamLocalForwardPayload describes the extra data sent in a
+// streamlocal-forward@openssh.com containing the socket path to bind to.
+type streamLocalForwardPayload struct {
+	SocketPath string
+}
+
+// forwardedStreamLocalPayload describes the data sent as the payload in the new
+// channel request when a Unix connection is accepted by the listener.
+type forwardedStreamLocalPayload struct {
+	SocketPath string
+	Reserved   uint32
+}
+
+// forwardedUnixHandler is a clone of ssh.ForwardedTCPHandler that does
+// streamlocal forwarding (aka. unix forwarding) instead of TCP forwarding.
+type forwardedUnixHandler struct {
+	sync.Mutex
+	log      slog.Logger
+	forwards map[string]net.Listener
+}
+
+func (h *forwardedUnixHandler) HandleSSHRequest(ctx ssh.Context, _ *ssh.Server, req *gossh.Request) (bool, []byte) {
+	h.Lock()
+	if h.forwards == nil {
+		h.forwards = make(map[string]net.Listener)
+	}
+	h.Unlock()
+	conn, ok := ctx.Value(ssh.ContextKeyConn).(*gossh.ServerConn)
+	if !ok {
+		h.log.Warn(ctx, "SSH unix forward request from client with no gossh connection")
+		return false, nil
+	}
+
+	switch req.Type {
+	case "streamlocal-forward@openssh.com":
+		var reqPayload streamLocalForwardPayload
+		err := gossh.Unmarshal(req.Payload, &reqPayload)
+		if err != nil {
+			h.log.Warn(ctx, "parse streamlocal-forward@openssh.com request payload from client", slog.Error(err))
+			return false, nil
+		}
+
+		addr := reqPayload.SocketPath
+		h.Lock()
+		_, ok := h.forwards[addr]
+		h.Unlock()
+		if ok {
+			h.log.Warn(ctx, "SSH unix forward request for socket path that is already being forwarded (maybe to another client?)",
+				slog.F("socket_path", addr),
+			)
+			return false, nil
+		}
+
+		// Create socket parent dir if not exists.
+		parentDir := filepath.Dir(addr)
+		err = os.MkdirAll(parentDir, 0o700)
+		if err != nil {
+			h.log.Warn(ctx, "create parent dir for SSH unix forward request",
+				slog.F("parent_dir", parentDir),
+				slog.F("socket_path", addr),
+				slog.Error(err),
+			)
+			return false, nil
+		}
+
+		ln, err := net.Listen("unix", addr)
+		if err != nil {
+			h.log.Warn(ctx, "listen on Unix socket for SSH unix forward request",
+				slog.F("socket_path", addr),
+				slog.Error(err),
+			)
+			return false, nil
+		}
+
+		// The listener needs to successfully start before it can be added to
+		// the map, so we don't have to worry about checking for an existing
+		// listener.
+		//
+		// This is also what the upstream TCP version of this code does.
+		h.Lock()
+		h.forwards[addr] = ln
+		h.Unlock()
+
+		ctx, cancel := context.WithCancel(ctx)
+		go func() {
+			<-ctx.Done()
+			_ = ln.Close()
+		}()
+		go func() {
+			defer cancel()
+
+			for {
+				c, err := ln.Accept()
+				if err != nil {
+					if !xerrors.Is(err, net.ErrClosed) {
+						h.log.Warn(ctx, "accept on local Unix socket for SSH unix forward request",
+							slog.F("socket_path", addr),
+							slog.Error(err),
+						)
+					}
+					// closed below
+					break
+				}
+				payload := gossh.Marshal(&forwardedStreamLocalPayload{
+					SocketPath: addr,
+				})
+
+				go func() {
+					ch, reqs, err := conn.OpenChannel("forwarded-streamlocal@openssh.com", payload)
+					if err != nil {
+						h.log.Warn(ctx, "open SSH channel to forward Unix connection to client",
+							slog.F("socket_path", addr),
+							slog.Error(err),
+						)
+						_ = c.Close()
+						return
+					}
+					go gossh.DiscardRequests(reqs)
+					Bicopy(ctx, ch, c)
+				}()
+			}
+
+			h.Lock()
+			ln2, ok := h.forwards[addr]
+			if ok && ln2 == ln {
+				delete(h.forwards, addr)
+			}
+			h.Unlock()
+			_ = ln.Close()
+		}()
+
+		return true, nil
+
+	case "cancel-streamlocal-forward@openssh.com":
+		var reqPayload streamLocalForwardPayload
+		err := gossh.Unmarshal(req.Payload, &reqPayload)
+		if err != nil {
+			h.log.Warn(ctx, "parse cancel-streamlocal-forward@openssh.com request payload from client", slog.Error(err))
+			return false, nil
+		}
+		h.Lock()
+		ln, ok := h.forwards[reqPayload.SocketPath]
+		h.Unlock()
+		if ok {
+			_ = ln.Close()
+		}
+		return true, nil
+
+	default:
+		return false, nil
+	}
+}
+
+// directStreamLocalPayload describes the extra data sent in a
+// direct-streamlocal@openssh.com channel request containing the socket path.
+type directStreamLocalPayload struct {
+	SocketPath string
+
+	Reserved1 string
+	Reserved2 uint32
+}
+
+func directStreamLocalHandler(_ *ssh.Server, _ *gossh.ServerConn, newChan gossh.NewChannel, ctx ssh.Context) {
+	var reqPayload directStreamLocalPayload
+	err := gossh.Unmarshal(newChan.ExtraData(), &reqPayload)
+	if err != nil {
+		_ = newChan.Reject(gossh.ConnectionFailed, "could not parse direct-streamlocal@openssh.com channel payload")
+		return
+	}
+
+	var dialer net.Dialer
+	dconn, err := dialer.DialContext(ctx, "unix", reqPayload.SocketPath)
+	if err != nil {
+		_ = newChan.Reject(gossh.ConnectionFailed, fmt.Sprintf("dial unix socket %q: %+v", reqPayload.SocketPath, err.Error()))
+		return
+	}
+
+	ch, reqs, err := newChan.Accept()
+	if err != nil {
+		_ = dconn.Close()
+		return
+	}
+	go gossh.DiscardRequests(reqs)
+
+	Bicopy(ctx, ch, dconn)
+}

agent/agentssh/x11.go

@@ -0,0 +1,197 @@
+package agentssh
+
+import (
+	"context"
+	"encoding/binary"
+	"encoding/hex"
+	"errors"
+	"fmt"
+	"net"
+	"os"
+	"path/filepath"
+	"strconv"
+	"time"
+
+	"github.com/gliderlabs/ssh"
+	"github.com/gofrs/flock"
+	"github.com/spf13/afero"
+	gossh "golang.org/x/crypto/ssh"
+	"golang.org/x/xerrors"
+
+	"cdr.dev/slog"
+)
+
+// x11Callback is called when the client requests X11 forwarding.
+// It adds an Xauthority entry to the Xauthority file.
+func (s *Server) x11Callback(ctx ssh.Context, x11 ssh.X11) bool {
+	hostname, err := os.Hostname()
+	if err != nil {
+		s.logger.Warn(ctx, "failed to get hostname", slog.Error(err))
+		return false
+	}
+
+	err = s.fs.MkdirAll(s.x11SocketDir, 0o700)
+	if err != nil {
+		s.logger.Warn(ctx, "failed to make the x11 socket dir", slog.F("dir", s.x11SocketDir), slog.Error(err))
+		return false
+	}
+
+	err = addXauthEntry(ctx, s.fs, hostname, strconv.Itoa(int(x11.ScreenNumber)), x11.AuthProtocol, x11.AuthCookie)
+	if err != nil {
+		s.logger.Warn(ctx, "failed to add Xauthority entry", slog.Error(err))
+		return false
+	}
+	return true
+}
+
+// x11Handler is called when a session has requested X11 forwarding.
+// It listens for X11 connections and forwards them to the client.
+func (s *Server) x11Handler(ctx ssh.Context, x11 ssh.X11) bool {
+	serverConn, valid := ctx.Value(ssh.ContextKeyConn).(*gossh.ServerConn)
+	if !valid {
+		s.logger.Warn(ctx, "failed to get server connection")
+		return false
+	}
+	// We want to overwrite the socket so that subsequent connections will succeed.
+	socketPath := filepath.Join(s.x11SocketDir, fmt.Sprintf("X%d", x11.ScreenNumber))
+	err := os.Remove(socketPath)
+	if err != nil && !errors.Is(err, os.ErrNotExist) {
+		s.logger.Warn(ctx, "failed to remove existing X11 socket", slog.Error(err))
+		return false
+	}
+	listener, err := net.Listen("unix", socketPath)
+	if err != nil {
+		s.logger.Warn(ctx, "failed to listen for X11", slog.Error(err))
+		return false
+	}
+	s.trackListener(listener, true)
+
+	go func() {
+		defer listener.Close()
+		defer s.trackListener(listener, false)
+		handledFirstConnection := false
+
+		for {
+			conn, err := listener.Accept()
+			if err != nil {
+				if errors.Is(err, net.ErrClosed) {
+					return
+				}
+				s.logger.Warn(ctx, "failed to accept X11 connection", slog.Error(err))
+				return
+			}
+			if x11.SingleConnection && handledFirstConnection {
+				s.logger.Warn(ctx, "X11 connection rejected because single connection is enabled")
+				_ = conn.Close()
+				continue
+			}
+			handledFirstConnection = true
+
+			unixConn, ok := conn.(*net.UnixConn)
+			if !ok {
+				s.logger.Warn(ctx, fmt.Sprintf("failed to cast connection to UnixConn. got: %T", conn))
+				return
+			}
+			unixAddr, ok := unixConn.LocalAddr().(*net.UnixAddr)
+			if !ok {
+				s.logger.Warn(ctx, fmt.Sprintf("failed to cast local address to UnixAddr. got: %T", unixConn.LocalAddr()))
+				return
+			}
+
+			channel, reqs, err := serverConn.OpenChannel("x11", gossh.Marshal(struct {
+				OriginatorAddress string
+				OriginatorPort    uint32
+			}{
+				OriginatorAddress: unixAddr.Name,
+				OriginatorPort:    0,
+			}))
+			if err != nil {
+				s.logger.Warn(ctx, "failed to open X11 channel", slog.Error(err))
+				return
+			}
+			go gossh.DiscardRequests(reqs)
+			go Bicopy(ctx, conn, channel)
+		}
+	}()
+	return true
+}
+
+// addXauthEntry adds an Xauthority entry to the Xauthority file.
+// The Xauthority file is located at ~/.Xauthority.
+func addXauthEntry(ctx context.Context, fs afero.Fs, host string, display string, authProtocol string, authCookie string) error {
+	// Get the Xauthority file path
+	homeDir, err := os.UserHomeDir()
+	if err != nil {
+		return xerrors.Errorf("failed to get user home directory: %w", err)
+	}
+
+	xauthPath := filepath.Join(homeDir, ".Xauthority")
+
+	lock := flock.New(xauthPath)
+	defer lock.Close()
+	ok, err := lock.TryLockContext(ctx, 100*time.Millisecond)
+	if !ok {
+		return xerrors.Errorf("failed to lock Xauthority file: %w", err)
+	}
+	if err != nil {
+		return xerrors.Errorf("failed to lock Xauthority file: %w", err)
+	}
+
+	// Open or create the Xauthority file
+	file, err := fs.OpenFile(xauthPath, os.O_RDWR|os.O_CREATE|os.O_APPEND, 0o600)
+	if err != nil {
+		return xerrors.Errorf("failed to open Xauthority file: %w", err)
+	}
+	defer file.Close()
+
+	// Convert the authCookie from hex string to byte slice
+	authCookieBytes, err := hex.DecodeString(authCookie)
+	if err != nil {
+		return xerrors.Errorf("failed to decode auth cookie: %w", err)
+	}
+
+	// Write Xauthority entry
+	family := uint16(0x0100) // FamilyLocal
+	err = binary.Write(file, binary.BigEndian, family)
+	if err != nil {
+		return xerrors.Errorf("failed to write family: %w", err)
+	}
+
+	err = binary.Write(file, binary.BigEndian, uint16(len(host)))
+	if err != nil {
+		return xerrors.Errorf("failed to write host length: %w", err)
+	}
+	_, err = file.WriteString(host)
+	if err != nil {
+		return xerrors.Errorf("failed to write host: %w", err)
+	}
+
+	err = binary.Write(file, binary.BigEndian, uint16(len(display)))
+	if err != nil {
+		return xerrors.Errorf("failed to write display length: %w", err)
+	}
+	_, err = file.WriteString(display)
+	if err != nil {
+		return xerrors.Errorf("failed to write display: %w", err)
+	}
+
+	err = binary.Write(file, binary.BigEndian, uint16(len(authProtocol)))
+	if err != nil {
+		return xerrors.Errorf("failed to write auth protocol length: %w", err)
+	}
+	_, err = file.WriteString(authProtocol)
+	if err != nil {
+		return xerrors.Errorf("failed to write auth protocol: %w", err)
+	}
+
+	err = binary.Write(file, binary.BigEndian, uint16(len(authCookieBytes)))
+	if err != nil {
+		return xerrors.Errorf("failed to write auth cookie length: %w", err)
+	}
+	_, err = file.Write(authCookieBytes)
+	if err != nil {
+		return xerrors.Errorf("failed to write auth cookie: %w", err)
+	}
+
+	return nil
+}

agent/agentssh/x11_test.go

@@ -0,0 +1,99 @@
+package agentssh_test
+
+import (
+	"context"
+	"encoding/hex"
+	"net"
+	"os"
+	"path/filepath"
+	"runtime"
+	"testing"
+
+	"github.com/gliderlabs/ssh"
+	"github.com/spf13/afero"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"go.uber.org/atomic"
+	gossh "golang.org/x/crypto/ssh"
+
+	"cdr.dev/slog"
+	"cdr.dev/slog/sloggers/slogtest"
+	"github.com/coder/coder/agent/agentssh"
+	"github.com/coder/coder/codersdk/agentsdk"
+	"github.com/coder/coder/testutil"
+)
+
+func TestServer_X11(t *testing.T) {
+	t.Parallel()
+	if runtime.GOOS != "linux" {
+		t.Skip("X11 forwarding is only supported on Linux")
+	}
+
+	ctx := context.Background()
+	logger := slogtest.Make(t, nil).Leveled(slog.LevelDebug)
+	fs := afero.NewOsFs()
+	dir := t.TempDir()
+	s, err := agentssh.NewServer(ctx, logger, fs, 0, dir)
+	require.NoError(t, err)
+	defer s.Close()
+
+	// The assumption is that these are set before serving SSH connections.
+	s.AgentToken = func() string { return "" }
+	s.Manifest = atomic.NewPointer(&agentsdk.Manifest{})
+
+	ln, err := net.Listen("tcp", "127.0.0.1:0")
+	require.NoError(t, err)
+
+	done := make(chan struct{})
+	go func() {
+		defer close(done)
+		err := s.Serve(ln)
+		assert.Error(t, err) // Server is closed.
+	}()
+
+	c := sshClient(t, ln.Addr().String())
+
+	sess, err := c.NewSession()
+	require.NoError(t, err)
+
+	reply, err := sess.SendRequest("x11-req", true, gossh.Marshal(ssh.X11{
+		AuthProtocol: "MIT-MAGIC-COOKIE-1",
+		AuthCookie:   hex.EncodeToString([]byte("cookie")),
+		ScreenNumber: 0,
+	}))
+	require.NoError(t, err)
+	assert.True(t, reply)
+
+	err = sess.Shell()
+	require.NoError(t, err)
+
+	x11Chans := c.HandleChannelOpen("x11")
+	payload := "hello world"
+	require.Eventually(t, func() bool {
+		conn, err := net.Dial("unix", filepath.Join(dir, "X0"))
+		if err == nil {
+			_, err = conn.Write([]byte(payload))
+			assert.NoError(t, err)
+			_ = conn.Close()
+		}
+		return err == nil
+	}, testutil.WaitShort, testutil.IntervalFast)
+
+	x11 := <-x11Chans
+	ch, reqs, err := x11.Accept()
+	require.NoError(t, err)
+	go gossh.DiscardRequests(reqs)
+	got := make([]byte, len(payload))
+	_, err = ch.Read(got)
+	require.NoError(t, err)
+	assert.Equal(t, payload, string(got))
+	_ = ch.Close()
+	_ = s.Close()
+	<-done
+
+	// Ensure the Xauthority file was written!
+	home, err := os.UserHomeDir()
+	require.NoError(t, err)
+	_, err = fs.Stat(filepath.Join(home, ".Xauthority"))
+	require.NoError(t, err)
+}

agent/api.go

@@ -11,7 +11,7 @@ import (
 	"github.com/coder/coder/codersdk"
 )
 
-func (*agent) statisticsHandler() http.Handler {
+func (a *agent) apiHandler() http.Handler {
 	r := chi.NewRouter()
 	r.Get("/", func(rw http.ResponseWriter, r *http.Request) {
 		httpapi.Write(r.Context(), rw, http.StatusOK, codersdk.Response{
@@ -19,16 +19,24 @@ func (*agent) statisticsHandler() http.Handler {
 		})
 	})
 
-	lp := &listeningPortsHandler{}
+	// Make a copy to ensure the map is not modified after the handler is
+	// created.
+	cpy := make(map[int]string)
+	for k, b := range a.ignorePorts {
+		cpy[k] = b
+	}
+
+	lp := &listeningPortsHandler{ignorePorts: cpy}
 	r.Get("/api/v0/listening-ports", lp.handler)
 
 	return r
 }
 
 type listeningPortsHandler struct {
-	mut   sync.Mutex
-	ports []codersdk.ListeningPort
-	mtime time.Time
+	mut         sync.Mutex
+	ports       []codersdk.WorkspaceAgentListeningPort
+	mtime       time.Time
+	ignorePorts map[int]string
 }
 
 // handler returns a list of listening ports. This is tested by coderd's
@@ -43,7 +51,7 @@ func (lp *listeningPortsHandler) handler(rw http.ResponseWriter, r *http.Request
 		return
 	}
 
-	httpapi.Write(r.Context(), rw, http.StatusOK, codersdk.ListeningPortsResponse{
+	httpapi.Write(r.Context(), rw, http.StatusOK, codersdk.WorkspaceAgentListeningPortsResponse{
 		Ports: ports,
 	})
 }

agent/apphealth.go

@@ -6,10 +6,12 @@ import (
 	"sync"
 	"time"
 
+	"github.com/google/uuid"
 	"golang.org/x/xerrors"
 
 	"cdr.dev/slog"
 	"github.com/coder/coder/codersdk"
+	"github.com/coder/coder/codersdk/agentsdk"
 	"github.com/coder/retry"
 )
 
@@ -17,34 +19,27 @@ import (
 type WorkspaceAgentApps func(context.Context) ([]codersdk.WorkspaceApp, error)
 
 // PostWorkspaceAgentAppHealth updates the workspace app health.
-type PostWorkspaceAgentAppHealth func(context.Context, codersdk.PostWorkspaceAppHealthsRequest) error
+type PostWorkspaceAgentAppHealth func(context.Context, agentsdk.PostAppHealthsRequest) error
 
 // WorkspaceAppHealthReporter is a function that checks and reports the health of the workspace apps until the passed context is canceled.
 type WorkspaceAppHealthReporter func(ctx context.Context)
 
 // NewWorkspaceAppHealthReporter creates a WorkspaceAppHealthReporter that reports app health to coderd.
-func NewWorkspaceAppHealthReporter(logger slog.Logger, workspaceAgentApps WorkspaceAgentApps, postWorkspaceAgentAppHealth PostWorkspaceAgentAppHealth) WorkspaceAppHealthReporter {
+func NewWorkspaceAppHealthReporter(logger slog.Logger, apps []codersdk.WorkspaceApp, postWorkspaceAgentAppHealth PostWorkspaceAgentAppHealth) WorkspaceAppHealthReporter {
 	runHealthcheckLoop := func(ctx context.Context) error {
-		apps, err := workspaceAgentApps(ctx)
-		if err != nil {
-			if xerrors.Is(err, context.Canceled) {
-				return nil
-			}
-			return xerrors.Errorf("getting workspace apps: %w", err)
-		}
-
 		// no need to run this loop if no apps for this workspace.
 		if len(apps) == 0 {
 			return nil
 		}
 
 		hasHealthchecksEnabled := false
-		health := make(map[string]codersdk.WorkspaceAppHealth, 0)
+		health := make(map[uuid.UUID]codersdk.WorkspaceAppHealth, 0)
 		for _, app := range apps {
-			health[app.Name] = app.Health
-			if !hasHealthchecksEnabled && app.Health != codersdk.WorkspaceAppHealthDisabled {
-				hasHealthchecksEnabled = true
+			if app.Health == codersdk.WorkspaceAppHealthDisabled {
+				continue
 			}
+			health[app.ID] = app.Health
+			hasHealthchecksEnabled = true
 		}
 
 		// no need to run this loop if no health checks are configured.
@@ -54,14 +49,16 @@ func NewWorkspaceAppHealthReporter(logger slog.Logger, workspaceAgentApps Worksp
 
 		// run a ticker for each app health check.
 		var mu sync.RWMutex
-		failures := make(map[string]int, 0)
+		failures := make(map[uuid.UUID]int, 0)
 		for _, nextApp := range apps {
 			if !shouldStartTicker(nextApp) {
 				continue
 			}
 			app := nextApp
-			t := time.NewTicker(time.Duration(app.Healthcheck.Interval) * time.Second)
 			go func() {
+				t := time.NewTicker(time.Duration(app.Healthcheck.Interval) * time.Second)
+				defer t.Stop()
+
 				for {
 					select {
 					case <-ctx.Done():
@@ -82,7 +79,7 @@ func NewWorkspaceAppHealthReporter(logger slog.Logger, workspaceAgentApps Worksp
 							return err
 						}
 						// successful healthcheck is a non-5XX status code
-						res.Body.Close()
+						_ = res.Body.Close()
 						if res.StatusCode >= http.StatusInternalServerError {
 							return xerrors.Errorf("error status code: %d", res.StatusCode)
 						}
@@ -91,21 +88,21 @@ func NewWorkspaceAppHealthReporter(logger slog.Logger, workspaceAgentApps Worksp
 					}()
 					if err != nil {
 						mu.Lock()
-						if failures[app.Name] < int(app.Healthcheck.Threshold) {
+						if failures[app.ID] < int(app.Healthcheck.Threshold) {
 							// increment the failure count and keep status the same.
 							// we will change it when we hit the threshold.
-							failures[app.Name]++
+							failures[app.ID]++
 						} else {
 							// set to unhealthy if we hit the failure threshold.
 							// we stop incrementing at the threshold to prevent the failure value from increasing forever.
-							health[app.Name] = codersdk.WorkspaceAppHealthUnhealthy
+							health[app.ID] = codersdk.WorkspaceAppHealthUnhealthy
 						}
 						mu.Unlock()
 					} else {
 						mu.Lock()
 						// we only need one successful health check to be considered healthy.
-						health[app.Name] = codersdk.WorkspaceAppHealthHealthy
-						failures[app.Name] = 0
+						health[app.ID] = codersdk.WorkspaceAppHealthHealthy
+						failures[app.ID] = 0
 						mu.Unlock()
 					}
 
@@ -118,6 +115,7 @@ func NewWorkspaceAppHealthReporter(logger slog.Logger, workspaceAgentApps Worksp
 		lastHealth := copyHealth(health)
 		mu.Unlock()
 		reportTicker := time.NewTicker(time.Second)
+		defer reportTicker.Stop()
 		// every second we check if the health values of the apps have changed
 		// and if there is a change we will report the new values.
 		for {
@@ -135,7 +133,7 @@ func NewWorkspaceAppHealthReporter(logger slog.Logger, workspaceAgentApps Worksp
 				mu.Lock()
 				lastHealth = copyHealth(health)
 				mu.Unlock()
-				err := postWorkspaceAgentAppHealth(ctx, codersdk.PostWorkspaceAppHealthsRequest{
+				err := postWorkspaceAgentAppHealth(ctx, agentsdk.PostAppHealthsRequest{
 					Healths: lastHealth,
 				})
 				if err != nil {
@@ -160,7 +158,7 @@ func shouldStartTicker(app codersdk.WorkspaceApp) bool {
 	return app.Healthcheck.URL != "" && app.Healthcheck.Interval > 0 && app.Healthcheck.Threshold > 0
 }
 
-func healthChanged(old map[string]codersdk.WorkspaceAppHealth, new map[string]codersdk.WorkspaceAppHealth) bool {
+func healthChanged(old map[uuid.UUID]codersdk.WorkspaceAppHealth, new map[uuid.UUID]codersdk.WorkspaceAppHealth) bool {
 	for name, newValue := range new {
 		oldValue, found := old[name]
 		if !found {
@@ -174,8 +172,8 @@ func healthChanged(old map[string]codersdk.WorkspaceAppHealth, new map[string]co
 	return false
 }
 
-func copyHealth(h1 map[string]codersdk.WorkspaceAppHealth) map[string]codersdk.WorkspaceAppHealth {
-	h2 := make(map[string]codersdk.WorkspaceAppHealth, 0)
+func copyHealth(h1 map[uuid.UUID]codersdk.WorkspaceAppHealth) map[uuid.UUID]codersdk.WorkspaceAppHealth {
+	h2 := make(map[uuid.UUID]codersdk.WorkspaceAppHealth, 0)
 	for k, v := range h1 {
 		h2[k] = v
 	}

agent/apphealth_test.go

@@ -16,151 +16,149 @@ import (
 	"github.com/coder/coder/agent"
 	"github.com/coder/coder/coderd/httpapi"
 	"github.com/coder/coder/codersdk"
+	"github.com/coder/coder/codersdk/agentsdk"
 	"github.com/coder/coder/testutil"
 )
 
-func TestAppHealth(t *testing.T) {
+func TestAppHealth_Healthy(t *testing.T) {
 	t.Parallel()
-	t.Run("Healthy", func(t *testing.T) {
-		t.Parallel()
-		ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitLong)
-		defer cancel()
-		apps := []codersdk.WorkspaceApp{
-			{
-				Name:        "app1",
-				Healthcheck: codersdk.Healthcheck{},
-				Health:      codersdk.WorkspaceAppHealthDisabled,
+	ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitLong)
+	defer cancel()
+	apps := []codersdk.WorkspaceApp{
+		{
+			Slug:        "app1",
+			Healthcheck: codersdk.Healthcheck{},
+			Health:      codersdk.WorkspaceAppHealthDisabled,
+		},
+		{
+			Slug: "app2",
+			Healthcheck: codersdk.Healthcheck{
+				// URL: We don't set the URL for this test because the setup will
+				// create a httptest server for us and set it for us.
+				Interval:  1,
+				Threshold: 1,
 			},
-			{
-				Name: "app2",
-				Healthcheck: codersdk.Healthcheck{
-					// URL: We don't set the URL for this test because the setup will
-					// create a httptest server for us and set it for us.
-					Interval:  1,
-					Threshold: 1,
-				},
-				Health: codersdk.WorkspaceAppHealthInitializing,
-			},
-		}
-		handlers := []http.Handler{
-			nil,
-			http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-				httpapi.Write(r.Context(), w, http.StatusOK, nil)
-			}),
-		}
-		getApps, closeFn := setupAppReporter(ctx, t, apps, handlers)
-		defer closeFn()
+			Health: codersdk.WorkspaceAppHealthInitializing,
+		},
+	}
+	handlers := []http.Handler{
+		nil,
+		http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			httpapi.Write(r.Context(), w, http.StatusOK, nil)
+		}),
+	}
+	getApps, closeFn := setupAppReporter(ctx, t, apps, handlers)
+	defer closeFn()
+	apps, err := getApps(ctx)
+	require.NoError(t, err)
+	require.EqualValues(t, codersdk.WorkspaceAppHealthDisabled, apps[0].Health)
+	require.Eventually(t, func() bool {
 		apps, err := getApps(ctx)
-		require.NoError(t, err)
-		require.EqualValues(t, codersdk.WorkspaceAppHealthDisabled, apps[0].Health)
-		require.Eventually(t, func() bool {
-			apps, err := getApps(ctx)
-			if err != nil {
-				return false
-			}
+		if err != nil {
+			return false
+		}
 
-			return apps[1].Health == codersdk.WorkspaceAppHealthHealthy
-		}, testutil.WaitLong, testutil.IntervalSlow)
-	})
+		return apps[1].Health == codersdk.WorkspaceAppHealthHealthy
+	}, testutil.WaitLong, testutil.IntervalSlow)
+}
 
-	t.Run("500", func(t *testing.T) {
-		t.Parallel()
-		ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitLong)
-		defer cancel()
-		apps := []codersdk.WorkspaceApp{
-			{
-				Name: "app2",
-				Healthcheck: codersdk.Healthcheck{
-					// URL: We don't set the URL for this test because the setup will
-					// create a httptest server for us and set it for us.
-					Interval:  1,
-					Threshold: 1,
-				},
-				Health: codersdk.WorkspaceAppHealthInitializing,
+func TestAppHealth_500(t *testing.T) {
+	t.Parallel()
+	ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitLong)
+	defer cancel()
+	apps := []codersdk.WorkspaceApp{
+		{
+			Slug: "app2",
+			Healthcheck: codersdk.Healthcheck{
+				// URL: We don't set the URL for this test because the setup will
+				// create a httptest server for us and set it for us.
+				Interval:  1,
+				Threshold: 1,
 			},
+			Health: codersdk.WorkspaceAppHealthInitializing,
+		},
+	}
+	handlers := []http.Handler{
+		http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			httpapi.Write(r.Context(), w, http.StatusInternalServerError, nil)
+		}),
+	}
+	getApps, closeFn := setupAppReporter(ctx, t, apps, handlers)
+	defer closeFn()
+	require.Eventually(t, func() bool {
+		apps, err := getApps(ctx)
+		if err != nil {
+			return false
 		}
-		handlers := []http.Handler{
-			http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-				httpapi.Write(r.Context(), w, http.StatusInternalServerError, nil)
-			}),
-		}
-		getApps, closeFn := setupAppReporter(ctx, t, apps, handlers)
-		defer closeFn()
-		require.Eventually(t, func() bool {
-			apps, err := getApps(ctx)
-			if err != nil {
-				return false
-			}
 
-			return apps[0].Health == codersdk.WorkspaceAppHealthUnhealthy
-		}, testutil.WaitLong, testutil.IntervalSlow)
-	})
+		return apps[0].Health == codersdk.WorkspaceAppHealthUnhealthy
+	}, testutil.WaitLong, testutil.IntervalSlow)
+}
 
-	t.Run("Timeout", func(t *testing.T) {
-		t.Parallel()
-		ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitLong)
-		defer cancel()
-		apps := []codersdk.WorkspaceApp{
-			{
-				Name: "app2",
-				Healthcheck: codersdk.Healthcheck{
-					// URL: We don't set the URL for this test because the setup will
-					// create a httptest server for us and set it for us.
-					Interval:  1,
-					Threshold: 1,
-				},
-				Health: codersdk.WorkspaceAppHealthInitializing,
+func TestAppHealth_Timeout(t *testing.T) {
+	t.Parallel()
+	ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitLong)
+	defer cancel()
+	apps := []codersdk.WorkspaceApp{
+		{
+			Slug: "app2",
+			Healthcheck: codersdk.Healthcheck{
+				// URL: We don't set the URL for this test because the setup will
+				// create a httptest server for us and set it for us.
+				Interval:  1,
+				Threshold: 1,
 			},
+			Health: codersdk.WorkspaceAppHealthInitializing,
+		},
+	}
+	handlers := []http.Handler{
+		http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			// sleep longer than the interval to cause the health check to time out
+			time.Sleep(2 * time.Second)
+			httpapi.Write(r.Context(), w, http.StatusOK, nil)
+		}),
+	}
+	getApps, closeFn := setupAppReporter(ctx, t, apps, handlers)
+	defer closeFn()
+	require.Eventually(t, func() bool {
+		apps, err := getApps(ctx)
+		if err != nil {
+			return false
 		}
-		handlers := []http.Handler{
-			http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-				// sleep longer than the interval to cause the health check to time out
-				time.Sleep(2 * time.Second)
-				httpapi.Write(r.Context(), w, http.StatusOK, nil)
-			}),
-		}
-		getApps, closeFn := setupAppReporter(ctx, t, apps, handlers)
-		defer closeFn()
-		require.Eventually(t, func() bool {
-			apps, err := getApps(ctx)
-			if err != nil {
-				return false
-			}
 
-			return apps[0].Health == codersdk.WorkspaceAppHealthUnhealthy
-		}, testutil.WaitLong, testutil.IntervalSlow)
-	})
+		return apps[0].Health == codersdk.WorkspaceAppHealthUnhealthy
+	}, testutil.WaitLong, testutil.IntervalSlow)
+}
 
-	t.Run("NotSpamming", func(t *testing.T) {
-		t.Parallel()
-		ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitLong)
-		defer cancel()
-		apps := []codersdk.WorkspaceApp{
-			{
-				Name: "app2",
-				Healthcheck: codersdk.Healthcheck{
-					// URL: We don't set the URL for this test because the setup will
-					// create a httptest server for us and set it for us.
-					Interval:  1,
-					Threshold: 1,
-				},
-				Health: codersdk.WorkspaceAppHealthInitializing,
+func TestAppHealth_NotSpamming(t *testing.T) {
+	t.Parallel()
+	ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitLong)
+	defer cancel()
+	apps := []codersdk.WorkspaceApp{
+		{
+			Slug: "app2",
+			Healthcheck: codersdk.Healthcheck{
+				// URL: We don't set the URL for this test because the setup will
+				// create a httptest server for us and set it for us.
+				Interval:  1,
+				Threshold: 1,
 			},
-		}
+			Health: codersdk.WorkspaceAppHealthInitializing,
+		},
+	}
 
-		var counter = new(int32)
-		handlers := []http.Handler{
-			http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-				atomic.AddInt32(counter, 1)
-			}),
-		}
-		_, closeFn := setupAppReporter(ctx, t, apps, handlers)
-		defer closeFn()
-		// Ensure we haven't made more than 2 (expected 1 + 1 for buffer) requests in the last second.
-		// if there is a bug where we are spamming the healthcheck route this will catch it.
-		time.Sleep(time.Second)
-		require.LessOrEqual(t, *counter, int32(2))
-	})
+	counter := new(int32)
+	handlers := []http.Handler{
+		http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			atomic.AddInt32(counter, 1)
+		}),
+	}
+	_, closeFn := setupAppReporter(ctx, t, apps, handlers)
+	defer closeFn()
+	// Ensure we haven't made more than 2 (expected 1 + 1 for buffer) requests in the last second.
+	// if there is a bug where we are spamming the healthcheck route this will catch it.
+	time.Sleep(time.Second)
+	require.LessOrEqual(t, atomic.LoadInt32(counter), int32(2))
 }
 
 func setupAppReporter(ctx context.Context, t *testing.T, apps []codersdk.WorkspaceApp, handlers []http.Handler) (agent.WorkspaceAgentApps, func()) {
@@ -183,11 +181,11 @@ func setupAppReporter(ctx context.Context, t *testing.T, apps []codersdk.Workspa
 		var newApps []codersdk.WorkspaceApp
 		return append(newApps, apps...), nil
 	}
-	postWorkspaceAgentAppHealth := func(_ context.Context, req codersdk.PostWorkspaceAppHealthsRequest) error {
+	postWorkspaceAgentAppHealth := func(_ context.Context, req agentsdk.PostAppHealthsRequest) error {
 		mu.Lock()
-		for name, health := range req.Healths {
+		for id, health := range req.Healths {
 			for i, app := range apps {
-				if app.Name != name {
+				if app.ID != id {
 					continue
 				}
 				app.Health = health
@@ -199,7 +197,7 @@ func setupAppReporter(ctx context.Context, t *testing.T, apps []codersdk.Workspa
 		return nil
 	}
 
-	go agent.NewWorkspaceAppHealthReporter(slogtest.Make(t, nil).Leveled(slog.LevelDebug), workspaceAgentApps, postWorkspaceAgentAppHealth)(ctx)
+	go agent.NewWorkspaceAppHealthReporter(slogtest.Make(t, nil).Leveled(slog.LevelDebug), apps, postWorkspaceAgentAppHealth)(ctx)
 
 	return workspaceAgentApps, func() {
 		for _, closeFn := range closers {

agent/metrics.go

@@ -0,0 +1,52 @@
+package agent
+
+import (
+	"fmt"
+	"strings"
+
+	"tailscale.com/util/clientmetric"
+
+	"github.com/coder/coder/codersdk/agentsdk"
+)
+
+func collectMetrics() []agentsdk.AgentMetric {
+	// Tailscale metrics
+	metrics := clientmetric.Metrics()
+	collected := make([]agentsdk.AgentMetric, 0, len(metrics))
+	for _, m := range metrics {
+		if isIgnoredMetric(m.Name()) {
+			continue
+		}
+
+		collected = append(collected, agentsdk.AgentMetric{
+			Name:  m.Name(),
+			Type:  asMetricType(m.Type()),
+			Value: float64(m.Value()),
+		})
+	}
+	return collected
+}
+
+// isIgnoredMetric checks if the metric should be ignored, as Coder agent doesn't use related features.
+// Expected metric families: magicsock_*, derp_*, tstun_*, netcheck_*, portmap_*, etc.
+func isIgnoredMetric(metricName string) bool {
+	if strings.HasPrefix(metricName, "dns_") ||
+		strings.HasPrefix(metricName, "controlclient_") ||
+		strings.HasPrefix(metricName, "peerapi_") ||
+		strings.HasPrefix(metricName, "profiles_") ||
+		strings.HasPrefix(metricName, "tstun_") {
+		return true
+	}
+	return false
+}
+
+func asMetricType(typ clientmetric.Type) agentsdk.AgentMetricType {
+	switch typ {
+	case clientmetric.TypeGauge:
+		return agentsdk.AgentMetricTypeGauge
+	case clientmetric.TypeCounter:
+		return agentsdk.AgentMetricTypeCounter
+	default:
+		panic(fmt.Sprintf("unknown metric type: %d", typ))
+	}
+}

agent/ports_supported.go

@@ -11,13 +11,13 @@ import (
 	"github.com/coder/coder/codersdk"
 )
 
-func (lp *listeningPortsHandler) getListeningPorts() ([]codersdk.ListeningPort, error) {
+func (lp *listeningPortsHandler) getListeningPorts() ([]codersdk.WorkspaceAgentListeningPort, error) {
 	lp.mut.Lock()
 	defer lp.mut.Unlock()
 
 	if time.Since(lp.mtime) < time.Second {
 		// copy
-		ports := make([]codersdk.ListeningPort, len(lp.ports))
+		ports := make([]codersdk.WorkspaceAgentListeningPort, len(lp.ports))
 		copy(ports, lp.ports)
 		return ports, nil
 	}
@@ -30,9 +30,14 @@ func (lp *listeningPortsHandler) getListeningPorts() ([]codersdk.ListeningPort,
 	}
 
 	seen := make(map[uint16]struct{}, len(tabs))
-	ports := []codersdk.ListeningPort{}
+	ports := []codersdk.WorkspaceAgentListeningPort{}
 	for _, tab := range tabs {
-		if tab.LocalAddr == nil || tab.LocalAddr.Port < uint16(codersdk.MinimumListeningPort) {
+		if tab.LocalAddr == nil || tab.LocalAddr.Port < codersdk.WorkspaceAgentMinimumListeningPort {
+			continue
+		}
+
+		// Ignore ports that we've been told to ignore.
+		if _, ok := lp.ignorePorts[int(tab.LocalAddr.Port)]; ok {
 			continue
 		}
 
@@ -47,9 +52,9 @@ func (lp *listeningPortsHandler) getListeningPorts() ([]codersdk.ListeningPort,
 		if tab.Process != nil {
 			procName = tab.Process.Name
 		}
-		ports = append(ports, codersdk.ListeningPort{
+		ports = append(ports, codersdk.WorkspaceAgentListeningPort{
 			ProcessName: procName,
-			Network:     codersdk.ListeningPortNetworkTCP,
+			Network:     "tcp",
 			Port:        tab.LocalAddr.Port,
 		})
 	}
@@ -58,7 +63,7 @@ func (lp *listeningPortsHandler) getListeningPorts() ([]codersdk.ListeningPort,
 	lp.mtime = time.Now()
 
 	// copy
-	ports = make([]codersdk.ListeningPort, len(lp.ports))
+	ports = make([]codersdk.WorkspaceAgentListeningPort, len(lp.ports))
 	copy(ports, lp.ports)
 	return ports, nil
 }

agent/ports_unsupported.go

@@ -4,9 +4,9 @@ package agent
 
 import "github.com/coder/coder/codersdk"
 
-func (lp *listeningPortsHandler) getListeningPorts() ([]codersdk.ListeningPort, error) {
+func (lp *listeningPortsHandler) getListeningPorts() ([]codersdk.WorkspaceAgentListeningPort, error) {
 	// Can't scan for ports on non-linux or non-windows_amd64 systems at the
 	// moment. The UI will not show any "no ports found" message to the user, so
 	// the user won't suspect a thing.
-	return []codersdk.ListeningPort{}, nil
+	return []codersdk.WorkspaceAgentListeningPort{}, nil
 }

agent/reaper/reaper.go

@@ -1,6 +1,10 @@
 package reaper
 
-import "github.com/hashicorp/go-reap"
+import (
+	"os"
+
+	"github.com/hashicorp/go-reap"
+)
 
 type Option func(o *options)
 
@@ -22,7 +26,16 @@ func WithPIDCallback(ch reap.PidCh) Option {
 	}
 }
 
-type options struct {
-	ExecArgs []string
-	PIDs     reap.PidCh
+// WithCatchSignals sets the signals that are caught and forwarded to the
+// child process. By default no signals are forwarded.
+func WithCatchSignals(sigs ...os.Signal) Option {
+	return func(o *options) {
+		o.CatchSignals = sigs
+	}
+}
+
+type options struct {
+	ExecArgs     []string
+	PIDs         reap.PidCh
+	CatchSignals []os.Signal
 }

agent/reaper/reaper_test.go

@@ -3,8 +3,11 @@
 package reaper_test
 
 import (
+	"fmt"
 	"os"
 	"os/exec"
+	"os/signal"
+	"syscall"
 	"testing"
 	"time"
 
@@ -15,52 +18,85 @@ import (
 	"github.com/coder/coder/testutil"
 )
 
+// TestReap checks that's the reaper is successfully reaping
+// exited processes and passing the PIDs through the shared
+// channel.
+//
+//nolint:paralleltest
 func TestReap(t *testing.T) {
-	t.Parallel()
-
 	// Don't run the reaper test in CI. It does weird
 	// things like forkexecing which may have unintended
 	// consequences in CI.
-	if _, ok := os.LookupEnv("CI"); ok {
+	if testutil.InCI() {
 		t.Skip("Detected CI, skipping reaper tests")
 	}
 
-	// OK checks that's the reaper is successfully reaping
-	// exited processes and passing the PIDs through the shared
-	// channel.
-	t.Run("OK", func(t *testing.T) {
-		t.Parallel()
-		pids := make(reap.PidCh, 1)
-		err := reaper.ForkReap(
-			reaper.WithPIDCallback(pids),
-			// Provide some argument that immediately exits.
-			reaper.WithExecArgs("/bin/sh", "-c", "exit 0"),
-		)
-		require.NoError(t, err)
+	pids := make(reap.PidCh, 1)
+	err := reaper.ForkReap(
+		reaper.WithPIDCallback(pids),
+		// Provide some argument that immediately exits.
+		reaper.WithExecArgs("/bin/sh", "-c", "exit 0"),
+	)
+	require.NoError(t, err)
 
-		cmd := exec.Command("tail", "-f", "/dev/null")
-		err = cmd.Start()
-		require.NoError(t, err)
+	cmd := exec.Command("tail", "-f", "/dev/null")
+	err = cmd.Start()
+	require.NoError(t, err)
 
-		cmd2 := exec.Command("tail", "-f", "/dev/null")
-		err = cmd2.Start()
-		require.NoError(t, err)
+	cmd2 := exec.Command("tail", "-f", "/dev/null")
+	err = cmd2.Start()
+	require.NoError(t, err)
 
-		err = cmd.Process.Kill()
-		require.NoError(t, err)
+	err = cmd.Process.Kill()
+	require.NoError(t, err)
 
-		err = cmd2.Process.Kill()
-		require.NoError(t, err)
+	err = cmd2.Process.Kill()
+	require.NoError(t, err)
 
-		expectedPIDs := []int{cmd.Process.Pid, cmd2.Process.Pid}
+	expectedPIDs := []int{cmd.Process.Pid, cmd2.Process.Pid}
 
-		for i := 0; i < len(expectedPIDs); i++ {
-			select {
-			case <-time.After(testutil.WaitShort):
-				t.Fatalf("Timed out waiting for process")
-			case pid := <-pids:
-				require.Contains(t, expectedPIDs, pid)
-			}
+	for i := 0; i < len(expectedPIDs); i++ {
+		select {
+		case <-time.After(testutil.WaitShort):
+			t.Fatalf("Timed out waiting for process")
+		case pid := <-pids:
+			require.Contains(t, expectedPIDs, pid)
 		}
-	})
+	}
+}
+
+//nolint:paralleltest // Signal handling.
+func TestReapInterrupt(t *testing.T) {
+	// Don't run the reaper test in CI. It does weird
+	// things like forkexecing which may have unintended
+	// consequences in CI.
+	if testutil.InCI() {
+		t.Skip("Detected CI, skipping reaper tests")
+	}
+
+	errC := make(chan error, 1)
+	pids := make(reap.PidCh, 1)
+
+	// Use signals to notify when the child process is ready for the
+	//  next step of our test.
+	usrSig := make(chan os.Signal, 1)
+	signal.Notify(usrSig, syscall.SIGUSR1, syscall.SIGUSR2)
+	defer signal.Stop(usrSig)
+
+	go func() {
+		errC <- reaper.ForkReap(
+			reaper.WithPIDCallback(pids),
+			reaper.WithCatchSignals(os.Interrupt),
+			// Signal propagation does not extend to children of children, so
+			// we create a little bash script to ensure sleep is interrupted.
+			reaper.WithExecArgs("/bin/sh", "-c", fmt.Sprintf("pid=0; trap 'kill -USR2 %d; kill -TERM $pid' INT; sleep 10 &\npid=$!; kill -USR1 %d; wait", os.Getpid(), os.Getpid())),
+		)
+	}()
+
+	require.Equal(t, <-usrSig, syscall.SIGUSR1)
+	err := syscall.Kill(os.Getpid(), syscall.SIGINT)
+	require.NoError(t, err)
+	require.Equal(t, <-usrSig, syscall.SIGUSR2)
+
+	require.NoError(t, <-errC)
 }

agent/reaper/reaper_unix.go

@@ -4,6 +4,7 @@ package reaper
 
 import (
 	"os"
+	"os/signal"
 	"syscall"
 
 	"github.com/hashicorp/go-reap"
@@ -15,6 +16,24 @@ func IsInitProcess() bool {
 	return os.Getpid() == 1
 }
 
+func catchSignals(pid int, sigs []os.Signal) {
+	if len(sigs) == 0 {
+		return
+	}
+
+	sc := make(chan os.Signal, 1)
+	signal.Notify(sc, sigs...)
+	defer signal.Stop(sc)
+
+	for {
+		s := <-sc
+		sig, ok := s.(syscall.Signal)
+		if ok {
+			_ = syscall.Kill(pid, sig)
+		}
+	}
+}
+
 // ForkReap spawns a goroutine that reaps children. In order to avoid
 // complications with spawning `exec.Commands` in the same process that
 // is reaping, we forkexec a child process. This prevents a race between
@@ -51,13 +70,17 @@ func ForkReap(opt ...Option) error {
 	}
 
 	//#nosec G204
-	pid, _ := syscall.ForkExec(opts.ExecArgs[0], opts.ExecArgs, pattrs)
+	pid, err := syscall.ForkExec(opts.ExecArgs[0], opts.ExecArgs, pattrs)
+	if err != nil {
+		return xerrors.Errorf("fork exec: %w", err)
+	}
+
+	go catchSignals(pid, opts.CatchSignals)
 
 	var wstatus syscall.WaitStatus
 	_, err = syscall.Wait4(pid, &wstatus, 0, nil)
 	for xerrors.Is(err, syscall.EINTR) {
 		_, err = syscall.Wait4(pid, &wstatus, 0, nil)
 	}
-
-	return nil
+	return err
 }

agent/stats.go

@@ -1,68 +0,0 @@
-package agent
-
-import (
-	"context"
-	"io"
-	"net"
-	"sync/atomic"
-
-	"cdr.dev/slog"
-	"github.com/coder/coder/codersdk"
-)
-
-// statsConn wraps a net.Conn with statistics.
-type statsConn struct {
-	*Stats
-	net.Conn `json:"-"`
-}
-
-var _ net.Conn = new(statsConn)
-
-func (c *statsConn) Read(b []byte) (n int, err error) {
-	n, err = c.Conn.Read(b)
-	atomic.AddInt64(&c.RxBytes, int64(n))
-	return n, err
-}
-
-func (c *statsConn) Write(b []byte) (n int, err error) {
-	n, err = c.Conn.Write(b)
-	atomic.AddInt64(&c.TxBytes, int64(n))
-	return n, err
-}
-
-var _ net.Conn = new(statsConn)
-
-// Stats records the Agent's network connection statistics for use in
-// user-facing metrics and debugging.
-// Each member value must be written and read with atomic.
-type Stats struct {
-	NumConns int64 `json:"num_comms"`
-	RxBytes  int64 `json:"rx_bytes"`
-	TxBytes  int64 `json:"tx_bytes"`
-}
-
-func (s *Stats) Copy() *codersdk.AgentStats {
-	return &codersdk.AgentStats{
-		NumConns: atomic.LoadInt64(&s.NumConns),
-		RxBytes:  atomic.LoadInt64(&s.RxBytes),
-		TxBytes:  atomic.LoadInt64(&s.TxBytes),
-	}
-}
-
-// wrapConn returns a new connection that records statistics.
-func (s *Stats) wrapConn(conn net.Conn) net.Conn {
-	atomic.AddInt64(&s.NumConns, 1)
-	cs := &statsConn{
-		Stats: s,
-		Conn:  conn,
-	}
-
-	return cs
-}
-
-// StatsReporter periodically accept and records agent stats.
-type StatsReporter func(
-	ctx context.Context,
-	log slog.Logger,
-	stats func() *codersdk.AgentStats,
-) (io.Closer, error)

agent/usershell/usershell_windows.go

@@ -4,7 +4,11 @@ import "os/exec"
 
 // Get returns the command prompt binary name.
 func Get(username string) (string, error) {
-	_, err := exec.LookPath("powershell.exe")
+	_, err := exec.LookPath("pwsh.exe")
+	if err == nil {
+		return "pwsh.exe", nil
+	}
+	_, err = exec.LookPath("powershell.exe")
 	if err == nil {
 		return "powershell.exe", nil
 	}

buildinfo/buildinfo.go

@@ -21,8 +21,12 @@ var (
 	version     string
 	readVersion sync.Once
 
-	// Injected with ldflags at build!
-	tag string
+	// Updated by buildinfo_slim.go on start.
+	slim bool
+
+	// Injected with ldflags at build, see scripts/build_go.sh
+	tag  string
+	agpl string // either "true" or "false", ldflags does not support bools
 )
 
 const (
@@ -68,6 +72,21 @@ func VersionsMatch(v1, v2 string) bool {
 	return semver.MajorMinor(v1) == semver.MajorMinor(v2)
 }
 
+// IsDev returns true if this is a development build.
+func IsDev() bool {
+	return strings.HasPrefix(Version(), develPrefix)
+}
+
+// IsSlim returns true if this is a slim build.
+func IsSlim() bool {
+	return slim
+}
+
+// IsAGPL returns true if this is an AGPL build.
+func IsAGPL() bool {
+	return strings.Contains(agpl, "t")
+}
+
 // ExternalURL returns a URL referencing the current Coder version.
 // For production builds, this will link directly to a release.
 // For development builds, this will link to a commit.

buildinfo/buildinfo_slim.go

@@ -0,0 +1,7 @@
+//go:build slim
+
+package buildinfo
+
+func init() {
+	slim = true
+}

cli/agent.go

@@ -3,183 +3,192 @@ package cli
 import (
 	"context"
 	"fmt"
+	"io"
 	"net/http"
-	_ "net/http/pprof" //nolint: gosec
+	"net/http/pprof"
 	"net/url"
 	"os"
+	"os/signal"
 	"path/filepath"
 	"runtime"
+	"strconv"
+	"sync"
 	"time"
 
 	"cloud.google.com/go/compute/metadata"
-	"github.com/spf13/cobra"
 	"golang.org/x/xerrors"
 	"gopkg.in/natefinch/lumberjack.v2"
+	"tailscale.com/util/clientmetric"
 
 	"cdr.dev/slog"
 	"cdr.dev/slog/sloggers/sloghuman"
 	"github.com/coder/coder/agent"
 	"github.com/coder/coder/agent/reaper"
 	"github.com/coder/coder/buildinfo"
-	"github.com/coder/coder/cli/cliflag"
+	"github.com/coder/coder/cli/clibase"
 	"github.com/coder/coder/codersdk"
-	"github.com/coder/retry"
+	"github.com/coder/coder/codersdk/agentsdk"
 )
 
-func workspaceAgent() *cobra.Command {
+func (r *RootCmd) workspaceAgent() *clibase.Cmd {
 	var (
-		auth         string
-		pprofEnabled bool
-		pprofAddress string
-		noReap       bool
+		auth              string
+		logDir            string
+		pprofAddress      string
+		noReap            bool
+		sshMaxTimeout     time.Duration
+		tailnetListenPort int64
+		prometheusAddress string
+		debugAddress      string
 	)
-	cmd := &cobra.Command{
-		Use: "agent",
+	cmd := &clibase.Cmd{
+		Use:   "agent",
+		Short: `Starts the Coder workspace agent.`,
 		// This command isn't useful to manually execute.
 		Hidden: true,
-		RunE: func(cmd *cobra.Command, args []string) error {
-			rawURL, err := cmd.Flags().GetString(varAgentURL)
-			if err != nil {
-				return xerrors.Errorf("CODER_AGENT_URL must be set: %w", err)
-			}
-			coderURL, err := url.Parse(rawURL)
-			if err != nil {
-				return xerrors.Errorf("parse %q: %w", rawURL, err)
-			}
+		Handler: func(inv *clibase.Invocation) error {
+			ctx, cancel := context.WithCancel(inv.Context())
+			defer cancel()
 
-			logWriter := &lumberjack.Logger{
-				Filename: filepath.Join(os.TempDir(), "coder-agent.log"),
-				MaxSize:  5, // MB
-			}
-			defer logWriter.Close()
-			logger := slog.Make(sloghuman.Sink(cmd.ErrOrStderr()), sloghuman.Sink(logWriter)).Leveled(slog.LevelDebug)
+			ignorePorts := map[int]string{}
 
 			isLinux := runtime.GOOS == "linux"
 
 			// Spawn a reaper so that we don't accumulate a ton
 			// of zombie processes.
 			if reaper.IsInitProcess() && !noReap && isLinux {
-				logger.Info(cmd.Context(), "spawning reaper process")
+				logWriter := &lumberjack.Logger{
+					Filename: filepath.Join(logDir, "coder-agent-init.log"),
+					MaxSize:  5, // MB
+				}
+				defer logWriter.Close()
+				logger := slog.Make(sloghuman.Sink(inv.Stderr), sloghuman.Sink(logWriter)).Leveled(slog.LevelDebug)
+
+				logger.Info(ctx, "spawning reaper process")
 				// Do not start a reaper on the child process. It's important
 				// to do this else we fork bomb ourselves.
 				args := append(os.Args, "--no-reap")
-				err := reaper.ForkReap(reaper.WithExecArgs(args...))
+				err := reaper.ForkReap(
+					reaper.WithExecArgs(args...),
+					reaper.WithCatchSignals(InterruptSignals...),
+				)
 				if err != nil {
-					logger.Error(cmd.Context(), "failed to reap", slog.Error(err))
+					logger.Error(ctx, "failed to reap", slog.Error(err))
 					return xerrors.Errorf("fork reap: %w", err)
 				}
 
-				logger.Info(cmd.Context(), "reaper process exiting")
+				logger.Info(ctx, "reaper process exiting")
 				return nil
 			}
 
+			// Handle interrupt signals to allow for graceful shutdown,
+			// note that calling stopNotify disables the signal handler
+			// and the next interrupt will terminate the program (you
+			// probably want cancel instead).
+			//
+			// Note that we don't want to handle these signals in the
+			// process that runs as PID 1, that's why we do this after
+			// the reaper forked.
+			ctx, stopNotify := signal.NotifyContext(ctx, InterruptSignals...)
+			defer stopNotify()
+
+			// DumpHandler does signal handling, so we call it after the
+			// reaper.
+			go DumpHandler(ctx)
+
+			ljLogger := &lumberjack.Logger{
+				Filename: filepath.Join(logDir, "coder-agent.log"),
+				MaxSize:  5, // MB
+			}
+			defer ljLogger.Close()
+			logWriter := &closeWriter{w: ljLogger}
+			defer logWriter.Close()
+
+			logger := slog.Make(sloghuman.Sink(inv.Stderr), sloghuman.Sink(logWriter)).Leveled(slog.LevelDebug)
+
 			version := buildinfo.Version()
-			logger.Info(cmd.Context(), "starting agent",
-				slog.F("url", coderURL),
+			logger.Info(ctx, "starting agent",
+				slog.F("url", r.agentURL),
 				slog.F("auth", auth),
 				slog.F("version", version),
 			)
-			client := codersdk.New(coderURL)
+			client := agentsdk.New(r.agentURL)
+			client.SDK.Logger = logger
+			// Set a reasonable timeout so requests can't hang forever!
+			// The timeout needs to be reasonably long, because requests
+			// with large payloads can take a bit. e.g. startup scripts
+			// may take a while to insert.
+			client.SDK.HTTPClient.Timeout = 30 * time.Second
 
-			if pprofEnabled {
-				srvClose := serveHandler(cmd.Context(), logger, nil, pprofAddress, "pprof")
-				defer srvClose()
-			} else {
-				// If pprof wasn't enabled at startup, allow a
-				// `kill -USR1 $agent_pid` to start it (on Unix).
-				srvClose := agentStartPPROFOnUSR1(cmd.Context(), logger, pprofAddress)
-				defer srvClose()
+			// Enable pprof handler
+			// This prevents the pprof import from being accidentally deleted.
+			_ = pprof.Handler
+			pprofSrvClose := ServeHandler(ctx, logger, nil, pprofAddress, "pprof")
+			defer pprofSrvClose()
+			// Do a best effort here. If this fails, it's not a big deal.
+			if port, err := urlPort(pprofAddress); err == nil {
+				ignorePorts[port] = "pprof"
+			}
+
+			prometheusSrvClose := ServeHandler(ctx, logger, prometheusMetricsHandler(), prometheusAddress, "prometheus")
+			defer prometheusSrvClose()
+			// Do a best effort here. If this fails, it's not a big deal.
+			if port, err := urlPort(prometheusAddress); err == nil {
+				ignorePorts[port] = "prometheus"
 			}
 
 			// exchangeToken returns a session token.
 			// This is abstracted to allow for the same looping condition
 			// regardless of instance identity auth type.
-			var exchangeToken func(context.Context) (codersdk.WorkspaceAgentAuthenticateResponse, error)
+			var exchangeToken func(context.Context) (agentsdk.AuthenticateResponse, error)
 			switch auth {
 			case "token":
-				token, err := cmd.Flags().GetString(varAgentToken)
+				token, err := inv.ParsedFlags().GetString(varAgentToken)
 				if err != nil {
 					return xerrors.Errorf("CODER_AGENT_TOKEN must be set for token auth: %w", err)
 				}
-				client.SessionToken = token
+				client.SetSessionToken(token)
 			case "google-instance-identity":
 				// This is *only* done for testing to mock client authentication.
 				// This will never be set in a production scenario.
 				var gcpClient *metadata.Client
-				gcpClientRaw := cmd.Context().Value("gcp-client")
+				gcpClientRaw := ctx.Value("gcp-client")
 				if gcpClientRaw != nil {
 					gcpClient, _ = gcpClientRaw.(*metadata.Client)
 				}
-				exchangeToken = func(ctx context.Context) (codersdk.WorkspaceAgentAuthenticateResponse, error) {
-					return client.AuthWorkspaceGoogleInstanceIdentity(ctx, "", gcpClient)
+				exchangeToken = func(ctx context.Context) (agentsdk.AuthenticateResponse, error) {
+					return client.AuthGoogleInstanceIdentity(ctx, "", gcpClient)
 				}
 			case "aws-instance-identity":
 				// This is *only* done for testing to mock client authentication.
 				// This will never be set in a production scenario.
 				var awsClient *http.Client
-				awsClientRaw := cmd.Context().Value("aws-client")
+				awsClientRaw := ctx.Value("aws-client")
 				if awsClientRaw != nil {
 					awsClient, _ = awsClientRaw.(*http.Client)
 					if awsClient != nil {
-						client.HTTPClient = awsClient
+						client.SDK.HTTPClient = awsClient
 					}
 				}
-				exchangeToken = func(ctx context.Context) (codersdk.WorkspaceAgentAuthenticateResponse, error) {
-					return client.AuthWorkspaceAWSInstanceIdentity(ctx)
+				exchangeToken = func(ctx context.Context) (agentsdk.AuthenticateResponse, error) {
+					return client.AuthAWSInstanceIdentity(ctx)
 				}
 			case "azure-instance-identity":
 				// This is *only* done for testing to mock client authentication.
 				// This will never be set in a production scenario.
 				var azureClient *http.Client
-				azureClientRaw := cmd.Context().Value("azure-client")
+				azureClientRaw := ctx.Value("azure-client")
 				if azureClientRaw != nil {
 					azureClient, _ = azureClientRaw.(*http.Client)
 					if azureClient != nil {
-						client.HTTPClient = azureClient
+						client.SDK.HTTPClient = azureClient
 					}
 				}
-				exchangeToken = func(ctx context.Context) (codersdk.WorkspaceAgentAuthenticateResponse, error) {
-					return client.AuthWorkspaceAzureInstanceIdentity(ctx)
+				exchangeToken = func(ctx context.Context) (agentsdk.AuthenticateResponse, error) {
+					return client.AuthAzureInstanceIdentity(ctx)
 				}
 			}
 
-			if exchangeToken != nil {
-				logger.Info(cmd.Context(), "exchanging identity token")
-				// Agent's can start before resources are returned from the provisioner
-				// daemon. If there are many resources being provisioned, this time
-				// could be significant. This is arbitrarily set at an hour to prevent
-				// tons of idle agents from pinging coderd.
-				ctx, cancelFunc := context.WithTimeout(cmd.Context(), time.Hour)
-				defer cancelFunc()
-				for retry.New(100*time.Millisecond, 5*time.Second).Wait(ctx) {
-					var response codersdk.WorkspaceAgentAuthenticateResponse
-
-					response, err = exchangeToken(ctx)
-					if err != nil {
-						logger.Warn(ctx, "authenticate workspace", slog.F("method", auth), slog.Error(err))
-						continue
-					}
-					client.SessionToken = response.SessionToken
-					logger.Info(ctx, "authenticated", slog.F("method", auth))
-					break
-				}
-				if err != nil {
-					return xerrors.Errorf("agent failed to authenticate in time: %w", err)
-				}
-			}
-
-			ctx, cancelFunc := context.WithTimeout(cmd.Context(), time.Hour)
-			defer cancelFunc()
-			for retry.New(100*time.Millisecond, 5*time.Second).Wait(ctx) {
-				err := client.PostWorkspaceAgentVersion(cmd.Context(), version)
-				if err != nil {
-					logger.Warn(cmd.Context(), "post agent version: %w", slog.Error(err), slog.F("version", version))
-					continue
-				}
-				logger.Info(ctx, "updated agent version", slog.F("version", version))
-				break
-			}
-
 			executablePath, err := os.Executable()
 			if err != nil {
 				return xerrors.Errorf("getting os executable: %w", err)
@@ -189,27 +198,192 @@ func workspaceAgent() *cobra.Command {
 				return xerrors.Errorf("add executable to $PATH: %w", err)
 			}
 
-			closer := agent.New(agent.Options{
-				FetchMetadata: client.WorkspaceAgentMetadata,
-				Logger:        logger,
-				EnvironmentVariables: map[string]string{
-					// Override the "CODER_AGENT_TOKEN" variable in all
-					// shells so "gitssh" works!
-					"CODER_AGENT_TOKEN": client.SessionToken,
+			subsystem := inv.Environ.Get(agent.EnvAgentSubsystem)
+			agnt := agent.New(agent.Options{
+				Client:            client,
+				Logger:            logger,
+				LogDir:            logDir,
+				TailnetListenPort: uint16(tailnetListenPort),
+				ExchangeToken: func(ctx context.Context) (string, error) {
+					if exchangeToken == nil {
+						return client.SDK.SessionToken(), nil
+					}
+					resp, err := exchangeToken(ctx)
+					if err != nil {
+						return "", err
+					}
+					client.SetSessionToken(resp.SessionToken)
+					return resp.SessionToken, nil
 				},
-				CoordinatorDialer:           client.ListenWorkspaceAgentTailnet,
-				StatsReporter:               client.AgentReportStats,
-				WorkspaceAgentApps:          client.WorkspaceAgentApps,
-				PostWorkspaceAgentAppHealth: client.PostWorkspaceAgentAppHealth,
+				EnvironmentVariables: map[string]string{
+					"GIT_ASKPASS": executablePath,
+				},
+				IgnorePorts:   ignorePorts,
+				SSHMaxTimeout: sshMaxTimeout,
+				Subsystem:     codersdk.AgentSubsystem(subsystem),
 			})
-			<-cmd.Context().Done()
-			return closer.Close()
+
+			debugSrvClose := ServeHandler(ctx, logger, agnt.HTTPDebug(), debugAddress, "debug")
+			defer debugSrvClose()
+			// Do a best effort here. If this fails, it's not a big deal.
+			if port, err := urlPort(debugAddress); err == nil {
+				ignorePorts[port] = "debug"
+			}
+
+			<-ctx.Done()
+			return agnt.Close()
+		},
+	}
+
+	cmd.Options = clibase.OptionSet{
+		{
+			Flag:        "auth",
+			Default:     "token",
+			Description: "Specify the authentication type to use for the agent.",
+			Env:         "CODER_AGENT_AUTH",
+			Value:       clibase.StringOf(&auth),
+		},
+		{
+			Flag:        "log-dir",
+			Default:     os.TempDir(),
+			Description: "Specify the location for the agent log files.",
+			Env:         "CODER_AGENT_LOG_DIR",
+			Value:       clibase.StringOf(&logDir),
+		},
+		{
+			Flag:        "pprof-address",
+			Default:     "127.0.0.1:6060",
+			Env:         "CODER_AGENT_PPROF_ADDRESS",
+			Value:       clibase.StringOf(&pprofAddress),
+			Description: "The address to serve pprof.",
+		},
+		{
+			Flag: "no-reap",
+
+			Env:         "",
+			Description: "Do not start a process reaper.",
+			Value:       clibase.BoolOf(&noReap),
+		},
+		{
+			Flag:        "ssh-max-timeout",
+			Default:     "0",
+			Env:         "CODER_AGENT_SSH_MAX_TIMEOUT",
+			Description: "Specify the max timeout for a SSH connection.",
+			Value:       clibase.DurationOf(&sshMaxTimeout),
+		},
+		{
+			Flag:        "tailnet-listen-port",
+			Default:     "0",
+			Env:         "CODER_AGENT_TAILNET_LISTEN_PORT",
+			Description: "Specify a static port for Tailscale to use for listening.",
+			Value:       clibase.Int64Of(&tailnetListenPort),
+		},
+		{
+			Flag:        "prometheus-address",
+			Default:     "127.0.0.1:2112",
+			Env:         "CODER_AGENT_PROMETHEUS_ADDRESS",
+			Value:       clibase.StringOf(&prometheusAddress),
+			Description: "The bind address to serve Prometheus metrics.",
+		},
+		{
+			Flag:        "debug-address",
+			Default:     "127.0.0.1:2113",
+			Env:         "CODER_AGENT_DEBUG_ADDRESS",
+			Value:       clibase.StringOf(&debugAddress),
+			Description: "The bind address to serve a debug HTTP server.",
 		},
 	}
 
-	cliflag.StringVarP(cmd.Flags(), &auth, "auth", "", "CODER_AGENT_AUTH", "token", "Specify the authentication type to use for the agent")
-	cliflag.BoolVarP(cmd.Flags(), &pprofEnabled, "pprof-enable", "", "CODER_AGENT_PPROF_ENABLE", false, "Enable serving pprof metrics on the address defined by --pprof-address.")
-	cliflag.BoolVarP(cmd.Flags(), &noReap, "no-reap", "", "", false, "Do not start a process reaper.")
-	cliflag.StringVarP(cmd.Flags(), &pprofAddress, "pprof-address", "", "CODER_AGENT_PPROF_ADDRESS", "127.0.0.1:6060", "The address to serve pprof.")
 	return cmd
 }
+
+func ServeHandler(ctx context.Context, logger slog.Logger, handler http.Handler, addr, name string) (closeFunc func()) {
+	logger.Debug(ctx, "http server listening", slog.F("addr", addr), slog.F("name", name))
+
+	// ReadHeaderTimeout is purposefully not enabled. It caused some issues with
+	// websockets over the dev tunnel.
+	// See: https://github.com/coder/coder/pull/3730
+	//nolint:gosec
+	srv := &http.Server{
+		Addr:    addr,
+		Handler: handler,
+	}
+	go func() {
+		err := srv.ListenAndServe()
+		if err != nil && !xerrors.Is(err, http.ErrServerClosed) {
+			logger.Error(ctx, "http server listen", slog.F("name", name), slog.Error(err))
+		}
+	}()
+
+	return func() {
+		_ = srv.Close()
+	}
+}
+
+// closeWriter is a wrapper around an io.WriteCloser that prevents
+// writes after Close. This is necessary because lumberjack will
+// re-open the file on write.
+type closeWriter struct {
+	w      io.WriteCloser
+	mu     sync.Mutex // Protects following.
+	closed bool
+}
+
+func (c *closeWriter) Close() error {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+
+	c.closed = true
+	return c.w.Close()
+}
+
+func (c *closeWriter) Write(p []byte) (int, error) {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+
+	if c.closed {
+		return 0, io.ErrClosedPipe
+	}
+	return c.w.Write(p)
+}
+
+// extractPort handles different url strings.
+// - localhost:6060
+// - http://localhost:6060
+func extractPort(u string) (int, error) {
+	port, firstError := urlPort(u)
+	if firstError == nil {
+		return port, nil
+	}
+
+	// Try with a scheme
+	port, err := urlPort("http://" + u)
+	if err == nil {
+		return port, nil
+	}
+	return -1, xerrors.Errorf("invalid url %q: %w", u, firstError)
+}
+
+// urlPort extracts the port from a valid URL.
+func urlPort(u string) (int, error) {
+	parsed, err := url.Parse(u)
+	if err != nil {
+		return -1, xerrors.Errorf("invalid url %q: %w", u, err)
+	}
+	if parsed.Port() != "" {
+		port, err := strconv.ParseUint(parsed.Port(), 10, 16)
+		if err == nil && port > 0 && port < 1<<16 {
+			return int(port), nil
+		}
+	}
+	return -1, xerrors.Errorf("invalid port: %s", u)
+}
+
+func prometheusMetricsHandler() http.Handler {
+	// We don't have any other internal metrics so far, so it's safe to expose metrics this way.
+	// Based on: https://github.com/tailscale/tailscale/blob/280255acae604796a1113861f5a84e6fa2dc6121/ipn/localapi/localapi.go#L489
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "text/plain")
+		clientmetric.WritePrometheusExpositionFormat(w)
+	})
+}

cli/agent_internal_test.go

@@ -0,0 +1,63 @@
+package cli
+
+import (
+	"fmt"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+func Test_extractPort(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name      string
+		urlString string
+		want      int
+		wantErr   bool
+	}{
+		{
+			name:      "Empty",
+			urlString: "",
+			wantErr:   true,
+		},
+		{
+			name:      "NoScheme",
+			urlString: "localhost:6060",
+			want:      6060,
+		},
+		{
+			name:      "WithScheme",
+			urlString: "http://localhost:6060",
+			want:      6060,
+		},
+		{
+			name:      "NoPort",
+			urlString: "http://localhost",
+			wantErr:   true,
+		},
+		{
+			name:      "NoPortNoScheme",
+			urlString: "localhost",
+			wantErr:   true,
+		},
+		{
+			name:      "OnlyPort",
+			urlString: "6060",
+			wantErr:   true,
+		},
+	}
+	for _, tt := range tests {
+		tt := tt
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+			got, err := extractPort(tt.urlString)
+			if tt.wantErr {
+				require.Error(t, err, fmt.Sprintf("extractPort(%v)", tt.urlString))
+			} else {
+				require.NoError(t, err, fmt.Sprintf("extractPort(%v)", tt.urlString))
+				require.Equal(t, tt.want, got, fmt.Sprintf("extractPort(%v)", tt.urlString))
+			}
+		})
+	}
+}

cli/agent_test.go

@@ -2,22 +2,66 @@ package cli_test
 
 import (
 	"context"
+	"os"
+	"path/filepath"
+	"runtime"
+	"strings"
 	"testing"
 
+	"github.com/google/uuid"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 
-	"cdr.dev/slog"
-
+	"github.com/coder/coder/agent"
 	"github.com/coder/coder/cli/clitest"
 	"github.com/coder/coder/coderd/coderdtest"
+	"github.com/coder/coder/codersdk"
 	"github.com/coder/coder/provisioner/echo"
 	"github.com/coder/coder/provisionersdk/proto"
-	"github.com/coder/coder/testutil"
+	"github.com/coder/coder/pty/ptytest"
 )
 
 func TestWorkspaceAgent(t *testing.T) {
 	t.Parallel()
+
+	t.Run("LogDirectory", func(t *testing.T) {
+		t.Parallel()
+
+		authToken := uuid.NewString()
+		client := coderdtest.New(t, &coderdtest.Options{
+			IncludeProvisionerDaemon: true,
+		})
+		user := coderdtest.CreateFirstUser(t, client)
+		version := coderdtest.CreateTemplateVersion(t, client, user.OrganizationID, &echo.Responses{
+			Parse:          echo.ParseComplete,
+			ProvisionApply: echo.ProvisionApplyWithAgent(authToken),
+		})
+		template := coderdtest.CreateTemplate(t, client, user.OrganizationID, version.ID)
+		coderdtest.AwaitTemplateVersionJob(t, client, version.ID)
+		workspace := coderdtest.CreateWorkspace(t, client, user.OrganizationID, template.ID)
+		coderdtest.AwaitWorkspaceBuildJob(t, client, workspace.LatestBuild.ID)
+
+		logDir := t.TempDir()
+		inv, _ := clitest.New(t,
+			"agent",
+			"--auth", "token",
+			"--agent-token", authToken,
+			"--agent-url", client.URL.String(),
+			"--log-dir", logDir,
+		)
+
+		pty := ptytest.New(t).Attach(inv)
+
+		clitest.Start(t, inv)
+		pty.ExpectMatch("starting agent")
+
+		coderdtest.AwaitWorkspaceAgents(t, client, workspace.ID)
+
+		info, err := os.Stat(filepath.Join(logDir, "coder-agent.log"))
+		require.NoError(t, err)
+		require.Greater(t, info.Size(), int64(0))
+	})
+
 	t.Run("Azure", func(t *testing.T) {
 		t.Parallel()
 		instanceID := "instanceidentifier"
@@ -29,7 +73,7 @@ func TestWorkspaceAgent(t *testing.T) {
 		user := coderdtest.CreateFirstUser(t, client)
 		version := coderdtest.CreateTemplateVersion(t, client, user.OrganizationID, &echo.Responses{
 			Parse: echo.ParseComplete,
-			Provision: []*proto.Provision_Response{{
+			ProvisionApply: []*proto.Provision_Response{{
 				Type: &proto.Provision_Response_Complete{
 					Complete: &proto.Provision_Complete{
 						Resources: []*proto.Resource{{
@@ -50,16 +94,14 @@ func TestWorkspaceAgent(t *testing.T) {
 		workspace := coderdtest.CreateWorkspace(t, client, user.OrganizationID, template.ID)
 		coderdtest.AwaitWorkspaceBuildJob(t, client, workspace.LatestBuild.ID)
 
-		cmd, _ := clitest.New(t, "agent", "--auth", "azure-instance-identity", "--agent-url", client.URL.String())
+		inv, _ := clitest.New(t, "agent", "--auth", "azure-instance-identity", "--agent-url", client.URL.String())
+		inv = inv.WithContext(
+			//nolint:revive,staticcheck
+			context.WithValue(inv.Context(), "azure-client", metadataClient),
+		)
 		ctx, cancelFunc := context.WithCancel(context.Background())
 		defer cancelFunc()
-		errC := make(chan error)
-		go func() {
-			// A linting error occurs for weakly typing the context value here.
-			//nolint // The above seems reasonable for a one-off test.
-			ctx := context.WithValue(ctx, "azure-client", metadataClient)
-			errC <- cmd.ExecuteContext(ctx)
-		}()
+		clitest.Start(t, inv)
 		coderdtest.AwaitWorkspaceAgents(t, client, workspace.ID)
 		workspace, err := client.Workspace(ctx, workspace.ID)
 		require.NoError(t, err)
@@ -67,16 +109,10 @@ func TestWorkspaceAgent(t *testing.T) {
 		if assert.NotEmpty(t, workspace.LatestBuild.Resources) && assert.NotEmpty(t, resources[0].Agents) {
 			assert.NotEmpty(t, resources[0].Agents[0].Version)
 		}
-		dialer, err := client.DialWorkspaceAgentTailnet(ctx, slog.Logger{}, resources[0].Agents[0].ID)
+		dialer, err := client.DialWorkspaceAgent(ctx, resources[0].Agents[0].ID, nil)
 		require.NoError(t, err)
 		defer dialer.Close()
-		require.Eventually(t, func() bool {
-			_, err := dialer.Ping()
-			return err == nil
-		}, testutil.WaitMedium, testutil.IntervalFast)
-		cancelFunc()
-		err = <-errC
-		require.NoError(t, err)
+		require.True(t, dialer.AwaitReachable(context.Background()))
 	})
 
 	t.Run("AWS", func(t *testing.T) {
@@ -90,7 +126,7 @@ func TestWorkspaceAgent(t *testing.T) {
 		user := coderdtest.CreateFirstUser(t, client)
 		version := coderdtest.CreateTemplateVersion(t, client, user.OrganizationID, &echo.Responses{
 			Parse: echo.ParseComplete,
-			Provision: []*proto.Provision_Response{{
+			ProvisionApply: []*proto.Provision_Response{{
 				Type: &proto.Provision_Response_Complete{
 					Complete: &proto.Provision_Complete{
 						Resources: []*proto.Resource{{
@@ -111,39 +147,29 @@ func TestWorkspaceAgent(t *testing.T) {
 		workspace := coderdtest.CreateWorkspace(t, client, user.OrganizationID, template.ID)
 		coderdtest.AwaitWorkspaceBuildJob(t, client, workspace.LatestBuild.ID)
 
-		cmd, _ := clitest.New(t, "agent", "--auth", "aws-instance-identity", "--agent-url", client.URL.String())
-		ctx, cancelFunc := context.WithCancel(context.Background())
-		defer cancelFunc()
-		errC := make(chan error)
-		go func() {
-			// A linting error occurs for weakly typing the context value here.
-			//nolint // The above seems reasonable for a one-off test.
-			ctx := context.WithValue(ctx, "aws-client", metadataClient)
-			errC <- cmd.ExecuteContext(ctx)
-		}()
+		inv, _ := clitest.New(t, "agent", "--auth", "aws-instance-identity", "--agent-url", client.URL.String())
+		inv = inv.WithContext(
+			//nolint:revive,staticcheck
+			context.WithValue(inv.Context(), "aws-client", metadataClient),
+		)
+		clitest.Start(t, inv)
 		coderdtest.AwaitWorkspaceAgents(t, client, workspace.ID)
-		workspace, err := client.Workspace(ctx, workspace.ID)
+		workspace, err := client.Workspace(inv.Context(), workspace.ID)
 		require.NoError(t, err)
 		resources := workspace.LatestBuild.Resources
 		if assert.NotEmpty(t, resources) && assert.NotEmpty(t, resources[0].Agents) {
 			assert.NotEmpty(t, resources[0].Agents[0].Version)
 		}
-		dialer, err := client.DialWorkspaceAgentTailnet(ctx, slog.Logger{}, resources[0].Agents[0].ID)
+		dialer, err := client.DialWorkspaceAgent(inv.Context(), resources[0].Agents[0].ID, nil)
 		require.NoError(t, err)
 		defer dialer.Close()
-		require.Eventually(t, func() bool {
-			_, err := dialer.Ping()
-			return err == nil
-		}, testutil.WaitMedium, testutil.IntervalFast)
-		cancelFunc()
-		err = <-errC
-		require.NoError(t, err)
+		require.True(t, dialer.AwaitReachable(context.Background()))
 	})
 
 	t.Run("GoogleCloud", func(t *testing.T) {
 		t.Parallel()
 		instanceID := "instanceidentifier"
-		validator, metadata := coderdtest.NewGoogleInstanceIdentity(t, instanceID, false)
+		validator, metadataClient := coderdtest.NewGoogleInstanceIdentity(t, instanceID, false)
 		client := coderdtest.New(t, &coderdtest.Options{
 			GoogleTokenValidator:     validator,
 			IncludeProvisionerDaemon: true,
@@ -151,7 +177,7 @@ func TestWorkspaceAgent(t *testing.T) {
 		user := coderdtest.CreateFirstUser(t, client)
 		version := coderdtest.CreateTemplateVersion(t, client, user.OrganizationID, &echo.Responses{
 			Parse: echo.ParseComplete,
-			Provision: []*proto.Provision_Response{{
+			ProvisionApply: []*proto.Provision_Response{{
 				Type: &proto.Provision_Response_Complete{
 					Complete: &proto.Provision_Complete{
 						Resources: []*proto.Resource{{
@@ -172,16 +198,18 @@ func TestWorkspaceAgent(t *testing.T) {
 		workspace := coderdtest.CreateWorkspace(t, client, user.OrganizationID, template.ID)
 		coderdtest.AwaitWorkspaceBuildJob(t, client, workspace.LatestBuild.ID)
 
-		cmd, _ := clitest.New(t, "agent", "--auth", "google-instance-identity", "--agent-url", client.URL.String())
-		ctx, cancelFunc := context.WithCancel(context.Background())
-		defer cancelFunc()
-		errC := make(chan error)
-		go func() {
-			// A linting error occurs for weakly typing the context value here.
-			//nolint // The above seems reasonable for a one-off test.
-			ctx := context.WithValue(ctx, "gcp-client", metadata)
-			errC <- cmd.ExecuteContext(ctx)
-		}()
+		inv, cfg := clitest.New(t, "agent", "--auth", "google-instance-identity", "--agent-url", client.URL.String())
+		ptytest.New(t).Attach(inv)
+		clitest.SetupConfig(t, client, cfg)
+		clitest.Start(t,
+			inv.WithContext(
+				//nolint:revive,staticcheck
+				context.WithValue(context.Background(), "gcp-client", metadataClient),
+			),
+		)
+
+		ctx := inv.Context()
+
 		coderdtest.AwaitWorkspaceAgents(t, client, workspace.ID)
 		workspace, err := client.Workspace(ctx, workspace.ID)
 		require.NoError(t, err)
@@ -189,15 +217,63 @@ func TestWorkspaceAgent(t *testing.T) {
 		if assert.NotEmpty(t, resources) && assert.NotEmpty(t, resources[0].Agents) {
 			assert.NotEmpty(t, resources[0].Agents[0].Version)
 		}
-		dialer, err := client.DialWorkspaceAgentTailnet(ctx, slog.Logger{}, resources[0].Agents[0].ID)
+		dialer, err := client.DialWorkspaceAgent(ctx, resources[0].Agents[0].ID, nil)
 		require.NoError(t, err)
 		defer dialer.Close()
-		require.Eventually(t, func() bool {
-			_, err := dialer.Ping()
-			return err == nil
-		}, testutil.WaitMedium, testutil.IntervalFast)
-		cancelFunc()
-		err = <-errC
+		require.True(t, dialer.AwaitReachable(context.Background()))
+		sshClient, err := dialer.SSHClient(ctx)
+		require.NoError(t, err)
+		defer sshClient.Close()
+		session, err := sshClient.NewSession()
+		require.NoError(t, err)
+		defer session.Close()
+		key := "CODER_AGENT_TOKEN"
+		command := "sh -c 'echo $" + key + "'"
+		if runtime.GOOS == "windows" {
+			command = "cmd.exe /c echo %" + key + "%"
+		}
+		token, err := session.CombinedOutput(command)
+		require.NoError(t, err)
+		_, err = uuid.Parse(strings.TrimSpace(string(token)))
 		require.NoError(t, err)
 	})
+
+	t.Run("PostStartup", func(t *testing.T) {
+		t.Parallel()
+
+		authToken := uuid.NewString()
+		client := coderdtest.New(t, &coderdtest.Options{
+			IncludeProvisionerDaemon: true,
+		})
+		user := coderdtest.CreateFirstUser(t, client)
+		version := coderdtest.CreateTemplateVersion(t, client, user.OrganizationID, &echo.Responses{
+			Parse:          echo.ParseComplete,
+			ProvisionApply: echo.ProvisionApplyWithAgent(authToken),
+		})
+		template := coderdtest.CreateTemplate(t, client, user.OrganizationID, version.ID)
+		coderdtest.AwaitTemplateVersionJob(t, client, version.ID)
+		workspace := coderdtest.CreateWorkspace(t, client, user.OrganizationID, template.ID)
+		coderdtest.AwaitWorkspaceBuildJob(t, client, workspace.LatestBuild.ID)
+
+		logDir := t.TempDir()
+		inv, _ := clitest.New(t,
+			"agent",
+			"--auth", "token",
+			"--agent-token", authToken,
+			"--agent-url", client.URL.String(),
+			"--log-dir", logDir,
+		)
+		// Set the subsystem for the agent.
+		inv.Environ.Set(agent.EnvAgentSubsystem, string(codersdk.AgentSubsystemEnvbox))
+
+		pty := ptytest.New(t).Attach(inv)
+
+		clitest.Start(t, inv)
+		pty.ExpectMatch("starting agent")
+
+		resources := coderdtest.AwaitWorkspaceAgents(t, client, workspace.ID)
+		require.Len(t, resources, 1)
+		require.Len(t, resources[0].Agents, 1)
+		require.Equal(t, codersdk.AgentSubsystemEnvbox, resources[0].Agents[0].Subsystem)
+	})
 }

cli/agent_unix.go

@@ -1,38 +0,0 @@
-//go:build !windows
-
-package cli
-
-import (
-	"context"
-	"os"
-	"os/signal"
-	"syscall"
-
-	"cdr.dev/slog"
-)
-
-func agentStartPPROFOnUSR1(ctx context.Context, logger slog.Logger, pprofAddress string) (srvClose func()) {
-	ctx, cancel := context.WithCancel(ctx)
-
-	usr1 := make(chan os.Signal, 1)
-	signal.Notify(usr1, syscall.SIGUSR1)
-	go func() {
-		defer close(usr1)
-		defer signal.Stop(usr1)
-
-		select {
-		case <-usr1:
-			signal.Stop(usr1)
-			srvClose := serveHandler(ctx, logger, nil, pprofAddress, "pprof")
-			defer srvClose()
-		case <-ctx.Done():
-			return
-		}
-		<-ctx.Done() // Prevent defer close until done.
-	}()
-
-	return func() {
-		cancel()
-		<-usr1 // Wait until usr1 is closed, ensures srvClose was run.
-	}
-}

cli/agent_windows.go

@@ -1,12 +0,0 @@
-package cli
-
-import (
-	"context"
-
-	"cdr.dev/slog"
-)
-
-// agentStartPPROFOnUSR1 is no-op on Windows (no SIGUSR1 signal).
-func agentStartPPROFOnUSR1(ctx context.Context, logger slog.Logger, pprofAddress string) (srvClose func()) {
-	return func() {}
-}

cli/clibase/clibase.go

@@ -0,0 +1,80 @@
+// Package clibase offers an all-in-one solution for a highly configurable CLI
+// application. Within Coder, we use it for all of our subcommands, which
+// demands more functionality than cobra/viber offers.
+//
+// The Command interface is loosely based on the chi middleware pattern and
+// http.Handler/HandlerFunc.
+package clibase
+
+import (
+	"strings"
+
+	"golang.org/x/exp/maps"
+)
+
+// Group describes a hierarchy of groups that an option or command belongs to.
+type Group struct {
+	Parent      *Group `json:"parent,omitempty"`
+	Name        string `json:"name,omitempty"`
+	YAML        string `json:"yaml,omitempty"`
+	Description string `json:"description,omitempty"`
+}
+
+// Ancestry returns the group and all of its parents, in order.
+func (g *Group) Ancestry() []Group {
+	if g == nil {
+		return nil
+	}
+
+	groups := []Group{*g}
+	for p := g.Parent; p != nil; p = p.Parent {
+		// Prepend to the slice so that the order is correct.
+		groups = append([]Group{*p}, groups...)
+	}
+	return groups
+}
+
+func (g *Group) FullName() string {
+	var names []string
+	for _, g := range g.Ancestry() {
+		names = append(names, g.Name)
+	}
+	return strings.Join(names, " / ")
+}
+
+// Annotations is an arbitrary key-mapping used to extend the Option and Command types.
+// Its methods won't panic if the map is nil.
+type Annotations map[string]string
+
+// Mark sets a value on the annotations map, creating one
+// if it doesn't exist. Mark does not mutate the original and
+// returns a copy. It is suitable for chaining.
+func (a Annotations) Mark(key string, value string) Annotations {
+	var aa Annotations
+	if a != nil {
+		aa = maps.Clone(a)
+	} else {
+		aa = make(Annotations)
+	}
+	aa[key] = value
+	return aa
+}
+
+// IsSet returns true if the key is set in the annotations map.
+func (a Annotations) IsSet(key string) bool {
+	if a == nil {
+		return false
+	}
+	_, ok := a[key]
+	return ok
+}
+
+// Get retrieves a key from the map, returning false if the key is not found
+// or the map is nil.
+func (a Annotations) Get(key string) (string, bool) {
+	if a == nil {
+		return "", false
+	}
+	v, ok := a[key]
+	return v, ok
+}

cli/clibase/cmd.go

@@ -0,0 +1,544 @@
+package clibase
+
+import (
+	"context"
+	"errors"
+	"flag"
+	"fmt"
+	"io"
+	"os"
+	"strings"
+	"unicode"
+
+	"github.com/spf13/pflag"
+	"golang.org/x/exp/slices"
+	"golang.org/x/xerrors"
+	"gopkg.in/yaml.v3"
+)
+
+// Cmd describes an executable command.
+type Cmd struct {
+	// Parent is the direct parent of the command.
+	Parent *Cmd
+	// Children is a list of direct descendants.
+	Children []*Cmd
+	// Use is provided in form "command [flags] [args...]".
+	Use string
+
+	// Aliases is a list of alternative names for the command.
+	Aliases []string
+
+	// Short is a one-line description of the command.
+	Short string
+
+	// Hidden determines whether the command should be hidden from help.
+	Hidden bool
+
+	// RawArgs determines whether the command should receive unparsed arguments.
+	// No flags are parsed when set, and the command is responsible for parsing
+	// its own flags.
+	RawArgs bool
+
+	// Long is a detailed description of the command,
+	// presented on its help page. It may contain examples.
+	Long        string
+	Options     OptionSet
+	Annotations Annotations
+
+	// Middleware is called before the Handler.
+	// Use Chain() to combine multiple middlewares.
+	Middleware  MiddlewareFunc
+	Handler     HandlerFunc
+	HelpHandler HandlerFunc
+}
+
+// AddSubcommands adds the given subcommands, setting their
+// Parent field automatically.
+func (c *Cmd) AddSubcommands(cmds ...*Cmd) {
+	for _, cmd := range cmds {
+		cmd.Parent = c
+		c.Children = append(c.Children, cmd)
+	}
+}
+
+// Walk calls fn for the command and all its children.
+func (c *Cmd) Walk(fn func(*Cmd)) {
+	fn(c)
+	for _, child := range c.Children {
+		child.Parent = c
+		child.Walk(fn)
+	}
+}
+
+// PrepareAll performs initialization and linting on the command and all its children.
+func (c *Cmd) PrepareAll() error {
+	if c.Use == "" {
+		return xerrors.New("command must have a Use field so that it has a name")
+	}
+	var merr error
+
+	for i := range c.Options {
+		opt := &c.Options[i]
+		if opt.Name == "" {
+			switch {
+			case opt.Flag != "":
+				opt.Name = opt.Flag
+			case opt.Env != "":
+				opt.Name = opt.Env
+			case opt.YAML != "":
+				opt.Name = opt.YAML
+			default:
+				merr = errors.Join(merr, xerrors.Errorf("option must have a Name, Flag, Env or YAML field"))
+			}
+		}
+		if opt.Description != "" {
+			// Enforce that description uses sentence form.
+			if unicode.IsLower(rune(opt.Description[0])) {
+				merr = errors.Join(merr, xerrors.Errorf("option %q description should start with a capital letter", opt.Name))
+			}
+			if !strings.HasSuffix(opt.Description, ".") {
+				merr = errors.Join(merr, xerrors.Errorf("option %q description should end with a period", opt.Name))
+			}
+		}
+	}
+
+	slices.SortFunc(c.Options, func(a, b Option) bool {
+		return a.Name < b.Name
+	})
+	slices.SortFunc(c.Children, func(a, b *Cmd) bool {
+		return a.Name() < b.Name()
+	})
+	for _, child := range c.Children {
+		child.Parent = c
+		err := child.PrepareAll()
+		if err != nil {
+			merr = errors.Join(merr, xerrors.Errorf("command %v: %w", child.Name(), err))
+		}
+	}
+	return merr
+}
+
+// Name returns the first word in the Use string.
+func (c *Cmd) Name() string {
+	return strings.Split(c.Use, " ")[0]
+}
+
+// FullName returns the full invocation name of the command,
+// as seen on the command line.
+func (c *Cmd) FullName() string {
+	var names []string
+	if c.Parent != nil {
+		names = append(names, c.Parent.FullName())
+	}
+	names = append(names, c.Name())
+	return strings.Join(names, " ")
+}
+
+// FullName returns usage of the command, preceded
+// by the usage of its parents.
+func (c *Cmd) FullUsage() string {
+	var uses []string
+	if c.Parent != nil {
+		uses = append(uses, c.Parent.FullName())
+	}
+	uses = append(uses, c.Use)
+	return strings.Join(uses, " ")
+}
+
+// Invoke creates a new invocation of the command, with
+// stdio discarded.
+//
+// The returned invocation is not live until Run() is called.
+func (c *Cmd) Invoke(args ...string) *Invocation {
+	return &Invocation{
+		Command: c,
+		Args:    args,
+		Stdout:  io.Discard,
+		Stderr:  io.Discard,
+		Stdin:   strings.NewReader(""),
+	}
+}
+
+// Invocation represents an instance of a command being executed.
+type Invocation struct {
+	ctx         context.Context
+	Command     *Cmd
+	parsedFlags *pflag.FlagSet
+	Args        []string
+	// Environ is a list of environment variables. Use EnvsWithPrefix to parse
+	// os.Environ.
+	Environ Environ
+	Stdout  io.Writer
+	Stderr  io.Writer
+	Stdin   io.Reader
+}
+
+// WithOS returns the invocation as a main package, filling in the invocation's unset
+// fields with OS defaults.
+func (inv *Invocation) WithOS() *Invocation {
+	return inv.with(func(i *Invocation) {
+		i.Stdout = os.Stdout
+		i.Stderr = os.Stderr
+		i.Stdin = os.Stdin
+		i.Args = os.Args[1:]
+		i.Environ = ParseEnviron(os.Environ(), "")
+	})
+}
+
+func (inv *Invocation) Context() context.Context {
+	if inv.ctx == nil {
+		return context.Background()
+	}
+	return inv.ctx
+}
+
+func (inv *Invocation) ParsedFlags() *pflag.FlagSet {
+	if inv.parsedFlags == nil {
+		panic("flags not parsed, has Run() been called?")
+	}
+	return inv.parsedFlags
+}
+
+type runState struct {
+	allArgs      []string
+	commandDepth int
+
+	flagParseErr error
+}
+
+func copyFlagSetWithout(fs *pflag.FlagSet, without string) *pflag.FlagSet {
+	fs2 := pflag.NewFlagSet("", pflag.ContinueOnError)
+	fs2.Usage = func() {}
+	fs.VisitAll(func(f *pflag.Flag) {
+		if f.Name == without {
+			return
+		}
+		fs2.AddFlag(f)
+	})
+	return fs2
+}
+
+// run recursively executes the command and its children.
+// allArgs is wired through the stack so that global flags can be accepted
+// anywhere in the command invocation.
+func (inv *Invocation) run(state *runState) error {
+	err := inv.Command.Options.ParseEnv(inv.Environ)
+	if err != nil {
+		return xerrors.Errorf("parsing env: %w", err)
+	}
+
+	// Now the fun part, argument parsing!
+
+	children := make(map[string]*Cmd)
+	for _, child := range inv.Command.Children {
+		child.Parent = inv.Command
+		for _, name := range append(child.Aliases, child.Name()) {
+			if _, ok := children[name]; ok {
+				return xerrors.Errorf("duplicate command name: %s", name)
+			}
+			children[name] = child
+		}
+	}
+
+	if inv.parsedFlags == nil {
+		inv.parsedFlags = pflag.NewFlagSet(inv.Command.Name(), pflag.ContinueOnError)
+		// We handle Usage ourselves.
+		inv.parsedFlags.Usage = func() {}
+	}
+
+	// If we find a duplicate flag, we want the deeper command's flag to override
+	// the shallow one. Unfortunately, pflag has no way to remove a flag, so we
+	// have to create a copy of the flagset without a value.
+	inv.Command.Options.FlagSet().VisitAll(func(f *pflag.Flag) {
+		if inv.parsedFlags.Lookup(f.Name) != nil {
+			inv.parsedFlags = copyFlagSetWithout(inv.parsedFlags, f.Name)
+		}
+		inv.parsedFlags.AddFlag(f)
+	})
+
+	var parsedArgs []string
+
+	if !inv.Command.RawArgs {
+		// Flag parsing will fail on intermediate commands in the command tree,
+		// so we check the error after looking for a child command.
+		state.flagParseErr = inv.parsedFlags.Parse(state.allArgs)
+		parsedArgs = inv.parsedFlags.Args()
+	}
+
+	// Set value sources for flags.
+	for i, opt := range inv.Command.Options {
+		if fl := inv.parsedFlags.Lookup(opt.Flag); fl != nil && fl.Changed {
+			inv.Command.Options[i].ValueSource = ValueSourceFlag
+		}
+	}
+
+	// Read YAML configs, if any.
+	for _, opt := range inv.Command.Options {
+		path, ok := opt.Value.(*YAMLConfigPath)
+		if !ok || path.String() == "" {
+			continue
+		}
+
+		byt, err := os.ReadFile(path.String())
+		if err != nil {
+			return xerrors.Errorf("reading yaml: %w", err)
+		}
+
+		var n yaml.Node
+		err = yaml.Unmarshal(byt, &n)
+		if err != nil {
+			return xerrors.Errorf("decoding yaml: %w", err)
+		}
+
+		err = inv.Command.Options.UnmarshalYAML(&n)
+		if err != nil {
+			return xerrors.Errorf("applying yaml: %w", err)
+		}
+	}
+
+	err = inv.Command.Options.SetDefaults()
+	if err != nil {
+		return xerrors.Errorf("setting defaults: %w", err)
+	}
+
+	// Run child command if found (next child only)
+	// We must do subcommand detection after flag parsing so we don't mistake flag
+	// values for subcommand names.
+	if len(parsedArgs) > state.commandDepth {
+		nextArg := parsedArgs[state.commandDepth]
+		if child, ok := children[nextArg]; ok {
+			child.Parent = inv.Command
+			inv.Command = child
+			state.commandDepth++
+			return inv.run(state)
+		}
+	}
+
+	// Flag parse errors are irrelevant for raw args commands.
+	if !inv.Command.RawArgs && state.flagParseErr != nil && !errors.Is(state.flagParseErr, pflag.ErrHelp) {
+		return xerrors.Errorf(
+			"parsing flags (%v) for %q: %w",
+			state.allArgs,
+			inv.Command.FullName(), state.flagParseErr,
+		)
+	}
+
+	if inv.Command.RawArgs {
+		// If we're at the root command, then the name is omitted
+		// from the arguments, so we can just use the entire slice.
+		if state.commandDepth == 0 {
+			inv.Args = state.allArgs
+		} else {
+			argPos, err := findArg(inv.Command.Name(), state.allArgs, inv.parsedFlags)
+			if err != nil {
+				panic(err)
+			}
+			inv.Args = state.allArgs[argPos+1:]
+		}
+	} else {
+		// In non-raw-arg mode, we want to skip over flags.
+		inv.Args = parsedArgs[state.commandDepth:]
+	}
+
+	mw := inv.Command.Middleware
+	if mw == nil {
+		mw = Chain()
+	}
+
+	ctx := inv.ctx
+	if ctx == nil {
+		ctx = context.Background()
+	}
+
+	ctx, cancel := context.WithCancel(ctx)
+	defer cancel()
+	inv = inv.WithContext(ctx)
+
+	if inv.Command.Handler == nil || errors.Is(state.flagParseErr, pflag.ErrHelp) {
+		if inv.Command.HelpHandler == nil {
+			return xerrors.Errorf("no handler or help for command %s", inv.Command.FullName())
+		}
+		return inv.Command.HelpHandler(inv)
+	}
+
+	err = mw(inv.Command.Handler)(inv)
+	if err != nil {
+		return &RunCommandError{
+			Cmd: inv.Command,
+			Err: err,
+		}
+	}
+	return nil
+}
+
+type RunCommandError struct {
+	Cmd *Cmd
+	Err error
+}
+
+func (e *RunCommandError) Unwrap() error {
+	return e.Err
+}
+
+func (e *RunCommandError) Error() string {
+	return fmt.Sprintf("running command %q: %+v", e.Cmd.FullName(), e.Err)
+}
+
+// findArg returns the index of the first occurrence of arg in args, skipping
+// over all flags.
+func findArg(want string, args []string, fs *pflag.FlagSet) (int, error) {
+	for i := 0; i < len(args); i++ {
+		arg := args[i]
+		if !strings.HasPrefix(arg, "-") {
+			if arg == want {
+				return i, nil
+			}
+			continue
+		}
+
+		// This is a flag!
+		if strings.Contains(arg, "=") {
+			// The flag contains the value in the same arg, just skip.
+			continue
+		}
+
+		// We need to check if NoOptValue is set, then we should not wait
+		// for the next arg to be the value.
+		f := fs.Lookup(strings.TrimLeft(arg, "-"))
+		if f == nil {
+			return -1, xerrors.Errorf("unknown flag: %s", arg)
+		}
+		if f.NoOptDefVal != "" {
+			continue
+		}
+
+		if i == len(args)-1 {
+			return -1, xerrors.Errorf("flag %s requires a value", arg)
+		}
+
+		// Skip the value.
+		i++
+	}
+
+	return -1, xerrors.Errorf("arg %s not found", want)
+}
+
+// Run executes the command.
+// If two command share a flag name, the first command wins.
+//
+//nolint:revive
+func (inv *Invocation) Run() (err error) {
+	defer func() {
+		// Pflag is panicky, so additional context is helpful in tests.
+		if flag.Lookup("test.v") == nil {
+			return
+		}
+		if r := recover(); r != nil {
+			err = xerrors.Errorf("panic recovered for %s: %v", inv.Command.FullName(), r)
+			panic(err)
+		}
+	}()
+	err = inv.run(&runState{
+		allArgs: inv.Args,
+	})
+	return err
+}
+
+// WithContext returns a copy of the Invocation with the given context.
+func (inv *Invocation) WithContext(ctx context.Context) *Invocation {
+	return inv.with(func(i *Invocation) {
+		i.ctx = ctx
+	})
+}
+
+// with returns a copy of the Invocation with the given function applied.
+func (inv *Invocation) with(fn func(*Invocation)) *Invocation {
+	i2 := *inv
+	fn(&i2)
+	return &i2
+}
+
+// MiddlewareFunc returns the next handler in the chain,
+// or nil if there are no more.
+type MiddlewareFunc func(next HandlerFunc) HandlerFunc
+
+func chain(ms ...MiddlewareFunc) MiddlewareFunc {
+	return MiddlewareFunc(func(next HandlerFunc) HandlerFunc {
+		if len(ms) > 0 {
+			return chain(ms[1:]...)(ms[0](next))
+		}
+		return next
+	})
+}
+
+// Chain returns a Handler that first calls middleware in order.
+//
+//nolint:revive
+func Chain(ms ...MiddlewareFunc) MiddlewareFunc {
+	// We need to reverse the array to provide top-to-bottom execution
+	// order when defining a command.
+	reversed := make([]MiddlewareFunc, len(ms))
+	for i := range ms {
+		reversed[len(ms)-1-i] = ms[i]
+	}
+	return chain(reversed...)
+}
+
+func RequireNArgs(want int) MiddlewareFunc {
+	return RequireRangeArgs(want, want)
+}
+
+// RequireRangeArgs returns a Middleware that requires the number of arguments
+// to be between start and end (inclusive). If end is -1, then the number of
+// arguments must be at least start.
+func RequireRangeArgs(start, end int) MiddlewareFunc {
+	if start < 0 {
+		panic("start must be >= 0")
+	}
+	return func(next HandlerFunc) HandlerFunc {
+		return func(i *Invocation) error {
+			got := len(i.Args)
+			switch {
+			case start == end && got != start:
+				switch start {
+				case 0:
+					if len(i.Command.Children) > 0 {
+						return xerrors.Errorf("unrecognized subcommand %q", i.Args[0])
+					}
+					return xerrors.Errorf("wanted no args but got %v %v", got, i.Args)
+				default:
+					return xerrors.Errorf(
+						"wanted %v args but got %v %v",
+						start,
+						got,
+						i.Args,
+					)
+				}
+			case start > 0 && end == -1:
+				switch {
+				case got < start:
+					return xerrors.Errorf(
+						"wanted at least %v args but got %v",
+						start,
+						got,
+					)
+				default:
+					return next(i)
+				}
+			case start > end:
+				panic("start must be <= end")
+			case got < start || got > end:
+				return xerrors.Errorf(
+					"wanted between %v and %v args but got %v",
+					start, end,
+					got,
+				)
+			default:
+				return next(i)
+			}
+		}
+	}
+}
+
+// HandlerFunc handles an Invocation of a command.
+type HandlerFunc func(i *Invocation) error

cli/clibase/cmd_test.go

@@ -0,0 +1,635 @@
+package clibase_test
+
+import (
+	"bytes"
+	"context"
+	"fmt"
+	"os"
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+	"golang.org/x/xerrors"
+
+	"github.com/coder/coder/cli/clibase"
+)
+
+// ioBufs is the standard input, output, and error for a command.
+type ioBufs struct {
+	Stdin  bytes.Buffer
+	Stdout bytes.Buffer
+	Stderr bytes.Buffer
+}
+
+// fakeIO sets Stdin, Stdout, and Stderr to buffers.
+func fakeIO(i *clibase.Invocation) *ioBufs {
+	var b ioBufs
+	i.Stdout = &b.Stdout
+	i.Stderr = &b.Stderr
+	i.Stdin = &b.Stdin
+	return &b
+}
+
+func TestCommand(t *testing.T) {
+	t.Parallel()
+
+	cmd := func() *clibase.Cmd {
+		var (
+			verbose bool
+			lower   bool
+			prefix  string
+		)
+		return &clibase.Cmd{
+			Use: "root [subcommand]",
+			Options: clibase.OptionSet{
+				clibase.Option{
+					Name:  "verbose",
+					Flag:  "verbose",
+					Value: clibase.BoolOf(&verbose),
+				},
+				clibase.Option{
+					Name:  "prefix",
+					Flag:  "prefix",
+					Value: clibase.StringOf(&prefix),
+				},
+			},
+			Children: []*clibase.Cmd{
+				{
+					Use:   "toupper [word]",
+					Short: "Converts a word to upper case",
+					Middleware: clibase.Chain(
+						clibase.RequireNArgs(1),
+					),
+					Aliases: []string{"up"},
+					Options: clibase.OptionSet{
+						clibase.Option{
+							Name:  "lower",
+							Flag:  "lower",
+							Value: clibase.BoolOf(&lower),
+						},
+					},
+					Handler: (func(i *clibase.Invocation) error {
+						i.Stdout.Write([]byte(prefix))
+						w := i.Args[0]
+						if lower {
+							w = strings.ToLower(w)
+						} else {
+							w = strings.ToUpper(w)
+						}
+						_, _ = i.Stdout.Write(
+							[]byte(
+								w,
+							),
+						)
+						if verbose {
+							i.Stdout.Write([]byte("!!!"))
+						}
+						return nil
+					}),
+				},
+			},
+		}
+	}
+
+	t.Run("SimpleOK", func(t *testing.T) {
+		t.Parallel()
+		i := cmd().Invoke("toupper", "hello")
+		io := fakeIO(i)
+		i.Run()
+		require.Equal(t, "HELLO", io.Stdout.String())
+	})
+
+	t.Run("Alias", func(t *testing.T) {
+		t.Parallel()
+		i := cmd().Invoke(
+			"up", "hello",
+		)
+		io := fakeIO(i)
+		i.Run()
+		require.Equal(t, "HELLO", io.Stdout.String())
+	})
+
+	t.Run("NoSubcommand", func(t *testing.T) {
+		t.Parallel()
+		i := cmd().Invoke(
+			"na",
+		)
+		io := fakeIO(i)
+		err := i.Run()
+		require.Empty(t, io.Stdout.String())
+		require.Error(t, err)
+	})
+
+	t.Run("BadArgs", func(t *testing.T) {
+		t.Parallel()
+		i := cmd().Invoke(
+			"toupper",
+		)
+		io := fakeIO(i)
+		err := i.Run()
+		require.Empty(t, io.Stdout.String())
+		require.Error(t, err)
+	})
+
+	t.Run("UnknownFlags", func(t *testing.T) {
+		t.Parallel()
+		i := cmd().Invoke(
+			"toupper", "--unknown",
+		)
+		io := fakeIO(i)
+		err := i.Run()
+		require.Empty(t, io.Stdout.String())
+		require.Error(t, err)
+	})
+
+	t.Run("Verbose", func(t *testing.T) {
+		t.Parallel()
+		i := cmd().Invoke(
+			"--verbose", "toupper", "hello",
+		)
+		io := fakeIO(i)
+		require.NoError(t, i.Run())
+		require.Equal(t, "HELLO!!!", io.Stdout.String())
+	})
+
+	t.Run("Verbose=", func(t *testing.T) {
+		t.Parallel()
+		i := cmd().Invoke(
+			"--verbose=true", "toupper", "hello",
+		)
+		io := fakeIO(i)
+		require.NoError(t, i.Run())
+		require.Equal(t, "HELLO!!!", io.Stdout.String())
+	})
+
+	t.Run("PrefixSpace", func(t *testing.T) {
+		t.Parallel()
+		i := cmd().Invoke(
+			"--prefix", "conv: ", "toupper", "hello",
+		)
+		io := fakeIO(i)
+		require.NoError(t, i.Run())
+		require.Equal(t, "conv: HELLO", io.Stdout.String())
+	})
+
+	t.Run("GlobalFlagsAnywhere", func(t *testing.T) {
+		t.Parallel()
+		i := cmd().Invoke(
+			"toupper", "--prefix", "conv: ", "hello", "--verbose",
+		)
+		io := fakeIO(i)
+		require.NoError(t, i.Run())
+		require.Equal(t, "conv: HELLO!!!", io.Stdout.String())
+	})
+
+	t.Run("LowerVerbose", func(t *testing.T) {
+		t.Parallel()
+		i := cmd().Invoke(
+			"toupper", "--verbose", "hello", "--lower",
+		)
+		io := fakeIO(i)
+		require.NoError(t, i.Run())
+		require.Equal(t, "hello!!!", io.Stdout.String())
+	})
+
+	t.Run("ParsedFlags", func(t *testing.T) {
+		t.Parallel()
+		i := cmd().Invoke(
+			"toupper", "--verbose", "hello", "--lower",
+		)
+		_ = fakeIO(i)
+		require.NoError(t, i.Run())
+		require.Equal(t,
+			"true",
+			i.ParsedFlags().Lookup("verbose").Value.String(),
+		)
+	})
+
+	t.Run("NoDeepChild", func(t *testing.T) {
+		t.Parallel()
+		i := cmd().Invoke(
+			"root", "level", "level", "toupper", "--verbose", "hello", "--lower",
+		)
+		fio := fakeIO(i)
+		require.Error(t, i.Run(), fio.Stdout.String())
+	})
+}
+
+func TestCommand_DeepNest(t *testing.T) {
+	t.Parallel()
+	cmd := &clibase.Cmd{
+		Use: "1",
+		Children: []*clibase.Cmd{
+			{
+				Use: "2",
+				Children: []*clibase.Cmd{
+					{
+						Use: "3",
+						Handler: func(i *clibase.Invocation) error {
+							i.Stdout.Write([]byte("3"))
+							return nil
+						},
+					},
+				},
+			},
+		},
+	}
+	inv := cmd.Invoke("2", "3")
+	stdio := fakeIO(inv)
+	err := inv.Run()
+	require.NoError(t, err)
+	require.Equal(t, "3", stdio.Stdout.String())
+}
+
+func TestCommand_FlagOverride(t *testing.T) {
+	t.Parallel()
+	var flag string
+
+	cmd := &clibase.Cmd{
+		Use: "1",
+		Options: clibase.OptionSet{
+			{
+				Name:  "flag",
+				Flag:  "f",
+				Value: clibase.DiscardValue,
+			},
+		},
+		Children: []*clibase.Cmd{
+			{
+				Use: "2",
+				Options: clibase.OptionSet{
+					{
+						Name:  "flag",
+						Flag:  "f",
+						Value: clibase.StringOf(&flag),
+					},
+				},
+				Handler: func(i *clibase.Invocation) error {
+					return nil
+				},
+			},
+		},
+	}
+
+	err := cmd.Invoke("2", "--f", "mhmm").Run()
+	require.NoError(t, err)
+
+	require.Equal(t, "mhmm", flag)
+}
+
+func TestCommand_MiddlewareOrder(t *testing.T) {
+	t.Parallel()
+
+	mw := func(letter string) clibase.MiddlewareFunc {
+		return func(next clibase.HandlerFunc) clibase.HandlerFunc {
+			return (func(i *clibase.Invocation) error {
+				_, _ = i.Stdout.Write([]byte(letter))
+				return next(i)
+			})
+		}
+	}
+
+	cmd := &clibase.Cmd{
+		Use:   "toupper [word]",
+		Short: "Converts a word to upper case",
+		Middleware: clibase.Chain(
+			mw("A"),
+			mw("B"),
+			mw("C"),
+		),
+		Handler: (func(i *clibase.Invocation) error {
+			return nil
+		}),
+	}
+
+	i := cmd.Invoke(
+		"hello", "world",
+	)
+	io := fakeIO(i)
+	require.NoError(t, i.Run())
+	require.Equal(t, "ABC", io.Stdout.String())
+}
+
+func TestCommand_RawArgs(t *testing.T) {
+	t.Parallel()
+
+	cmd := func() *clibase.Cmd {
+		return &clibase.Cmd{
+			Use: "root",
+			Options: clibase.OptionSet{
+				{
+					Name:  "password",
+					Flag:  "password",
+					Value: clibase.StringOf(new(string)),
+				},
+			},
+			Children: []*clibase.Cmd{
+				{
+					Use:     "sushi <args...>",
+					Short:   "Throws back raw output",
+					RawArgs: true,
+					Handler: (func(i *clibase.Invocation) error {
+						if v := i.ParsedFlags().Lookup("password").Value.String(); v != "codershack" {
+							return xerrors.Errorf("password %q is wrong!", v)
+						}
+						i.Stdout.Write([]byte(strings.Join(i.Args, " ")))
+						return nil
+					}),
+				},
+			},
+		}
+	}
+
+	t.Run("OK", func(t *testing.T) {
+		// Flag parsed before the raw arg command should still work.
+		t.Parallel()
+
+		i := cmd().Invoke(
+			"--password", "codershack", "sushi", "hello", "--verbose", "world",
+		)
+		io := fakeIO(i)
+		require.NoError(t, i.Run())
+		require.Equal(t, "hello --verbose world", io.Stdout.String())
+	})
+
+	t.Run("BadFlag", func(t *testing.T) {
+		// Verbose before the raw arg command should fail.
+		t.Parallel()
+
+		i := cmd().Invoke(
+			"--password", "codershack", "--verbose", "sushi", "hello", "world",
+		)
+		io := fakeIO(i)
+		require.Error(t, i.Run())
+		require.Empty(t, io.Stdout.String())
+	})
+
+	t.Run("NoPassword", func(t *testing.T) {
+		// Flag parsed before the raw arg command should still work.
+		t.Parallel()
+		i := cmd().Invoke(
+			"sushi", "hello", "--verbose", "world",
+		)
+		_ = fakeIO(i)
+		require.Error(t, i.Run())
+	})
+}
+
+func TestCommand_RootRaw(t *testing.T) {
+	t.Parallel()
+	cmd := &clibase.Cmd{
+		RawArgs: true,
+		Handler: func(i *clibase.Invocation) error {
+			i.Stdout.Write([]byte(strings.Join(i.Args, " ")))
+			return nil
+		},
+	}
+
+	inv := cmd.Invoke("hello", "--verbose", "--friendly")
+	stdio := fakeIO(inv)
+	err := inv.Run()
+	require.NoError(t, err)
+
+	require.Equal(t, "hello --verbose --friendly", stdio.Stdout.String())
+}
+
+func TestCommand_HyphenHyphen(t *testing.T) {
+	t.Parallel()
+	cmd := &clibase.Cmd{
+		Handler: (func(i *clibase.Invocation) error {
+			i.Stdout.Write([]byte(strings.Join(i.Args, " ")))
+			return nil
+		}),
+	}
+
+	inv := cmd.Invoke("--", "--verbose", "--friendly")
+	stdio := fakeIO(inv)
+	err := inv.Run()
+	require.NoError(t, err)
+
+	require.Equal(t, "--verbose --friendly", stdio.Stdout.String())
+}
+
+func TestCommand_ContextCancels(t *testing.T) {
+	t.Parallel()
+
+	var gotCtx context.Context
+
+	cmd := &clibase.Cmd{
+		Handler: (func(i *clibase.Invocation) error {
+			gotCtx = i.Context()
+			if err := gotCtx.Err(); err != nil {
+				return xerrors.Errorf("unexpected context error: %w", i.Context().Err())
+			}
+			return nil
+		}),
+	}
+
+	err := cmd.Invoke().Run()
+	require.NoError(t, err)
+
+	require.Error(t, gotCtx.Err())
+}
+
+func TestCommand_Help(t *testing.T) {
+	t.Parallel()
+
+	cmd := func() *clibase.Cmd {
+		return &clibase.Cmd{
+			Use: "root",
+			HelpHandler: (func(i *clibase.Invocation) error {
+				i.Stdout.Write([]byte("abdracadabra"))
+				return nil
+			}),
+			Handler: (func(i *clibase.Invocation) error {
+				return xerrors.New("should not be called")
+			}),
+		}
+	}
+
+	t.Run("NoHandler", func(t *testing.T) {
+		t.Parallel()
+
+		c := cmd()
+		c.HelpHandler = nil
+		err := c.Invoke("--help").Run()
+		require.Error(t, err)
+	})
+
+	t.Run("Long", func(t *testing.T) {
+		t.Parallel()
+
+		inv := cmd().Invoke("--help")
+		stdio := fakeIO(inv)
+		err := inv.Run()
+		require.NoError(t, err)
+
+		require.Contains(t, stdio.Stdout.String(), "abdracadabra")
+	})
+
+	t.Run("Short", func(t *testing.T) {
+		t.Parallel()
+
+		inv := cmd().Invoke("-h")
+		stdio := fakeIO(inv)
+		err := inv.Run()
+		require.NoError(t, err)
+
+		require.Contains(t, stdio.Stdout.String(), "abdracadabra")
+	})
+}
+
+func TestCommand_SliceFlags(t *testing.T) {
+	t.Parallel()
+
+	cmd := func(want ...string) *clibase.Cmd {
+		var got []string
+		return &clibase.Cmd{
+			Use: "root",
+			Options: clibase.OptionSet{
+				{
+					Name:    "arr",
+					Flag:    "arr",
+					Default: "bad,bad,bad",
+					Value:   clibase.StringArrayOf(&got),
+				},
+			},
+			Handler: (func(i *clibase.Invocation) error {
+				require.Equal(t, want, got)
+				return nil
+			}),
+		}
+	}
+
+	err := cmd("good", "good", "good").Invoke("--arr", "good", "--arr", "good", "--arr", "good").Run()
+	require.NoError(t, err)
+
+	err = cmd("bad", "bad", "bad").Invoke().Run()
+	require.NoError(t, err)
+}
+
+func TestCommand_EmptySlice(t *testing.T) {
+	t.Parallel()
+
+	cmd := func(want ...string) *clibase.Cmd {
+		var got []string
+		return &clibase.Cmd{
+			Use: "root",
+			Options: clibase.OptionSet{
+				{
+					Name:    "arr",
+					Flag:    "arr",
+					Default: "def,def,def",
+					Env:     "ARR",
+					Value:   clibase.StringArrayOf(&got),
+				},
+			},
+			Handler: (func(i *clibase.Invocation) error {
+				require.Equal(t, want, got)
+				return nil
+			}),
+		}
+	}
+
+	// Base-case, uses default.
+	err := cmd("def", "def", "def").Invoke().Run()
+	require.NoError(t, err)
+
+	// Empty-env uses default, too.
+	inv := cmd("def", "def", "def").Invoke()
+	inv.Environ.Set("ARR", "")
+	require.NoError(t, err)
+
+	// Reset to nothing at all via flag.
+	inv = cmd().Invoke("--arr", "")
+	inv.Environ.Set("ARR", "cant see")
+	err = inv.Run()
+	require.NoError(t, err)
+
+	// Reset to a specific value with flag.
+	inv = cmd("great").Invoke("--arr", "great")
+	inv.Environ.Set("ARR", "")
+	err = inv.Run()
+	require.NoError(t, err)
+}
+
+func TestCommand_DefaultsOverride(t *testing.T) {
+	t.Parallel()
+
+	test := func(name string, want string, fn func(t *testing.T, inv *clibase.Invocation)) {
+		t.Run(name, func(t *testing.T) {
+			t.Parallel()
+
+			var (
+				got    string
+				config clibase.YAMLConfigPath
+			)
+			cmd := &clibase.Cmd{
+				Options: clibase.OptionSet{
+					{
+						Name:    "url",
+						Flag:    "url",
+						Default: "def.com",
+						Env:     "URL",
+						Value:   clibase.StringOf(&got),
+						YAML:    "url",
+					},
+					{
+						Name:    "config",
+						Flag:    "config",
+						Default: "",
+						Value:   &config,
+					},
+				},
+				Handler: (func(i *clibase.Invocation) error {
+					_, _ = fmt.Fprintf(i.Stdout, "%s", got)
+					return nil
+				}),
+			}
+
+			inv := cmd.Invoke()
+			stdio := fakeIO(inv)
+			fn(t, inv)
+			err := inv.Run()
+			require.NoError(t, err)
+			require.Equal(t, want, stdio.Stdout.String())
+		})
+	}
+
+	test("DefaultOverNothing", "def.com", func(t *testing.T, inv *clibase.Invocation) {})
+
+	test("FlagOverDefault", "good.com", func(t *testing.T, inv *clibase.Invocation) {
+		inv.Args = []string{"--url", "good.com"}
+	})
+
+	test("EnvOverDefault", "good.com", func(t *testing.T, inv *clibase.Invocation) {
+		inv.Environ.Set("URL", "good.com")
+	})
+
+	test("FlagOverEnv", "good.com", func(t *testing.T, inv *clibase.Invocation) {
+		inv.Environ.Set("URL", "bad.com")
+		inv.Args = []string{"--url", "good.com"}
+	})
+
+	test("FlagOverYAML", "good.com", func(t *testing.T, inv *clibase.Invocation) {
+		fi, err := os.CreateTemp(t.TempDir(), "config.yaml")
+		require.NoError(t, err)
+		defer fi.Close()
+
+		_, err = fi.WriteString("url: bad.com")
+		require.NoError(t, err)
+
+		inv.Args = []string{"--config", fi.Name(), "--url", "good.com"}
+	})
+
+	test("YAMLOverDefault", "good.com", func(t *testing.T, inv *clibase.Invocation) {
+		fi, err := os.CreateTemp(t.TempDir(), "config.yaml")
+		require.NoError(t, err)
+		defer fi.Close()
+
+		_, err = fi.WriteString("url: good.com")
+		require.NoError(t, err)
+
+		inv.Args = []string{"--config", fi.Name()}
+	})
+}

cli/clibase/env.go

@@ -0,0 +1,76 @@
+package clibase
+
+import "strings"
+
+// name returns the name of the environment variable.
+func envName(line string) string {
+	return strings.ToUpper(
+		strings.SplitN(line, "=", 2)[0],
+	)
+}
+
+// value returns the value of the environment variable.
+func envValue(line string) string {
+	tokens := strings.SplitN(line, "=", 2)
+	if len(tokens) < 2 {
+		return ""
+	}
+	return tokens[1]
+}
+
+// Var represents a single environment variable of form
+// NAME=VALUE.
+type EnvVar struct {
+	Name  string
+	Value string
+}
+
+type Environ []EnvVar
+
+func (e Environ) ToOS() []string {
+	var env []string
+	for _, v := range e {
+		env = append(env, v.Name+"="+v.Value)
+	}
+	return env
+}
+
+func (e Environ) Lookup(name string) (string, bool) {
+	for _, v := range e {
+		if v.Name == name {
+			return v.Value, true
+		}
+	}
+	return "", false
+}
+
+func (e Environ) Get(name string) string {
+	v, _ := e.Lookup(name)
+	return v
+}
+
+func (e *Environ) Set(name, value string) {
+	for i, v := range *e {
+		if v.Name == name {
+			(*e)[i].Value = value
+			return
+		}
+	}
+	*e = append(*e, EnvVar{Name: name, Value: value})
+}
+
+// ParseEnviron returns all environment variables starting with
+// prefix without said prefix.
+func ParseEnviron(environ []string, prefix string) Environ {
+	var filtered []EnvVar
+	for _, line := range environ {
+		name := envName(line)
+		if strings.HasPrefix(name, prefix) {
+			filtered = append(filtered, EnvVar{
+				Name:  strings.TrimPrefix(name, prefix),
+				Value: envValue(line),
+			})
+		}
+	}
+	return filtered
+}

cli/clibase/env_test.go

@@ -0,0 +1,44 @@
+package clibase_test
+
+import (
+	"reflect"
+	"testing"
+
+	"github.com/coder/coder/cli/clibase"
+)
+
+func TestFilterNamePrefix(t *testing.T) {
+	t.Parallel()
+	type args struct {
+		environ []string
+		prefix  string
+	}
+	tests := []struct {
+		name string
+		args args
+		want clibase.Environ
+	}{
+		{"empty", args{[]string{}, "SHIRE"}, nil},
+		{
+			"ONE",
+			args{
+				[]string{
+					"SHIRE_BRANDYBUCK=hmm",
+				},
+				"SHIRE_",
+			},
+			[]clibase.EnvVar{
+				{Name: "BRANDYBUCK", Value: "hmm"},
+			},
+		},
+	}
+	for _, tt := range tests {
+		tt := tt
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+			if got := clibase.ParseEnviron(tt.args.environ, tt.args.prefix); !reflect.DeepEqual(got, tt.want) {
+				t.Errorf("FilterNamePrefix() = %v, want %v", got, tt.want)
+			}
+		})
+	}
+}

cli/clibase/option.go

@@ -0,0 +1,231 @@
+package clibase
+
+import (
+	"os"
+	"strings"
+
+	"github.com/hashicorp/go-multierror"
+	"github.com/spf13/pflag"
+	"golang.org/x/xerrors"
+)
+
+type ValueSource string
+
+const (
+	ValueSourceNone    ValueSource = ""
+	ValueSourceFlag    ValueSource = "flag"
+	ValueSourceEnv     ValueSource = "env"
+	ValueSourceYAML    ValueSource = "yaml"
+	ValueSourceDefault ValueSource = "default"
+)
+
+// Option is a configuration option for a CLI application.
+type Option struct {
+	Name        string `json:"name,omitempty"`
+	Description string `json:"description,omitempty"`
+
+	// Flag is the long name of the flag used to configure this option. If unset,
+	// flag configuring is disabled.
+	Flag string `json:"flag,omitempty"`
+	// FlagShorthand is the one-character shorthand for the flag. If unset, no
+	// shorthand is used.
+	FlagShorthand string `json:"flag_shorthand,omitempty"`
+
+	// Env is the environment variable used to configure this option. If unset,
+	// environment configuring is disabled.
+	Env string `json:"env,omitempty"`
+
+	// YAML is the YAML key used to configure this option. If unset, YAML
+	// configuring is disabled.
+	YAML string `json:"yaml,omitempty"`
+
+	// Default is parsed into Value if set.
+	Default string `json:"default,omitempty"`
+	// Value includes the types listed in values.go.
+	Value pflag.Value `json:"value,omitempty"`
+
+	// Annotations enable extensions to clibase higher up in the stack. It's useful for
+	// help formatting and documentation generation.
+	Annotations Annotations `json:"annotations,omitempty"`
+
+	// Group is a group hierarchy that helps organize this option in help, configs
+	// and other documentation.
+	Group *Group `json:"group,omitempty"`
+
+	// UseInstead is a list of options that should be used instead of this one.
+	// The field is used to generate a deprecation warning.
+	UseInstead []Option `json:"use_instead,omitempty"`
+
+	Hidden bool `json:"hidden,omitempty"`
+
+	ValueSource ValueSource `json:"value_source,omitempty"`
+}
+
+func (o Option) YAMLPath() string {
+	if o.YAML == "" {
+		return ""
+	}
+	var gs []string
+	for _, g := range o.Group.Ancestry() {
+		gs = append(gs, g.YAML)
+	}
+	return strings.Join(append(gs, o.YAML), ".")
+}
+
+// OptionSet is a group of options that can be applied to a command.
+type OptionSet []Option
+
+// Add adds the given Options to the OptionSet.
+func (s *OptionSet) Add(opts ...Option) {
+	*s = append(*s, opts...)
+}
+
+// Filter will only return options that match the given filter. (return true)
+func (s OptionSet) Filter(filter func(opt Option) bool) OptionSet {
+	cpy := make(OptionSet, 0)
+	for _, opt := range s {
+		if filter(opt) {
+			cpy = append(cpy, opt)
+		}
+	}
+	return cpy
+}
+
+// FlagSet returns a pflag.FlagSet for the OptionSet.
+func (s *OptionSet) FlagSet() *pflag.FlagSet {
+	if s == nil {
+		return &pflag.FlagSet{}
+	}
+
+	fs := pflag.NewFlagSet("", pflag.ContinueOnError)
+	for _, opt := range *s {
+		if opt.Flag == "" {
+			continue
+		}
+		var noOptDefValue string
+		{
+			no, ok := opt.Value.(NoOptDefValuer)
+			if ok {
+				noOptDefValue = no.NoOptDefValue()
+			}
+		}
+
+		val := opt.Value
+		if val == nil {
+			val = DiscardValue
+		}
+
+		fs.AddFlag(&pflag.Flag{
+			Name:        opt.Flag,
+			Shorthand:   opt.FlagShorthand,
+			Usage:       opt.Description,
+			Value:       val,
+			DefValue:    "",
+			Changed:     false,
+			Deprecated:  "",
+			NoOptDefVal: noOptDefValue,
+			Hidden:      opt.Hidden,
+		})
+	}
+	fs.Usage = func() {
+		_, _ = os.Stderr.WriteString("Override (*FlagSet).Usage() to print help text.\n")
+	}
+	return fs
+}
+
+// ParseEnv parses the given environment variables into the OptionSet.
+// Use EnvsWithPrefix to filter out prefixes.
+func (s *OptionSet) ParseEnv(vs []EnvVar) error {
+	if s == nil {
+		return nil
+	}
+
+	var merr *multierror.Error
+
+	// We parse environment variables first instead of using a nested loop to
+	// avoid N*M complexity when there are a lot of options and environment
+	// variables.
+	envs := make(map[string]string)
+	for _, v := range vs {
+		envs[v.Name] = v.Value
+	}
+
+	for i, opt := range *s {
+		if opt.Env == "" {
+			continue
+		}
+
+		envVal, ok := envs[opt.Env]
+		// Currently, empty values are treated as if the environment variable is
+		// unset. This behavior is technically not correct as there is now no
+		// way for a user to change a Default value to an empty string from
+		// the environment. Unfortunately, we have old configuration files
+		// that rely on the faulty behavior.
+		//
+		// TODO: We should remove this hack in May 2023, when deployments
+		// have had months to migrate to the new behavior.
+		if !ok || envVal == "" {
+			continue
+		}
+
+		(*s)[i].ValueSource = ValueSourceEnv
+		if err := opt.Value.Set(envVal); err != nil {
+			merr = multierror.Append(
+				merr, xerrors.Errorf("parse %q: %w", opt.Name, err),
+			)
+		}
+	}
+
+	return merr.ErrorOrNil()
+}
+
+// SetDefaults sets the default values for each Option, skipping values
+// that already have a value source.
+func (s *OptionSet) SetDefaults() error {
+	if s == nil {
+		return nil
+	}
+
+	var merr *multierror.Error
+
+	for i, opt := range *s {
+		// Skip values that may have already been set by the user.
+		if opt.ValueSource != ValueSourceNone {
+			continue
+		}
+
+		if opt.Default == "" {
+			continue
+		}
+
+		if opt.Value == nil {
+			merr = multierror.Append(
+				merr,
+				xerrors.Errorf(
+					"parse %q: no Value field set\nFull opt: %+v",
+					opt.Name, opt,
+				),
+			)
+			continue
+		}
+		(*s)[i].ValueSource = ValueSourceDefault
+		if err := opt.Value.Set(opt.Default); err != nil {
+			merr = multierror.Append(
+				merr, xerrors.Errorf("parse %q: %w", opt.Name, err),
+			)
+		}
+	}
+	return merr.ErrorOrNil()
+}
+
+// ByName returns the Option with the given name, or nil if no such option
+// exists.
+func (s *OptionSet) ByName(name string) *Option {
+	for i := range *s {
+		opt := &(*s)[i]
+		if opt.Name == name {
+			return opt
+		}
+	}
+	return nil
+}

cli/clibase/option_test.go

@@ -0,0 +1,169 @@
+package clibase_test
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/require"
+
+	"github.com/coder/coder/cli/clibase"
+)
+
+func TestOptionSet_ParseFlags(t *testing.T) {
+	t.Parallel()
+
+	t.Run("SimpleString", func(t *testing.T) {
+		t.Parallel()
+
+		var workspaceName clibase.String
+
+		os := clibase.OptionSet{
+			clibase.Option{
+				Name:          "Workspace Name",
+				Value:         &workspaceName,
+				Flag:          "workspace-name",
+				FlagShorthand: "n",
+			},
+		}
+
+		var err error
+		err = os.FlagSet().Parse([]string{"--workspace-name", "foo"})
+		require.NoError(t, err)
+		require.EqualValues(t, "foo", workspaceName)
+
+		err = os.FlagSet().Parse([]string{"-n", "f"})
+		require.NoError(t, err)
+		require.EqualValues(t, "f", workspaceName)
+	})
+
+	t.Run("StringArray", func(t *testing.T) {
+		t.Parallel()
+
+		var names clibase.StringArray
+
+		os := clibase.OptionSet{
+			clibase.Option{
+				Name:          "name",
+				Value:         &names,
+				Flag:          "name",
+				FlagShorthand: "n",
+			},
+		}
+
+		err := os.SetDefaults()
+		require.NoError(t, err)
+
+		err = os.FlagSet().Parse([]string{"--name", "foo", "--name", "bar"})
+		require.NoError(t, err)
+		require.EqualValues(t, []string{"foo", "bar"}, names)
+	})
+
+	t.Run("ExtraFlags", func(t *testing.T) {
+		t.Parallel()
+
+		var workspaceName clibase.String
+
+		os := clibase.OptionSet{
+			clibase.Option{
+				Name:  "Workspace Name",
+				Value: &workspaceName,
+			},
+		}
+
+		err := os.FlagSet().Parse([]string{"--some-unknown", "foo"})
+		require.Error(t, err)
+	})
+}
+
+func TestOptionSet_ParseEnv(t *testing.T) {
+	t.Parallel()
+
+	t.Run("SimpleString", func(t *testing.T) {
+		t.Parallel()
+
+		var workspaceName clibase.String
+
+		os := clibase.OptionSet{
+			clibase.Option{
+				Name:  "Workspace Name",
+				Value: &workspaceName,
+				Env:   "WORKSPACE_NAME",
+			},
+		}
+
+		err := os.ParseEnv([]clibase.EnvVar{
+			{Name: "WORKSPACE_NAME", Value: "foo"},
+		})
+		require.NoError(t, err)
+		require.EqualValues(t, "foo", workspaceName)
+	})
+
+	t.Run("EmptyValue", func(t *testing.T) {
+		t.Parallel()
+
+		var workspaceName clibase.String
+
+		os := clibase.OptionSet{
+			clibase.Option{
+				Name:    "Workspace Name",
+				Value:   &workspaceName,
+				Default: "defname",
+				Env:     "WORKSPACE_NAME",
+			},
+		}
+
+		err := os.SetDefaults()
+		require.NoError(t, err)
+
+		err = os.ParseEnv(clibase.ParseEnviron([]string{"CODER_WORKSPACE_NAME="}, "CODER_"))
+		require.NoError(t, err)
+		require.EqualValues(t, "defname", workspaceName)
+	})
+
+	t.Run("StringSlice", func(t *testing.T) {
+		t.Parallel()
+
+		var actual clibase.StringArray
+		expected := []string{"foo", "bar", "baz"}
+
+		os := clibase.OptionSet{
+			clibase.Option{
+				Name:  "name",
+				Value: &actual,
+				Env:   "NAMES",
+			},
+		}
+
+		err := os.SetDefaults()
+		require.NoError(t, err)
+
+		err = os.ParseEnv([]clibase.EnvVar{
+			{Name: "NAMES", Value: "foo,bar,baz"},
+		})
+		require.NoError(t, err)
+		require.EqualValues(t, expected, actual)
+	})
+
+	t.Run("StructMapStringString", func(t *testing.T) {
+		t.Parallel()
+
+		var actual clibase.Struct[map[string]string]
+		expected := map[string]string{"foo": "bar", "baz": "zap"}
+
+		os := clibase.OptionSet{
+			clibase.Option{
+				Name:  "labels",
+				Value: &actual,
+				Env:   "LABELS",
+			},
+		}
+
+		err := os.SetDefaults()
+		require.NoError(t, err)
+
+		err = os.ParseEnv([]clibase.EnvVar{
+			{Name: "LABELS", Value: `{"foo":"bar","baz":"zap"}`},
+		})
+		require.NoError(t, err)
+		require.EqualValues(t, expected, actual.Value)
+	})
+}

cli/clibase/values.go

@@ -0,0 +1,444 @@
+package clibase
+
+import (
+	"encoding/csv"
+	"encoding/json"
+	"fmt"
+	"net"
+	"net/url"
+	"reflect"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/spf13/pflag"
+	"golang.org/x/xerrors"
+	"gopkg.in/yaml.v3"
+)
+
+// NoOptDefValuer describes behavior when no
+// option is passed into the flag.
+//
+// This is useful for boolean or otherwise binary flags.
+type NoOptDefValuer interface {
+	NoOptDefValue() string
+}
+
+// values.go contains a standard set of value types that can be used as
+// Option Values.
+
+type Int64 int64
+
+func Int64Of(i *int64) *Int64 {
+	return (*Int64)(i)
+}
+
+func (i *Int64) Set(s string) error {
+	ii, err := strconv.ParseInt(s, 10, 64)
+	*i = Int64(ii)
+	return err
+}
+
+func (i Int64) Value() int64 {
+	return int64(i)
+}
+
+func (i Int64) String() string {
+	return strconv.Itoa(int(i))
+}
+
+func (Int64) Type() string {
+	return "int"
+}
+
+type Bool bool
+
+func BoolOf(b *bool) *Bool {
+	return (*Bool)(b)
+}
+
+func (b *Bool) Set(s string) error {
+	if s == "" {
+		*b = Bool(false)
+		return nil
+	}
+	bb, err := strconv.ParseBool(s)
+	*b = Bool(bb)
+	return err
+}
+
+func (*Bool) NoOptDefValue() string {
+	return "true"
+}
+
+func (b Bool) String() string {
+	return strconv.FormatBool(bool(b))
+}
+
+func (b Bool) Value() bool {
+	return bool(b)
+}
+
+func (Bool) Type() string {
+	return "bool"
+}
+
+type String string
+
+func StringOf(s *string) *String {
+	return (*String)(s)
+}
+
+func (*String) NoOptDefValue() string {
+	return ""
+}
+
+func (s *String) Set(v string) error {
+	*s = String(v)
+	return nil
+}
+
+func (s String) String() string {
+	return string(s)
+}
+
+func (s String) Value() string {
+	return string(s)
+}
+
+func (String) Type() string {
+	return "string"
+}
+
+var _ pflag.SliceValue = &StringArray{}
+
+// StringArray is a slice of strings that implements pflag.Value and pflag.SliceValue.
+type StringArray []string
+
+func StringArrayOf(ss *[]string) *StringArray {
+	return (*StringArray)(ss)
+}
+
+func (s *StringArray) Append(v string) error {
+	*s = append(*s, v)
+	return nil
+}
+
+func (s *StringArray) Replace(vals []string) error {
+	*s = vals
+	return nil
+}
+
+func (s *StringArray) GetSlice() []string {
+	return *s
+}
+
+func readAsCSV(v string) ([]string, error) {
+	return csv.NewReader(strings.NewReader(v)).Read()
+}
+
+func writeAsCSV(vals []string) string {
+	var sb strings.Builder
+	err := csv.NewWriter(&sb).Write(vals)
+	if err != nil {
+		return fmt.Sprintf("error: %s", err)
+	}
+	return sb.String()
+}
+
+func (s *StringArray) Set(v string) error {
+	if v == "" {
+		*s = nil
+		return nil
+	}
+	ss, err := readAsCSV(v)
+	if err != nil {
+		return err
+	}
+	*s = append(*s, ss...)
+	return nil
+}
+
+func (s StringArray) String() string {
+	return writeAsCSV([]string(s))
+}
+
+func (s StringArray) Value() []string {
+	return []string(s)
+}
+
+func (StringArray) Type() string {
+	return "string-array"
+}
+
+type Duration time.Duration
+
+func DurationOf(d *time.Duration) *Duration {
+	return (*Duration)(d)
+}
+
+func (d *Duration) Set(v string) error {
+	dd, err := time.ParseDuration(v)
+	*d = Duration(dd)
+	return err
+}
+
+func (d *Duration) Value() time.Duration {
+	return time.Duration(*d)
+}
+
+func (d *Duration) String() string {
+	return time.Duration(*d).String()
+}
+
+func (Duration) Type() string {
+	return "duration"
+}
+
+func (d *Duration) MarshalYAML() (interface{}, error) {
+	return yaml.Node{
+		Kind:  yaml.ScalarNode,
+		Value: d.String(),
+	}, nil
+}
+
+func (d *Duration) UnmarshalYAML(n *yaml.Node) error {
+	return d.Set(n.Value)
+}
+
+type URL url.URL
+
+func URLOf(u *url.URL) *URL {
+	return (*URL)(u)
+}
+
+func (u *URL) Set(v string) error {
+	uu, err := url.Parse(v)
+	if err != nil {
+		return err
+	}
+	*u = URL(*uu)
+	return nil
+}
+
+func (u *URL) String() string {
+	uu := url.URL(*u)
+	return uu.String()
+}
+
+func (u *URL) MarshalYAML() (interface{}, error) {
+	return yaml.Node{
+		Kind:  yaml.ScalarNode,
+		Value: u.String(),
+	}, nil
+}
+
+func (u *URL) UnmarshalYAML(n *yaml.Node) error {
+	return u.Set(n.Value)
+}
+
+func (u *URL) MarshalJSON() ([]byte, error) {
+	return json.Marshal(u.String())
+}
+
+func (u *URL) UnmarshalJSON(b []byte) error {
+	var s string
+	err := json.Unmarshal(b, &s)
+	if err != nil {
+		return err
+	}
+	return u.Set(s)
+}
+
+func (*URL) Type() string {
+	return "url"
+}
+
+func (u *URL) Value() *url.URL {
+	return (*url.URL)(u)
+}
+
+// HostPort is a host:port pair.
+type HostPort struct {
+	Host string
+	Port string
+}
+
+func (hp *HostPort) Set(v string) error {
+	if v == "" {
+		return xerrors.Errorf("must not be empty")
+	}
+	var err error
+	hp.Host, hp.Port, err = net.SplitHostPort(v)
+	return err
+}
+
+func (hp *HostPort) String() string {
+	if hp.Host == "" && hp.Port == "" {
+		return ""
+	}
+	// Warning: net.JoinHostPort must be used over concatenation to support
+	// IPv6 addresses.
+	return net.JoinHostPort(hp.Host, hp.Port)
+}
+
+func (hp *HostPort) MarshalJSON() ([]byte, error) {
+	return json.Marshal(hp.String())
+}
+
+func (hp *HostPort) UnmarshalJSON(b []byte) error {
+	var s string
+	err := json.Unmarshal(b, &s)
+	if err != nil {
+		return err
+	}
+	if s == "" {
+		hp.Host = ""
+		hp.Port = ""
+		return nil
+	}
+	return hp.Set(s)
+}
+
+func (hp *HostPort) MarshalYAML() (interface{}, error) {
+	return yaml.Node{
+		Kind:  yaml.ScalarNode,
+		Value: hp.String(),
+	}, nil
+}
+
+func (hp *HostPort) UnmarshalYAML(n *yaml.Node) error {
+	return hp.Set(n.Value)
+}
+
+func (*HostPort) Type() string {
+	return "host:port"
+}
+
+var (
+	_ yaml.Marshaler   = new(Struct[struct{}])
+	_ yaml.Unmarshaler = new(Struct[struct{}])
+)
+
+// Struct is a special value type that encodes an arbitrary struct.
+// It implements the flag.Value interface, but in general these values should
+// only be accepted via config for ergonomics.
+//
+// The string encoding type is YAML.
+type Struct[T any] struct {
+	Value T
+}
+
+func (s *Struct[T]) Set(v string) error {
+	return yaml.Unmarshal([]byte(v), &s.Value)
+}
+
+func (s *Struct[T]) String() string {
+	byt, err := yaml.Marshal(s.Value)
+	if err != nil {
+		return "decode failed: " + err.Error()
+	}
+	return string(byt)
+}
+
+func (s *Struct[T]) MarshalYAML() (interface{}, error) {
+	var n yaml.Node
+	err := n.Encode(s.Value)
+	if err != nil {
+		return nil, err
+	}
+	return n, nil
+}
+
+func (s *Struct[T]) UnmarshalYAML(n *yaml.Node) error {
+	// HACK: for compatibility with flags, we use nil slices instead of empty
+	// slices. In most cases, nil slices and empty slices are treated
+	// the same, so this behavior may be removed at some point.
+	if typ := reflect.TypeOf(s.Value); typ.Kind() == reflect.Slice && len(n.Content) == 0 {
+		reflect.ValueOf(&s.Value).Elem().Set(reflect.Zero(typ))
+		return nil
+	}
+	return n.Decode(&s.Value)
+}
+
+func (s *Struct[T]) Type() string {
+	return fmt.Sprintf("struct[%T]", s.Value)
+}
+
+func (s *Struct[T]) MarshalJSON() ([]byte, error) {
+	return json.Marshal(s.Value)
+}
+
+func (s *Struct[T]) UnmarshalJSON(b []byte) error {
+	return json.Unmarshal(b, &s.Value)
+}
+
+// DiscardValue does nothing but implements the pflag.Value interface.
+// It's useful in cases where you want to accept an option, but access the
+// underlying value directly instead of through the Option methods.
+var DiscardValue discardValue
+
+type discardValue struct{}
+
+func (discardValue) Set(string) error {
+	return nil
+}
+
+func (discardValue) String() string {
+	return ""
+}
+
+func (discardValue) Type() string {
+	return "discard"
+}
+
+var _ pflag.Value = (*Enum)(nil)
+
+type Enum struct {
+	Choices []string
+	Value   *string
+}
+
+func EnumOf(v *string, choices ...string) *Enum {
+	return &Enum{
+		Choices: choices,
+		Value:   v,
+	}
+}
+
+func (e *Enum) Set(v string) error {
+	for _, c := range e.Choices {
+		if v == c {
+			*e.Value = v
+			return nil
+		}
+	}
+	return xerrors.Errorf("invalid choice: %s, should be one of %v", v, e.Choices)
+}
+
+func (e *Enum) Type() string {
+	return fmt.Sprintf("enum[%v]", strings.Join(e.Choices, "|"))
+}
+
+func (e *Enum) String() string {
+	return *e.Value
+}
+
+var _ pflag.Value = (*YAMLConfigPath)(nil)
+
+// YAMLConfigPath is a special value type that encodes a path to a YAML
+// configuration file where options are read from.
+type YAMLConfigPath string
+
+func (p *YAMLConfigPath) Set(v string) error {
+	*p = YAMLConfigPath(v)
+	return nil
+}
+
+func (p *YAMLConfigPath) String() string {
+	return string(*p)
+}
+
+func (*YAMLConfigPath) Type() string {
+	return "yaml-config-path"
+}

cli/clibase/yaml.go

@@ -0,0 +1,295 @@
+package clibase
+
+import (
+	"errors"
+	"fmt"
+	"strings"
+
+	"github.com/mitchellh/go-wordwrap"
+	"golang.org/x/xerrors"
+	"gopkg.in/yaml.v3"
+)
+
+var (
+	_ yaml.Marshaler   = new(OptionSet)
+	_ yaml.Unmarshaler = new(OptionSet)
+)
+
+// deepMapNode returns the mapping node at the given path,
+// creating it if it doesn't exist.
+func deepMapNode(n *yaml.Node, path []string, headComment string) *yaml.Node {
+	if len(path) == 0 {
+		return n
+	}
+
+	// Name is every two nodes.
+	for i := 0; i < len(n.Content)-1; i += 2 {
+		if n.Content[i].Value == path[0] {
+			// Found matching name, recurse.
+			return deepMapNode(n.Content[i+1], path[1:], headComment)
+		}
+	}
+
+	// Not found, create it.
+	nameNode := yaml.Node{
+		Kind:        yaml.ScalarNode,
+		Value:       path[0],
+		HeadComment: headComment,
+	}
+	valueNode := yaml.Node{
+		Kind: yaml.MappingNode,
+	}
+	n.Content = append(n.Content, &nameNode)
+	n.Content = append(n.Content, &valueNode)
+	return deepMapNode(&valueNode, path[1:], headComment)
+}
+
+// MarshalYAML converts the option set to a YAML node, that can be
+// converted into bytes via yaml.Marshal.
+//
+// The node is returned to enable post-processing higher up in
+// the stack.
+//
+// It is isomorphic with FromYAML.
+func (s *OptionSet) MarshalYAML() (any, error) {
+	root := yaml.Node{
+		Kind: yaml.MappingNode,
+	}
+
+	for _, opt := range *s {
+		if opt.YAML == "" {
+			continue
+		}
+
+		defValue := opt.Default
+		if defValue == "" {
+			defValue = "<unset>"
+		}
+		comment := wordwrap.WrapString(
+			fmt.Sprintf("%s\n(default: %s, type: %s)", opt.Description, defValue, opt.Value.Type()),
+			80,
+		)
+		nameNode := yaml.Node{
+			Kind:        yaml.ScalarNode,
+			Value:       opt.YAML,
+			HeadComment: comment,
+		}
+		var valueNode yaml.Node
+		if opt.Value == nil {
+			valueNode = yaml.Node{
+				Kind:  yaml.ScalarNode,
+				Value: "null",
+			}
+		} else if m, ok := opt.Value.(yaml.Marshaler); ok {
+			v, err := m.MarshalYAML()
+			if err != nil {
+				return nil, xerrors.Errorf(
+					"marshal %q: %w", opt.Name, err,
+				)
+			}
+			valueNode, ok = v.(yaml.Node)
+			if !ok {
+				return nil, xerrors.Errorf(
+					"marshal %q: unexpected underlying type %T",
+					opt.Name, v,
+				)
+			}
+		} else {
+			// The all-other types case.
+			//
+			// A bit of a hack, we marshal and then unmarshal to get
+			// the underlying node.
+			byt, err := yaml.Marshal(opt.Value)
+			if err != nil {
+				return nil, xerrors.Errorf(
+					"marshal %q: %w", opt.Name, err,
+				)
+			}
+
+			var docNode yaml.Node
+			err = yaml.Unmarshal(byt, &docNode)
+			if err != nil {
+				return nil, xerrors.Errorf(
+					"unmarshal %q: %w", opt.Name, err,
+				)
+			}
+			if len(docNode.Content) != 1 {
+				return nil, xerrors.Errorf(
+					"unmarshal %q: expected one node, got %d",
+					opt.Name, len(docNode.Content),
+				)
+			}
+
+			valueNode = *docNode.Content[0]
+		}
+		var group []string
+		for _, g := range opt.Group.Ancestry() {
+			if g.YAML == "" {
+				return nil, xerrors.Errorf(
+					"group yaml name is empty for %q, groups: %+v",
+					opt.Name,
+					opt.Group,
+				)
+			}
+			group = append(group, g.YAML)
+		}
+		var groupDesc string
+		if opt.Group != nil {
+			groupDesc = wordwrap.WrapString(opt.Group.Description, 80)
+		}
+		parentValueNode := deepMapNode(
+			&root, group,
+			groupDesc,
+		)
+		parentValueNode.Content = append(
+			parentValueNode.Content,
+			&nameNode,
+			&valueNode,
+		)
+	}
+	return &root, nil
+}
+
+// mapYAMLNodes converts parent into a map with keys of form "group.subgroup.option"
+// and values as the corresponding YAML nodes.
+func mapYAMLNodes(parent *yaml.Node) (map[string]*yaml.Node, error) {
+	if parent.Kind != yaml.MappingNode {
+		return nil, xerrors.Errorf("expected mapping node, got type %v", parent.Kind)
+	}
+	if len(parent.Content)%2 != 0 {
+		return nil, xerrors.Errorf("expected an even number of k/v pairs, got %d", len(parent.Content))
+	}
+	var (
+		key  string
+		m    = make(map[string]*yaml.Node, len(parent.Content)/2)
+		merr error
+	)
+	for i, child := range parent.Content {
+		if i%2 == 0 {
+			if child.Kind != yaml.ScalarNode {
+				// We immediately because the rest of the code is bound to fail
+				// if we don't know to expect a key or a value.
+				return nil, xerrors.Errorf("expected scalar node for key, got type %v", child.Kind)
+			}
+			key = child.Value
+			continue
+		}
+
+		// We don't know if this is a grouped simple option or complex option,
+		// so we store both "key" and "group.key". Since we're storing pointers,
+		// the additional memory is of little concern.
+		m[key] = child
+		if child.Kind != yaml.MappingNode {
+			continue
+		}
+
+		sub, err := mapYAMLNodes(child)
+		if err != nil {
+			merr = errors.Join(merr, xerrors.Errorf("mapping node %q: %w", key, err))
+			continue
+		}
+		for k, v := range sub {
+			m[key+"."+k] = v
+		}
+	}
+
+	return m, nil
+}
+
+func (o *Option) setFromYAMLNode(n *yaml.Node) error {
+	o.ValueSource = ValueSourceYAML
+	if um, ok := o.Value.(yaml.Unmarshaler); ok {
+		return um.UnmarshalYAML(n)
+	}
+
+	switch n.Kind {
+	case yaml.ScalarNode:
+		return o.Value.Set(n.Value)
+	case yaml.SequenceNode:
+		// We treat empty values as nil for consistency with other option
+		// mechanisms.
+		if len(n.Content) == 0 {
+			o.Value = nil
+			return nil
+		}
+		return n.Decode(o.Value)
+	case yaml.MappingNode:
+		return xerrors.Errorf("mapping nodes must implement yaml.Unmarshaler")
+	default:
+		return xerrors.Errorf("unexpected node kind %v", n.Kind)
+	}
+}
+
+// UnmarshalYAML converts the given YAML node into the option set.
+// It is isomorphic with ToYAML.
+func (s *OptionSet) UnmarshalYAML(rootNode *yaml.Node) error {
+	// The rootNode will be a DocumentNode if it's read from a file. We do
+	// not support multiple documents in a single file.
+	if rootNode.Kind == yaml.DocumentNode {
+		if len(rootNode.Content) != 1 {
+			return xerrors.Errorf("expected one node in document, got %d", len(rootNode.Content))
+		}
+		rootNode = rootNode.Content[0]
+	}
+
+	yamlNodes, err := mapYAMLNodes(rootNode)
+	if err != nil {
+		return xerrors.Errorf("mapping nodes: %w", err)
+	}
+
+	matchedNodes := make(map[string]*yaml.Node, len(yamlNodes))
+
+	var merr error
+	for i := range *s {
+		opt := &(*s)[i]
+		if opt.YAML == "" {
+			continue
+		}
+		var group []string
+		for _, g := range opt.Group.Ancestry() {
+			if g.YAML == "" {
+				return xerrors.Errorf(
+					"group yaml name is empty for %q, groups: %+v",
+					opt.Name,
+					opt.Group,
+				)
+			}
+			group = append(group, g.YAML)
+			delete(yamlNodes, strings.Join(group, "."))
+		}
+
+		key := strings.Join(append(group, opt.YAML), ".")
+		node, ok := yamlNodes[key]
+		if !ok {
+			continue
+		}
+
+		matchedNodes[key] = node
+		if opt.ValueSource != ValueSourceNone {
+			continue
+		}
+		if err := opt.setFromYAMLNode(node); err != nil {
+			merr = errors.Join(merr, xerrors.Errorf("setting %q: %w", opt.YAML, err))
+		}
+	}
+
+	// Remove all matched nodes and their descendants from yamlNodes so we
+	// can accurately report unknown options.
+	for k := range yamlNodes {
+		var key string
+		for _, part := range strings.Split(k, ".") {
+			if key != "" {
+				key += "."
+			}
+			key += part
+			if _, ok := matchedNodes[key]; ok {
+				delete(yamlNodes, k)
+			}
+		}
+	}
+	for k := range yamlNodes {
+		merr = errors.Join(merr, xerrors.Errorf("unknown option %q", k))
+	}
+
+	return merr
+}

cli/clibase/yaml_test.go

@@ -0,0 +1,202 @@
+package clibase_test
+
+import (
+	"testing"
+
+	"github.com/spf13/pflag"
+	"github.com/stretchr/testify/require"
+	"golang.org/x/exp/slices"
+	"gopkg.in/yaml.v3"
+
+	"github.com/coder/coder/cli/clibase"
+)
+
+func TestOptionSet_YAML(t *testing.T) {
+	t.Parallel()
+
+	t.Run("RequireKey", func(t *testing.T) {
+		t.Parallel()
+		var workspaceName clibase.String
+		os := clibase.OptionSet{
+			clibase.Option{
+				Name:    "Workspace Name",
+				Value:   &workspaceName,
+				Default: "billie",
+			},
+		}
+
+		node, err := os.MarshalYAML()
+		require.NoError(t, err)
+		require.Len(t, node.(*yaml.Node).Content, 0)
+	})
+
+	t.Run("SimpleString", func(t *testing.T) {
+		t.Parallel()
+
+		var workspaceName clibase.String
+
+		os := clibase.OptionSet{
+			clibase.Option{
+				Name:        "Workspace Name",
+				Value:       &workspaceName,
+				Default:     "billie",
+				Description: "The workspace's name.",
+				Group:       &clibase.Group{YAML: "names"},
+				YAML:        "workspaceName",
+			},
+		}
+
+		err := os.SetDefaults()
+		require.NoError(t, err)
+
+		n, err := os.MarshalYAML()
+		require.NoError(t, err)
+		// Visually inspect for now.
+		byt, err := yaml.Marshal(n)
+		require.NoError(t, err)
+		t.Logf("Raw YAML:\n%s", string(byt))
+	})
+}
+
+func TestOptionSet_YAMLUnknownOptions(t *testing.T) {
+	t.Parallel()
+	os := clibase.OptionSet{
+		{
+			Name:        "Workspace Name",
+			Default:     "billie",
+			Description: "The workspace's name.",
+			YAML:        "workspaceName",
+			Value:       new(clibase.String),
+		},
+	}
+
+	const yamlDoc = `something: else`
+	err := yaml.Unmarshal([]byte(yamlDoc), &os)
+	require.Error(t, err)
+	require.Empty(t, os[0].Value.String())
+
+	os[0].YAML = "something"
+
+	err = yaml.Unmarshal([]byte(yamlDoc), &os)
+	require.NoError(t, err)
+
+	require.Equal(t, "else", os[0].Value.String())
+}
+
+// TestOptionSet_YAMLIsomorphism tests that the YAML representations of an
+// OptionSet converts to the same OptionSet when read back in.
+func TestOptionSet_YAMLIsomorphism(t *testing.T) {
+	t.Parallel()
+	// This is used to form a generic.
+	//nolint:unused
+	type kid struct {
+		Name string `yaml:"name"`
+		Age  int    `yaml:"age"`
+	}
+
+	for _, tc := range []struct {
+		name      string
+		os        clibase.OptionSet
+		zeroValue func() pflag.Value
+	}{
+		{
+			name: "SimpleString",
+			os: clibase.OptionSet{
+				{
+					Name:        "Workspace Name",
+					Default:     "billie",
+					Description: "The workspace's name.",
+					Group:       &clibase.Group{YAML: "names"},
+					YAML:        "workspaceName",
+				},
+			},
+			zeroValue: func() pflag.Value {
+				return clibase.StringOf(new(string))
+			},
+		},
+		{
+			name: "Array",
+			os: clibase.OptionSet{
+				{
+					YAML:    "names",
+					Default: "jill,jack,joan",
+				},
+			},
+			zeroValue: func() pflag.Value {
+				return clibase.StringArrayOf(&[]string{})
+			},
+		},
+		{
+			name: "ComplexObject",
+			os: clibase.OptionSet{
+				{
+					YAML: "kids",
+					Default: `- name: jill
+  age: 12
+- name: jack
+  age: 13`,
+				},
+			},
+			zeroValue: func() pflag.Value {
+				return &clibase.Struct[[]kid]{}
+			},
+		},
+		{
+			name: "DeepGroup",
+			os: clibase.OptionSet{
+				{
+					YAML:    "names",
+					Default: "jill,jack,joan",
+					Group:   &clibase.Group{YAML: "kids", Parent: &clibase.Group{YAML: "family"}},
+				},
+			},
+			zeroValue: func() pflag.Value {
+				return clibase.StringArrayOf(&[]string{})
+			},
+		},
+	} {
+		tc := tc
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			// Set initial values.
+			for i := range tc.os {
+				tc.os[i].Value = tc.zeroValue()
+			}
+			err := tc.os.SetDefaults()
+			require.NoError(t, err)
+
+			y, err := tc.os.MarshalYAML()
+			require.NoError(t, err)
+
+			toByt, err := yaml.Marshal(y)
+			require.NoError(t, err)
+
+			t.Logf("Raw YAML:\n%s", string(toByt))
+
+			var y2 yaml.Node
+			err = yaml.Unmarshal(toByt, &y2)
+			require.NoError(t, err)
+
+			os2 := slices.Clone(tc.os)
+			for i := range os2 {
+				os2[i].Value = tc.zeroValue()
+				os2[i].ValueSource = clibase.ValueSourceNone
+			}
+
+			// os2 values should be zeroed whereas tc.os should be
+			// set to defaults.
+			// This check makes sure we aren't mixing pointers.
+			require.NotEqual(t, tc.os, os2)
+			err = os2.UnmarshalYAML(&y2)
+			require.NoError(t, err)
+
+			want := tc.os
+			for i := range want {
+				want[i].ValueSource = clibase.ValueSourceYAML
+			}
+
+			require.Equal(t, tc.os, os2)
+		})
+	}
+}

cli/cliflag/cliflag.go

@@ -1,185 +0,0 @@
-// Package cliflag extends flagset with environment variable defaults.
-//
-// Usage:
-//
-// cliflag.String(root.Flags(), &address, "address", "a", "CODER_ADDRESS", "127.0.0.1:3000", "The address to serve the API and dashboard")
-//
-// Will produce the following usage docs:
-//
-//	-a, --address string              The address to serve the API and dashboard (uses $CODER_ADDRESS). (default "127.0.0.1:3000")
-package cliflag
-
-import (
-	"fmt"
-	"os"
-	"strconv"
-	"strings"
-	"time"
-
-	"github.com/spf13/cobra"
-	"github.com/spf13/pflag"
-
-	"github.com/coder/coder/cli/cliui"
-)
-
-// IsSetBool returns the value of the boolean flag if it is set.
-// It returns false if the flag isn't set or if any error occurs attempting
-// to parse the value of the flag.
-func IsSetBool(cmd *cobra.Command, name string) bool {
-	val, ok := IsSet(cmd, name)
-	if !ok {
-		return false
-	}
-
-	b, err := strconv.ParseBool(val)
-	return err == nil && b
-}
-
-// IsSet returns the string value of the flag and whether it was set.
-func IsSet(cmd *cobra.Command, name string) (string, bool) {
-	flag := cmd.Flag(name)
-	if flag == nil {
-		return "", false
-	}
-
-	return flag.Value.String(), flag.Changed
-}
-
-// String sets a string flag on the given flag set.
-func String(flagset *pflag.FlagSet, name, shorthand, env, def, usage string) {
-	v, ok := os.LookupEnv(env)
-	if !ok || v == "" {
-		v = def
-	}
-	flagset.StringP(name, shorthand, v, fmtUsage(usage, env))
-}
-
-// StringVarP sets a string flag on the given flag set.
-func StringVarP(flagset *pflag.FlagSet, p *string, name string, shorthand string, env string, def string, usage string) {
-	v, ok := os.LookupEnv(env)
-	if !ok || v == "" {
-		v = def
-	}
-	flagset.StringVarP(p, name, shorthand, v, fmtUsage(usage, env))
-}
-
-func StringArray(flagset *pflag.FlagSet, name, shorthand, env string, def []string, usage string) {
-	v, ok := os.LookupEnv(env)
-	if !ok || v == "" {
-		if v == "" {
-			def = []string{}
-		} else {
-			def = strings.Split(v, ",")
-		}
-	}
-	flagset.StringArrayP(name, shorthand, def, fmtUsage(usage, env))
-}
-
-func StringArrayVarP(flagset *pflag.FlagSet, ptr *[]string, name string, shorthand string, env string, def []string, usage string) {
-	val, ok := os.LookupEnv(env)
-	if ok {
-		if val == "" {
-			def = []string{}
-		} else {
-			def = strings.Split(val, ",")
-		}
-	}
-	flagset.StringArrayVarP(ptr, name, shorthand, def, fmtUsage(usage, env))
-}
-
-// Uint8VarP sets a uint8 flag on the given flag set.
-func Uint8VarP(flagset *pflag.FlagSet, ptr *uint8, name string, shorthand string, env string, def uint8, usage string) {
-	val, ok := os.LookupEnv(env)
-	if !ok || val == "" {
-		flagset.Uint8VarP(ptr, name, shorthand, def, fmtUsage(usage, env))
-		return
-	}
-
-	vi64, err := strconv.ParseUint(val, 10, 8)
-	if err != nil {
-		flagset.Uint8VarP(ptr, name, shorthand, def, fmtUsage(usage, env))
-		return
-	}
-
-	flagset.Uint8VarP(ptr, name, shorthand, uint8(vi64), fmtUsage(usage, env))
-}
-
-// IntVarP sets a uint8 flag on the given flag set.
-func IntVarP(flagset *pflag.FlagSet, ptr *int, name string, shorthand string, env string, def int, usage string) {
-	val, ok := os.LookupEnv(env)
-	if !ok || val == "" {
-		flagset.IntVarP(ptr, name, shorthand, def, fmtUsage(usage, env))
-		return
-	}
-
-	vi64, err := strconv.ParseUint(val, 10, 8)
-	if err != nil {
-		flagset.IntVarP(ptr, name, shorthand, def, fmtUsage(usage, env))
-		return
-	}
-
-	flagset.IntVarP(ptr, name, shorthand, int(vi64), fmtUsage(usage, env))
-}
-
-func Bool(flagset *pflag.FlagSet, name, shorthand, env string, def bool, usage string) {
-	val, ok := os.LookupEnv(env)
-	if !ok || val == "" {
-		flagset.BoolP(name, shorthand, def, fmtUsage(usage, env))
-		return
-	}
-
-	valb, err := strconv.ParseBool(val)
-	if err != nil {
-		flagset.BoolP(name, shorthand, def, fmtUsage(usage, env))
-		return
-	}
-
-	flagset.BoolP(name, shorthand, valb, fmtUsage(usage, env))
-}
-
-// BoolVarP sets a bool flag on the given flag set.
-func BoolVarP(flagset *pflag.FlagSet, ptr *bool, name string, shorthand string, env string, def bool, usage string) {
-	val, ok := os.LookupEnv(env)
-	if !ok || val == "" {
-		flagset.BoolVarP(ptr, name, shorthand, def, fmtUsage(usage, env))
-		return
-	}
-
-	valb, err := strconv.ParseBool(val)
-	if err != nil {
-		flagset.BoolVarP(ptr, name, shorthand, def, fmtUsage(usage, env))
-		return
-	}
-
-	flagset.BoolVarP(ptr, name, shorthand, valb, fmtUsage(usage, env))
-}
-
-// DurationVarP sets a time.Duration flag on the given flag set.
-func DurationVarP(flagset *pflag.FlagSet, ptr *time.Duration, name string, shorthand string, env string, def time.Duration, usage string) {
-	val, ok := os.LookupEnv(env)
-	if !ok || val == "" {
-		flagset.DurationVarP(ptr, name, shorthand, def, fmtUsage(usage, env))
-		return
-	}
-
-	valb, err := time.ParseDuration(val)
-	if err != nil {
-		flagset.DurationVarP(ptr, name, shorthand, def, fmtUsage(usage, env))
-		return
-	}
-
-	flagset.DurationVarP(ptr, name, shorthand, valb, fmtUsage(usage, env))
-}
-
-func fmtUsage(u string, env string) string {
-	if env != "" {
-		// Avoid double dotting.
-		dot := "."
-		if strings.HasSuffix(u, ".") {
-			dot = ""
-		}
-		u = fmt.Sprintf("%s%s\n"+cliui.Styles.Placeholder.Render("Consumes $%s"), u, dot, env)
-	}
-
-	return u
-}

cli/cliflag/cliflag_test.go

@@ -1,277 +0,0 @@
-package cliflag_test
-
-import (
-	"fmt"
-	"strconv"
-	"testing"
-	"time"
-
-	"github.com/spf13/pflag"
-	"github.com/stretchr/testify/require"
-
-	"github.com/coder/coder/cli/cliflag"
-	"github.com/coder/coder/cryptorand"
-)
-
-// Testcliflag cannot run in parallel because it uses t.Setenv.
-//
-//nolint:paralleltest
-func TestCliflag(t *testing.T) {
-	t.Run("StringDefault", func(t *testing.T) {
-		flagset, name, shorthand, env, usage := randomFlag()
-		def, _ := cryptorand.String(10)
-		cliflag.String(flagset, name, shorthand, env, def, usage)
-		got, err := flagset.GetString(name)
-		require.NoError(t, err)
-		require.Equal(t, def, got)
-		require.Contains(t, flagset.FlagUsages(), usage)
-		require.Contains(t, flagset.FlagUsages(), fmt.Sprintf("Consumes $%s", env))
-	})
-
-	t.Run("StringEnvVar", func(t *testing.T) {
-		flagset, name, shorthand, env, usage := randomFlag()
-		envValue, _ := cryptorand.String(10)
-		t.Setenv(env, envValue)
-		def, _ := cryptorand.String(10)
-		cliflag.String(flagset, name, shorthand, env, def, usage)
-		got, err := flagset.GetString(name)
-		require.NoError(t, err)
-		require.Equal(t, envValue, got)
-	})
-
-	t.Run("StringVarPDefault", func(t *testing.T) {
-		var ptr string
-		flagset, name, shorthand, env, usage := randomFlag()
-		def, _ := cryptorand.String(10)
-
-		cliflag.StringVarP(flagset, &ptr, name, shorthand, env, def, usage)
-		got, err := flagset.GetString(name)
-		require.NoError(t, err)
-		require.Equal(t, def, got)
-		require.Contains(t, flagset.FlagUsages(), usage)
-		require.Contains(t, flagset.FlagUsages(), fmt.Sprintf("Consumes $%s", env))
-	})
-
-	t.Run("StringVarPEnvVar", func(t *testing.T) {
-		var ptr string
-		flagset, name, shorthand, env, usage := randomFlag()
-		envValue, _ := cryptorand.String(10)
-		t.Setenv(env, envValue)
-		def, _ := cryptorand.String(10)
-
-		cliflag.StringVarP(flagset, &ptr, name, shorthand, env, def, usage)
-		got, err := flagset.GetString(name)
-		require.NoError(t, err)
-		require.Equal(t, envValue, got)
-	})
-
-	t.Run("EmptyEnvVar", func(t *testing.T) {
-		var ptr string
-		flagset, name, shorthand, _, usage := randomFlag()
-		def, _ := cryptorand.String(10)
-
-		cliflag.StringVarP(flagset, &ptr, name, shorthand, "", def, usage)
-		got, err := flagset.GetString(name)
-		require.NoError(t, err)
-		require.Equal(t, def, got)
-		require.Contains(t, flagset.FlagUsages(), usage)
-		require.NotContains(t, flagset.FlagUsages(), "Consumes")
-	})
-
-	t.Run("StringArrayDefault", func(t *testing.T) {
-		var ptr []string
-		flagset, name, shorthand, env, usage := randomFlag()
-		def := []string{"hello"}
-		cliflag.StringArrayVarP(flagset, &ptr, name, shorthand, env, def, usage)
-		got, err := flagset.GetStringArray(name)
-		require.NoError(t, err)
-		require.Equal(t, def, got)
-	})
-
-	t.Run("StringArrayEnvVar", func(t *testing.T) {
-		var ptr []string
-		flagset, name, shorthand, env, usage := randomFlag()
-		t.Setenv(env, "wow,test")
-		cliflag.StringArrayVarP(flagset, &ptr, name, shorthand, env, nil, usage)
-		got, err := flagset.GetStringArray(name)
-		require.NoError(t, err)
-		require.Equal(t, []string{"wow", "test"}, got)
-	})
-
-	t.Run("StringArrayEnvVarEmpty", func(t *testing.T) {
-		var ptr []string
-		flagset, name, shorthand, env, usage := randomFlag()
-		t.Setenv(env, "")
-		cliflag.StringArrayVarP(flagset, &ptr, name, shorthand, env, nil, usage)
-		got, err := flagset.GetStringArray(name)
-		require.NoError(t, err)
-		require.Equal(t, []string{}, got)
-	})
-
-	t.Run("UInt8Default", func(t *testing.T) {
-		var ptr uint8
-		flagset, name, shorthand, env, usage := randomFlag()
-		def, _ := cryptorand.Int63n(10)
-
-		cliflag.Uint8VarP(flagset, &ptr, name, shorthand, env, uint8(def), usage)
-		got, err := flagset.GetUint8(name)
-		require.NoError(t, err)
-		require.Equal(t, uint8(def), got)
-		require.Contains(t, flagset.FlagUsages(), usage)
-		require.Contains(t, flagset.FlagUsages(), fmt.Sprintf("Consumes $%s", env))
-	})
-
-	t.Run("UInt8EnvVar", func(t *testing.T) {
-		var ptr uint8
-		flagset, name, shorthand, env, usage := randomFlag()
-		envValue, _ := cryptorand.Int63n(10)
-		t.Setenv(env, strconv.FormatUint(uint64(envValue), 10))
-		def, _ := cryptorand.Int()
-
-		cliflag.Uint8VarP(flagset, &ptr, name, shorthand, env, uint8(def), usage)
-		got, err := flagset.GetUint8(name)
-		require.NoError(t, err)
-		require.Equal(t, uint8(envValue), got)
-	})
-
-	t.Run("UInt8FailParse", func(t *testing.T) {
-		var ptr uint8
-		flagset, name, shorthand, env, usage := randomFlag()
-		envValue, _ := cryptorand.String(10)
-		t.Setenv(env, envValue)
-		def, _ := cryptorand.Int63n(10)
-
-		cliflag.Uint8VarP(flagset, &ptr, name, shorthand, env, uint8(def), usage)
-		got, err := flagset.GetUint8(name)
-		require.NoError(t, err)
-		require.Equal(t, uint8(def), got)
-	})
-
-	t.Run("IntDefault", func(t *testing.T) {
-		var ptr int
-		flagset, name, shorthand, env, usage := randomFlag()
-		def, _ := cryptorand.Int63n(10)
-
-		cliflag.IntVarP(flagset, &ptr, name, shorthand, env, int(def), usage)
-		got, err := flagset.GetInt(name)
-		require.NoError(t, err)
-		require.Equal(t, int(def), got)
-		require.Contains(t, flagset.FlagUsages(), usage)
-		require.Contains(t, flagset.FlagUsages(), fmt.Sprintf("Consumes $%s", env))
-	})
-
-	t.Run("IntEnvVar", func(t *testing.T) {
-		var ptr int
-		flagset, name, shorthand, env, usage := randomFlag()
-		envValue, _ := cryptorand.Int63n(10)
-		t.Setenv(env, strconv.FormatUint(uint64(envValue), 10))
-		def, _ := cryptorand.Int()
-
-		cliflag.IntVarP(flagset, &ptr, name, shorthand, env, def, usage)
-		got, err := flagset.GetInt(name)
-		require.NoError(t, err)
-		require.Equal(t, int(envValue), got)
-	})
-
-	t.Run("IntFailParse", func(t *testing.T) {
-		var ptr int
-		flagset, name, shorthand, env, usage := randomFlag()
-		envValue, _ := cryptorand.String(10)
-		t.Setenv(env, envValue)
-		def, _ := cryptorand.Int63n(10)
-
-		cliflag.IntVarP(flagset, &ptr, name, shorthand, env, int(def), usage)
-		got, err := flagset.GetInt(name)
-		require.NoError(t, err)
-		require.Equal(t, int(def), got)
-	})
-
-	t.Run("BoolDefault", func(t *testing.T) {
-		var ptr bool
-		flagset, name, shorthand, env, usage := randomFlag()
-		def, _ := cryptorand.Bool()
-
-		cliflag.BoolVarP(flagset, &ptr, name, shorthand, env, def, usage)
-		got, err := flagset.GetBool(name)
-		require.NoError(t, err)
-		require.Equal(t, def, got)
-		require.Contains(t, flagset.FlagUsages(), usage)
-		require.Contains(t, flagset.FlagUsages(), fmt.Sprintf("Consumes $%s", env))
-	})
-
-	t.Run("BoolEnvVar", func(t *testing.T) {
-		var ptr bool
-		flagset, name, shorthand, env, usage := randomFlag()
-		envValue, _ := cryptorand.Bool()
-		t.Setenv(env, strconv.FormatBool(envValue))
-		def, _ := cryptorand.Bool()
-
-		cliflag.BoolVarP(flagset, &ptr, name, shorthand, env, def, usage)
-		got, err := flagset.GetBool(name)
-		require.NoError(t, err)
-		require.Equal(t, envValue, got)
-	})
-
-	t.Run("BoolFailParse", func(t *testing.T) {
-		var ptr bool
-		flagset, name, shorthand, env, usage := randomFlag()
-		envValue, _ := cryptorand.String(10)
-		t.Setenv(env, envValue)
-		def, _ := cryptorand.Bool()
-
-		cliflag.BoolVarP(flagset, &ptr, name, shorthand, env, def, usage)
-		got, err := flagset.GetBool(name)
-		require.NoError(t, err)
-		require.Equal(t, def, got)
-	})
-
-	t.Run("DurationDefault", func(t *testing.T) {
-		var ptr time.Duration
-		flagset, name, shorthand, env, usage := randomFlag()
-		def, _ := cryptorand.Duration()
-
-		cliflag.DurationVarP(flagset, &ptr, name, shorthand, env, def, usage)
-		got, err := flagset.GetDuration(name)
-		require.NoError(t, err)
-		require.Equal(t, def, got)
-		require.Contains(t, flagset.FlagUsages(), usage)
-		require.Contains(t, flagset.FlagUsages(), fmt.Sprintf("Consumes $%s", env))
-	})
-
-	t.Run("DurationEnvVar", func(t *testing.T) {
-		var ptr time.Duration
-		flagset, name, shorthand, env, usage := randomFlag()
-		envValue, _ := cryptorand.Duration()
-		t.Setenv(env, envValue.String())
-		def, _ := cryptorand.Duration()
-
-		cliflag.DurationVarP(flagset, &ptr, name, shorthand, env, def, usage)
-		got, err := flagset.GetDuration(name)
-		require.NoError(t, err)
-		require.Equal(t, envValue, got)
-	})
-
-	t.Run("DurationFailParse", func(t *testing.T) {
-		var ptr time.Duration
-		flagset, name, shorthand, env, usage := randomFlag()
-		envValue, _ := cryptorand.String(10)
-		t.Setenv(env, envValue)
-		def, _ := cryptorand.Duration()
-
-		cliflag.DurationVarP(flagset, &ptr, name, shorthand, env, def, usage)
-		got, err := flagset.GetDuration(name)
-		require.NoError(t, err)
-		require.Equal(t, def, got)
-	})
-}
-
-func randomFlag() (*pflag.FlagSet, string, string, string, string) {
-	fsname, _ := cryptorand.String(10)
-	flagset := pflag.NewFlagSet(fsname, pflag.PanicOnError)
-	name, _ := cryptorand.String(10)
-	shorthand, _ := cryptorand.String(1)
-	env, _ := cryptorand.String(10)
-	usage, _ := cryptorand.String(10)
-
-	return flagset, name, shorthand, env, usage
-}

cli/clitest/clitest.go

@@ -3,47 +3,76 @@ package clitest
 import (
 	"archive/tar"
 	"bytes"
+	"context"
 	"errors"
 	"io"
 	"io/ioutil"
 	"os"
 	"path/filepath"
+	"strings"
+	"sync"
+	"sync/atomic"
 	"testing"
+	"time"
 
-	"github.com/spf13/cobra"
+	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 
 	"github.com/coder/coder/cli"
+	"github.com/coder/coder/cli/clibase"
 	"github.com/coder/coder/cli/config"
 	"github.com/coder/coder/codersdk"
 	"github.com/coder/coder/provisioner/echo"
+	"github.com/coder/coder/testutil"
 )
 
 // New creates a CLI instance with a configuration pointed to a
 // temporary testing directory.
-func New(t *testing.T, args ...string) (*cobra.Command, config.Root) {
-	return NewWithSubcommands(t, cli.AGPL(), args...)
+func New(t *testing.T, args ...string) (*clibase.Invocation, config.Root) {
+	var root cli.RootCmd
+
+	cmd, err := root.Command(root.AGPL())
+	require.NoError(t, err)
+
+	return NewWithCommand(t, cmd, args...)
 }
 
-func NewWithSubcommands(
-	t *testing.T, subcommands []*cobra.Command, args ...string,
-) (*cobra.Command, config.Root) {
-	cmd := cli.Root(subcommands)
-	dir := t.TempDir()
-	root := config.Root(dir)
-	cmd.SetArgs(append([]string{"--global-config", dir}, args...))
+type logWriter struct {
+	prefix string
+	t      *testing.T
+}
 
-	// We could consider using writers
-	// that log via t.Log here instead.
-	cmd.SetOut(io.Discard)
-	cmd.SetErr(io.Discard)
+func (l *logWriter) Write(p []byte) (n int, err error) {
+	trimmed := strings.TrimSpace(string(p))
+	if trimmed == "" {
+		return len(p), nil
+	}
+	l.t.Log(
+		l.prefix + ": " + trimmed,
+	)
+	return len(p), nil
+}
 
-	return cmd, root
+func NewWithCommand(
+	t *testing.T, cmd *clibase.Cmd, args ...string,
+) (*clibase.Invocation, config.Root) {
+	configDir := config.Root(t.TempDir())
+	i := &clibase.Invocation{
+		Command: cmd,
+		Args:    append([]string{"--global-config", string(configDir)}, args...),
+		Stdin:   io.LimitReader(nil, 0),
+		Stdout:  (&logWriter{prefix: "stdout", t: t}),
+		Stderr:  (&logWriter{prefix: "stderr", t: t}),
+	}
+	t.Logf("invoking command: %s %s", cmd.Name(), strings.Join(i.Args, " "))
+
+	// These can be overridden by the test.
+	return i, configDir
 }
 
 // SetupConfig applies the URL and SessionToken of the client to the config.
 func SetupConfig(t *testing.T, client *codersdk.Client, root config.Root) {
-	err := root.Session().Write(client.SessionToken)
+	err := root.Session().Write(client.SessionToken())
 	require.NoError(t, err)
 	err = root.URL().Write(client.URL.String())
 	require.NoError(t, err)
@@ -55,7 +84,7 @@ func CreateTemplateVersionSource(t *testing.T, responses *echo.Responses) string
 	directory := t.TempDir()
 	f, err := ioutil.TempFile(directory, "*.tf")
 	require.NoError(t, err)
-	f.Close()
+	_ = f.Close()
 	data, err := echo.Tar(responses)
 	require.NoError(t, err)
 	extractTar(t, data, directory)
@@ -70,11 +99,14 @@ func extractTar(t *testing.T, data []byte, directory string) {
 			break
 		}
 		require.NoError(t, err)
+		if header.Name == "." || strings.Contains(header.Name, "..") {
+			continue
+		}
 		// #nosec
 		path := filepath.Join(directory, header.Name)
 		mode := header.FileInfo().Mode()
 		if mode == 0 {
-			mode = 0600
+			mode = 0o600
 		}
 		switch header.Typeflag {
 		case tar.TypeDir:
@@ -94,3 +126,126 @@ func extractTar(t *testing.T, data []byte, directory string) {
 		}
 	}
 }
+
+// Start runs the command in a goroutine and cleans it up when the test
+// completed.
+func Start(t *testing.T, inv *clibase.Invocation) {
+	t.Helper()
+
+	closeCh := make(chan struct{})
+	// StartWithWaiter adds its own `t.Cleanup`, so we need to be sure it's added
+	// before ours.
+	waiter := StartWithWaiter(t, inv)
+	t.Cleanup(func() {
+		waiter.Cancel()
+		<-closeCh
+	})
+
+	go func() {
+		defer close(closeCh)
+		err := waiter.Wait()
+		switch {
+		case errors.Is(err, context.Canceled):
+			return
+		default:
+			assert.NoError(t, err)
+		}
+	}()
+}
+
+// Run runs the command and asserts that there is no error.
+func Run(t *testing.T, inv *clibase.Invocation) {
+	t.Helper()
+
+	err := inv.Run()
+	require.NoError(t, err)
+}
+
+type ErrorWaiter struct {
+	waitOnce    sync.Once
+	cachedError error
+	cancelFunc  context.CancelFunc
+
+	c <-chan error
+	t *testing.T
+}
+
+func (w *ErrorWaiter) Cancel() {
+	w.cancelFunc()
+}
+
+func (w *ErrorWaiter) Wait() error {
+	w.waitOnce.Do(func() {
+		var ok bool
+		w.cachedError, ok = <-w.c
+		if !ok {
+			panic("unexpected channel close")
+		}
+	})
+	return w.cachedError
+}
+
+func (w *ErrorWaiter) RequireSuccess() {
+	require.NoError(w.t, w.Wait())
+}
+
+func (w *ErrorWaiter) RequireError() {
+	require.Error(w.t, w.Wait())
+}
+
+func (w *ErrorWaiter) RequireContains(s string) {
+	require.ErrorContains(w.t, w.Wait(), s)
+}
+
+func (w *ErrorWaiter) RequireIs(want error) {
+	require.ErrorIs(w.t, w.Wait(), want)
+}
+
+func (w *ErrorWaiter) RequireAs(want interface{}) {
+	require.ErrorAs(w.t, w.Wait(), want)
+}
+
+// StartWithWaiter runs the command in a goroutine but returns the error instead
+// of asserting it. This is useful for testing error cases.
+func StartWithWaiter(t *testing.T, inv *clibase.Invocation) *ErrorWaiter {
+	t.Helper()
+
+	var (
+		ctx    = inv.Context()
+		cancel func()
+
+		cleaningUp atomic.Bool
+		errCh      = make(chan error, 1)
+		doneCh     = make(chan struct{})
+	)
+	if _, ok := ctx.Deadline(); !ok {
+		ctx, cancel = context.WithDeadline(ctx, time.Now().Add(testutil.WaitMedium))
+	} else {
+		ctx, cancel = context.WithCancel(inv.Context())
+	}
+
+	inv = inv.WithContext(ctx)
+
+	go func() {
+		defer close(doneCh)
+		defer close(errCh)
+		err := inv.Run()
+		if cleaningUp.Load() && errors.Is(err, context.DeadlineExceeded) {
+			// If we're cleaning up, this error is likely related to the CLI
+			// teardown process. E.g., the server could be slow to shut down
+			// Postgres.
+			t.Logf("command %q timed out during test cleanup", inv.Command.FullName())
+		}
+		// Whether or not this fails the test is left to the caller.
+		t.Logf("command %q exited with error: %v", inv.Command.FullName(), err)
+		errCh <- err
+	}()
+
+	// Don't exit test routine until server is done.
+	t.Cleanup(func() {
+		cancel()
+		cleaningUp.Store(true)
+		<-doneCh
+	})
+	return &ErrorWaiter{c: errCh, t: t, cancelFunc: cancel}
+}

cli/clitest/clitest_test.go

@@ -18,13 +18,9 @@ func TestCli(t *testing.T) {
 	t.Parallel()
 	clitest.CreateTemplateVersionSource(t, nil)
 	client := coderdtest.New(t, nil)
-	cmd, config := clitest.New(t)
+	i, config := clitest.New(t)
 	clitest.SetupConfig(t, client, config)
-	pty := ptytest.New(t)
-	cmd.SetIn(pty.Input())
-	cmd.SetOut(pty.Output())
-	go func() {
-		_ = cmd.Execute()
-	}()
+	pty := ptytest.New(t).Attach(i)
+	clitest.Start(t, i)
 	pty.ExpectMatch("coder")
 }

cli/cliui/agent.go

@@ -10,16 +10,24 @@ import (
 	"time"
 
 	"github.com/briandowns/spinner"
+	"github.com/muesli/reflow/indent"
+	"github.com/muesli/reflow/wordwrap"
 	"golang.org/x/xerrors"
 
 	"github.com/coder/coder/codersdk"
 )
 
+var (
+	AgentStartError   = xerrors.New("agent startup exited with non-zero exit status")
+	AgentShuttingDown = xerrors.New("agent is shutting down")
+)
+
 type AgentOptions struct {
 	WorkspaceName string
 	Fetch         func(context.Context) (codersdk.WorkspaceAgent, error)
 	FetchInterval time.Duration
 	WarnInterval  time.Duration
+	NoWait        bool // If true, don't wait for the agent to be ready.
 }
 
 // Agent displays a spinning indicator that waits for a workspace agent to connect.
@@ -35,73 +43,222 @@ func Agent(ctx context.Context, writer io.Writer, opts AgentOptions) error {
 	if err != nil {
 		return xerrors.Errorf("fetch: %w", err)
 	}
-	if agent.Status == codersdk.WorkspaceAgentConnected {
+
+	// Fast path if the agent is ready (avoid showing connecting prompt).
+	// We don't take the fast path for opts.NoWait yet because we want to
+	// show the message.
+	if agent.Status == codersdk.WorkspaceAgentConnected &&
+		(agent.LoginBeforeReady || agent.LifecycleState == codersdk.WorkspaceAgentLifecycleReady) {
 		return nil
 	}
-	if agent.Status == codersdk.WorkspaceAgentDisconnected {
-		opts.WarnInterval = 0
-	}
+
+	ctx, cancel := signal.NotifyContext(ctx, os.Interrupt)
+	defer cancel()
+
 	spin := spinner.New(spinner.CharSets[78], 100*time.Millisecond, spinner.WithColor("fgHiGreen"))
 	spin.Writer = writer
 	spin.ForceOutput = true
-	spin.Suffix = " Waiting for connection from " + Styles.Field.Render(agent.Name) + "..."
-	spin.Start()
-	defer spin.Stop()
+	spin.Suffix = waitingMessage(agent, opts).Spin
 
-	ctx, cancelFunc := context.WithCancel(ctx)
-	defer cancelFunc()
-	stopSpin := make(chan os.Signal, 1)
-	signal.Notify(stopSpin, os.Interrupt)
-	defer signal.Stop(stopSpin)
-	go func() {
-		select {
-		case <-ctx.Done():
-			return
-		case <-stopSpin:
-		}
-		signal.Stop(stopSpin)
-		spin.Stop()
-		// nolint:revive
-		os.Exit(1)
-	}()
-
-	ticker := time.NewTicker(opts.FetchInterval)
-	defer ticker.Stop()
-	timer := time.NewTimer(opts.WarnInterval)
-	defer timer.Stop()
-	go func() {
-		select {
-		case <-ctx.Done():
-			return
-		case <-timer.C:
-		}
+	waitMessage := &message{}
+	showMessage := func() {
 		resourceMutex.Lock()
 		defer resourceMutex.Unlock()
-		message := "Don't panic, your workspace is booting up!"
-		if agent.Status == codersdk.WorkspaceAgentDisconnected {
-			message = "The workspace agent lost connection! Wait for it to reconnect or restart your workspace."
+
+		m := waitingMessage(agent, opts)
+		if m.Prompt == waitMessage.Prompt {
+			return
+		}
+		moveUp := ""
+		if waitMessage.Prompt != "" {
+			// If this is an update, move a line up
+			// to keep it tidy and aligned.
+			moveUp = "\033[1A"
+		}
+		waitMessage = m
+
+		// Stop the spinner while we write our message.
+		spin.Stop()
+		spin.Suffix = waitMessage.Spin
+		// Clear the line and (if necessary) move up a line to write our message.
+		_, _ = fmt.Fprintf(writer, "\033[2K%s\n%s\n", moveUp, waitMessage.Prompt)
+		select {
+		case <-ctx.Done():
+		default:
+			// Safe to resume operation.
+			if spin.Suffix != "" {
+				spin.Start()
+			}
+		}
+	}
+
+	// Fast path for showing the error message even when using no wait,
+	// we do this just before starting the spinner to avoid needless
+	// spinning.
+	if agent.Status == codersdk.WorkspaceAgentConnected &&
+		!agent.LoginBeforeReady && opts.NoWait {
+		showMessage()
+		return nil
+	}
+
+	// Start spinning after fast paths are handled.
+	if spin.Suffix != "" {
+		spin.Start()
+	}
+	defer spin.Stop()
+
+	warnAfter := time.NewTimer(opts.WarnInterval)
+	defer warnAfter.Stop()
+	warningShown := make(chan struct{})
+	go func() {
+		select {
+		case <-ctx.Done():
+			close(warningShown)
+		case <-warnAfter.C:
+			close(warningShown)
+			showMessage()
 		}
-		// This saves the cursor position, then defers clearing from the cursor
-		// position to the end of the screen.
-		_, _ = fmt.Fprintf(writer, "\033[s\r\033[2K%s\n\n", Styles.Paragraph.Render(Styles.Prompt.String()+message))
-		defer fmt.Fprintf(writer, "\033[u\033[J")
 	}()
+
+	fetchInterval := time.NewTicker(opts.FetchInterval)
+	defer fetchInterval.Stop()
 	for {
 		select {
 		case <-ctx.Done():
 			return ctx.Err()
-		case <-ticker.C:
+		case <-fetchInterval.C:
 		}
 		resourceMutex.Lock()
 		agent, err = opts.Fetch(ctx)
 		if err != nil {
+			resourceMutex.Unlock()
 			return xerrors.Errorf("fetch: %w", err)
 		}
-		if agent.Status != codersdk.WorkspaceAgentConnected {
-			resourceMutex.Unlock()
-			continue
-		}
 		resourceMutex.Unlock()
-		return nil
+		switch agent.Status {
+		case codersdk.WorkspaceAgentConnected:
+			// NOTE(mafredri): Once we have access to the workspace agent's
+			// startup script logs, we can show them here.
+			// https://github.com/coder/coder/issues/2957
+			if !agent.LoginBeforeReady && !opts.NoWait {
+				switch agent.LifecycleState {
+				case codersdk.WorkspaceAgentLifecycleReady:
+					return nil
+				case codersdk.WorkspaceAgentLifecycleStartTimeout:
+					showMessage()
+				case codersdk.WorkspaceAgentLifecycleStartError:
+					showMessage()
+					return AgentStartError
+				case codersdk.WorkspaceAgentLifecycleShuttingDown, codersdk.WorkspaceAgentLifecycleShutdownTimeout,
+					codersdk.WorkspaceAgentLifecycleShutdownError, codersdk.WorkspaceAgentLifecycleOff:
+					showMessage()
+					return AgentShuttingDown
+				default:
+					select {
+					case <-warningShown:
+						showMessage()
+					default:
+						// This state is normal, we don't want
+						// to show a message prematurely.
+					}
+				}
+				continue
+			}
+			return nil
+		case codersdk.WorkspaceAgentTimeout, codersdk.WorkspaceAgentDisconnected:
+			showMessage()
+		}
 	}
 }
+
+type message struct {
+	Spin         string
+	Prompt       string
+	Troubleshoot bool
+}
+
+func waitingMessage(agent codersdk.WorkspaceAgent, opts AgentOptions) (m *message) {
+	m = &message{
+		Spin:   fmt.Sprintf("Waiting for connection from %s...", Styles.Field.Render(agent.Name)),
+		Prompt: "Don't panic, your workspace is booting up!",
+	}
+	defer func() {
+		if agent.Status == codersdk.WorkspaceAgentConnected && opts.NoWait {
+			m.Spin = ""
+		}
+		if m.Spin != "" {
+			m.Spin = " " + m.Spin
+		}
+
+		// We don't want to wrap the troubleshooting URL, so we'll handle word
+		// wrapping ourselves (vs using lipgloss).
+		w := wordwrap.NewWriter(Styles.Paragraph.GetWidth() - Styles.Paragraph.GetMarginLeft()*2)
+		w.Breakpoints = []rune{' ', '\n'}
+
+		_, _ = fmt.Fprint(w, m.Prompt)
+		if m.Troubleshoot {
+			if agent.TroubleshootingURL != "" {
+				_, _ = fmt.Fprintf(w, " See troubleshooting instructions at:\n%s", agent.TroubleshootingURL)
+			} else {
+				_, _ = fmt.Fprint(w, " Wait for it to (re)connect or restart your workspace.")
+			}
+		}
+		_, _ = fmt.Fprint(w, "\n")
+
+		// We want to prefix the prompt with a caret, but we want text on the
+		// following lines to align with the text on the first line (i.e. added
+		// spacing).
+		ind := " " + Styles.Prompt.String()
+		iw := indent.NewWriter(1, func(w io.Writer) {
+			_, _ = w.Write([]byte(ind))
+			ind = "   " // Set indentation to space after initial prompt.
+		})
+		_, _ = fmt.Fprint(iw, w.String())
+		m.Prompt = iw.String()
+	}()
+
+	switch agent.Status {
+	case codersdk.WorkspaceAgentTimeout:
+		m.Prompt = "The workspace agent is having trouble connecting."
+	case codersdk.WorkspaceAgentDisconnected:
+		m.Prompt = "The workspace agent lost connection!"
+	case codersdk.WorkspaceAgentConnected:
+		m.Spin = fmt.Sprintf("Waiting for %s to become ready...", Styles.Field.Render(agent.Name))
+		m.Prompt = "Don't panic, your workspace agent has connected and the workspace is getting ready!"
+		if opts.NoWait {
+			m.Prompt = "Your workspace is still getting ready, it may be in an incomplete state."
+		}
+
+		switch agent.LifecycleState {
+		case codersdk.WorkspaceAgentLifecycleStartTimeout:
+			m.Prompt = "The workspace is taking longer than expected to get ready, the agent startup script is still executing."
+		case codersdk.WorkspaceAgentLifecycleStartError:
+			m.Spin = ""
+			m.Prompt = "The workspace ran into a problem while getting ready, the agent startup script exited with non-zero status."
+		default:
+			switch agent.LifecycleState {
+			case codersdk.WorkspaceAgentLifecycleShutdownTimeout:
+				m.Spin = ""
+				m.Prompt = "The workspace is shutting down, but is taking longer than expected to shut down and the agent shutdown script is still executing."
+				m.Troubleshoot = true
+			case codersdk.WorkspaceAgentLifecycleShutdownError:
+				m.Spin = ""
+				m.Prompt = "The workspace ran into a problem while shutting down, the agent shutdown script exited with non-zero status."
+				m.Troubleshoot = true
+			case codersdk.WorkspaceAgentLifecycleShuttingDown:
+				m.Spin = ""
+				m.Prompt = "The workspace is shutting down."
+			case codersdk.WorkspaceAgentLifecycleOff:
+				m.Spin = ""
+				m.Prompt = "The workspace is not running."
+			}
+			// Not a failure state, no troubleshooting necessary.
+			return m
+		}
+	default:
+		// Not a failure state, no troubleshooting necessary.
+		return m
+	}
+	m.Troubleshoot = true
+	return m
+}

cli/cliui/agent_test.go

@@ -5,26 +5,33 @@ import (
 	"testing"
 	"time"
 
-	"github.com/spf13/cobra"
 	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
 	"go.uber.org/atomic"
 
+	"github.com/coder/coder/cli/clibase"
 	"github.com/coder/coder/cli/cliui"
 	"github.com/coder/coder/codersdk"
 	"github.com/coder/coder/pty/ptytest"
+	"github.com/coder/coder/testutil"
 )
 
 func TestAgent(t *testing.T) {
 	t.Parallel()
+
+	ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitShort)
+	defer cancel()
+
 	var disconnected atomic.Bool
 	ptty := ptytest.New(t)
-	cmd := &cobra.Command{
-		RunE: func(cmd *cobra.Command, args []string) error {
-			err := cliui.Agent(cmd.Context(), cmd.OutOrStdout(), cliui.AgentOptions{
+	cmd := &clibase.Cmd{
+		Handler: func(inv *clibase.Invocation) error {
+			err := cliui.Agent(inv.Context(), inv.Stdout, cliui.AgentOptions{
 				WorkspaceName: "example",
-				Fetch: func(ctx context.Context) (codersdk.WorkspaceAgent, error) {
+				Fetch: func(_ context.Context) (codersdk.WorkspaceAgent, error) {
 					agent := codersdk.WorkspaceAgent{
-						Status: codersdk.WorkspaceAgentDisconnected,
+						Status:           codersdk.WorkspaceAgentDisconnected,
+						LoginBeforeReady: true,
 					}
 					if disconnected.Load() {
 						agent.Status = codersdk.WorkspaceAgentConnected
@@ -37,15 +44,320 @@ func TestAgent(t *testing.T) {
 			return err
 		},
 	}
-	cmd.SetOutput(ptty.Output())
-	cmd.SetIn(ptty.Input())
+
+	inv := cmd.Invoke()
+	ptty.Attach(inv)
 	done := make(chan struct{})
 	go func() {
 		defer close(done)
-		err := cmd.Execute()
+		err := inv.Run()
 		assert.NoError(t, err)
 	}()
-	ptty.ExpectMatch("lost connection")
+	ptty.ExpectMatchContext(ctx, "lost connection")
 	disconnected.Store(true)
 	<-done
 }
+
+func TestAgent_TimeoutWithTroubleshootingURL(t *testing.T) {
+	t.Parallel()
+
+	ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitShort)
+	defer cancel()
+
+	wantURL := "https://coder.com/troubleshoot"
+
+	var connected, timeout atomic.Bool
+	cmd := &clibase.Cmd{
+		Handler: func(inv *clibase.Invocation) error {
+			err := cliui.Agent(inv.Context(), inv.Stdout, cliui.AgentOptions{
+				WorkspaceName: "example",
+				Fetch: func(_ context.Context) (codersdk.WorkspaceAgent, error) {
+					agent := codersdk.WorkspaceAgent{
+						Status:             codersdk.WorkspaceAgentConnecting,
+						TroubleshootingURL: wantURL,
+						LoginBeforeReady:   true,
+					}
+					switch {
+					case !connected.Load() && timeout.Load():
+						agent.Status = codersdk.WorkspaceAgentTimeout
+					case connected.Load():
+						agent.Status = codersdk.WorkspaceAgentConnected
+					}
+					return agent, nil
+				},
+				FetchInterval: time.Millisecond,
+				WarnInterval:  5 * time.Millisecond,
+			})
+			return err
+		},
+	}
+	ptty := ptytest.New(t)
+
+	inv := cmd.Invoke()
+	ptty.Attach(inv)
+	done := make(chan error, 1)
+	go func() {
+		done <- inv.WithContext(ctx).Run()
+	}()
+	ptty.ExpectMatchContext(ctx, "Don't panic, your workspace is booting")
+	timeout.Store(true)
+	ptty.ExpectMatchContext(ctx, wantURL)
+	connected.Store(true)
+	require.NoError(t, <-done)
+}
+
+func TestAgent_StartupTimeout(t *testing.T) {
+	t.Parallel()
+
+	ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitShort)
+	defer cancel()
+
+	wantURL := "https://coder.com/this-is-a-really-long-troubleshooting-url-that-should-not-wrap"
+
+	var status, state atomic.String
+	setStatus := func(s codersdk.WorkspaceAgentStatus) { status.Store(string(s)) }
+	setState := func(s codersdk.WorkspaceAgentLifecycle) { state.Store(string(s)) }
+
+	cmd := &clibase.Cmd{
+		Handler: func(inv *clibase.Invocation) error {
+			err := cliui.Agent(inv.Context(), inv.Stdout, cliui.AgentOptions{
+				WorkspaceName: "example",
+				Fetch: func(_ context.Context) (codersdk.WorkspaceAgent, error) {
+					agent := codersdk.WorkspaceAgent{
+						Status:             codersdk.WorkspaceAgentConnecting,
+						LoginBeforeReady:   false,
+						LifecycleState:     codersdk.WorkspaceAgentLifecycleCreated,
+						TroubleshootingURL: wantURL,
+					}
+
+					if s := status.Load(); s != "" {
+						agent.Status = codersdk.WorkspaceAgentStatus(s)
+					}
+					if s := state.Load(); s != "" {
+						agent.LifecycleState = codersdk.WorkspaceAgentLifecycle(s)
+					}
+					return agent, nil
+				},
+				FetchInterval: time.Millisecond,
+				WarnInterval:  time.Millisecond,
+				NoWait:        false,
+			})
+			return err
+		},
+	}
+
+	ptty := ptytest.New(t)
+
+	inv := cmd.Invoke()
+	ptty.Attach(inv)
+	done := make(chan error, 1)
+	go func() {
+		done <- inv.WithContext(ctx).Run()
+	}()
+	setStatus(codersdk.WorkspaceAgentConnecting)
+	ptty.ExpectMatchContext(ctx, "Don't panic, your workspace is booting")
+	setStatus(codersdk.WorkspaceAgentConnected)
+	setState(codersdk.WorkspaceAgentLifecycleStarting)
+	ptty.ExpectMatchContext(ctx, "workspace is getting ready")
+	setState(codersdk.WorkspaceAgentLifecycleStartTimeout)
+	ptty.ExpectMatchContext(ctx, "is taking longer")
+	ptty.ExpectMatchContext(ctx, wantURL)
+	setState(codersdk.WorkspaceAgentLifecycleReady)
+	require.NoError(t, <-done)
+}
+
+func TestAgent_StartErrorExit(t *testing.T) {
+	t.Parallel()
+
+	ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitShort)
+	defer cancel()
+
+	wantURL := "https://coder.com/this-is-a-really-long-troubleshooting-url-that-should-not-wrap"
+
+	var status, state atomic.String
+	setStatus := func(s codersdk.WorkspaceAgentStatus) { status.Store(string(s)) }
+	setState := func(s codersdk.WorkspaceAgentLifecycle) { state.Store(string(s)) }
+	cmd := &clibase.Cmd{
+		Handler: func(inv *clibase.Invocation) error {
+			err := cliui.Agent(inv.Context(), inv.Stdout, cliui.AgentOptions{
+				WorkspaceName: "example",
+				Fetch: func(_ context.Context) (codersdk.WorkspaceAgent, error) {
+					agent := codersdk.WorkspaceAgent{
+						Status:             codersdk.WorkspaceAgentConnecting,
+						LoginBeforeReady:   false,
+						LifecycleState:     codersdk.WorkspaceAgentLifecycleCreated,
+						TroubleshootingURL: wantURL,
+					}
+
+					if s := status.Load(); s != "" {
+						agent.Status = codersdk.WorkspaceAgentStatus(s)
+					}
+					if s := state.Load(); s != "" {
+						agent.LifecycleState = codersdk.WorkspaceAgentLifecycle(s)
+					}
+					return agent, nil
+				},
+				FetchInterval: time.Millisecond,
+				WarnInterval:  60 * time.Second,
+				NoWait:        false,
+			})
+			return err
+		},
+	}
+
+	ptty := ptytest.New(t)
+
+	inv := cmd.Invoke()
+	ptty.Attach(inv)
+	done := make(chan error, 1)
+	go func() {
+		done <- inv.WithContext(ctx).Run()
+	}()
+	setStatus(codersdk.WorkspaceAgentConnected)
+	setState(codersdk.WorkspaceAgentLifecycleStarting)
+	ptty.ExpectMatchContext(ctx, "to become ready...")
+	setState(codersdk.WorkspaceAgentLifecycleStartError)
+	ptty.ExpectMatchContext(ctx, "ran into a problem")
+	err := <-done
+	require.ErrorIs(t, err, cliui.AgentStartError, "lifecycle start_error should exit with error")
+}
+
+func TestAgent_NoWait(t *testing.T) {
+	t.Parallel()
+
+	ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitShort)
+	defer cancel()
+
+	wantURL := "https://coder.com/this-is-a-really-long-troubleshooting-url-that-should-not-wrap"
+
+	var status, state atomic.String
+	setStatus := func(s codersdk.WorkspaceAgentStatus) { status.Store(string(s)) }
+	setState := func(s codersdk.WorkspaceAgentLifecycle) { state.Store(string(s)) }
+	cmd := &clibase.Cmd{
+		Handler: func(inv *clibase.Invocation) error {
+			err := cliui.Agent(inv.Context(), inv.Stdout, cliui.AgentOptions{
+				WorkspaceName: "example",
+				Fetch: func(_ context.Context) (codersdk.WorkspaceAgent, error) {
+					agent := codersdk.WorkspaceAgent{
+						Status:             codersdk.WorkspaceAgentConnecting,
+						LoginBeforeReady:   false,
+						LifecycleState:     codersdk.WorkspaceAgentLifecycleCreated,
+						TroubleshootingURL: wantURL,
+					}
+
+					if s := status.Load(); s != "" {
+						agent.Status = codersdk.WorkspaceAgentStatus(s)
+					}
+					if s := state.Load(); s != "" {
+						agent.LifecycleState = codersdk.WorkspaceAgentLifecycle(s)
+					}
+					return agent, nil
+				},
+				FetchInterval: time.Millisecond,
+				WarnInterval:  time.Second,
+				NoWait:        true,
+			})
+			return err
+		},
+	}
+
+	ptty := ptytest.New(t)
+
+	inv := cmd.Invoke()
+	ptty.Attach(inv)
+	done := make(chan error, 1)
+	go func() {
+		done <- inv.WithContext(ctx).Run()
+	}()
+	setStatus(codersdk.WorkspaceAgentConnecting)
+	ptty.ExpectMatchContext(ctx, "Don't panic, your workspace is booting")
+
+	setStatus(codersdk.WorkspaceAgentConnected)
+	require.NoError(t, <-done, "created - should exit early")
+
+	setState(codersdk.WorkspaceAgentLifecycleStarting)
+	go func() { done <- inv.WithContext(ctx).Run() }()
+	require.NoError(t, <-done, "starting - should exit early")
+
+	setState(codersdk.WorkspaceAgentLifecycleStartTimeout)
+	go func() { done <- inv.WithContext(ctx).Run() }()
+	require.NoError(t, <-done, "start timeout - should exit early")
+
+	setState(codersdk.WorkspaceAgentLifecycleStartError)
+	go func() { done <- inv.WithContext(ctx).Run() }()
+	require.NoError(t, <-done, "start error - should exit early")
+
+	setState(codersdk.WorkspaceAgentLifecycleReady)
+	go func() { done <- inv.WithContext(ctx).Run() }()
+	require.NoError(t, <-done, "ready - should exit early")
+}
+
+func TestAgent_LoginBeforeReadyEnabled(t *testing.T) {
+	t.Parallel()
+
+	ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitShort)
+	defer cancel()
+
+	wantURL := "https://coder.com/this-is-a-really-long-troubleshooting-url-that-should-not-wrap"
+
+	var status, state atomic.String
+	setStatus := func(s codersdk.WorkspaceAgentStatus) { status.Store(string(s)) }
+	setState := func(s codersdk.WorkspaceAgentLifecycle) { state.Store(string(s)) }
+	cmd := &clibase.Cmd{
+		Handler: func(inv *clibase.Invocation) error {
+			err := cliui.Agent(inv.Context(), inv.Stdout, cliui.AgentOptions{
+				WorkspaceName: "example",
+				Fetch: func(_ context.Context) (codersdk.WorkspaceAgent, error) {
+					agent := codersdk.WorkspaceAgent{
+						Status:             codersdk.WorkspaceAgentConnecting,
+						LoginBeforeReady:   true,
+						LifecycleState:     codersdk.WorkspaceAgentLifecycleCreated,
+						TroubleshootingURL: wantURL,
+					}
+
+					if s := status.Load(); s != "" {
+						agent.Status = codersdk.WorkspaceAgentStatus(s)
+					}
+					if s := state.Load(); s != "" {
+						agent.LifecycleState = codersdk.WorkspaceAgentLifecycle(s)
+					}
+					return agent, nil
+				},
+				FetchInterval: time.Millisecond,
+				WarnInterval:  time.Second,
+				NoWait:        false,
+			})
+			return err
+		},
+	}
+
+	inv := cmd.Invoke()
+
+	ptty := ptytest.New(t)
+	ptty.Attach(inv)
+	done := make(chan error, 1)
+	go func() {
+		done <- inv.WithContext(ctx).Run()
+	}()
+	setStatus(codersdk.WorkspaceAgentConnecting)
+	ptty.ExpectMatchContext(ctx, "Don't panic, your workspace is booting")
+
+	setStatus(codersdk.WorkspaceAgentConnected)
+	require.NoError(t, <-done, "created - should exit early")
+
+	setState(codersdk.WorkspaceAgentLifecycleStarting)
+	go func() { done <- inv.WithContext(ctx).Run() }()
+	require.NoError(t, <-done, "starting - should exit early")
+
+	setState(codersdk.WorkspaceAgentLifecycleStartTimeout)
+	go func() { done <- inv.WithContext(ctx).Run() }()
+	require.NoError(t, <-done, "start timeout - should exit early")
+
+	setState(codersdk.WorkspaceAgentLifecycleStartError)
+	go func() { done <- inv.WithContext(ctx).Run() }()
+	require.NoError(t, <-done, "start error - should exit early")
+
+	setState(codersdk.WorkspaceAgentLifecycleReady)
+	go func() { done <- inv.WithContext(ctx).Run() }()
+	require.NoError(t, <-done, "ready - should exit early")
+}

cli/cliui/cliui.go

@@ -49,10 +49,12 @@ var Styles = struct {
 	Keyword:       defaultStyles.Keyword,
 	Paragraph:     defaultStyles.Paragraph,
 	Placeholder:   lipgloss.NewStyle().Foreground(lipgloss.AdaptiveColor{Light: "#585858", Dark: "#4d46b3"}),
-	Prompt:        defaultStyles.Prompt.Foreground(lipgloss.AdaptiveColor{Light: "#9B9B9B", Dark: "#5C5C5C"}),
-	FocusedPrompt: defaultStyles.FocusedPrompt.Foreground(lipgloss.Color("#651fff")),
+	Prompt:        defaultStyles.Prompt.Copy().Foreground(lipgloss.AdaptiveColor{Light: "#9B9B9B", Dark: "#5C5C5C"}),
+	FocusedPrompt: defaultStyles.FocusedPrompt.Copy().Foreground(lipgloss.Color("#651fff")),
 	Fuchsia:       defaultStyles.SelectedMenuItem.Copy(),
-	Logo:          defaultStyles.Logo.SetString("Coder"),
-	Warn:          lipgloss.NewStyle().Foreground(lipgloss.AdaptiveColor{Light: "#04B575", Dark: "#ECFD65"}),
-	Wrap:          lipgloss.NewStyle().Width(80),
+	Logo:          defaultStyles.Logo.Copy().SetString("Coder"),
+	Warn: lipgloss.NewStyle().Foreground(
+		lipgloss.AdaptiveColor{Light: "#04B575", Dark: "#ECFD65"},
+	),
+	Wrap: lipgloss.NewStyle().Width(80),
 }

cli/cliui/gitauth.go

@@ -0,0 +1,72 @@
+package cliui
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"time"
+
+	"github.com/briandowns/spinner"
+
+	"github.com/coder/coder/codersdk"
+)
+
+type GitAuthOptions struct {
+	Fetch         func(context.Context) ([]codersdk.TemplateVersionGitAuth, error)
+	FetchInterval time.Duration
+}
+
+func GitAuth(ctx context.Context, writer io.Writer, opts GitAuthOptions) error {
+	if opts.FetchInterval == 0 {
+		opts.FetchInterval = 500 * time.Millisecond
+	}
+	gitAuth, err := opts.Fetch(ctx)
+	if err != nil {
+		return err
+	}
+
+	spin := spinner.New(spinner.CharSets[78], 100*time.Millisecond, spinner.WithColor("fgHiGreen"))
+	spin.Writer = writer
+	spin.ForceOutput = true
+	spin.Suffix = " Waiting for Git authentication..."
+	defer spin.Stop()
+
+	ticker := time.NewTicker(opts.FetchInterval)
+	defer ticker.Stop()
+	for _, auth := range gitAuth {
+		if auth.Authenticated {
+			return nil
+		}
+
+		_, _ = fmt.Fprintf(writer, "You must authenticate with %s to create a workspace with this template. Visit:\n\n\t%s\n\n", auth.Type.Pretty(), auth.AuthenticateURL)
+
+		ticker.Reset(opts.FetchInterval)
+		spin.Start()
+		for {
+			select {
+			case <-ctx.Done():
+				return ctx.Err()
+			case <-ticker.C:
+			}
+			gitAuth, err := opts.Fetch(ctx)
+			if err != nil {
+				return err
+			}
+			var authed bool
+			for _, a := range gitAuth {
+				if !a.Authenticated || a.ID != auth.ID {
+					continue
+				}
+				authed = true
+				break
+			}
+			// The user authenticated with the provider!
+			if authed {
+				break
+			}
+		}
+		spin.Stop()
+		_, _ = fmt.Fprintf(writer, "Successfully authenticated with %s!\n\n", auth.Type.Pretty())
+	}
+	return nil
+}

cli/cliui/gitauth_test.go

@@ -0,0 +1,57 @@
+package cliui_test
+
+import (
+	"context"
+	"net/url"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+
+	"github.com/coder/coder/cli/clibase"
+	"github.com/coder/coder/cli/cliui"
+	"github.com/coder/coder/codersdk"
+	"github.com/coder/coder/pty/ptytest"
+	"github.com/coder/coder/testutil"
+)
+
+func TestGitAuth(t *testing.T) {
+	t.Parallel()
+
+	ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitShort)
+	defer cancel()
+
+	ptty := ptytest.New(t)
+	cmd := &clibase.Cmd{
+		Handler: func(inv *clibase.Invocation) error {
+			var fetched atomic.Bool
+			return cliui.GitAuth(inv.Context(), inv.Stdout, cliui.GitAuthOptions{
+				Fetch: func(ctx context.Context) ([]codersdk.TemplateVersionGitAuth, error) {
+					defer fetched.Store(true)
+					return []codersdk.TemplateVersionGitAuth{{
+						ID:              "github",
+						Type:            codersdk.GitProviderGitHub,
+						Authenticated:   fetched.Load(),
+						AuthenticateURL: "https://example.com/gitauth/github?redirect=" + url.QueryEscape("/gitauth?notify"),
+					}}, nil
+				},
+				FetchInterval: time.Millisecond,
+			})
+		},
+	}
+
+	inv := cmd.Invoke().WithContext(ctx)
+
+	ptty.Attach(inv)
+	done := make(chan struct{})
+	go func() {
+		defer close(done)
+		err := inv.Run()
+		assert.NoError(t, err)
+	}()
+	ptty.ExpectMatchContext(ctx, "You must authenticate with")
+	ptty.ExpectMatchContext(ctx, "https://example.com/gitauth/github")
+	ptty.ExpectMatchContext(ctx, "Successfully authenticated with GitHub")
+	<-done
+}

cli/cliui/log.go

@@ -10,17 +10,22 @@ import (
 
 // cliMessage provides a human-readable message for CLI errors and messages.
 type cliMessage struct {
-	Level  string
 	Style  lipgloss.Style
 	Header string
+	Prefix string
 	Lines  []string
 }
 
 // String formats the CLI message for consumption by a human.
 func (m cliMessage) String() string {
 	var str strings.Builder
-	_, _ = fmt.Fprintf(&str, "%s\r\n",
-		Styles.Bold.Render(m.Header))
+
+	if m.Prefix != "" {
+		_, _ = str.WriteString(m.Style.Bold(true).Render(m.Prefix))
+	}
+
+	_, _ = str.WriteString(m.Style.Bold(false).Render(m.Header))
+	_, _ = str.WriteString("\r\n")
 	for _, line := range m.Lines {
 		_, _ = fmt.Fprintf(&str, "  %s %s\r\n", m.Style.Render("|"), line)
 	}
@@ -30,9 +35,42 @@ func (m cliMessage) String() string {
 // Warn writes a log to the writer provided.
 func Warn(wtr io.Writer, header string, lines ...string) {
 	_, _ = fmt.Fprint(wtr, cliMessage{
-		Level:  "warning",
-		Style:  Styles.Warn,
+		Style:  Styles.Warn.Copy(),
+		Prefix: "WARN: ",
 		Header: header,
 		Lines:  lines,
 	}.String())
 }
+
+// Warn writes a formatted log to the writer provided.
+func Warnf(wtr io.Writer, fmtStr string, args ...interface{}) {
+	Warn(wtr, fmt.Sprintf(fmtStr, args...))
+}
+
+// Info writes a log to the writer provided.
+func Info(wtr io.Writer, header string, lines ...string) {
+	_, _ = fmt.Fprint(wtr, cliMessage{
+		Header: header,
+		Lines:  lines,
+	}.String())
+}
+
+// Infof writes a formatted log to the writer provided.
+func Infof(wtr io.Writer, fmtStr string, args ...interface{}) {
+	Info(wtr, fmt.Sprintf(fmtStr, args...))
+}
+
+// Error writes a log to the writer provided.
+func Error(wtr io.Writer, header string, lines ...string) {
+	_, _ = fmt.Fprint(wtr, cliMessage{
+		Style:  Styles.Error.Copy(),
+		Prefix: "ERROR: ",
+		Header: header,
+		Lines:  lines,
+	}.String())
+}
+
+// Errorf writes a formatted log to the writer provided.
+func Errorf(wtr io.Writer, fmtStr string, args ...interface{}) {
+	Error(wtr, fmt.Sprintf(fmtStr, args...))
+}

cli/cliui/output.go

@@ -0,0 +1,226 @@
+package cliui
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"reflect"
+	"strings"
+
+	"golang.org/x/xerrors"
+
+	"github.com/coder/coder/cli/clibase"
+)
+
+type OutputFormat interface {
+	ID() string
+	AttachOptions(opts *clibase.OptionSet)
+	Format(ctx context.Context, data any) (string, error)
+}
+
+type OutputFormatter struct {
+	formats  []OutputFormat
+	formatID string
+}
+
+// NewOutputFormatter creates a new OutputFormatter with the given formats. The
+// first format is the default format. At least two formats must be provided.
+func NewOutputFormatter(formats ...OutputFormat) *OutputFormatter {
+	if len(formats) < 2 {
+		panic("at least two output formats must be provided")
+	}
+
+	formatIDs := make(map[string]struct{}, len(formats))
+	for _, format := range formats {
+		if format.ID() == "" {
+			panic("output format ID must not be empty")
+		}
+		if _, ok := formatIDs[format.ID()]; ok {
+			panic("duplicate format ID: " + format.ID())
+		}
+		formatIDs[format.ID()] = struct{}{}
+	}
+
+	return &OutputFormatter{
+		formats:  formats,
+		formatID: formats[0].ID(),
+	}
+}
+
+// AttachOptions attaches the --output flag to the given command, and any
+// additional flags required by the output formatters.
+func (f *OutputFormatter) AttachOptions(opts *clibase.OptionSet) {
+	for _, format := range f.formats {
+		format.AttachOptions(opts)
+	}
+
+	formatNames := make([]string, 0, len(f.formats))
+	for _, format := range f.formats {
+		formatNames = append(formatNames, format.ID())
+	}
+
+	*opts = append(*opts,
+		clibase.Option{
+			Flag:          "output",
+			FlagShorthand: "o",
+			Default:       f.formats[0].ID(),
+			Value:         clibase.StringOf(&f.formatID),
+			Description:   "Output format. Available formats: " + strings.Join(formatNames, ", ") + ".",
+		},
+	)
+}
+
+// Format formats the given data using the format specified by the --output
+// flag. If the flag is not set, the default format is used.
+func (f *OutputFormatter) Format(ctx context.Context, data any) (string, error) {
+	for _, format := range f.formats {
+		if format.ID() == f.formatID {
+			return format.Format(ctx, data)
+		}
+	}
+
+	return "", xerrors.Errorf("unknown output format %q", f.formatID)
+}
+
+type tableFormat struct {
+	defaultColumns []string
+	allColumns     []string
+	sort           string
+
+	columns []string
+}
+
+var _ OutputFormat = &tableFormat{}
+
+// TableFormat creates a table formatter for the given output type. The output
+// type should be specified as an empty slice of the desired type.
+//
+// E.g.: TableFormat([]MyType{}, []string{"foo", "bar"})
+//
+// defaultColumns is optional and specifies the default columns to display. If
+// not specified, all columns are displayed by default.
+func TableFormat(out any, defaultColumns []string) OutputFormat {
+	v := reflect.Indirect(reflect.ValueOf(out))
+	if v.Kind() != reflect.Slice {
+		panic("DisplayTable called with a non-slice type")
+	}
+
+	// Get the list of table column headers.
+	headers, defaultSort, err := typeToTableHeaders(v.Type().Elem())
+	if err != nil {
+		panic("parse table headers: " + err.Error())
+	}
+
+	tf := &tableFormat{
+		defaultColumns: headers,
+		allColumns:     headers,
+		sort:           defaultSort,
+	}
+	if len(defaultColumns) > 0 {
+		tf.defaultColumns = defaultColumns
+	}
+
+	return tf
+}
+
+// ID implements OutputFormat.
+func (*tableFormat) ID() string {
+	return "table"
+}
+
+// AttachOptions implements OutputFormat.
+func (f *tableFormat) AttachOptions(opts *clibase.OptionSet) {
+	*opts = append(*opts,
+		clibase.Option{
+			Flag:          "column",
+			FlagShorthand: "c",
+			Default:       strings.Join(f.defaultColumns, ","),
+			Value:         clibase.StringArrayOf(&f.columns),
+			Description:   "Columns to display in table output. Available columns: " + strings.Join(f.allColumns, ", ") + ".",
+		},
+	)
+}
+
+// Format implements OutputFormat.
+func (f *tableFormat) Format(_ context.Context, data any) (string, error) {
+	return DisplayTable(data, f.sort, f.columns)
+}
+
+type jsonFormat struct{}
+
+var _ OutputFormat = jsonFormat{}
+
+// JSONFormat creates a JSON formatter.
+func JSONFormat() OutputFormat {
+	return jsonFormat{}
+}
+
+// ID implements OutputFormat.
+func (jsonFormat) ID() string {
+	return "json"
+}
+
+// AttachOptions implements OutputFormat.
+func (jsonFormat) AttachOptions(_ *clibase.OptionSet) {}
+
+// Format implements OutputFormat.
+func (jsonFormat) Format(_ context.Context, data any) (string, error) {
+	outBytes, err := json.MarshalIndent(data, "", "  ")
+	if err != nil {
+		return "", xerrors.Errorf("marshal output to JSON: %w", err)
+	}
+
+	return string(outBytes), nil
+}
+
+type textFormat struct{}
+
+var _ OutputFormat = textFormat{}
+
+// TextFormat is a formatter that just outputs unstructured text.
+// It uses fmt.Sprintf under the hood.
+func TextFormat() OutputFormat {
+	return textFormat{}
+}
+
+func (textFormat) ID() string {
+	return "text"
+}
+
+func (textFormat) AttachOptions(_ *clibase.OptionSet) {}
+
+func (textFormat) Format(_ context.Context, data any) (string, error) {
+	return fmt.Sprintf("%s", data), nil
+}
+
+// DataChangeFormat allows manipulating the data passed to an output format.
+// This is because sometimes the data needs to be manipulated before it can be
+// passed to the output format.
+// For example, you may want to pass something different to the text formatter
+// than what you pass to the json formatter.
+type DataChangeFormat struct {
+	format OutputFormat
+	change func(data any) (any, error)
+}
+
+// ChangeFormatterData allows manipulating the data passed to an output
+// format.
+func ChangeFormatterData(format OutputFormat, change func(data any) (any, error)) *DataChangeFormat {
+	return &DataChangeFormat{format: format, change: change}
+}
+
+func (d *DataChangeFormat) ID() string {
+	return d.format.ID()
+}
+
+func (d *DataChangeFormat) AttachOptions(opts *clibase.OptionSet) {
+	d.format.AttachOptions(opts)
+}
+
+func (d *DataChangeFormat) Format(ctx context.Context, data any) (string, error) {
+	newData, err := d.change(data)
+	if err != nil {
+		return "", err
+	}
+	return d.format.Format(ctx, newData)
+}

cli/cliui/output_test.go

@@ -0,0 +1,139 @@
+package cliui_test
+
+import (
+	"context"
+	"encoding/json"
+	"sync/atomic"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+
+	"github.com/coder/coder/cli/clibase"
+	"github.com/coder/coder/cli/cliui"
+)
+
+type format struct {
+	id              string
+	attachOptionsFn func(opts *clibase.OptionSet)
+	formatFn        func(ctx context.Context, data any) (string, error)
+}
+
+var _ cliui.OutputFormat = &format{}
+
+func (f *format) ID() string {
+	return f.id
+}
+
+func (f *format) AttachOptions(opts *clibase.OptionSet) {
+	if f.attachOptionsFn != nil {
+		f.attachOptionsFn(opts)
+	}
+}
+
+func (f *format) Format(ctx context.Context, data any) (string, error) {
+	if f.formatFn != nil {
+		return f.formatFn(ctx, data)
+	}
+
+	return "", nil
+}
+
+func Test_OutputFormatter(t *testing.T) {
+	t.Parallel()
+
+	t.Run("RequiresTwoFormatters", func(t *testing.T) {
+		t.Parallel()
+
+		require.Panics(t, func() {
+			cliui.NewOutputFormatter()
+		})
+		require.Panics(t, func() {
+			cliui.NewOutputFormatter(cliui.JSONFormat())
+		})
+		require.NotPanics(t, func() {
+			cliui.NewOutputFormatter(cliui.JSONFormat(), cliui.TextFormat())
+		})
+	})
+
+	t.Run("NoMissingFormatID", func(t *testing.T) {
+		t.Parallel()
+
+		require.Panics(t, func() {
+			cliui.NewOutputFormatter(
+				cliui.JSONFormat(),
+				&format{id: ""},
+			)
+		})
+	})
+
+	t.Run("NoDuplicateFormats", func(t *testing.T) {
+		t.Parallel()
+
+		require.Panics(t, func() {
+			cliui.NewOutputFormatter(
+				cliui.JSONFormat(),
+				cliui.JSONFormat(),
+			)
+		})
+	})
+
+	t.Run("OK", func(t *testing.T) {
+		t.Parallel()
+
+		var called int64
+		f := cliui.NewOutputFormatter(
+			cliui.JSONFormat(),
+			&format{
+				id: "foo",
+				attachOptionsFn: func(opts *clibase.OptionSet) {
+					opts.Add(clibase.Option{
+						Name:          "foo",
+						Flag:          "foo",
+						FlagShorthand: "f",
+						Value:         clibase.DiscardValue,
+						Description:   "foo flag 1234",
+					})
+				},
+				formatFn: func(_ context.Context, _ any) (string, error) {
+					atomic.AddInt64(&called, 1)
+					return "foo", nil
+				},
+			},
+		)
+
+		cmd := &clibase.Cmd{}
+		f.AttachOptions(&cmd.Options)
+
+		fs := cmd.Options.FlagSet()
+
+		selected, err := fs.GetString("output")
+		require.NoError(t, err)
+		require.Equal(t, "json", selected)
+		usage := fs.FlagUsages()
+		require.Contains(t, usage, "Available formats: json, foo")
+		require.Contains(t, usage, "foo flag 1234")
+
+		ctx := context.Background()
+		data := []string{"hi", "dean", "was", "here"}
+		out, err := f.Format(ctx, data)
+		require.NoError(t, err)
+
+		var got []string
+		require.NoError(t, json.Unmarshal([]byte(out), &got))
+		require.Equal(t, data, got)
+		require.EqualValues(t, 0, atomic.LoadInt64(&called))
+
+		require.NoError(t, fs.Set("output", "foo"))
+		out, err = f.Format(ctx, data)
+		require.NoError(t, err)
+		require.Equal(t, "foo", out)
+		require.EqualValues(t, 1, atomic.LoadInt64(&called))
+
+		require.NoError(t, fs.Set("output", "bar"))
+		out, err = f.Format(ctx, data)
+		require.Error(t, err)
+		require.ErrorContains(t, err, "bar")
+		require.Equal(t, "", out)
+		require.EqualValues(t, 1, atomic.LoadInt64(&called))
+	})
+}

cli/cliui/parameter.go

@@ -1,19 +1,19 @@
 package cliui
 
 import (
+	"encoding/json"
 	"fmt"
 	"strings"
 
-	"github.com/spf13/cobra"
-
+	"github.com/coder/coder/cli/clibase"
 	"github.com/coder/coder/coderd/parameter"
 	"github.com/coder/coder/codersdk"
 )
 
-func ParameterSchema(cmd *cobra.Command, parameterSchema codersdk.ParameterSchema) (string, error) {
-	_, _ = fmt.Fprintln(cmd.OutOrStdout(), Styles.Bold.Render("var."+parameterSchema.Name))
+func ParameterSchema(inv *clibase.Invocation, parameterSchema codersdk.ParameterSchema) (string, error) {
+	_, _ = fmt.Fprintln(inv.Stdout, Styles.Bold.Render("var."+parameterSchema.Name))
 	if parameterSchema.Description != "" {
-		_, _ = fmt.Fprintln(cmd.OutOrStdout(), "  "+strings.TrimSpace(strings.Join(strings.Split(parameterSchema.Description, "\n"), "\n  "))+"\n")
+		_, _ = fmt.Fprintln(inv.Stdout, "  "+strings.TrimSpace(strings.Join(strings.Split(parameterSchema.Description, "\n"), "\n  "))+"\n")
 	}
 
 	var err error
@@ -27,15 +27,15 @@ func ParameterSchema(cmd *cobra.Command, parameterSchema codersdk.ParameterSchem
 	var value string
 	if len(options) > 0 {
 		// Move the cursor up a single line for nicer display!
-		_, _ = fmt.Fprint(cmd.OutOrStdout(), "\033[1A")
-		value, err = Select(cmd, SelectOptions{
+		_, _ = fmt.Fprint(inv.Stdout, "\033[1A")
+		value, err = Select(inv, SelectOptions{
 			Options:    options,
 			Default:    parameterSchema.DefaultSourceValue,
 			HideSearch: true,
 		})
 		if err == nil {
-			_, _ = fmt.Fprintln(cmd.OutOrStdout())
-			_, _ = fmt.Fprintln(cmd.OutOrStdout(), "  "+Styles.Prompt.String()+Styles.Field.Render(value))
+			_, _ = fmt.Fprintln(inv.Stdout)
+			_, _ = fmt.Fprintln(inv.Stdout, "  "+Styles.Prompt.String()+Styles.Field.Render(value))
 		}
 	} else {
 		text := "Enter a value"
@@ -44,7 +44,7 @@ func ParameterSchema(cmd *cobra.Command, parameterSchema codersdk.ParameterSchem
 		}
 		text += ":"
 
-		value, err = Prompt(cmd, PromptOptions{
+		value, err = Prompt(inv, PromptOptions{
 			Text: Styles.Bold.Render(text),
 		})
 		value = strings.TrimSpace(value)
@@ -60,3 +60,85 @@ func ParameterSchema(cmd *cobra.Command, parameterSchema codersdk.ParameterSchem
 
 	return value, nil
 }
+
+func RichParameter(inv *clibase.Invocation, templateVersionParameter codersdk.TemplateVersionParameter) (string, error) {
+	label := templateVersionParameter.Name
+	if templateVersionParameter.DisplayName != "" {
+		label = templateVersionParameter.DisplayName
+	}
+
+	_, _ = fmt.Fprintln(inv.Stdout, Styles.Bold.Render(label))
+	if templateVersionParameter.DescriptionPlaintext != "" {
+		_, _ = fmt.Fprintln(inv.Stdout, "  "+strings.TrimSpace(strings.Join(strings.Split(templateVersionParameter.DescriptionPlaintext, "\n"), "\n  "))+"\n")
+	}
+
+	var err error
+	var value string
+	if templateVersionParameter.Type == "list(string)" {
+		// Move the cursor up a single line for nicer display!
+		_, _ = fmt.Fprint(inv.Stdout, "\033[1A")
+
+		var options []string
+		err = json.Unmarshal([]byte(templateVersionParameter.DefaultValue), &options)
+		if err != nil {
+			return "", err
+		}
+
+		values, err := MultiSelect(inv, options)
+		if err == nil {
+			v, err := json.Marshal(&values)
+			if err != nil {
+				return "", err
+			}
+
+			_, _ = fmt.Fprintln(inv.Stdout)
+			_, _ = fmt.Fprintln(inv.Stdout, "  "+Styles.Prompt.String()+Styles.Field.Render(strings.Join(values, ", ")))
+			value = string(v)
+		}
+	} else if len(templateVersionParameter.Options) > 0 {
+		// Move the cursor up a single line for nicer display!
+		_, _ = fmt.Fprint(inv.Stdout, "\033[1A")
+		var richParameterOption *codersdk.TemplateVersionParameterOption
+		richParameterOption, err = RichSelect(inv, RichSelectOptions{
+			Options:    templateVersionParameter.Options,
+			Default:    templateVersionParameter.DefaultValue,
+			HideSearch: true,
+		})
+		if err == nil {
+			_, _ = fmt.Fprintln(inv.Stdout)
+			_, _ = fmt.Fprintln(inv.Stdout, "  "+Styles.Prompt.String()+Styles.Field.Render(richParameterOption.Name))
+			value = richParameterOption.Value
+		}
+	} else {
+		text := "Enter a value"
+		if !templateVersionParameter.Required {
+			text += fmt.Sprintf(" (default: %q)", templateVersionParameter.DefaultValue)
+		}
+		text += ":"
+
+		value, err = Prompt(inv, PromptOptions{
+			Text: Styles.Bold.Render(text),
+			Validate: func(value string) error {
+				return validateRichPrompt(value, templateVersionParameter)
+			},
+		})
+		value = strings.TrimSpace(value)
+	}
+	if err != nil {
+		return "", err
+	}
+
+	// If they didn't specify anything, use the default value if set.
+	if len(templateVersionParameter.Options) == 0 && value == "" {
+		value = templateVersionParameter.DefaultValue
+	}
+
+	return value, nil
+}
+
+func validateRichPrompt(value string, p codersdk.TemplateVersionParameter) error {
+	return codersdk.ValidateWorkspaceBuildParameter(p, &codersdk.WorkspaceBuildParameter{
+		Name:  p.Name,
+		Value: value,
+	}, nil)
+}

cli/cliui/prompt.go

@@ -11,8 +11,9 @@ import (
 
 	"github.com/bgentry/speakeasy"
 	"github.com/mattn/go-isatty"
-	"github.com/spf13/cobra"
 	"golang.org/x/xerrors"
+
+	"github.com/coder/coder/cli/clibase"
 )
 
 // PromptOptions supply a set of options to the prompt.
@@ -26,8 +27,16 @@ type PromptOptions struct {
 
 const skipPromptFlag = "yes"
 
-func AllowSkipPrompt(cmd *cobra.Command) {
-	cmd.Flags().BoolP(skipPromptFlag, "y", false, "Bypass prompts")
+// SkipPromptOption adds a "--yes/-y" flag to the cmd that can be used to skip
+// prompts.
+func SkipPromptOption() clibase.Option {
+	return clibase.Option{
+		Flag:          skipPromptFlag,
+		FlagShorthand: "y",
+		Description:   "Bypass prompts.",
+		// Discard
+		Value: clibase.BoolOf(new(bool)),
+	}
 }
 
 const (
@@ -36,17 +45,17 @@ const (
 )
 
 // Prompt asks the user for input.
-func Prompt(cmd *cobra.Command, opts PromptOptions) (string, error) {
+func Prompt(inv *clibase.Invocation, opts PromptOptions) (string, error) {
 	// If the cmd has a "yes" flag for skipping confirm prompts, honor it.
 	// If it's not a "Confirm" prompt, then don't skip. As the default value of
 	// "yes" makes no sense.
-	if opts.IsConfirm && cmd.Flags().Lookup(skipPromptFlag) != nil {
-		if skip, _ := cmd.Flags().GetBool(skipPromptFlag); skip {
+	if opts.IsConfirm && inv.ParsedFlags().Lookup(skipPromptFlag) != nil {
+		if skip, _ := inv.ParsedFlags().GetBool(skipPromptFlag); skip {
 			return ConfirmYes, nil
 		}
 	}
 
-	_, _ = fmt.Fprint(cmd.OutOrStdout(), Styles.FocusedPrompt.String()+opts.Text+" ")
+	_, _ = fmt.Fprint(inv.Stdout, Styles.FocusedPrompt.String()+opts.Text+" ")
 	if opts.IsConfirm {
 		if len(opts.Default) == 0 {
 			opts.Default = ConfirmYes
@@ -58,19 +67,24 @@ func Prompt(cmd *cobra.Command, opts PromptOptions) (string, error) {
 		} else {
 			renderedNo = Styles.Bold.Render(ConfirmNo)
 		}
-		_, _ = fmt.Fprint(cmd.OutOrStdout(), Styles.Placeholder.Render("("+renderedYes+Styles.Placeholder.Render("/"+renderedNo+Styles.Placeholder.Render(") "))))
+		_, _ = fmt.Fprint(inv.Stdout, Styles.Placeholder.Render("("+renderedYes+Styles.Placeholder.Render("/"+renderedNo+Styles.Placeholder.Render(") "))))
 	} else if opts.Default != "" {
-		_, _ = fmt.Fprint(cmd.OutOrStdout(), Styles.Placeholder.Render("("+opts.Default+") "))
+		_, _ = fmt.Fprint(inv.Stdout, Styles.Placeholder.Render("("+opts.Default+") "))
 	}
 	interrupt := make(chan os.Signal, 1)
 
+	if inv.Stdin == nil {
+		panic("inv.Stdin is nil")
+	}
+
 	errCh := make(chan error, 1)
 	lineCh := make(chan string)
+
 	go func() {
 		var line string
 		var err error
 
-		inFile, isInputFile := cmd.InOrStdin().(*os.File)
+		inFile, isInputFile := inv.Stdin.(*os.File)
 		if opts.Secret && isInputFile && isatty.IsTerminal(inFile.Fd()) {
 			// we don't install a signal handler here because speakeasy has its own
 			line, err = speakeasy.Ask("")
@@ -78,7 +92,7 @@ func Prompt(cmd *cobra.Command, opts PromptOptions) (string, error) {
 			signal.Notify(interrupt, os.Interrupt)
 			defer signal.Stop(interrupt)
 
-			reader := bufio.NewReader(cmd.InOrStdin())
+			reader := bufio.NewReader(inv.Stdin)
 			line, err = reader.ReadString('\n')
 
 			// Check if the first line beings with JSON object or array chars.
@@ -96,7 +110,10 @@ func Prompt(cmd *cobra.Command, opts PromptOptions) (string, error) {
 		if line == "" {
 			line = opts.Default
 		}
-		lineCh <- line
+		select {
+		case <-inv.Context().Done():
+		case lineCh <- line:
+		}
 	}()
 
 	select {
@@ -109,16 +126,16 @@ func Prompt(cmd *cobra.Command, opts PromptOptions) (string, error) {
 		if opts.Validate != nil {
 			err := opts.Validate(line)
 			if err != nil {
-				_, _ = fmt.Fprintln(cmd.OutOrStdout(), defaultStyles.Error.Render(err.Error()))
-				return Prompt(cmd, opts)
+				_, _ = fmt.Fprintln(inv.Stdout, defaultStyles.Error.Render(err.Error()))
+				return Prompt(inv, opts)
 			}
 		}
 		return line, nil
-	case <-cmd.Context().Done():
-		return "", cmd.Context().Err()
+	case <-inv.Context().Done():
+		return "", inv.Context().Err()
 	case <-interrupt:
 		// Print a newline so that any further output starts properly on a new line.
-		_, _ = fmt.Fprintln(cmd.OutOrStdout())
+		_, _ = fmt.Fprintln(inv.Stdout)
 		return "", Canceled
 	}
 }

cli/cliui/prompt_test.go

@@ -8,10 +8,10 @@ import (
 	"os/exec"
 	"testing"
 
-	"github.com/spf13/cobra"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 
+	"github.com/coder/coder/cli/clibase"
 	"github.com/coder/coder/cli/cliui"
 	"github.com/coder/coder/pty"
 	"github.com/coder/coder/pty/ptytest"
@@ -77,9 +77,9 @@ func TestPrompt(t *testing.T) {
 			resp, err := newPrompt(ptty, cliui.PromptOptions{
 				Text:      "ShouldNotSeeThis",
 				IsConfirm: true,
-			}, func(cmd *cobra.Command) {
-				cliui.AllowSkipPrompt(cmd)
-				cmd.SetArgs([]string{"-y"})
+			}, func(inv *clibase.Invocation) {
+				inv.Command.Options = append(inv.Command.Options, cliui.SkipPromptOption())
+				inv.Args = []string{"-y"}
 			})
 			assert.NoError(t, err)
 			doneChan <- resp
@@ -145,23 +145,25 @@ func TestPrompt(t *testing.T) {
 	})
 }
 
-func newPrompt(ptty *ptytest.PTY, opts cliui.PromptOptions, cmdOpt func(cmd *cobra.Command)) (string, error) {
+func newPrompt(ptty *ptytest.PTY, opts cliui.PromptOptions, invOpt func(inv *clibase.Invocation)) (string, error) {
 	value := ""
-	cmd := &cobra.Command{
-		RunE: func(cmd *cobra.Command, args []string) error {
+	cmd := &clibase.Cmd{
+		Handler: func(inv *clibase.Invocation) error {
 			var err error
-			value, err = cliui.Prompt(cmd, opts)
+			value, err = cliui.Prompt(inv, opts)
 			return err
 		},
 	}
+
+	inv := cmd.Invoke()
 	// Optionally modify the cmd
-	if cmdOpt != nil {
-		cmdOpt(cmd)
+	if invOpt != nil {
+		invOpt(inv)
 	}
-	cmd.SetOut(ptty.Output())
-	cmd.SetErr(ptty.Output())
-	cmd.SetIn(ptty.Input())
-	return value, cmd.ExecuteContext(context.Background())
+	inv.Stdout = ptty.Output()
+	inv.Stderr = ptty.Output()
+	inv.Stdin = ptty.Input()
+	return value, inv.WithContext(context.Background()).Run()
 }
 
 func TestPasswordTerminalState(t *testing.T) {
@@ -208,13 +210,17 @@ func TestPasswordTerminalState(t *testing.T) {
 
 // nolint:unused
 func passwordHelper() {
-	cmd := &cobra.Command{
-		Run: func(cmd *cobra.Command, args []string) {
-			cliui.Prompt(cmd, cliui.PromptOptions{
+	cmd := &clibase.Cmd{
+		Handler: func(inv *clibase.Invocation) error {
+			cliui.Prompt(inv, cliui.PromptOptions{
 				Text:   "Password:",
 				Secret: true,
 			})
+			return nil
 		},
 	}
-	cmd.ExecuteContext(context.Background())
+	err := cmd.Invoke().WithOS().Run()
+	if err != nil {
+		panic(err)
+	}
 }

cli/cliui/provisionerjob.go

@@ -16,14 +16,14 @@ import (
 	"github.com/coder/coder/codersdk"
 )
 
-func WorkspaceBuild(ctx context.Context, writer io.Writer, client *codersdk.Client, build uuid.UUID, before time.Time) error {
+func WorkspaceBuild(ctx context.Context, writer io.Writer, client *codersdk.Client, build uuid.UUID) error {
 	return ProvisionerJob(ctx, writer, ProvisionerJobOptions{
 		Fetch: func() (codersdk.ProvisionerJob, error) {
 			build, err := client.WorkspaceBuild(ctx, build)
 			return build.Job, err
 		},
 		Logs: func() (<-chan codersdk.ProvisionerJobLog, io.Closer, error) {
-			return client.WorkspaceBuildLogsAfter(ctx, build, before)
+			return client.WorkspaceBuildLogsAfter(ctx, build, 0)
 		},
 	})
 }
@@ -41,6 +41,17 @@ type ProvisionerJobOptions struct {
 	Silent bool
 }
 
+type ProvisionerJobError struct {
+	Message string
+	Code    codersdk.JobErrorCode
+}
+
+var _ error = new(ProvisionerJobError)
+
+func (err *ProvisionerJobError) Error() string {
+	return err.Message
+}
+
 // ProvisionerJob renders a provisioner job with interactive cancellation.
 func ProvisionerJob(ctx context.Context, writer io.Writer, opts ProvisionerJobOptions) error {
 	if opts.FetchInterval == 0 {
@@ -103,7 +114,6 @@ func ProvisionerJob(ctx context.Context, writer io.Writer, opts ProvisionerJobOp
 		}
 		updateStage("Running", *job.StartedAt)
 	}
-	updateJob()
 
 	if opts.Cancel != nil {
 		// Handles ctrl+c to cancel a job.
@@ -131,10 +141,11 @@ func ProvisionerJob(ctx context.Context, writer io.Writer, opts ProvisionerJobOp
 
 	// The initial stage needs to print after the signal handler has been registered.
 	printStage()
+	updateJob()
 
 	logs, closer, err := opts.Logs()
 	if err != nil {
-		return xerrors.Errorf("logs: %w", err)
+		return xerrors.Errorf("begin streaming logs: %w", err)
 	}
 	defer closer.Close()
 
@@ -181,7 +192,10 @@ func ProvisionerJob(ctx context.Context, writer io.Writer, opts ProvisionerJobOp
 					return nil
 				case codersdk.ProvisionerJobFailed:
 				}
-				err = xerrors.New(job.Error)
+				err = &ProvisionerJobError{
+					Message: job.Error,
+					Code:    job.ErrorCode,
+				}
 				jobMutex.Unlock()
 				flushLogBuffer()
 				return err

cli/cliui/provisionerjob_test.go

@@ -9,9 +9,9 @@ import (
 	"testing"
 	"time"
 
-	"github.com/spf13/cobra"
 	"github.com/stretchr/testify/assert"
 
+	"github.com/coder/coder/cli/clibase"
 	"github.com/coder/coder/cli/cliui"
 	"github.com/coder/coder/coderd/database"
 	"github.com/coder/coder/codersdk"
@@ -125,9 +125,9 @@ func newProvisionerJob(t *testing.T) provisionerJobTest {
 	}
 	jobLock := sync.Mutex{}
 	logs := make(chan codersdk.ProvisionerJobLog, 1)
-	cmd := &cobra.Command{
-		RunE: func(cmd *cobra.Command, args []string) error {
-			return cliui.ProvisionerJob(cmd.Context(), cmd.OutOrStdout(), cliui.ProvisionerJobOptions{
+	cmd := &clibase.Cmd{
+		Handler: func(inv *clibase.Invocation) error {
+			return cliui.ProvisionerJob(inv.Context(), inv.Stdout, cliui.ProvisionerJobOptions{
 				FetchInterval: time.Millisecond,
 				Fetch: func() (codersdk.ProvisionerJob, error) {
 					jobLock.Lock()
@@ -145,13 +145,14 @@ func newProvisionerJob(t *testing.T) provisionerJobTest {
 			})
 		},
 	}
+	inv := cmd.Invoke()
+
 	ptty := ptytest.New(t)
-	cmd.SetOutput(ptty.Output())
-	cmd.SetIn(ptty.Input())
+	ptty.Attach(inv)
 	done := make(chan struct{})
 	go func() {
 		defer close(done)
-		err := cmd.ExecuteContext(context.Background())
+		err := inv.WithContext(context.Background()).Run()
 		if err != nil {
 			assert.ErrorIs(t, err, cliui.Canceled)
 		}

cli/cliui/resources.go

@@ -127,6 +127,13 @@ func renderAgentStatus(agent codersdk.WorkspaceAgent) string {
 		since := database.Now().Sub(*agent.DisconnectedAt)
 		return Styles.Error.Render("⦾ disconnected") + " " +
 			Styles.Placeholder.Render("["+strconv.Itoa(int(since.Seconds()))+"s]")
+	case codersdk.WorkspaceAgentTimeout:
+		since := database.Now().Sub(agent.CreatedAt)
+		return fmt.Sprintf(
+			"%s %s",
+			Styles.Warn.Render("⦾ timeout"),
+			Styles.Placeholder.Render("["+strconv.Itoa(int(since.Seconds()))+"s]"),
+		)
 	case codersdk.WorkspaceAgentConnected:
 		return Styles.Keyword.Render("⦿ connected")
 	default:

cli/cliui/resources_test.go

@@ -26,6 +26,7 @@ func TestWorkspaceResources(t *testing.T) {
 				Agents: []codersdk.WorkspaceAgent{{
 					Name:            "dev",
 					Status:          codersdk.WorkspaceAgentConnected,
+					LifecycleState:  codersdk.WorkspaceAgentLifecycleCreated,
 					Architecture:    "amd64",
 					OperatingSystem: "linux",
 				}},
@@ -60,6 +61,7 @@ func TestWorkspaceResources(t *testing.T) {
 				Agents: []codersdk.WorkspaceAgent{{
 					CreatedAt:       database.Now().Add(-10 * time.Second),
 					Status:          codersdk.WorkspaceAgentConnecting,
+					LifecycleState:  codersdk.WorkspaceAgentLifecycleCreated,
 					Name:            "dev",
 					OperatingSystem: "linux",
 					Architecture:    "amd64",
@@ -70,12 +72,14 @@ func TestWorkspaceResources(t *testing.T) {
 				Name:       "dev",
 				Agents: []codersdk.WorkspaceAgent{{
 					Status:          codersdk.WorkspaceAgentConnected,
+					LifecycleState:  codersdk.WorkspaceAgentLifecycleReady,
 					Name:            "go",
 					Architecture:    "amd64",
 					OperatingSystem: "linux",
 				}, {
 					DisconnectedAt:  &disconnected,
 					Status:          codersdk.WorkspaceAgentDisconnected,
+					LifecycleState:  codersdk.WorkspaceAgentLifecycleReady,
 					Name:            "postgres",
 					Architecture:    "amd64",
 					OperatingSystem: "linux",

cli/cliui/select.go

@@ -8,7 +8,10 @@ import (
 
 	"github.com/AlecAivazis/survey/v2"
 	"github.com/AlecAivazis/survey/v2/terminal"
-	"github.com/spf13/cobra"
+	"golang.org/x/xerrors"
+
+	"github.com/coder/coder/cli/clibase"
+	"github.com/coder/coder/codersdk"
 )
 
 func init() {
@@ -32,6 +35,21 @@ func init() {
   {{- template "option" $.IterateOption $ix $option}}
 {{- end}}
 {{- end }}`
+
+	survey.MultiSelectQuestionTemplate = `
+{{- define "option"}}
+    {{- if eq .SelectedIndex .CurrentIndex }}{{color .Config.Icons.SelectFocus.Format }}{{ .Config.Icons.SelectFocus.Text }}{{color "reset"}}{{else}} {{end}}
+    {{- if index .Checked .CurrentOpt.Index }}{{color .Config.Icons.MarkedOption.Format }} {{ .Config.Icons.MarkedOption.Text }} {{else}}{{color .Config.Icons.UnmarkedOption.Format }} {{ .Config.Icons.UnmarkedOption.Text }} {{end}}
+    {{- color "reset"}}
+    {{- " "}}{{- .CurrentOpt.Value}}
+{{end}}
+{{- if .ShowHelp }}{{- color .Config.Icons.Help.Format }}{{ .Config.Icons.Help.Text }} {{ .Help }}{{color "reset"}}{{"\n"}}{{end}}
+{{- if not .ShowAnswer }}
+  {{- "\n"}}
+  {{- range $ix, $option := .PageEntries}}
+    {{- template "option" $.IterateOption $ix $option}}
+  {{- end}}
+{{- end}}`
 }
 
 type SelectOptions struct {
@@ -42,8 +60,49 @@ type SelectOptions struct {
 	HideSearch bool
 }
 
+type RichSelectOptions struct {
+	Options    []codersdk.TemplateVersionParameterOption
+	Default    string
+	Size       int
+	HideSearch bool
+}
+
+// RichSelect displays a list of user options including name and description.
+func RichSelect(inv *clibase.Invocation, richOptions RichSelectOptions) (*codersdk.TemplateVersionParameterOption, error) {
+	opts := make([]string, len(richOptions.Options))
+	var defaultOpt string
+	for i, option := range richOptions.Options {
+		line := option.Name
+		if len(option.Description) > 0 {
+			line += ": " + option.Description
+		}
+		opts[i] = line
+
+		if option.Value == richOptions.Default {
+			defaultOpt = line
+		}
+	}
+
+	selected, err := Select(inv, SelectOptions{
+		Options:    opts,
+		Default:    defaultOpt,
+		Size:       richOptions.Size,
+		HideSearch: richOptions.HideSearch,
+	})
+	if err != nil {
+		return nil, err
+	}
+
+	for i, option := range opts {
+		if option == selected {
+			return &richOptions.Options[i], nil
+		}
+	}
+	return nil, xerrors.Errorf("unknown option selected: %s", selected)
+}
+
 // Select displays a list of user options.
-func Select(cmd *cobra.Command, opts SelectOptions) (string, error) {
+func Select(inv *clibase.Invocation, opts SelectOptions) (string, error) {
 	// The survey library used *always* fails when testing on Windows,
 	// as it requires a live TTY (can't be a conpty). We should fork
 	// this library to add a dummy fallback, that simply reads/writes
@@ -69,16 +128,39 @@ func Select(cmd *cobra.Command, opts SelectOptions) (string, error) {
 			is.Help.Text = ""
 		}
 	}), survey.WithStdio(fileReadWriter{
-		Reader: cmd.InOrStdin(),
+		Reader: inv.Stdin,
 	}, fileReadWriter{
-		Writer: cmd.OutOrStdout(),
-	}, cmd.OutOrStdout()))
+		Writer: inv.Stdout,
+	}, inv.Stdout))
 	if errors.Is(err, terminal.InterruptErr) {
 		return value, Canceled
 	}
 	return value, err
 }
 
+func MultiSelect(inv *clibase.Invocation, items []string) ([]string, error) {
+	// Similar hack is applied to Select()
+	if flag.Lookup("test.v") != nil {
+		return items, nil
+	}
+
+	prompt := &survey.MultiSelect{
+		Options: items,
+		Default: items,
+	}
+
+	var values []string
+	err := survey.AskOne(prompt, &values, survey.WithStdio(fileReadWriter{
+		Reader: inv.Stdin,
+	}, fileReadWriter{
+		Writer: inv.Stdout,
+	}, inv.Stdout))
+	if errors.Is(err, terminal.InterruptErr) {
+		return nil, Canceled
+	}
+	return values, err
+}
+
 type fileReadWriter struct {
 	io.Reader
 	io.Writer

cli/cliui/select_test.go

@@ -1,14 +1,14 @@
 package cliui_test
 
 import (
-	"context"
 	"testing"
 
-	"github.com/spf13/cobra"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 
+	"github.com/coder/coder/cli/clibase"
 	"github.com/coder/coder/cli/cliui"
+	"github.com/coder/coder/codersdk"
 	"github.com/coder/coder/pty/ptytest"
 )
 
@@ -31,14 +31,90 @@ func TestSelect(t *testing.T) {
 
 func newSelect(ptty *ptytest.PTY, opts cliui.SelectOptions) (string, error) {
 	value := ""
-	cmd := &cobra.Command{
-		RunE: func(cmd *cobra.Command, args []string) error {
+	cmd := &clibase.Cmd{
+		Handler: func(inv *clibase.Invocation) error {
 			var err error
-			value, err = cliui.Select(cmd, opts)
+			value, err = cliui.Select(inv, opts)
 			return err
 		},
 	}
-	cmd.SetOutput(ptty.Output())
-	cmd.SetIn(ptty.Input())
-	return value, cmd.ExecuteContext(context.Background())
+	inv := cmd.Invoke()
+	ptty.Attach(inv)
+	return value, inv.Run()
+}
+
+func TestRichSelect(t *testing.T) {
+	t.Parallel()
+	t.Run("RichSelect", func(t *testing.T) {
+		t.Parallel()
+		ptty := ptytest.New(t)
+		msgChan := make(chan string)
+		go func() {
+			resp, err := newRichSelect(ptty, cliui.RichSelectOptions{
+				Options: []codersdk.TemplateVersionParameterOption{
+					{
+						Name:        "A-Name",
+						Value:       "A-Value",
+						Description: "A-Description.",
+					}, {
+						Name:        "B-Name",
+						Value:       "B-Value",
+						Description: "B-Description.",
+					},
+				},
+			})
+			assert.NoError(t, err)
+			msgChan <- resp
+		}()
+		require.Equal(t, "A-Value", <-msgChan)
+	})
+}
+
+func newRichSelect(ptty *ptytest.PTY, opts cliui.RichSelectOptions) (string, error) {
+	value := ""
+	cmd := &clibase.Cmd{
+		Handler: func(inv *clibase.Invocation) error {
+			richOption, err := cliui.RichSelect(inv, opts)
+			if err == nil {
+				value = richOption.Value
+			}
+			return err
+		},
+	}
+	inv := cmd.Invoke()
+	ptty.Attach(inv)
+	return value, inv.Run()
+}
+
+func TestMultiSelect(t *testing.T) {
+	t.Parallel()
+	t.Run("MultiSelect", func(t *testing.T) {
+		items := []string{"aaa", "bbb", "ccc"}
+
+		t.Parallel()
+		ptty := ptytest.New(t)
+		msgChan := make(chan []string)
+		go func() {
+			resp, err := newMultiSelect(ptty, items)
+			assert.NoError(t, err)
+			msgChan <- resp
+		}()
+		require.Equal(t, items, <-msgChan)
+	})
+}
+
+func newMultiSelect(ptty *ptytest.PTY, items []string) ([]string, error) {
+	var values []string
+	cmd := &clibase.Cmd{
+		Handler: func(inv *clibase.Invocation) error {
+			selectedItems, err := cliui.MultiSelect(inv, items)
+			if err == nil {
+				values = selectedItems
+			}
+			return err
+		},
+	}
+	inv := cmd.Invoke()
+	ptty.Attach(inv)
+	return values, inv.Run()
 }

cli/cliui/table.go

@@ -22,10 +22,10 @@ func Table() table.Writer {
 	return tableWriter
 }
 
-// FilterTableColumns returns configurations to hide columns
+// filterTableColumns returns configurations to hide columns
 // that are not provided in the array. If the array is empty,
 // no filtering will occur!
-func FilterTableColumns(header table.Row, columns []string) []table.ColumnConfig {
+func filterTableColumns(header table.Row, columns []string) []table.ColumnConfig {
 	if len(columns) == 0 {
 		return nil
 	}
@@ -51,6 +51,9 @@ func FilterTableColumns(header table.Row, columns []string) []table.ColumnConfig
 // of structs. At least one field in the struct must have a `table:""` tag
 // containing the name of the column in the outputted table.
 //
+// If `sort` is not specified, the field with the `table:"$NAME,default_sort"`
+// tag will be used to sort. An error will be returned if no field has this tag.
+//
 // Nested structs are processed if the field has the `table:"$NAME,recursive"`
 // tag and their fields will be named as `$PARENT_NAME $NAME`. If the tag is
 // malformed or a field is marked as recursive but does not contain a struct or
@@ -67,13 +70,16 @@ func DisplayTable(out any, sort string, filterColumns []string) (string, error)
 	}
 
 	// Get the list of table column headers.
-	headersRaw, err := typeToTableHeaders(v.Type().Elem())
+	headersRaw, defaultSort, err := typeToTableHeaders(v.Type().Elem())
 	if err != nil {
 		return "", xerrors.Errorf("get table headers recursively for type %q: %w", v.Type().Elem().String(), err)
 	}
 	if len(headersRaw) == 0 {
 		return "", xerrors.New(`no table headers found on the input type, make sure there is at least one "table" struct tag`)
 	}
+	if sort == "" {
+		sort = defaultSort
+	}
 	headers := make(table.Row, len(headersRaw))
 	for i, header := range headersRaw {
 		headers[i] = header
@@ -101,7 +107,7 @@ func DisplayTable(out any, sort string, filterColumns []string) (string, error)
 			column := strings.ToLower(strings.ReplaceAll(column, "_", " "))
 			h, ok := headersMap[column]
 			if !ok {
-				return "", xerrors.Errorf(`specified filter column %q not found in table headers, available columns are "%v"`, sort, strings.Join(headersRaw, `", "`))
+				return "", xerrors.Errorf(`specified filter column %q not found in table headers, available columns are "%v"`, column, strings.Join(headersRaw, `", "`))
 			}
 
 			// Autocorrect
@@ -128,7 +134,7 @@ func DisplayTable(out any, sort string, filterColumns []string) (string, error)
 	// Setup the table formatter.
 	tw := Table()
 	tw.AppendHeader(headers)
-	tw.SetColumnConfigs(FilterTableColumns(headers, filterColumns))
+	tw.SetColumnConfigs(filterTableColumns(headers, filterColumns))
 	if sort != "" {
 		tw.SortBy([]table.SortBy{{
 			Name: sort,
@@ -182,29 +188,32 @@ func DisplayTable(out any, sort string, filterColumns []string) (string, error)
 // returned. If the table tag is malformed, an error is returned.
 //
 // The returned name is transformed from "snake_case" to "normal text".
-func parseTableStructTag(field reflect.StructField) (name string, recurse bool, err error) {
+func parseTableStructTag(field reflect.StructField) (name string, defaultSort, recursive bool, err error) {
 	tags, err := structtag.Parse(string(field.Tag))
 	if err != nil {
-		return "", false, xerrors.Errorf("parse struct field tag %q: %w", string(field.Tag), err)
+		return "", false, false, xerrors.Errorf("parse struct field tag %q: %w", string(field.Tag), err)
 	}
 
 	tag, err := tags.Get("table")
 	if err != nil || tag.Name == "-" {
 		// tags.Get only returns an error if the tag is not found.
-		return "", false, nil
+		return "", false, false, nil
 	}
 
-	recursive := false
+	defaultSortOpt := false
+	recursiveOpt := false
 	for _, opt := range tag.Options {
-		if opt == "recursive" {
-			recursive = true
-			continue
+		switch opt {
+		case "default_sort":
+			defaultSortOpt = true
+		case "recursive":
+			recursiveOpt = true
+		default:
+			return "", false, false, xerrors.Errorf("unknown option %q in struct field tag", opt)
 		}
-
-		return "", false, xerrors.Errorf("unknown option %q in struct field tag", opt)
 	}
 
-	return strings.ReplaceAll(tag.Name, "_", " "), recursive, nil
+	return strings.ReplaceAll(tag.Name, "_", " "), defaultSortOpt, recursiveOpt, nil
 }
 
 func isStructOrStructPointer(t reflect.Type) bool {
@@ -214,34 +223,41 @@ func isStructOrStructPointer(t reflect.Type) bool {
 // typeToTableHeaders converts a type to a slice of column names. If the given
 // type is invalid (not a struct or a pointer to a struct, has invalid table
 // tags, etc.), an error is returned.
-func typeToTableHeaders(t reflect.Type) ([]string, error) {
+func typeToTableHeaders(t reflect.Type) ([]string, string, error) {
 	if !isStructOrStructPointer(t) {
-		return nil, xerrors.Errorf("typeToTableHeaders called with a non-struct or a non-pointer-to-a-struct type")
+		return nil, "", xerrors.Errorf("typeToTableHeaders called with a non-struct or a non-pointer-to-a-struct type")
 	}
 	if t.Kind() == reflect.Pointer {
 		t = t.Elem()
 	}
 
 	headers := []string{}
+	defaultSortName := ""
 	for i := 0; i < t.NumField(); i++ {
 		field := t.Field(i)
-		name, recursive, err := parseTableStructTag(field)
+		name, defaultSort, recursive, err := parseTableStructTag(field)
 		if err != nil {
-			return nil, xerrors.Errorf("parse struct tags for field %q in type %q: %w", field.Name, t.String(), err)
+			return nil, "", xerrors.Errorf("parse struct tags for field %q in type %q: %w", field.Name, t.String(), err)
 		}
 		if name == "" {
 			continue
 		}
+		if defaultSort {
+			if defaultSortName != "" {
+				return nil, "", xerrors.Errorf("multiple fields marked as default sort in type %q", t.String())
+			}
+			defaultSortName = name
+		}
 
 		fieldType := field.Type
 		if recursive {
 			if !isStructOrStructPointer(fieldType) {
-				return nil, xerrors.Errorf("field %q in type %q is marked as recursive but does not contain a struct or a pointer to a struct", field.Name, t.String())
+				return nil, "", xerrors.Errorf("field %q in type %q is marked as recursive but does not contain a struct or a pointer to a struct", field.Name, t.String())
 			}
 
-			childNames, err := typeToTableHeaders(fieldType)
+			childNames, _, err := typeToTableHeaders(fieldType)
 			if err != nil {
-				return nil, xerrors.Errorf("get child field header names for field %q in type %q: %w", field.Name, fieldType.String(), err)
+				return nil, "", xerrors.Errorf("get child field header names for field %q in type %q: %w", field.Name, fieldType.String(), err)
 			}
 			for _, childName := range childNames {
 				headers = append(headers, fmt.Sprintf("%s %s", name, childName))
@@ -252,7 +268,11 @@ func typeToTableHeaders(t reflect.Type) ([]string, error) {
 		headers = append(headers, name)
 	}
 
-	return headers, nil
+	if defaultSortName == "" {
+		return nil, "", xerrors.Errorf("no field marked as default_sort in type %q", t.String())
+	}
+
+	return headers, defaultSortName, nil
 }
 
 // valueToTableMap converts a struct to a map of column name to value. If the
@@ -276,7 +296,7 @@ func valueToTableMap(val reflect.Value) (map[string]any, error) {
 	for i := 0; i < val.NumField(); i++ {
 		field := val.Type().Field(i)
 		fieldVal := val.Field(i)
-		name, recursive, err := parseTableStructTag(field)
+		name, _, recursive, err := parseTableStructTag(field)
 		if err != nil {
 			return nil, xerrors.Errorf("parse struct tags for field %q in type %T: %w", field.Name, val, err)
 		}
@@ -309,18 +329,3 @@ func valueToTableMap(val reflect.Value) (map[string]any, error) {
 
 	return row, nil
 }
-
-// TableHeaders returns the table header names of all
-// fields in tSlice. tSlice must be a slice of some type.
-func TableHeaders(tSlice any) ([]string, error) {
-	v := reflect.Indirect(reflect.ValueOf(tSlice))
-	rawHeaders, err := typeToTableHeaders(v.Type().Elem())
-	if err != nil {
-		return nil, xerrors.Errorf("type to table headers: %w", err)
-	}
-	out := make([]string, 0, len(rawHeaders))
-	for _, hdr := range rawHeaders {
-		out = append(out, strings.Replace(hdr, " ", "_", -1))
-	}
-	return out, nil
-}

cli/cliui/table_test.go

@@ -24,7 +24,7 @@ func (s stringWrapper) String() string {
 }
 
 type tableTest1 struct {
-	Name        string      `table:"name"`
+	Name        string      `table:"name,default_sort"`
 	NotIncluded string      // no table tag
 	Age         int         `table:"age"`
 	Roles       []string    `table:"roles"`
@@ -39,21 +39,45 @@ type tableTest1 struct {
 }
 
 type tableTest2 struct {
-	Name        stringWrapper `table:"name"`
+	Name        stringWrapper `table:"name,default_sort"`
 	Age         int           `table:"age"`
 	NotIncluded string        `table:"-"`
 }
 
 type tableTest3 struct {
 	NotIncluded string     // no table tag
-	Sub         tableTest2 `table:"inner,recursive"`
+	Sub         tableTest2 `table:"inner,recursive,default_sort"`
 }
 
 func Test_DisplayTable(t *testing.T) {
 	t.Parallel()
 
-	someTime := time.Date(2022, 8, 2, 15, 49, 10, 0, time.Local)
+	someTime := time.Date(2022, 8, 2, 15, 49, 10, 0, time.UTC)
+
+	// Not sorted by name or age to test sorting.
 	in := []tableTest1{
+		{
+			Name:  "bar",
+			Age:   20,
+			Roles: []string{"a"},
+			Sub1: tableTest2{
+				Name: stringWrapper{str: "bar1"},
+				Age:  21,
+			},
+			Sub2: nil,
+			Sub3: tableTest3{
+				Sub: tableTest2{
+					Name: stringWrapper{str: "bar3"},
+					Age:  23,
+				},
+			},
+			Sub4: tableTest2{
+				Name: stringWrapper{str: "bar4"},
+				Age:  24,
+			},
+			Time:    someTime,
+			TimePtr: nil,
+		},
 		{
 			Name:  "foo",
 			Age:   10,
@@ -79,28 +103,6 @@ func Test_DisplayTable(t *testing.T) {
 			Time:    someTime,
 			TimePtr: &someTime,
 		},
-		{
-			Name:  "bar",
-			Age:   20,
-			Roles: []string{"a"},
-			Sub1: tableTest2{
-				Name: stringWrapper{str: "bar1"},
-				Age:  21,
-			},
-			Sub2: nil,
-			Sub3: tableTest3{
-				Sub: tableTest2{
-					Name: stringWrapper{str: "bar3"},
-					Age:  23,
-				},
-			},
-			Sub4: tableTest2{
-				Name: stringWrapper{str: "bar4"},
-				Age:  24,
-			},
-			Time:    someTime,
-			TimePtr: nil,
-		},
 		{
 			Name:  "baz",
 			Age:   30,
@@ -132,9 +134,9 @@ func Test_DisplayTable(t *testing.T) {
 
 		expected := `
 NAME  AGE  ROLES    SUB 1 NAME  SUB 1 AGE  SUB 2 NAME  SUB 2 AGE  SUB 3 INNER NAME  SUB 3 INNER AGE  SUB 4       TIME                  TIME PTR
-foo    10  [a b c]  foo1               11  foo2        12         foo3                           13  {foo4 14 }  2022-08-02T15:49:10Z  2022-08-02T15:49:10Z
 bar    20  [a]      bar1               21  <nil>       <nil>      bar3                           23  {bar4 24 }  2022-08-02T15:49:10Z  <nil>
 baz    30  []       baz1               31  <nil>       <nil>      baz3                           33  {baz4 34 }  2022-08-02T15:49:10Z  <nil>
+foo    10  [a b c]  foo1               11  foo2        12         foo3                           13  {foo4 14 }  2022-08-02T15:49:10Z  2022-08-02T15:49:10Z
 		`
 
 		// Test with non-pointer values.
@@ -154,17 +156,17 @@ baz    30  []       baz1               31  <nil>       <nil>      baz3
 		compareTables(t, expected, out)
 	})
 
-	t.Run("Sort", func(t *testing.T) {
+	t.Run("CustomSort", func(t *testing.T) {
 		t.Parallel()
 
 		expected := `
 NAME  AGE  ROLES    SUB 1 NAME  SUB 1 AGE  SUB 2 NAME  SUB 2 AGE  SUB 3 INNER NAME  SUB 3 INNER AGE  SUB 4       TIME                  TIME PTR
+foo    10  [a b c]  foo1               11  foo2        12         foo3                           13  {foo4 14 }  2022-08-02T15:49:10Z  2022-08-02T15:49:10Z
 bar    20  [a]      bar1               21  <nil>       <nil>      bar3                           23  {bar4 24 }  2022-08-02T15:49:10Z  <nil>
 baz    30  []       baz1               31  <nil>       <nil>      baz3                           33  {baz4 34 }  2022-08-02T15:49:10Z  <nil>
-foo    10  [a b c]  foo1               11  foo2        12         foo3                           13  {foo4 14 }  2022-08-02T15:49:10Z  2022-08-02T15:49:10Z
 		`
 
-		out, err := cliui.DisplayTable(in, "name", nil)
+		out, err := cliui.DisplayTable(in, "age", nil)
 		log.Println("rendered table:\n" + out)
 		require.NoError(t, err)
 		compareTables(t, expected, out)
@@ -175,9 +177,9 @@ foo    10  [a b c]  foo1               11  foo2        12         foo3
 
 		expected := `
 NAME  SUB 1 NAME  SUB 3 INNER NAME  TIME
-foo   foo1        foo3              2022-08-02T15:49:10Z
 bar   bar1        bar3              2022-08-02T15:49:10Z
 baz   baz1        baz3              2022-08-02T15:49:10Z
+foo   foo1        foo3              2022-08-02T15:49:10Z
 		`
 
 		out, err := cliui.DisplayTable(in, "", []string{"name", "sub_1_name", "sub_3 inner name", "time"})
@@ -327,28 +329,6 @@ baz   baz1        baz3              2022-08-02T15:49:10Z
 	})
 }
 
-func Test_TableHeaders(t *testing.T) {
-	t.Parallel()
-	s := []tableTest1{}
-	expectedFields := []string{
-		"name",
-		"age",
-		"roles",
-		"sub_1_name",
-		"sub_1_age",
-		"sub_2_name",
-		"sub_2_age",
-		"sub_3_inner_name",
-		"sub_3_inner_age",
-		"sub_4",
-		"time",
-		"time_ptr",
-	}
-	headers, err := cliui.TableHeaders(s)
-	require.NoError(t, err)
-	require.EqualValues(t, expectedFields, headers)
-}
-
 // compareTables normalizes the incoming table lines
 func compareTables(t *testing.T, expected, out string) {
 	t.Helper()

cli/config/file.go

@@ -4,36 +4,65 @@ import (
 	"io"
 	"os"
 	"path/filepath"
+
+	"github.com/kirsle/configdir"
+	"golang.org/x/xerrors"
+)
+
+const (
+	FlagName = "global-config"
 )
 
 // Root represents the configuration directory.
 type Root string
 
+// mustNotBeEmpty prevents us from accidentally writing configuration to the
+// current directory. This is primarily valuable in development, where we may
+// accidentally use an empty root.
+func (r Root) mustNotEmpty() {
+	if r == "" {
+		panic("config root must not be empty")
+	}
+}
+
 func (r Root) Session() File {
+	r.mustNotEmpty()
 	return File(filepath.Join(string(r), "session"))
 }
 
+// ReplicaID is a unique identifier for the Coder server.
+func (r Root) ReplicaID() File {
+	r.mustNotEmpty()
+	return File(filepath.Join(string(r), "replica_id"))
+}
+
 func (r Root) URL() File {
+	r.mustNotEmpty()
 	return File(filepath.Join(string(r), "url"))
 }
 
 func (r Root) Organization() File {
+	r.mustNotEmpty()
 	return File(filepath.Join(string(r), "organization"))
 }
 
 func (r Root) DotfilesURL() File {
+	r.mustNotEmpty()
 	return File(filepath.Join(string(r), "dotfilesurl"))
 }
 
 func (r Root) PostgresPath() string {
+	r.mustNotEmpty()
 	return filepath.Join(string(r), "postgres")
 }
 
 func (r Root) PostgresPassword() File {
+	r.mustNotEmpty()
 	return File(filepath.Join(r.PostgresPath(), "password"))
 }
 
 func (r Root) PostgresPort() File {
+	r.mustNotEmpty()
 	return File(filepath.Join(r.PostgresPath(), "port"))
 }
 
@@ -42,16 +71,25 @@ type File string
 
 // Delete deletes the file.
 func (f File) Delete() error {
+	if f == "" {
+		return xerrors.Errorf("empty file path")
+	}
 	return os.Remove(string(f))
 }
 
 // Write writes the string to the file.
 func (f File) Write(s string) error {
-	return write(string(f), 0600, []byte(s))
+	if f == "" {
+		return xerrors.Errorf("empty file path")
+	}
+	return write(string(f), 0o600, []byte(s))
 }
 
 // Read reads the file to a string.
 func (f File) Read() (string, error) {
+	if f == "" {
+		return "", xerrors.Errorf("empty file path")
+	}
 	byt, err := read(string(f))
 	return string(byt), err
 }
@@ -59,7 +97,7 @@ func (f File) Read() (string, error) {
 // open opens a file in the configuration directory,
 // creating all intermediate directories.
 func open(path string, flag int, mode os.FileMode) (*os.File, error) {
-	err := os.MkdirAll(filepath.Dir(path), 0750)
+	err := os.MkdirAll(filepath.Dir(path), 0o750)
 	if err != nil {
 		return nil, err
 	}
@@ -85,3 +123,11 @@ func read(path string) ([]byte, error) {
 	defer fi.Close()
 	return io.ReadAll(fi)
 }
+
+func DefaultDir() string {
+	configDir := configdir.LocalConfig("coderv2")
+	if dir := os.Getenv("CLIDOCGEN_CONFIG_DIRECTORY"); dir != "" {
+		configDir = dir
+	}
+	return configDir
+}

cli/config/server.yaml

@@ -0,0 +1,25 @@
+# Coder Server Configuration
+
+# Automatically authenticate HTTP(s) Git requests.
+gitauth:
+# Supported: azure-devops, bitbucket, github, gitlab
+# - type: github
+#   client_id: xxxxxx
+#   client_secret: xxxxxx
+
+# Multiple providers are an Enterprise feature.
+# Contact sales@coder.com for a license.
+#
+# If multiple providers are used, a unique "id"
+# must be provided for each one.
+# - id: example
+#   type: azure-devops
+#   client_id: xxxxxxx
+#   client_secret: xxxxxxx
+# A custom regex can be used to match a specific
+# repository or organization to limit auth scope.
+#   regex: github.com/coder
+# Custom authentication and token URLs should be
+# used for self-managed Git provider deployments.
+#   auth_url: https://example.com/oauth/authorize
+#   token_url: https://example.com/oauth/token

cli/configssh.go

@@ -8,6 +8,7 @@ import (
 	"fmt"
 	"io"
 	"io/fs"
+	"net/http"
 	"os"
 	"path/filepath"
 	"runtime"
@@ -17,12 +18,11 @@ import (
 	"github.com/cli/safeexec"
 	"github.com/pkg/diff"
 	"github.com/pkg/diff/write"
-	"github.com/spf13/cobra"
 	"golang.org/x/exp/slices"
 	"golang.org/x/sync/errgroup"
 	"golang.org/x/xerrors"
 
-	"github.com/coder/coder/cli/cliflag"
+	"github.com/coder/coder/cli/clibase"
 	"github.com/coder/coder/cli/cliui"
 	"github.com/coder/coder/codersdk"
 )
@@ -48,6 +48,52 @@ type sshConfigOptions struct {
 	sshOptions []string
 }
 
+// addOptions expects options in the form of "option=value" or "option value".
+// It will override any existing option with the same key to prevent duplicates.
+// Invalid options will return an error.
+func (o *sshConfigOptions) addOptions(options ...string) error {
+	for _, option := range options {
+		err := o.addOption(option)
+		if err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func (o *sshConfigOptions) addOption(option string) error {
+	key, value, err := codersdk.ParseSSHConfigOption(option)
+	if err != nil {
+		return err
+	}
+	for i, existing := range o.sshOptions {
+		// Override existing option if they share the same key.
+		// This is case-insensitive. Parsing each time might be a little slow,
+		// but it is ok.
+		existingKey, _, err := codersdk.ParseSSHConfigOption(existing)
+		if err != nil {
+			// Don't mess with original values if there is an error.
+			// This could have come from the user's manual edits.
+			continue
+		}
+		if strings.EqualFold(existingKey, key) {
+			if value == "" {
+				// Delete existing option.
+				o.sshOptions = append(o.sshOptions[:i], o.sshOptions[i+1:]...)
+			} else {
+				// Override existing option.
+				o.sshOptions[i] = option
+			}
+			return nil
+		}
+	}
+	// Only append the option if it is not empty.
+	if value != "" {
+		o.sshOptions = append(o.sshOptions, option)
+	}
+	return nil
+}
+
 func (o sshConfigOptions) equal(other sshConfigOptions) bool {
 	// Compare without side-effects or regard to order.
 	opt1 := slices.Clone(o.sshOptions)
@@ -70,7 +116,7 @@ type sshWorkspaceConfig struct {
 }
 
 func sshFetchWorkspaceConfigs(ctx context.Context, client *codersdk.Client) ([]sshWorkspaceConfig, error) {
-	workspaces, err := client.Workspaces(ctx, codersdk.WorkspaceFilter{
+	res, err := client.Workspaces(ctx, codersdk.WorkspaceFilter{
 		Owner: codersdk.Me,
 	})
 	if err != nil {
@@ -78,8 +124,8 @@ func sshFetchWorkspaceConfigs(ctx context.Context, client *codersdk.Client) ([]s
 	}
 
 	var errGroup errgroup.Group
-	workspaceConfigs := make([]sshWorkspaceConfig, len(workspaces))
-	for i, workspace := range workspaces {
+	workspaceConfigs := make([]sshWorkspaceConfig, len(res.Workspaces))
+	for i, workspace := range res.Workspaces {
 		i := i
 		workspace := workspace
 		errGroup.Go(func() error {
@@ -132,19 +178,21 @@ func sshPrepareWorkspaceConfigs(ctx context.Context, client *codersdk.Client) (r
 	}
 }
 
-func configSSH() *cobra.Command {
+func (r *RootCmd) configSSH() *clibase.Cmd {
 	var (
 		sshConfigFile    string
 		sshConfigOpts    sshConfigOptions
 		usePreviousOpts  bool
 		dryRun           bool
 		skipProxyCommand bool
+		userHostPrefix   string
 	)
-	cmd := &cobra.Command{
+	client := new(codersdk.Client)
+	cmd := &clibase.Cmd{
 		Annotations: workspaceCommand,
 		Use:         "config-ssh",
 		Short:       "Add an SSH Host entry for your workspaces \"ssh coder.workspace\"",
-		Example: formatExamples(
+		Long: formatExamples(
 			example{
 				Description: "You can use -o (or --ssh-option) so set SSH options to be used for all your workspaces",
 				Command:     "coder config-ssh -o ForwardAgent=yes",
@@ -154,20 +202,18 @@ func configSSH() *cobra.Command {
 				Command:     "coder config-ssh --dry-run",
 			},
 		),
-		Args: cobra.ExactArgs(0),
-		RunE: func(cmd *cobra.Command, _ []string) error {
-			client, err := CreateClient(cmd)
-			if err != nil {
-				return err
-			}
+		Middleware: clibase.Chain(
+			clibase.RequireNArgs(0),
+			r.InitClient(client),
+		),
+		Handler: func(inv *clibase.Invocation) error {
+			recvWorkspaceConfigs := sshPrepareWorkspaceConfigs(inv.Context(), client)
 
-			recvWorkspaceConfigs := sshPrepareWorkspaceConfigs(cmd.Context(), client)
-
-			out := cmd.OutOrStdout()
+			out := inv.Stdout
 			if dryRun {
 				// Print everything except diff to stderr so
 				// that it's possible to capture the diff.
-				out = cmd.OutOrStderr()
+				out = inv.Stderr
 			}
 			coderBinary, err := currentBinPath(out)
 			if err != nil {
@@ -178,7 +224,7 @@ func configSSH() *cobra.Command {
 				return xerrors.Errorf("escape coder binary for ssh failed: %w", err)
 			}
 
-			root := createConfig(cmd)
+			root := r.createConfig()
 			escapedGlobalConfig, err := sshConfigExecEscape(string(root))
 			if err != nil {
 				return xerrors.Errorf("escape global config for ssh failed: %w", err)
@@ -206,7 +252,11 @@ func configSSH() *cobra.Command {
 			// Parse the previous configuration only if config-ssh
 			// has been run previously.
 			var lastConfig *sshConfigOptions
-			if section, ok := sshConfigGetCoderSection(configRaw); ok {
+			section, ok, err := sshConfigGetCoderSection(configRaw)
+			if err != nil {
+				return err
+			}
+			if ok {
 				c := sshConfigParseLastOptions(bytes.NewReader(section))
 				lastConfig = &c
 			}
@@ -216,6 +266,13 @@ func configSSH() *cobra.Command {
 			if usePreviousOpts && lastConfig != nil {
 				sshConfigOpts = *lastConfig
 			} else if lastConfig != nil && !sshConfigOpts.equal(*lastConfig) {
+				for _, v := range sshConfigOpts.sshOptions {
+					// If the user passes an invalid option, we should catch
+					// this early.
+					if _, _, err := codersdk.ParseSSHConfigOption(v); err != nil {
+						return xerrors.Errorf("invalid option from flag: %w", err)
+					}
+				}
 				newOpts := sshConfigOpts.asList()
 				newOptsMsg := "\n\n  New options: none"
 				if len(newOpts) > 0 {
@@ -227,7 +284,7 @@ func configSSH() *cobra.Command {
 					oldOptsMsg = fmt.Sprintf("\n\n  Previous options:\n    * %s", strings.Join(oldOpts, "\n    * "))
 				}
 
-				line, err := cliui.Prompt(cmd, cliui.PromptOptions{
+				line, err := cliui.Prompt(inv, cliui.PromptOptions{
 					Text:      fmt.Sprintf("New options differ from previous options:%s%s\n\n  Use new options?", newOptsMsg, oldOptsMsg),
 					IsConfirm: true,
 				})
@@ -241,7 +298,7 @@ func configSSH() *cobra.Command {
 					changes = append(changes, "Use new SSH options")
 				}
 				// Only print when prompts are shown.
-				if yes, _ := cmd.Flags().GetBool("yes"); !yes {
+				if yes, _ := inv.ParsedFlags().GetBool("yes"); !yes {
 					_, _ = fmt.Fprint(out, "\n")
 				}
 			}
@@ -249,7 +306,10 @@ func configSSH() *cobra.Command {
 			configModified := configRaw
 
 			buf := &bytes.Buffer{}
-			before, after := sshConfigSplitOnCoderSection(configModified)
+			before, _, after, err := sshConfigSplitOnCoderSection(configModified)
+			if err != nil {
+				return err
+			}
 			// Write the first half of the users config file to buf.
 			_, _ = buf.Write(before)
 
@@ -262,6 +322,25 @@ func configSSH() *cobra.Command {
 			if err != nil {
 				return xerrors.Errorf("fetch workspace configs failed: %w", err)
 			}
+
+			coderdConfig, err := client.SSHConfiguration(inv.Context())
+			if err != nil {
+				// If the error is 404, this deployment does not support
+				// this endpoint yet. Do not error, just assume defaults.
+				// TODO: Remove this in 2 months (May 31, 2023). Just return the error
+				// 	and remove this 404 check.
+				var sdkErr *codersdk.Error
+				if !(xerrors.As(err, &sdkErr) && sdkErr.StatusCode() == http.StatusNotFound) {
+					return xerrors.Errorf("fetch coderd config failed: %w", err)
+				}
+				coderdConfig.HostnamePrefix = "coder."
+			}
+
+			if userHostPrefix != "" {
+				// Override with user flag.
+				coderdConfig.HostnamePrefix = userHostPrefix
+			}
+
 			// Ensure stable sorting of output.
 			slices.SortFunc(workspaceConfigs, func(a, b sshWorkspaceConfig) bool {
 				return a.Name < b.Name
@@ -269,35 +348,59 @@ func configSSH() *cobra.Command {
 			for _, wc := range workspaceConfigs {
 				sort.Strings(wc.Hosts)
 				// Write agent configuration.
-				for _, hostname := range wc.Hosts {
-					configOptions := []string{
-						"Host coder." + hostname,
-					}
-					for _, option := range sshConfigOpts.sshOptions {
-						configOptions = append(configOptions, "\t"+option)
-					}
-					configOptions = append(configOptions,
-						"\tHostName coder."+hostname,
-						"\tConnectTimeout=0",
-						"\tStrictHostKeyChecking=no",
+				for _, workspaceHostname := range wc.Hosts {
+					sshHostname := fmt.Sprintf("%s%s", coderdConfig.HostnamePrefix, workspaceHostname)
+					defaultOptions := []string{
+						"HostName " + sshHostname,
+						"ConnectTimeout=0",
+						"StrictHostKeyChecking=no",
 						// Without this, the "REMOTE HOST IDENTITY CHANGED"
 						// message will appear.
-						"\tUserKnownHostsFile=/dev/null",
+						"UserKnownHostsFile=/dev/null",
 						// This disables the "Warning: Permanently added 'hostname' (RSA) to the list of known hosts."
 						// message from appearing on every SSH. This happens because we ignore the known hosts.
-						"\tLogLevel ERROR",
-					)
-					if !skipProxyCommand {
-						configOptions = append(
-							configOptions,
-							fmt.Sprintf(
-								"\tProxyCommand %s --global-config %s ssh --stdio %s",
-								escapedCoderBinary, escapedGlobalConfig, hostname,
-							),
-						)
+						"LogLevel ERROR",
 					}
 
-					_, _ = buf.WriteString(strings.Join(configOptions, "\n"))
+					if !skipProxyCommand {
+						defaultOptions = append(defaultOptions, fmt.Sprintf(
+							"ProxyCommand %s --global-config %s ssh --stdio %s",
+							escapedCoderBinary, escapedGlobalConfig, workspaceHostname,
+						))
+					}
+
+					var configOptions sshConfigOptions
+					// Add standard options.
+					err := configOptions.addOptions(defaultOptions...)
+					if err != nil {
+						return err
+					}
+
+					// Override with deployment options
+					for k, v := range coderdConfig.SSHConfigOptions {
+						opt := fmt.Sprintf("%s %s", k, v)
+						err := configOptions.addOptions(opt)
+						if err != nil {
+							return xerrors.Errorf("add coderd config option %q: %w", opt, err)
+						}
+					}
+					// Override with flag options
+					for _, opt := range sshConfigOpts.sshOptions {
+						err := configOptions.addOptions(opt)
+						if err != nil {
+							return xerrors.Errorf("add flag config option %q: %w", opt, err)
+						}
+					}
+
+					hostBlock := []string{
+						"Host " + sshHostname,
+					}
+					// Prefix with '\t'
+					for _, v := range configOptions.sshOptions {
+						hostBlock = append(hostBlock, "\t"+v)
+					}
+
+					_, _ = buf.WriteString(strings.Join(hostBlock, "\n"))
 					_ = buf.WriteByte('\n')
 				}
 			}
@@ -320,21 +423,21 @@ func configSSH() *cobra.Command {
 			if dryRun {
 				_, _ = fmt.Fprintf(out, "Dry run, the following changes would be made to your SSH configuration:\n\n  * %s\n\n", strings.Join(changes, "\n  * "))
 
-				color := isTTYOut(cmd)
+				color := isTTYOut(inv)
 				diff, err := diffBytes(sshConfigFile, configRaw, configModified, color)
 				if err != nil {
 					return xerrors.Errorf("diff failed: %w", err)
 				}
 				if len(diff) > 0 {
 					// Write diff to stdout.
-					_, _ = fmt.Fprintf(cmd.OutOrStdout(), "%s", diff)
+					_, _ = fmt.Fprintf(inv.Stdout, "%s", diff)
 				}
 
 				return nil
 			}
 
 			if len(changes) > 0 {
-				_, err = cliui.Prompt(cmd, cliui.PromptOptions{
+				_, err = cliui.Prompt(inv, cliui.PromptOptions{
 					Text:      fmt.Sprintf("The following changes will be made to your SSH configuration:\n\n    * %s\n\n  Continue?", strings.Join(changes, "\n    * ")),
 					IsConfirm: true,
 				})
@@ -342,7 +445,7 @@ func configSSH() *cobra.Command {
 					return nil
 				}
 				// Only print when prompts are shown.
-				if yes, _ := cmd.Flags().GetBool("yes"); !yes {
+				if yes, _ := inv.ParsedFlags().GetBool("yes"); !yes {
 					_, _ = fmt.Fprint(out, "\n")
 				}
 			}
@@ -352,24 +455,62 @@ func configSSH() *cobra.Command {
 				if err != nil {
 					return xerrors.Errorf("write ssh config failed: %w", err)
 				}
+				_, _ = fmt.Fprintf(out, "Updated %q\n", sshConfigFile)
 			}
 
 			if len(workspaceConfigs) > 0 {
 				_, _ = fmt.Fprintln(out, "You should now be able to ssh into your workspace.")
-				_, _ = fmt.Fprintf(out, "For example, try running:\n\n\t$ ssh coder.%s\n", workspaceConfigs[0].Name)
+				_, _ = fmt.Fprintf(out, "For example, try running:\n\n\t$ ssh %s%s\n", coderdConfig.HostnamePrefix, workspaceConfigs[0].Name)
 			} else {
 				_, _ = fmt.Fprint(out, "You don't have any workspaces yet, try creating one with:\n\n\t$ coder create <workspace>\n")
 			}
 			return nil
 		},
 	}
-	cliflag.StringVarP(cmd.Flags(), &sshConfigFile, "ssh-config-file", "", "CODER_SSH_CONFIG_FILE", sshDefaultConfigFileName, "Specifies the path to an SSH config.")
-	cmd.Flags().StringArrayVarP(&sshConfigOpts.sshOptions, "ssh-option", "o", []string{}, "Specifies additional SSH options to embed in each host stanza.")
-	cmd.Flags().BoolVarP(&dryRun, "dry-run", "n", false, "Perform a trial run with no changes made, showing a diff at the end.")
-	cmd.Flags().BoolVarP(&skipProxyCommand, "skip-proxy-command", "", false, "Specifies whether the ProxyCommand option should be skipped. Useful for testing.")
-	_ = cmd.Flags().MarkHidden("skip-proxy-command")
-	cliflag.BoolVarP(cmd.Flags(), &usePreviousOpts, "use-previous-options", "", "CODER_SSH_USE_PREVIOUS_OPTIONS", false, "Specifies whether or not to keep options from previous run of config-ssh.")
-	cliui.AllowSkipPrompt(cmd)
+
+	cmd.Options = clibase.OptionSet{
+		{
+			Flag:        "ssh-config-file",
+			Env:         "CODER_SSH_CONFIG_FILE",
+			Default:     sshDefaultConfigFileName,
+			Description: "Specifies the path to an SSH config.",
+			Value:       clibase.StringOf(&sshConfigFile),
+		},
+		{
+			Flag:          "ssh-option",
+			FlagShorthand: "o",
+			Env:           "CODER_SSH_CONFIG_OPTS",
+			Description:   "Specifies additional SSH options to embed in each host stanza.",
+			Value:         clibase.StringArrayOf(&sshConfigOpts.sshOptions),
+		},
+		{
+			Flag:          "dry-run",
+			FlagShorthand: "n",
+			Env:           "CODER_SSH_DRY_RUN",
+			Description:   "Perform a trial run with no changes made, showing a diff at the end.",
+			Value:         clibase.BoolOf(&dryRun),
+		},
+		{
+			Flag:        "skip-proxy-command",
+			Env:         "CODER_SSH_SKIP_PROXY_COMMAND",
+			Description: "Specifies whether the ProxyCommand option should be skipped. Useful for testing.",
+			Value:       clibase.BoolOf(&skipProxyCommand),
+			Hidden:      true,
+		},
+		{
+			Flag:        "use-previous-options",
+			Env:         "CODER_SSH_USE_PREVIOUS_OPTIONS",
+			Description: "Specifies whether or not to keep options from previous run of config-ssh.",
+			Value:       clibase.BoolOf(&usePreviousOpts),
+		},
+		{
+			Flag:        "ssh-host-prefix",
+			Env:         "",
+			Description: "Override the default host prefix.",
+			Value:       clibase.StringOf(&userHostPrefix),
+		},
+		cliui.SkipPromptOption(),
+	}
 
 	return cmd
 }
@@ -418,22 +559,39 @@ func sshConfigParseLastOptions(r io.Reader) (o sshConfigOptions) {
 	return o
 }
 
-func sshConfigGetCoderSection(data []byte) (section []byte, ok bool) {
-	startIndex := bytes.Index(data, []byte(sshStartToken))
-	endIndex := bytes.Index(data, []byte(sshEndToken))
-	if startIndex != -1 && endIndex != -1 {
-		return data[startIndex : endIndex+len(sshEndToken)], true
+// sshConfigGetCoderSection is a helper function that only returns the coder
+// section of the SSH config and a boolean if it exists.
+func sshConfigGetCoderSection(data []byte) (section []byte, ok bool, err error) {
+	_, section, _, err = sshConfigSplitOnCoderSection(data)
+	if err != nil {
+		return nil, false, err
 	}
-	return nil, false
+
+	return section, len(section) > 0, nil
 }
 
-// sshConfigSplitOnCoderSection splits the SSH config into two sections,
-// before contains the lines before sshStartToken and after contains the
-// lines after sshEndToken.
-func sshConfigSplitOnCoderSection(data []byte) (before, after []byte) {
+// sshConfigSplitOnCoderSection splits the SSH config into 3 sections.
+// All lines before sshStartToken, the coder section, and all lines after
+// sshEndToken.
+func sshConfigSplitOnCoderSection(data []byte) (before, section []byte, after []byte, err error) {
+	startCount := bytes.Count(data, []byte(sshStartToken))
+	endCount := bytes.Count(data, []byte(sshEndToken))
+	if startCount > 1 || endCount > 1 {
+		return nil, nil, nil, xerrors.New("Malformed config: ssh config has multiple coder sections, please remove all but one")
+	}
+
 	startIndex := bytes.Index(data, []byte(sshStartToken))
 	endIndex := bytes.Index(data, []byte(sshEndToken))
+	if startIndex == -1 && endIndex != -1 {
+		return nil, nil, nil, xerrors.New("Malformed config: ssh config has end header, but missing start header")
+	}
+	if startIndex != -1 && endIndex == -1 {
+		return nil, nil, nil, xerrors.New("Malformed config: ssh config has start header, but missing end header")
+	}
 	if startIndex != -1 && endIndex != -1 {
+		if startIndex > endIndex {
+			return nil, nil, nil, xerrors.New("Malformed config: ssh config has coder section, but it is malformed and the END header is before the START header")
+		}
 		// We use -1 and +1 here to also include the preceding
 		// and trailing newline, where applicable.
 		start := startIndex
@@ -444,10 +602,10 @@ func sshConfigSplitOnCoderSection(data []byte) (before, after []byte) {
 		if end < len(data) {
 			end++
 		}
-		return data[:start], data[end:]
+		return data[:start], data[start:end], data[end:], nil
 	}
 
-	return data, nil
+	return data, nil, nil, nil
 }
 
 // writeWithTempFileAndMove writes to a temporary file in the same

cli/configssh_internal_test.go

@@ -5,12 +5,132 @@ import (
 	"os/exec"
 	"path/filepath"
 	"runtime"
+	"sort"
 	"strings"
 	"testing"
 
 	"github.com/stretchr/testify/require"
 )
 
+func Test_sshConfigSplitOnCoderSection(t *testing.T) {
+	t.Parallel()
+
+	testCases := []struct {
+		Name    string
+		Input   string
+		Before  string
+		Section string
+		After   string
+		Err     bool
+	}{
+		{
+			Name:    "Empty",
+			Input:   "",
+			Before:  "",
+			Section: "",
+			After:   "",
+			Err:     false,
+		},
+		{
+			Name:    "JustSection",
+			Input:   strings.Join([]string{sshStartToken, sshEndToken}, "\n"),
+			Before:  "",
+			Section: strings.Join([]string{sshStartToken, sshEndToken}, "\n"),
+			After:   "",
+			Err:     false,
+		},
+		{
+			Name:    "NoSection",
+			Input:   strings.Join([]string{"# Some content"}, "\n"),
+			Before:  "# Some content",
+			Section: "",
+			After:   "",
+			Err:     false,
+		},
+		{
+			Name: "Normal",
+			Input: strings.Join([]string{
+				"# Content before the section",
+				sshStartToken,
+				sshEndToken,
+				"# Content after the section",
+			}, "\n"),
+			Before:  "# Content before the section",
+			Section: strings.Join([]string{"", sshStartToken, sshEndToken, ""}, "\n"),
+			After:   "# Content after the section",
+			Err:     false,
+		},
+		{
+			Name: "OutOfOrder",
+			Input: strings.Join([]string{
+				"# Content before the section",
+				sshEndToken,
+				sshStartToken,
+				"# Content after the section",
+			}, "\n"),
+			Err: true,
+		},
+		{
+			Name: "MissingStart",
+			Input: strings.Join([]string{
+				"# Content before the section",
+				sshEndToken,
+				"# Content after the section",
+			}, "\n"),
+			Err: true,
+		},
+		{
+			Name: "MissingEnd",
+			Input: strings.Join([]string{
+				"# Content before the section",
+				sshEndToken,
+				"# Content after the section",
+			}, "\n"),
+			Err: true,
+		},
+		{
+			Name: "ExtraStart",
+			Input: strings.Join([]string{
+				"# Content before the section",
+				sshStartToken,
+				sshEndToken,
+				sshStartToken,
+				"# Content after the section",
+			}, "\n"),
+			Err: true,
+		},
+		{
+			Name: "ExtraEnd",
+			Input: strings.Join([]string{
+				"# Content before the section",
+				sshStartToken,
+				sshEndToken,
+				sshEndToken,
+				"# Content after the section",
+			}, "\n"),
+			Err: true,
+		},
+	}
+
+	for _, tc := range testCases {
+		tc := tc
+		t.Run(tc.Name, func(t *testing.T) {
+			t.Parallel()
+
+			before, section, after, err := sshConfigSplitOnCoderSection([]byte(tc.Input))
+			if tc.Err {
+				require.Error(t, err)
+				return
+			}
+
+			require.NoError(t, err)
+			require.Equal(t, tc.Before, string(before), "before")
+			require.Equal(t, tc.Section, string(section), "section")
+			require.Equal(t, tc.After, string(after), "after")
+		})
+	}
+}
+
 // This test tries to mimic the behavior of OpenSSH
 // when executing e.g. a ProxyCommand.
 func Test_sshConfigExecEscape(t *testing.T) {
@@ -60,3 +180,80 @@ func Test_sshConfigExecEscape(t *testing.T) {
 		})
 	}
 }
+
+func Test_sshConfigOptions_addOption(t *testing.T) {
+	t.Parallel()
+	testCases := []struct {
+		Name        string
+		Start       []string
+		Add         []string
+		Expect      []string
+		ExpectError bool
+	}{
+		{
+			Name: "Empty",
+		},
+		{
+			Name: "AddOne",
+			Add:  []string{"foo bar"},
+			Expect: []string{
+				"foo bar",
+			},
+		},
+		{
+			Name: "Replace",
+			Start: []string{
+				"foo bar",
+			},
+			Add: []string{"Foo baz"},
+			Expect: []string{
+				"Foo baz",
+			},
+		},
+		{
+			Name: "AddAndReplace",
+			Start: []string{
+				"a b",
+				"foo bar",
+				"buzz bazz",
+			},
+			Add: []string{
+				"b c",
+				"A hello",
+				"hello world",
+			},
+			Expect: []string{
+				"foo bar",
+				"buzz bazz",
+				"b c",
+				"A hello",
+				"hello world",
+			},
+		},
+		{
+			Name:        "Error",
+			Add:         []string{"novalue"},
+			ExpectError: true,
+		},
+	}
+
+	for _, tt := range testCases {
+		tt := tt
+		t.Run(tt.Name, func(t *testing.T) {
+			t.Parallel()
+
+			o := sshConfigOptions{
+				sshOptions: tt.Start,
+			}
+			err := o.addOptions(tt.Add...)
+			if tt.ExpectError {
+				require.Error(t, err)
+				return
+			}
+			require.NoError(t, err)
+			sort.Strings(tt.Expect)
+			sort.Strings(o.sshOptions)
+			require.Equal(t, tt.Expect, o.sshOptions)
+		})
+	}
+}

cli/configssh_test.go

@@ -19,16 +19,17 @@ import (
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 
-	"cdr.dev/slog"
 	"cdr.dev/slog/sloggers/slogtest"
 
 	"github.com/coder/coder/agent"
 	"github.com/coder/coder/cli/clitest"
 	"github.com/coder/coder/coderd/coderdtest"
 	"github.com/coder/coder/codersdk"
+	"github.com/coder/coder/codersdk/agentsdk"
 	"github.com/coder/coder/provisioner/echo"
 	"github.com/coder/coder/provisionersdk/proto"
 	"github.com/coder/coder/pty/ptytest"
+	"github.com/coder/coder/testutil"
 )
 
 func sshConfigFileName(t *testing.T) (sshConfig string) {
@@ -63,12 +64,25 @@ func sshConfigFileRead(t *testing.T, name string) string {
 func TestConfigSSH(t *testing.T) {
 	t.Parallel()
 
-	client := coderdtest.New(t, &coderdtest.Options{IncludeProvisionerDaemon: true})
+	const hostname = "test-coder."
+	const expectedKey = "ConnectionAttempts"
+	const removeKey = "ConnectionTimeout"
+	client := coderdtest.New(t, &coderdtest.Options{
+		IncludeProvisionerDaemon: true,
+		ConfigSSH: codersdk.SSHConfigResponse{
+			HostnamePrefix: hostname,
+			SSHConfigOptions: map[string]string{
+				// Something we can test for
+				expectedKey: "3",
+				removeKey:   "",
+			},
+		},
+	})
 	user := coderdtest.CreateFirstUser(t, client)
 	authToken := uuid.NewString()
 	version := coderdtest.CreateTemplateVersion(t, client, user.OrganizationID, &echo.Responses{
 		Parse: echo.ParseComplete,
-		ProvisionDryRun: []*proto.Provision_Response{{
+		ProvisionPlan: []*proto.Provision_Response{{
 			Type: &proto.Provision_Response_Complete{
 				Complete: &proto.Provision_Complete{
 					Resources: []*proto.Resource{{
@@ -82,40 +96,23 @@ func TestConfigSSH(t *testing.T) {
 				},
 			},
 		}},
-		Provision: []*proto.Provision_Response{{
-			Type: &proto.Provision_Response_Complete{
-				Complete: &proto.Provision_Complete{
-					Resources: []*proto.Resource{{
-						Name: "example",
-						Type: "aws_instance",
-						Agents: []*proto.Agent{{
-							Id:   uuid.NewString(),
-							Name: "example",
-							Auth: &proto.Agent_Token{
-								Token: authToken,
-							},
-						}},
-					}},
-				},
-			},
-		}},
+		ProvisionApply: echo.ProvisionApplyWithAgent(authToken),
 	})
 	coderdtest.AwaitTemplateVersionJob(t, client, version.ID)
 	template := coderdtest.CreateTemplate(t, client, user.OrganizationID, version.ID)
 	workspace := coderdtest.CreateWorkspace(t, client, user.OrganizationID, template.ID)
 	coderdtest.AwaitWorkspaceBuildJob(t, client, workspace.LatestBuild.ID)
-	agentClient := codersdk.New(client.URL)
-	agentClient.SessionToken = authToken
+	agentClient := agentsdk.New(client.URL)
+	agentClient.SetSessionToken(authToken)
 	agentCloser := agent.New(agent.Options{
-		FetchMetadata:     agentClient.WorkspaceAgentMetadata,
-		CoordinatorDialer: agentClient.ListenWorkspaceAgentTailnet,
-		Logger:            slogtest.Make(t, nil).Named("agent"),
+		Client: agentClient,
+		Logger: slogtest.Make(t, nil).Named("agent"),
 	})
 	defer func() {
 		_ = agentCloser.Close()
 	}()
 	resources := coderdtest.AwaitWorkspaceAgents(t, client, workspace.ID)
-	agentConn, err := client.DialWorkspaceAgentTailnet(context.Background(), slog.Logger{}, resources[0].Agents[0].ID)
+	agentConn, err := client.DialWorkspaceAgent(context.Background(), resources[0].Agents[0].ID, nil)
 	require.NoError(t, err)
 	defer agentConn.Close()
 
@@ -133,7 +130,9 @@ func TestConfigSSH(t *testing.T) {
 			if err != nil {
 				break
 			}
-			ssh, err := agentConn.SSH()
+			ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitLong)
+			ssh, err := agentConn.SSH(ctx)
+			cancel()
 			assert.NoError(t, err)
 			wg.Add(2)
 			go func() {
@@ -152,21 +151,17 @@ func TestConfigSSH(t *testing.T) {
 
 	tcpAddr, valid := listener.Addr().(*net.TCPAddr)
 	require.True(t, valid)
-	cmd, root := clitest.New(t, "config-ssh",
+	inv, root := clitest.New(t, "config-ssh",
 		"--ssh-option", "HostName "+tcpAddr.IP.String(),
 		"--ssh-option", "Port "+strconv.Itoa(tcpAddr.Port),
 		"--ssh-config-file", sshConfigFile,
 		"--skip-proxy-command")
 	clitest.SetupConfig(t, client, root)
-	doneChan := make(chan struct{})
 	pty := ptytest.New(t)
-	cmd.SetIn(pty.Input())
-	cmd.SetOut(pty.Output())
-	go func() {
-		defer close(doneChan)
-		err := cmd.Execute()
-		assert.NoError(t, err)
-	}()
+	inv.Stdin = pty.Input()
+	inv.Stdout = pty.Output()
+
+	waiter := clitest.StartWithWaiter(t, inv)
 
 	matches := []struct {
 		match, write string
@@ -178,15 +173,20 @@ func TestConfigSSH(t *testing.T) {
 		pty.WriteLine(m.write)
 	}
 
-	<-doneChan
+	waiter.RequireSuccess()
+
+	fileContents, err := os.ReadFile(sshConfigFile)
+	require.NoError(t, err, "read ssh config file")
+	require.Contains(t, string(fileContents), expectedKey, "ssh config file contains expected key")
+	require.NotContains(t, string(fileContents), removeKey, "ssh config file should not have removed key")
 
 	home := filepath.Dir(filepath.Dir(sshConfigFile))
 	// #nosec
-	sshCmd := exec.Command("ssh", "-F", sshConfigFile, "coder."+workspace.Name, "echo", "test")
+	sshCmd := exec.Command("ssh", "-F", sshConfigFile, hostname+workspace.Name, "echo", "test")
 	pty = ptytest.New(t)
 	// Set HOME because coder config is included from ~/.ssh/coder.
 	sshCmd.Env = append(sshCmd.Env, fmt.Sprintf("HOME=%s", home))
-	sshCmd.Stderr = pty.Output()
+	inv.Stderr = pty.Output()
 	data, err := sshCmd.Output()
 	require.NoError(t, err)
 	require.Equal(t, "test", strings.TrimSpace(string(data)))
@@ -528,6 +528,36 @@ func TestConfigSSH_FileWriteAndOptionsFlow(t *testing.T) {
 				"--yes",
 			},
 		},
+		{
+			name:    "Start/End out of order",
+			matches: []match{
+				// {match: "Continue?", write: "yes"},
+			},
+			writeConfig: writeConfig{
+				ssh: strings.Join([]string{
+					"# Content before coder block",
+					headerEnd,
+					headerStart,
+					"# Content after coder block",
+				}, "\n"),
+			},
+			wantErr: true,
+		},
+		{
+			name:    "Multiple sections",
+			matches: []match{
+				// {match: "Continue?", write: "yes"},
+			},
+			writeConfig: writeConfig{
+				ssh: strings.Join([]string{
+					headerStart,
+					headerEnd,
+					headerStart,
+					headerEnd,
+				}, "\n"),
+			},
+			wantErr: true,
+		},
 	}
 	for _, tt := range tests {
 		tt := tt
@@ -555,14 +585,14 @@ func TestConfigSSH_FileWriteAndOptionsFlow(t *testing.T) {
 				"--ssh-config-file", sshConfigName,
 			}
 			args = append(args, tt.args...)
-			cmd, root := clitest.New(t, args...)
+			inv, root := clitest.New(t, args...)
 			clitest.SetupConfig(t, client, root)
 
 			pty := ptytest.New(t)
-			cmd.SetIn(pty.Input())
-			cmd.SetOut(pty.Output())
+			inv.Stdin = pty.Input()
+			inv.Stdout = pty.Output()
 			done := tGo(t, func() {
-				err := cmd.Execute()
+				err := inv.Run()
 				if !tt.wantErr {
 					assert.NoError(t, err)
 				} else {
@@ -661,9 +691,9 @@ func TestConfigSSH_Hostnames(t *testing.T) {
 			user := coderdtest.CreateFirstUser(t, client)
 			// authToken := uuid.NewString()
 			version := coderdtest.CreateTemplateVersion(t, client, user.OrganizationID, &echo.Responses{
-				Parse:           echo.ParseComplete,
-				ProvisionDryRun: provisionResponse,
-				Provision:       provisionResponse,
+				Parse:          echo.ParseComplete,
+				ProvisionPlan:  provisionResponse,
+				ProvisionApply: provisionResponse,
 			})
 			coderdtest.AwaitTemplateVersionJob(t, client, version.ID)
 			template := coderdtest.CreateTemplate(t, client, user.OrganizationID, version.ID)
@@ -672,17 +702,13 @@ func TestConfigSSH_Hostnames(t *testing.T) {
 
 			sshConfigFile := sshConfigFileName(t)
 
-			cmd, root := clitest.New(t, "config-ssh", "--ssh-config-file", sshConfigFile)
+			inv, root := clitest.New(t, "config-ssh", "--ssh-config-file", sshConfigFile)
 			clitest.SetupConfig(t, client, root)
-			doneChan := make(chan struct{})
+
 			pty := ptytest.New(t)
-			cmd.SetIn(pty.Input())
-			cmd.SetOut(pty.Output())
-			go func() {
-				defer close(doneChan)
-				err := cmd.Execute()
-				assert.NoError(t, err)
-			}()
+			inv.Stdin = pty.Input()
+			inv.Stdout = pty.Output()
+			clitest.Start(t, inv)
 
 			matches := []struct {
 				match, write string
@@ -694,7 +720,7 @@ func TestConfigSSH_Hostnames(t *testing.T) {
 				pty.WriteLine(m.write)
 			}
 
-			<-doneChan
+			pty.ExpectMatch("Updated")
 
 			var expectedHosts []string
 			for _, hostnamePattern := range tt.expected {

cli/create.go

@@ -1,52 +1,51 @@
 package cli
 
 import (
+	"context"
 	"fmt"
 	"io"
 	"time"
 
-	"github.com/spf13/cobra"
+	"github.com/google/uuid"
 	"golang.org/x/exp/slices"
 	"golang.org/x/xerrors"
 
-	"github.com/coder/coder/cli/cliflag"
+	"github.com/coder/coder/cli/clibase"
 	"github.com/coder/coder/cli/cliui"
 	"github.com/coder/coder/coderd/util/ptr"
 	"github.com/coder/coder/codersdk"
 )
 
-func create() *cobra.Command {
+func (r *RootCmd) create() *clibase.Cmd {
 	var (
-		parameterFile string
-		templateName  string
-		startAt       string
-		stopAfter     time.Duration
-		workspaceName string
+		parameterFile     string
+		richParameterFile string
+		templateName      string
+		startAt           string
+		stopAfter         time.Duration
+		workspaceName     string
 	)
-	cmd := &cobra.Command{
+	client := new(codersdk.Client)
+	cmd := &clibase.Cmd{
 		Annotations: workspaceCommand,
 		Use:         "create [name]",
 		Short:       "Create a workspace",
-		RunE: func(cmd *cobra.Command, args []string) error {
-			client, err := CreateClient(cmd)
+		Middleware:  clibase.Chain(r.InitClient(client)),
+		Handler: func(inv *clibase.Invocation) error {
+			organization, err := CurrentOrganization(inv, client)
 			if err != nil {
 				return err
 			}
 
-			organization, err := currentOrganization(cmd, client)
-			if err != nil {
-				return err
-			}
-
-			if len(args) >= 1 {
-				workspaceName = args[0]
+			if len(inv.Args) >= 1 {
+				workspaceName = inv.Args[0]
 			}
 
 			if workspaceName == "" {
-				workspaceName, err = cliui.Prompt(cmd, cliui.PromptOptions{
+				workspaceName, err = cliui.Prompt(inv, cliui.PromptOptions{
 					Text: "Specify a name for your workspace:",
 					Validate: func(workspaceName string) error {
-						_, err = client.WorkspaceByOwnerAndName(cmd.Context(), codersdk.Me, workspaceName, codersdk.WorkspaceOptions{})
+						_, err = client.WorkspaceByOwnerAndName(inv.Context(), codersdk.Me, workspaceName, codersdk.WorkspaceOptions{})
 						if err == nil {
 							return xerrors.Errorf("A workspace already exists named %q!", workspaceName)
 						}
@@ -58,16 +57,16 @@ func create() *cobra.Command {
 				}
 			}
 
-			_, err = client.WorkspaceByOwnerAndName(cmd.Context(), codersdk.Me, workspaceName, codersdk.WorkspaceOptions{})
+			_, err = client.WorkspaceByOwnerAndName(inv.Context(), codersdk.Me, workspaceName, codersdk.WorkspaceOptions{})
 			if err == nil {
 				return xerrors.Errorf("A workspace already exists named %q!", workspaceName)
 			}
 
 			var template codersdk.Template
 			if templateName == "" {
-				_, _ = fmt.Fprintln(cmd.OutOrStdout(), cliui.Styles.Wrap.Render("Select a template below to preview the provisioned infrastructure:"))
+				_, _ = fmt.Fprintln(inv.Stdout, cliui.Styles.Wrap.Render("Select a template below to preview the provisioned infrastructure:"))
 
-				templates, err := client.TemplatesByOrganization(cmd.Context(), organization.ID)
+				templates, err := client.TemplatesByOrganization(inv.Context(), organization.ID)
 				if err != nil {
 					return err
 				}
@@ -96,7 +95,7 @@ func create() *cobra.Command {
 				}
 
 				// Move the cursor up a single line for nicer display!
-				option, err := cliui.Select(cmd, cliui.SelectOptions{
+				option, err := cliui.Select(inv, cliui.SelectOptions{
 					Options:    templateNames,
 					HideSearch: true,
 				})
@@ -106,7 +105,7 @@ func create() *cobra.Command {
 
 				template = templateByName[option]
 			} else {
-				template, err = client.TemplateByName(cmd.Context(), organization.ID, templateName)
+				template, err = client.TemplateByName(inv.Context(), organization.ID, templateName)
 				if err != nil {
 					return xerrors.Errorf("get template by name: %w", err)
 				}
@@ -121,17 +120,18 @@ func create() *cobra.Command {
 				schedSpec = ptr.Ref(sched.String())
 			}
 
-			parameters, err := prepWorkspaceBuild(cmd, client, prepWorkspaceBuildArgs{
-				Template:         template,
-				ExistingParams:   []codersdk.Parameter{},
-				ParameterFile:    parameterFile,
-				NewWorkspaceName: workspaceName,
+			buildParams, err := prepWorkspaceBuild(inv, client, prepWorkspaceBuildArgs{
+				Template:          template,
+				ExistingParams:    []codersdk.Parameter{},
+				ParameterFile:     parameterFile,
+				RichParameterFile: richParameterFile,
+				NewWorkspaceName:  workspaceName,
 			})
 			if err != nil {
-				return err
+				return xerrors.Errorf("prepare build: %w", err)
 			}
 
-			_, err = cliui.Prompt(cmd, cliui.PromptOptions{
+			_, err = cliui.Prompt(inv, cliui.PromptOptions{
 				Text:      "Confirm create?",
 				IsConfirm: true,
 			})
@@ -139,51 +139,116 @@ func create() *cobra.Command {
 				return err
 			}
 
-			after := time.Now()
-			workspace, err := client.CreateWorkspace(cmd.Context(), organization.ID, codersdk.Me, codersdk.CreateWorkspaceRequest{
-				TemplateID:        template.ID,
-				Name:              workspaceName,
-				AutostartSchedule: schedSpec,
-				TTLMillis:         ptr.Ref(stopAfter.Milliseconds()),
-				ParameterValues:   parameters,
+			var ttlMillis *int64
+			if stopAfter > 0 {
+				ttlMillis = ptr.Ref(stopAfter.Milliseconds())
+			} else if template.MaxTTLMillis > 0 {
+				ttlMillis = &template.MaxTTLMillis
+			}
+
+			workspace, err := client.CreateWorkspace(inv.Context(), organization.ID, codersdk.Me, codersdk.CreateWorkspaceRequest{
+				TemplateID:          template.ID,
+				Name:                workspaceName,
+				AutostartSchedule:   schedSpec,
+				TTLMillis:           ttlMillis,
+				ParameterValues:     buildParams.parameters,
+				RichParameterValues: buildParams.richParameters,
 			})
 			if err != nil {
-				return err
+				return xerrors.Errorf("create workspace: %w", err)
 			}
 
-			err = cliui.WorkspaceBuild(cmd.Context(), cmd.OutOrStdout(), client, workspace.LatestBuild.ID, after)
+			err = cliui.WorkspaceBuild(inv.Context(), inv.Stdout, client, workspace.LatestBuild.ID)
 			if err != nil {
-				return err
+				return xerrors.Errorf("watch build: %w", err)
 			}
 
-			_, _ = fmt.Fprintf(cmd.OutOrStdout(), "\nThe %s workspace has been created at %s!\n", cliui.Styles.Keyword.Render(workspace.Name), cliui.Styles.DateTimeStamp.Render(time.Now().Format(time.Stamp)))
+			_, _ = fmt.Fprintf(inv.Stdout, "\nThe %s workspace has been created at %s!\n", cliui.Styles.Keyword.Render(workspace.Name), cliui.Styles.DateTimeStamp.Render(time.Now().Format(time.Stamp)))
 			return nil
 		},
 	}
+	cmd.Options = append(cmd.Options,
+		clibase.Option{
+			Flag:          "template",
+			FlagShorthand: "t",
+			Env:           "CODER_TEMPLATE_NAME",
+			Description:   "Specify a template name.",
+			Value:         clibase.StringOf(&templateName),
+		},
+		clibase.Option{
+			Flag:        "parameter-file",
+			Env:         "CODER_PARAMETER_FILE",
+			Description: "Specify a file path with parameter values.",
+			Value:       clibase.StringOf(&parameterFile),
+		},
+		clibase.Option{
+			Flag:        "rich-parameter-file",
+			Env:         "CODER_RICH_PARAMETER_FILE",
+			Description: "Specify a file path with values for rich parameters defined in the template.",
+			Value:       clibase.StringOf(&richParameterFile),
+		},
+		clibase.Option{
+			Flag:        "start-at",
+			Env:         "CODER_WORKSPACE_START_AT",
+			Description: "Specify the workspace autostart schedule. Check coder schedule start --help for the syntax.",
+			Value:       clibase.StringOf(&startAt),
+		},
+		clibase.Option{
+			Flag:        "stop-after",
+			Env:         "CODER_WORKSPACE_STOP_AFTER",
+			Description: "Specify a duration after which the workspace should shut down (e.g. 8h).",
+			Value:       clibase.DurationOf(&stopAfter),
+		},
+		cliui.SkipPromptOption(),
+	)
 
-	cliui.AllowSkipPrompt(cmd)
-	cliflag.StringVarP(cmd.Flags(), &templateName, "template", "t", "CODER_TEMPLATE_NAME", "", "Specify a template name.")
-	cliflag.StringVarP(cmd.Flags(), &parameterFile, "parameter-file", "", "CODER_PARAMETER_FILE", "", "Specify a file path with parameter values.")
-	cliflag.StringVarP(cmd.Flags(), &startAt, "start-at", "", "CODER_WORKSPACE_START_AT", "", "Specify the workspace autostart schedule. Check `coder schedule start --help` for the syntax.")
-	cliflag.DurationVarP(cmd.Flags(), &stopAfter, "stop-after", "", "CODER_WORKSPACE_STOP_AFTER", 8*time.Hour, "Specify a duration after which the workspace should shut down (e.g. 8h).")
 	return cmd
 }
 
 type prepWorkspaceBuildArgs struct {
-	Template         codersdk.Template
-	ExistingParams   []codersdk.Parameter
-	ParameterFile    string
-	NewWorkspaceName string
+	Template           codersdk.Template
+	ExistingParams     []codersdk.Parameter
+	ParameterFile      string
+	ExistingRichParams []codersdk.WorkspaceBuildParameter
+	RichParameterFile  string
+	NewWorkspaceName   string
+
+	UpdateWorkspace bool
+	WorkspaceID     uuid.UUID
+}
+
+type buildParameters struct {
+	// Parameters contains legacy parameters stored in /parameters.
+	parameters []codersdk.CreateParameterRequest
+	// Rich parameters stores values for build parameters annotated with description, icon, type, etc.
+	richParameters []codersdk.WorkspaceBuildParameter
 }
 
 // prepWorkspaceBuild will ensure a workspace build will succeed on the latest template version.
-// Any missing params will be prompted to the user.
-func prepWorkspaceBuild(cmd *cobra.Command, client *codersdk.Client, args prepWorkspaceBuildArgs) ([]codersdk.CreateParameterRequest, error) {
-	ctx := cmd.Context()
+// Any missing params will be prompted to the user. It supports legacy and rich parameters.
+func prepWorkspaceBuild(inv *clibase.Invocation, client *codersdk.Client, args prepWorkspaceBuildArgs) (*buildParameters, error) {
+	ctx := inv.Context()
+
+	var useRichParameters bool
+	if len(args.ExistingRichParams) > 0 && len(args.RichParameterFile) > 0 {
+		useRichParameters = true
+	}
+
+	var useLegacyParameters bool
+	if len(args.ExistingParams) > 0 || len(args.ParameterFile) > 0 {
+		useLegacyParameters = true
+	}
+
+	if useRichParameters && useLegacyParameters {
+		return nil, xerrors.Errorf("Rich parameters can't be used together with legacy parameters.")
+	}
+
 	templateVersion, err := client.TemplateVersion(ctx, args.Template.ActiveVersionID)
 	if err != nil {
 		return nil, err
 	}
+
+	// Legacy parameters
 	parameterSchemas, err := client.TemplateVersionSchema(ctx, templateVersion.ID)
 	if err != nil {
 		return nil, err
@@ -194,21 +259,21 @@ func prepWorkspaceBuild(cmd *cobra.Command, client *codersdk.Client, args prepWo
 	useParamFile := false
 	if args.ParameterFile != "" {
 		useParamFile = true
-		_, _ = fmt.Fprintln(cmd.OutOrStdout(), cliui.Styles.Paragraph.Render("Attempting to read the variables from the parameter file.")+"\r\n")
+		_, _ = fmt.Fprintln(inv.Stdout, cliui.Styles.Paragraph.Render("Attempting to read the variables from the parameter file.")+"\r\n")
 		parameterMapFromFile, err = createParameterMapFromFile(args.ParameterFile)
 		if err != nil {
 			return nil, err
 		}
 	}
 	disclaimerPrinted := false
-	parameters := make([]codersdk.CreateParameterRequest, 0)
+	legacyParameters := make([]codersdk.CreateParameterRequest, 0)
 PromptParamLoop:
 	for _, parameterSchema := range parameterSchemas {
 		if !parameterSchema.AllowOverrideSource {
 			continue
 		}
 		if !disclaimerPrinted {
-			_, _ = fmt.Fprintln(cmd.OutOrStdout(), cliui.Styles.Paragraph.Render("This template has customizable parameters. Values can be changed after create, but may have unintended side effects (like data loss).")+"\r\n")
+			_, _ = fmt.Fprintln(inv.Stdout, cliui.Styles.Paragraph.Render("This template has customizable parameters. Values can be changed after create, but may have unintended side effects (like data loss).")+"\r\n")
 			disclaimerPrinted = true
 		}
 
@@ -223,39 +288,113 @@ PromptParamLoop:
 			}
 		}
 
-		parameterValue, err := getParameterValueFromMapOrInput(cmd, parameterMapFromFile, parameterSchema)
+		parameterValue, err := getParameterValueFromMapOrInput(inv, parameterMapFromFile, parameterSchema)
 		if err != nil {
 			return nil, err
 		}
 
-		parameters = append(parameters, codersdk.CreateParameterRequest{
+		legacyParameters = append(legacyParameters, codersdk.CreateParameterRequest{
 			Name:              parameterSchema.Name,
 			SourceValue:       parameterValue,
 			SourceScheme:      codersdk.ParameterSourceSchemeData,
 			DestinationScheme: parameterSchema.DefaultDestinationScheme,
 		})
 	}
-	_, _ = fmt.Fprintln(cmd.OutOrStdout())
+
+	if disclaimerPrinted {
+		_, _ = fmt.Fprintln(inv.Stdout)
+	}
+
+	// Rich parameters
+	templateVersionParameters, err := client.TemplateVersionRichParameters(inv.Context(), templateVersion.ID)
+	if err != nil {
+		return nil, xerrors.Errorf("get template version rich parameters: %w", err)
+	}
+
+	parameterMapFromFile = map[string]string{}
+	useParamFile = false
+	if args.RichParameterFile != "" {
+		useParamFile = true
+		_, _ = fmt.Fprintln(inv.Stdout, cliui.Styles.Paragraph.Render("Attempting to read the variables from the rich parameter file.")+"\r\n")
+		parameterMapFromFile, err = createParameterMapFromFile(args.RichParameterFile)
+		if err != nil {
+			return nil, err
+		}
+	}
+	disclaimerPrinted = false
+	richParameters := make([]codersdk.WorkspaceBuildParameter, 0)
+PromptRichParamLoop:
+	for _, templateVersionParameter := range templateVersionParameters {
+		if !disclaimerPrinted {
+			_, _ = fmt.Fprintln(inv.Stdout, cliui.Styles.Paragraph.Render("This template has customizable parameters. Values can be changed after create, but may have unintended side effects (like data loss).")+"\r\n")
+			disclaimerPrinted = true
+		}
+
+		// Param file is all or nothing
+		if !useParamFile {
+			for _, e := range args.ExistingRichParams {
+				if e.Name == templateVersionParameter.Name {
+					// If the param already exists, we do not need to prompt it again.
+					// The workspace scope will reuse params for each build.
+					continue PromptRichParamLoop
+				}
+			}
+		}
+
+		if args.UpdateWorkspace && !templateVersionParameter.Mutable {
+			// Check if the immutable parameter was used in the previous build. If so, then it isn't a fresh one
+			// and the user should be warned.
+			exists, err := workspaceBuildParameterExists(ctx, client, args.WorkspaceID, templateVersionParameter)
+			if err != nil {
+				return nil, err
+			}
+
+			if exists {
+				_, _ = fmt.Fprintln(inv.Stdout, cliui.Styles.Warn.Render(fmt.Sprintf(`Parameter %q is not mutable, so can't be customized after workspace creation.`, templateVersionParameter.Name)))
+				continue
+			}
+		}
+
+		parameterValue, err := getWorkspaceBuildParameterValueFromMapOrInput(inv, parameterMapFromFile, templateVersionParameter)
+		if err != nil {
+			return nil, err
+		}
+
+		richParameters = append(richParameters, *parameterValue)
+	}
+
+	if disclaimerPrinted {
+		_, _ = fmt.Fprintln(inv.Stdout)
+	}
+
+	err = cliui.GitAuth(ctx, inv.Stdout, cliui.GitAuthOptions{
+		Fetch: func(ctx context.Context) ([]codersdk.TemplateVersionGitAuth, error) {
+			return client.TemplateVersionGitAuth(ctx, templateVersion.ID)
+		},
+	})
+	if err != nil {
+		return nil, xerrors.Errorf("template version git auth: %w", err)
+	}
 
 	// Run a dry-run with the given parameters to check correctness
-	after := time.Now()
-	dryRun, err := client.CreateTemplateVersionDryRun(cmd.Context(), templateVersion.ID, codersdk.CreateTemplateVersionDryRunRequest{
-		WorkspaceName:   args.NewWorkspaceName,
-		ParameterValues: parameters,
+	dryRun, err := client.CreateTemplateVersionDryRun(inv.Context(), templateVersion.ID, codersdk.CreateTemplateVersionDryRunRequest{
+		WorkspaceName:       args.NewWorkspaceName,
+		ParameterValues:     legacyParameters,
+		RichParameterValues: richParameters,
 	})
 	if err != nil {
 		return nil, xerrors.Errorf("begin workspace dry-run: %w", err)
 	}
-	_, _ = fmt.Fprintln(cmd.OutOrStdout(), "Planning workspace...")
-	err = cliui.ProvisionerJob(cmd.Context(), cmd.OutOrStdout(), cliui.ProvisionerJobOptions{
+	_, _ = fmt.Fprintln(inv.Stdout, "Planning workspace...")
+	err = cliui.ProvisionerJob(inv.Context(), inv.Stdout, cliui.ProvisionerJobOptions{
 		Fetch: func() (codersdk.ProvisionerJob, error) {
-			return client.TemplateVersionDryRun(cmd.Context(), templateVersion.ID, dryRun.ID)
+			return client.TemplateVersionDryRun(inv.Context(), templateVersion.ID, dryRun.ID)
 		},
 		Cancel: func() error {
-			return client.CancelTemplateVersionDryRun(cmd.Context(), templateVersion.ID, dryRun.ID)
+			return client.CancelTemplateVersionDryRun(inv.Context(), templateVersion.ID, dryRun.ID)
 		},
 		Logs: func() (<-chan codersdk.ProvisionerJobLog, io.Closer, error) {
-			return client.TemplateVersionDryRunLogsAfter(cmd.Context(), templateVersion.ID, dryRun.ID, after)
+			return client.TemplateVersionDryRunLogsAfter(inv.Context(), templateVersion.ID, dryRun.ID, 0)
 		},
 		// Don't show log output for the dry-run unless there's an error.
 		Silent: true,
@@ -266,20 +405,37 @@ PromptParamLoop:
 		return nil, xerrors.Errorf("dry-run workspace: %w", err)
 	}
 
-	resources, err := client.TemplateVersionDryRunResources(cmd.Context(), templateVersion.ID, dryRun.ID)
+	resources, err := client.TemplateVersionDryRunResources(inv.Context(), templateVersion.ID, dryRun.ID)
 	if err != nil {
 		return nil, xerrors.Errorf("get workspace dry-run resources: %w", err)
 	}
 
-	err = cliui.WorkspaceResources(cmd.OutOrStdout(), resources, cliui.WorkspaceResourcesOptions{
+	err = cliui.WorkspaceResources(inv.Stdout, resources, cliui.WorkspaceResourcesOptions{
 		WorkspaceName: args.NewWorkspaceName,
 		// Since agents haven't connected yet, hiding this makes more sense.
 		HideAgentState: true,
 		Title:          "Workspace Preview",
 	})
 	if err != nil {
-		return nil, err
+		return nil, xerrors.Errorf("get resources: %w", err)
 	}
 
-	return parameters, nil
+	return &buildParameters{
+		parameters:     legacyParameters,
+		richParameters: richParameters,
+	}, nil
+}
+
+func workspaceBuildParameterExists(ctx context.Context, client *codersdk.Client, workspaceID uuid.UUID, templateVersionParameter codersdk.TemplateVersionParameter) (bool, error) {
+	lastBuildParameters, err := client.WorkspaceBuildParameters(ctx, workspaceID)
+	if err != nil {
+		return false, xerrors.Errorf("can't fetch last workspace build parameters: %w", err)
+	}
+
+	for _, p := range lastBuildParameters {
+		if p.Name == templateVersionParameter.Name {
+			return true, nil
+		}
+	}
+	return false, nil
 }