fi stop tracing 4xx http status codes as errors (#3707)

Signed-off-by: Spike Curtis <spike@coder.com>

Signed-off-by: Spike Curtis <spike@coder.com>

.editorconfig

@@ -0,0 +1,16 @@
+root = true
+
+[*]
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+indent_style = tab
+
+[*.{md,json,yaml,yml,tf,tfvars}]
+indent_style = space
+indent_size = 2
+
+[coderd/database/dump.sql]
+indent_style = space
+indent_size = 4

.gitattributes

@@ -3,3 +3,7 @@ coderd/database/dump.sql linguist-generated=true
 peerbroker/proto/*.go linguist-generated=true
 provisionerd/proto/*.go linguist-generated=true
 provisionersdk/proto/*.go linguist-generated=true
+*.tfplan.json linguist-generated=true
+*.tfstate.json linguist-generated=true
+*.tfstate.dot linguist-generated=true
+*.tfplan.dot linguist-generated=true

.github/CODEOWNERS

@@ -1,2 +1,2 @@
-site @coder/frontend
-site/src/xServices @presleyp
+site/ @coder/frontend
+docs/ @ammario

.github/ISSUE_TEMPLATE/bug-report.md

@@ -1,37 +0,0 @@
----
-name: Bug report
-about: Report a bug
-title: "Bug: "
-labels: "bug :bug:"
----
-
-## OS Information
-
-- OS:
-- Browser (if applicable): 
-- Architecture:
-- `coder --version`:
-
-## Steps to Reproduce
-
-<!-- 1. -->
-<!-- 2. -->
-<!-- 3. -->
-
-## Expected
-
-<!-- What should happen? -->
-
-## Actual
-
-<!-- What actually happens? -->
-
-## Logs
-
-## Screenshot
-
-<!-- Ideally provide a screenshot, gif, video or screen recording. -->
-
-## Notes
-
-<!-- Anything else you want to share -->

.github/ISSUE_TEMPLATE/config.yaml

@@ -1,5 +0,0 @@
-blank_issues_enabled: true
-contact_links:
-  - name: Question?
-    url: https://github.com/coder/coder/discussions/new?category=q-a
-    about: Ask for help on our GitHub Discussions board

.github/ISSUE_TEMPLATE/doc.md

@@ -1,12 +0,0 @@
----
-name: Documentation improvement
-about: Suggest a documentation improvement
-title: "Docs: "
-labels: "documentation :memo:"
----
-
-## What is your suggestion?
-
-## How will this improve the docs?
-
-## Are you interested in submitting a PR for this?

.github/ISSUE_TEMPLATE/external_bug_report.md

@@ -0,0 +1,9 @@
+<!--- 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/ISSUE_TEMPLATE/feature.md

@@ -1,14 +0,0 @@
----
-name: Feature request
-about: Suggest an idea to improve coder
-title: "Feat: "
-labels: "new feature :sparkles:"
----
-
-## What is your suggestion?
-
-## Why do you want this feature?
-
-## Are there any workarounds to get this functionality today?
-
-## Are you interested in submitting a PR for this?

.github/codecov.yml

@@ -0,0 +1,43 @@
+codecov:
+  require_ci_to_pass: false
+  notify:
+    after_n_builds: 5
+
+comment: false
+
+github_checks:
+  annotations: false
+
+coverage:
+  range: 50..75
+  round: down
+  precision: 2
+  status:
+    patch:
+      default:
+        informational: yes
+    project:
+      default:
+        target: 65%
+        informational: true
+
+ignore:
+  # This is generated code.
+  - coderd/database/models.go
+  - coderd/database/queries.sql.go
+  - coderd/database/databasefake
+  # These are generated or don't require tests.
+  - cmd
+  - coderd/tunnel
+  - coderd/database/dump
+  - coderd/database/postgres
+  - peerbroker/proto
+  - provisionerd/proto
+  - provisionersdk/proto
+  - scripts
+  - site/.storybook
+  - rules.go
+  # Packages used for writing tests.
+  - cli/clitest
+  - coderd/coderdtest
+  - pty/ptytest

.github/dependabot.yaml

@@ -3,9 +3,10 @@ updates:
   - package-ecosystem: "github-actions"
     directory: "/"
     schedule:
-      interval: "weekly"
+      interval: "monthly"
       time: "06:00"
       timezone: "America/Chicago"
+    labels: []
     commit-message:
       prefix: "chore"
     ignore:
@@ -27,26 +28,47 @@ updates:
   - package-ecosystem: "gomod"
     directory: "/"
     schedule:
-      interval: "weekly"
+      interval: "monthly"
       time: "06:00"
       timezone: "America/Chicago"
     commit-message:
       prefix: "chore"
+    labels: []
+    ignore:
+      # Ignore patch updates for all dependencies
+      - dependency-name: "*"
+        update-types:
+        - version-update:semver-patch
 
   - package-ecosystem: "npm"
     directory: "/site/"
     schedule:
-      interval: "weekly"
+      interval: "monthly"
       time: "06:00"
       timezone: "America/Chicago"
     commit-message:
       prefix: "chore"
-    labels:
-      - "dependencies"
-      - "typescript/js"
+    labels: []
     ignore:
+      # Ignore patch updates for all dependencies
+      - dependency-name: "*"
+        update-types:
+        - 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"
         update-types:
           - version-update:semver-major
+
+  - package-ecosystem: "terraform"
+    directory: "/examples/templates"
+    schedule:
+      interval: "monthly"
+      time: "06:00"
+      timezone: "America/Chicago"
+    commit-message:
+      prefix: "chore"
+    labels: []
+    ignore:
+      # We likely want to update this ourselves.
+      - dependency-name: "coder/coder"

.github/semantic.yaml

@@ -25,26 +25,22 @@ types:
   # A build of any kind.
   - build
 
-  # A RELEASED fix that will NOT be back-ported. The originating issue may have
-  # been discovered internally or externally to Coder.
-  - fix
-
-  # Any code task that is ignored for changelog purposes. Examples include
-  # devbin scripts and internal-only configurations.
+  # Any code task that operates outside of CI, docs, or the product. Examples
+  # include configurations, linters etc.
   - chore
 
   # Any work performed on CI.
   - ci
-
-  # An UNRELEASED correction. For example, features are often built
-  # incrementally and sometimes introduce minor flaws during a release cycle.
-  # Corrections address those increments and flaws.
-  - correct
+  
+  - example
 
   # Work that directly implements or supports the implementation of a feature.
   - feat
 
-  # A fix for a RELEASED bug (regression fix) that is intended for patch-release
+  # 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
 

.github/stale.yaml

@@ -1,14 +0,0 @@
-# Number of days of inactivity before an issue becomes stale
-daysUntilStale: 14
-# Number of days of inactivity before a stale issue is closed
-daysUntilClose: 5
-# Only apply the stale logic to pulls, since we are using issues to manage work
-only: pulls
-# Label to apply when stale.
-staleLabel: stale
-# Comment to post when marking an issue as stale. Set to `false` to disable
-markComment: >
-  This issue has been automatically marked as stale because it has not had
-  recent activity. It will be closed if no activity occurs in the next 5 days.
-# Comment to post when closing a stale issue. Set to `false` to disable
-closeComment: false

.github/workflows/chromatic.yaml

@@ -1,54 +0,0 @@
-# Note: Chromatic is a separate workflow for coder.yaml as suggested by the
-# chromatic docs. Explicitly, Chromatic works best on 'push' instead of other
-# event types (like pull request), keep in mind that it works build-over-build
-# by storing snapshots.
-#
-# SEE: https://www.chromatic.com/docs/ci
-name: chromatic
-
-# Chromatic works best with push events, not pull_request or other event types.
-on: push
-
-jobs:
-  deploy:
-    # REMARK: this is only used to build storybook and deploy it to Chromatic.
-    runs-on: ubuntu-latest
-
-    steps:
-      - uses: actions/checkout@v3
-        with:
-          # Required by Chromatic for build-over-build history, otherwise we
-          # only get 1 commit on shallow checkout.
-          fetch-depth: 0
-
-      - name: Install dependencies
-        run: cd site && yarn
-
-      # This step is not meant for mainline because any detected changes to
-      # storybook snapshots will require manual approval/review in order for
-      # the check to pass. This is desired in PRs, but not in mainline.
-      - name: Publish to Chromatic (non-mainline)
-        if: github.ref != 'refs/heads/main'
-        uses: chromaui/action@v1
-        with:
-          buildScriptName: "storybook:build"
-          exitOnceUploaded: true
-          # Chromatic states its fine to make this token public. See:
-          # https://www.chromatic.com/docs/github-actions#forked-repositories
-          projectToken: 695c25b6cb65
-          workingDir: "./site"
-
-      # This is a separate step for mainline only that auto accepts and changes
-      # instead of holding CI up. Since we squash/merge, this is defensive to
-      # avoid the same changeset from requiring review once squashed into
-      # main. Chromatic is supposed to be able to detect that we use squash
-      # commits, but it's good to be defensive in case, otherwise CI remains
-      # infinitely "in progress" in mainline unless we re-review each build.
-      - name: Publish to Chromatic (mainline)
-        if: github.ref == 'refs/heads/main'
-        uses: chromaui/action@v1
-        with:
-          autoAcceptChanges: true
-          buildScriptName: "storybook:build"
-          projectToken: 695c25b6cb65
-          workingDir: "./site"

.github/workflows/coder.yaml

@@ -2,6 +2,12 @@ name: coder
 
 on:
   push:
+    branches:
+      - main
+    tags:
+      - "*"
+
+  pull_request:
 
   workflow_dispatch:
 
@@ -24,21 +30,103 @@ concurrency:
   cancel-in-progress: ${{ github.event_name == 'pull_request' }}
 
 jobs:
+  typos:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+      - name: typos-action
+        uses: crate-ci/typos@master
+        with:
+          config: .github/workflows/typos.toml
+      - name: Fix Helper
+        if: ${{ failure() }}
+        run: |
+          echo "::notice:: you can automatically fix typos from your CLI:
+          cargo install typos-cli
+          typos -c .github/workflows/typos.toml -w"
+
+  changes:
+    runs-on: ubuntu-latest
+    outputs:
+      docs-only: ${{ steps.filter.outputs.docs_count == steps.filter.outputs.all_count }}
+      sh: ${{ steps.filter.outputs.sh }}
+      ts: ${{ steps.filter.outputs.ts }}
+      k8s: ${{ steps.filter.outputs.k8s }}
+    steps:
+      - uses: actions/checkout@v3
+      # For pull requests it's not necessary to checkout the code
+      - uses: dorny/paths-filter@v2
+        id: filter
+        with:
+          filters: |
+            all:
+              - '**'
+            docs:
+              - 'docs/**'
+              # For testing:
+              # - '.github/**'
+            sh:
+              - "**.sh"
+            ts:
+              - 'site/**'
+            k8s:
+              - 'helm/**'
+              - Dockerfile
+              - 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.18"
+          go-version: "~1.19"
       - name: golangci-lint
-        uses: golangci/golangci-lint-action@v3.1.0
+        uses: golangci/golangci-lint-action@v3.2.0
         with:
-          version: v1.45.2
+          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
@@ -62,31 +150,95 @@ jobs:
         run: yarn lint
         working-directory: site
 
-  gen:
-    name: "style/gen"
+  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
+    needs: changes
+    if: needs.changes.outputs.docs-only == 'false'
     steps:
       - 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: Install Protoc
         uses: arduino/setup-protoc@v1
         with:
-          version: "3.19.4"
+          version: "3.20.0"
       - uses: actions/setup-go@v3
         with:
-          go-version: "~1.18"
-      - run: curl -sSL
-          https://github.com/kyleconroy/sqlc/releases/download/v1.11.0/sqlc_1.11.0_linux_amd64.tar.gz
-          | sudo tar -C /usr/bin -xz sqlc
+          go-version: "~1.19"
 
-      - run: go install google.golang.org/protobuf/cmd/protoc-gen-go@v1.26
-      - run: go install storj.io/drpc/cmd/protoc-gen-go-drpc@v0.0.26
-      - run: go install golang.org/x/tools/cmd/goimports@latest
-      - run: "make --output-sync -j gen"
-      - run: ./scripts/check_unstaged.sh
+      - 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)"
+
+      - name: Go Build Cache
+        uses: actions/cache@v3
+        with:
+          path: ${{ steps.go-cache-paths.outputs.go-build }}
+          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 }}
+          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
+      - 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: make gen
+        run: "make --output-sync -j -B gen"
+
+      - name: Check for unstaged files
+        run: ./scripts/check_unstaged.sh
 
   style-fmt:
     name: "style/fmt"
     runs-on: ubuntu-latest
+    timeout-minutes: 5
     steps:
       - name: Checkout
         uses: actions/checkout@v3
@@ -108,12 +260,18 @@ jobs:
       - name: Install node_modules
         run: ./scripts/yarn_install.sh
 
-      - name: "make fmt"
-        run: "make --output-sync -j fmt"
+      - name: Install shfmt
+        run: go install mvdan.cc/sh/v3/cmd/shfmt@v3.5.0
+
+      - name: make fmt
+        run: |
+          export PATH=${PATH}:$(go env GOPATH)/bin
+          make --output-sync -j -B fmt
 
   test-go:
     name: "test/go"
     runs-on: ${{ matrix.os }}
+    timeout-minutes: 20
     strategy:
       matrix:
         os:
@@ -125,7 +283,7 @@ jobs:
 
       - uses: actions/setup-go@v3
         with:
-          go-version: "~1.18"
+          go-version: "~1.19"
 
       - name: Echo Go Cache Paths
         id: go-cache-paths
@@ -137,7 +295,7 @@ jobs:
         uses: actions/cache@v3
         with:
           path: ${{ steps.go-cache-paths.outputs.go-build }}
-          key: ${{ runner.os }}-go-build-${{ hashFiles('**/go.sum') }}
+          key: ${{ runner.os }}-go-build-${{ hashFiles('**/go.**', '**.go') }}
 
       - name: Go Mod Cache
         uses: actions/cache@v3
@@ -145,35 +303,41 @@ jobs:
           path: ${{ steps.go-cache-paths.outputs.go-mod }}
           key: ${{ runner.os }}-go-mod-${{ hashFiles('**/go.sum') }}
 
-      - name: Install goreleaser
-        uses: jaxxstorm/action-install-gh-release@v1.4.0
+      - name: Install gotestsum
+        uses: jaxxstorm/action-install-gh-release@v1.7.1
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         with:
           repo: gotestyourself/gotestsum
           tag: v1.7.0
 
-      - uses: hashicorp/setup-terraform@v1
+      - uses: hashicorp/setup-terraform@v2
         with:
-          terraform_version: 1.1.2
+          terraform_version: 1.1.9
           terraform_wrapper: false
 
-      - name: Install socat
-        if: runner.os == 'Linux'
-        run: sudo apt-get install -y socat
-
       - name: Test with Mock Database
+        id: test
         shell: bash
-        env:
-          GOCOUNT: ${{ runner.os == 'Windows' && 1 || 2 }}
-          GOMAXPROCS: ${{ runner.os == 'Windows' && 1 || 2 }}
-        run: gotestsum --junitfile="gotests.xml" --packages="./..." --
-          -covermode=atomic -coverprofile="gotests.coverage"
-          -coverpkg=./...,github.com/coder/coder/codersdk
-          -timeout=3m -count=$GOCOUNT -short -failfast
+        run: |
+          # Code coverage is more computationally expensive and also
+          # prevents test caching, so we disable it on alternate operating
+          # systems.
+          if [ "${{ matrix.os }}" == "ubuntu-latest" ]; then
+            echo ::set-output name=cover::true
+            export COVERAGE_FLAGS='-covermode=atomic -coverprofile="gotests.coverage" -coverpkg=./...'
+          else
+            echo ::set-output name=cover::false
+          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
 
       - name: Upload DataDog Trace
-        if: (success() || failure()) && github.actor != 'dependabot[bot]' && github.repository_owner == 'coder'
+        if: github.actor != 'dependabot[bot]' && !github.event.pull_request.head.repo.fork
         env:
           DATADOG_API_KEY: ${{ secrets.DATADOG_API_KEY }}
           DD_DATABASE: fake
@@ -182,22 +346,31 @@ jobs:
         run: go run scripts/datadog-cireport/main.go gotests.xml
 
       - uses: codecov/codecov-action@v3
-        if: github.actor != 'dependabot[bot]' && github.repository_owner == 'coder'
+        # This action has a tendency to error out unexpectedly, it has
+        # the `fail_ci_if_error` option that defaults to `false`, but
+        # that is no guarantee, see:
+        # https://github.com/codecov/codecov-action/issues/788
+        continue-on-error: true
+        if: steps.test.outputs.cover && github.actor != 'dependabot[bot]' && !github.event.pull_request.head.repo.fork
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
           files: ./gotests.coverage
           flags: unittest-go-${{ matrix.os }}
-          fail_ci_if_error: true
 
   test-go-postgres:
     name: "test/go/postgres"
     runs-on: 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
+    # even if some of the preceding steps are slow.
+    timeout-minutes: 25
     steps:
       - uses: actions/checkout@v3
 
       - uses: actions/setup-go@v3
         with:
-          go-version: "~1.18"
+          go-version: "~1.19"
 
       - name: Echo Go Cache Paths
         id: go-cache-paths
@@ -209,7 +382,7 @@ jobs:
         uses: actions/cache@v3
         with:
           path: ${{ steps.go-cache-paths.outputs.go-build }}
-          key: ${{ runner.os }}-go-build-${{ hashFiles('**/go.sum') }}
+          key: ${{ runner.os }}-go-build-${{ hashFiles('**/go.sum', '**/**.go') }}
 
       - name: Go Mod Cache
         uses: actions/cache@v3
@@ -217,49 +390,24 @@ jobs:
           path: ${{ steps.go-cache-paths.outputs.go-mod }}
           key: ${{ runner.os }}-go-mod-${{ hashFiles('**/go.sum') }}
 
-      - name: Install goreleaser
-        uses: jaxxstorm/action-install-gh-release@v1.4.0
+      - name: Install gotestsum
+        uses: jaxxstorm/action-install-gh-release@v1.7.1
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         with:
           repo: gotestyourself/gotestsum
           tag: v1.7.0
 
-      - uses: hashicorp/setup-terraform@v1
+      - uses: hashicorp/setup-terraform@v2
         with:
-          terraform_version: 1.1.2
+          terraform_version: 1.1.9
           terraform_wrapper: false
 
-      - name: Start PostgreSQL Database
-        env:
-          POSTGRES_PASSWORD: postgres
-          POSTGRES_USER: postgres
-          POSTGRES_DB: postgres
-          PGDATA: /tmp
-        run: |
-          docker run \
-            -e POSTGRES_PASSWORD=postgres \
-            -e POSTGRES_USER=postgres \
-            -e POSTGRES_DB=postgres \
-            -e PGDATA=/tmp \
-            -p 5432:5432 \
-            -d postgres:11 \
-            -c shared_buffers=1GB \
-            -c max_connections=1000
-          while ! pg_isready -h 127.0.0.1
-          do
-              echo "$(date) - waiting for database to start"
-              sleep 0.5
-          done
-
       - name: Test with PostgreSQL Database
-        run: DB=ci gotestsum --junitfile="gotests.xml" --packages="./..." --
-          -covermode=atomic -coverprofile="gotests.coverage" -timeout=3m
-          -coverpkg=./...,github.com/coder/coder/codersdk
-          -count=1 -parallel=2 -race -failfast
+        run: make test-postgres
 
       - name: Upload DataDog Trace
-        if: (success() || failure()) && github.actor != 'dependabot[bot]' && github.repository_owner == 'coder'
+        if: always() && github.actor != 'dependabot[bot]' && !github.event.pull_request.head.repo.fork
         env:
           DATADOG_API_KEY: ${{ secrets.DATADOG_API_KEY }}
           DD_DATABASE: postgresql
@@ -267,22 +415,32 @@ jobs:
         run: go run scripts/datadog-cireport/main.go gotests.xml
 
       - uses: codecov/codecov-action@v3
-        if: github.actor != 'dependabot[bot]' && github.repository_owner == 'coder'
+        # This action has a tendency to error out unexpectedly, it has
+        # the `fail_ci_if_error` option that defaults to `false`, but
+        # that is no guarantee, see:
+        # https://github.com/codecov/codecov-action/issues/788
+        continue-on-error: true
+        if: github.actor != 'dependabot[bot]' && !github.event.pull_request.head.repo.fork
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
           files: ./gotests.coverage
           flags: unittest-go-postgres-${{ matrix.os }}
-          fail_ci_if_error: true
 
   deploy:
     name: "deploy"
     runs-on: ubuntu-latest
-    if: github.ref == 'refs/heads/main' && github.repository_owner == 'coder'
+    timeout-minutes: 30
+    needs: changes
+    if: |
+      github.ref == 'refs/heads/main' && !github.event.pull_request.head.repo.fork
+      && needs.changes.outputs.docs-only == 'false'
     permissions:
       contents: read
       id-token: write
     steps:
       - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
 
       - name: Authenticate to Google Cloud
         uses: google-github-actions/auth@v0
@@ -295,7 +453,7 @@ jobs:
 
       - uses: actions/setup-go@v3
         with:
-          go-version: "~1.18"
+          go-version: "~1.19"
 
       - name: Echo Go Cache Paths
         id: go-cache-paths
@@ -315,10 +473,6 @@ jobs:
           path: ${{ steps.go-cache-paths.outputs.go-mod }}
           key: ${{ runner.os }}-release-go-mod-${{ hashFiles('**/go.sum') }}
 
-      - uses: goreleaser/goreleaser-action@v2
-        with:
-          install-only: true
-
       - name: Cache Node
         id: cache-node
         uses: actions/cache@v3
@@ -326,17 +480,39 @@ jobs:
           path: |
             **/node_modules
             .eslintcache
-          key: js-${{ runner.os }}-test-${{ hashFiles('**/yarn.lock') }}
+          key: js-${{ runner.os }}-release-node-${{ hashFiles('**/yarn.lock') }}
           restore-keys: |
             js-${{ runner.os }}-
 
-      - name: Build Release
-        run: make release
+      - name: Install nfpm
+        run: go install github.com/goreleaser/nfpm/v2/cmd/nfpm@v2.16.0
 
-      - uses: actions/upload-artifact@v3
-        with:
-          name: coder_linux_amd64.deb
-          path: ./dist/coder_*_linux_amd64.deb
+      - name: Install zstd
+        run: sudo apt-get install -y zstd
+
+      - name: Build site
+        run: make -B site/out/index.html
+
+      - name: Build Release
+        run: |
+          set -euo pipefail
+          go mod download
+
+          mkdir -p ./dist
+          # build slim binaries
+          ./scripts/build_go_slim.sh \
+            --output ./dist/ \
+            --compress 22 \
+            linux:amd64,armv7,arm64 \
+            windows:amd64,arm64 \
+            darwin:amd64,arm64
+
+          # build linux amd64 packages
+          ./scripts/build_go_matrix.sh \
+            --output ./dist/ \
+            --package-linux \
+            linux:amd64 \
+            windows:amd64
 
       - name: Install Release
         run: |
@@ -349,9 +525,22 @@ jobs:
       - name: Start
         run: gcloud compute ssh coder -- sudo service coder restart
 
+      - uses: actions/upload-artifact@v3
+        with:
+          name: coder
+          path: |
+            ./dist/*.zip
+            ./dist/*.exe
+            ./dist/*.tar.gz
+            ./dist/*.apk
+            ./dist/*.deb
+            ./dist/*.rpm
+          retention-days: 7
+
   test-js:
     name: "test/js"
     runs-on: ubuntu-latest
+    timeout-minutes: 20
     steps:
       - uses: actions/checkout@v3
 
@@ -369,7 +558,7 @@ jobs:
       # Go is required for uploading the test results to datadog
       - uses: actions/setup-go@v3
         with:
-          go-version: "~1.18"
+          go-version: "~1.19"
 
       - uses: actions/setup-node@v3
         with:
@@ -378,23 +567,23 @@ jobs:
       - name: Install node_modules
         run: ./scripts/yarn_install.sh
 
-      - name: Build frontend
-        run: yarn build
-        working-directory: site
-
       - run: yarn test:coverage
         working-directory: site
 
       - uses: codecov/codecov-action@v3
-        if: github.actor != 'dependabot[bot]' && github.repository_owner == 'coder'
+        # This action has a tendency to error out unexpectedly, it has
+        # the `fail_ci_if_error` option that defaults to `false`, but
+        # that is no guarantee, see:
+        # https://github.com/codecov/codecov-action/issues/788
+        continue-on-error: true
+        if: github.actor != 'dependabot[bot]' && !github.event.pull_request.head.repo.fork
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
           files: ./site/coverage/lcov.info
           flags: unittest-js
-          fail_ci_if_error: true
 
       - name: Upload DataDog Trace
-        if: (success() || failure()) && github.actor != 'dependabot[bot]' && github.repository_owner == 'coder'
+        if: always() && github.actor != 'dependabot[bot]' && !github.event.pull_request.head.repo.fork
         env:
           DATADOG_API_KEY: ${{ secrets.DATADOG_API_KEY }}
           DD_CATEGORY: unit
@@ -403,7 +592,11 @@ jobs:
 
   test-e2e:
     name: "test/e2e/${{ matrix.os }}"
+    needs:
+      - changes
+    if: needs.changes.outputs.docs-only == 'false'
     runs-on: ${{ matrix.os }}
+    timeout-minutes: 20
     strategy:
       matrix:
         os:
@@ -418,28 +611,22 @@ jobs:
           path: |
             **/node_modules
             .eslintcache
-          key: js-${{ runner.os }}-test-${{ hashFiles('**/yarn.lock') }}
-          restore-keys: |
-            js-${{ runner.os }}-
+          key: js-${{ runner.os }}-e2e-${{ hashFiles('**/yarn.lock') }}
 
       # Go is required for uploading the test results to datadog
       - uses: actions/setup-go@v3
         with:
-          go-version: "~1.18"
+          go-version: "~1.19"
 
-      - uses: hashicorp/setup-terraform@v1
+      - uses: hashicorp/setup-terraform@v2
         with:
-          terraform_version: 1.1.2
+          terraform_version: 1.1.9
           terraform_wrapper: false
 
       - uses: actions/setup-node@v3
         with:
           node-version: "14"
 
-      - uses: goreleaser/goreleaser-action@v2
-        with:
-          install-only: true
-
       - name: Echo Go Cache Paths
         id: go-cache-paths
         run: |
@@ -460,7 +647,8 @@ jobs:
 
       - name: Build
         run: |
-          make site/out
+          sudo npm install -g prettier
+          make -B site/out/index.html
 
       - run: yarn playwright:install
         working-directory: site
@@ -473,10 +661,62 @@ jobs:
           DEBUG: pw:api
         working-directory: site
 
+      - name: Upload Playwright Failed Tests
+        if: always() && github.actor != 'dependabot[bot]' && runner.os == 'Linux' && !github.event.pull_request.head.repo.fork
+        uses: actions/upload-artifact@v3
+        with:
+          name: failed-test-videos
+          path: ./site/test-results/**/*.webm
+          retention:days: 7
+
       - name: Upload DataDog Trace
-        if: (success() || failure()) && github.actor != 'dependabot[bot]' && runner.os == 'Linux' && github.repository_owner == 'coder'
+        if: always() && github.actor != 'dependabot[bot]' && runner.os == 'Linux' && !github.event.pull_request.head.repo.fork
         env:
           DATADOG_API_KEY: ${{ secrets.DATADOG_API_KEY }}
           DD_CATEGORY: e2e
           GIT_COMMIT_MESSAGE: ${{ github.event.head_commit.message }}
         run: go run scripts/datadog-cireport/main.go site/test-results/junit.xml
+  chromatic:
+    # REMARK: this is only used to build storybook and deploy it to Chromatic.
+    runs-on: ubuntu-latest
+    needs:
+      - changes
+    if: needs.changes.outputs.ts == 'true'
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          # Required by Chromatic for build-over-build history, otherwise we
+          # only get 1 commit on shallow checkout.
+          fetch-depth: 0
+
+      - name: Install dependencies
+        run: cd site && yarn
+
+      # This step is not meant for mainline because any detected changes to
+      # storybook snapshots will require manual approval/review in order for
+      # the check to pass. This is desired in PRs, but not in mainline.
+      - name: Publish to Chromatic (non-mainline)
+        if: github.ref != 'refs/heads/main' && github.repository_owner == 'coder'
+        uses: chromaui/action@v1
+        with:
+          buildScriptName: "storybook:build"
+          exitOnceUploaded: true
+          # Chromatic states its fine to make this token public. See:
+          # https://www.chromatic.com/docs/github-actions#forked-repositories
+          projectToken: 695c25b6cb65
+          workingDir: "./site"
+
+      # This is a separate step for mainline only that auto accepts and changes
+      # instead of holding CI up. Since we squash/merge, this is defensive to
+      # avoid the same changeset from requiring review once squashed into
+      # main. Chromatic is supposed to be able to detect that we use squash
+      # commits, but it's good to be defensive in case, otherwise CI remains
+      # infinitely "in progress" in mainline unless we re-review each build.
+      - name: Publish to Chromatic (mainline)
+        if: github.ref == 'refs/heads/main' && github.repository_owner == 'coder'
+        uses: chromaui/action@v1
+        with:
+          autoAcceptChanges: true
+          buildScriptName: "storybook:build"
+          projectToken: 695c25b6cb65
+          workingDir: "./site"

.github/workflows/dogfood.yaml

@@ -0,0 +1,51 @@
+name: dogfood
+
+on:
+  push:
+    branches:
+      - main
+    tags:
+      - "*"
+    paths:
+      - "dogfood/**"
+  pull_request:
+    paths:
+      - "dogfood/**"
+  workflow_dispatch:
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Get branch name
+        id: branch-name
+        uses: tj-actions/branch-names@v5.4
+
+      - name: "Branch name to Docker tag name"
+        id: docker-tag-name
+        run: |
+          tag=${{ steps.branch-name.outputs.current_branch }}
+          # Replace / with --, e.g. user/feature => user--feature.
+          tag=${tag//\//--}
+          echo "::set-output name=tag::${tag}"
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v2
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v2
+
+      - name: Login to DockerHub
+        uses: docker/login-action@v2
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_PASSWORD }}
+
+      - name: Build and push
+        uses: docker/build-push-action@v3
+        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

.github/workflows/release.yaml

@@ -1,37 +1,59 @@
+# GitHub release workflow.
+#
+# This workflow is a bit complicated because we have to build darwin binaries on
+# a mac runner, but the mac runners are extremely slow. So instead of running
+# the entire release on a mac (which will take an hour to run), we run only the
+# mac build on a mac, and the rest on a linux runner. The final release is then
+# published using a final linux runner.
 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.
+        type: boolean
+        required: true
+
+env:
+  CODER_RELEASE: ${{ github.event.inputs.snapshot && 'false' || 'true' }}
+
 jobs:
-  goreleaser:
+  linux-windows:
     runs-on: ubuntu-latest
+    env:
+      # Necessary for Docker manifest
+      DOCKER_CLI_EXPERIMENTAL: "enabled"
     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: Docker Login
+        uses: docker/login-action@v2
+        with:
+          registry: ghcr.io
+          username: ${{ github.repository_owner }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
       - uses: actions/setup-go@v3
         with:
           go-version: "~1.18"
 
-      - 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)"
-
-      - name: Go Build Cache
-        uses: actions/cache@v3
-        with:
-          path: ${{ steps.go-cache-paths.outputs.go-build }}
-          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 }}
-          key: ${{ runner.os }}-release-go-mod-${{ hashFiles('**/go.sum') }}
-
       - name: Cache Node
         id: cache-node
         uses: actions/cache@v3
@@ -43,13 +65,231 @@ jobs:
           restore-keys: |
             js-${{ runner.os }}-
 
-      - name: Build Site
-        run: make site/out
+      - name: Install nfpm
+        run: go install github.com/goreleaser/nfpm/v2/cmd/nfpm@v2.16.0
 
-      - name: Run GoReleaser
-        uses: goreleaser/goreleaser-action@v2.9.1
+      - name: Install zstd
+        run: sudo apt-get install -y zstd
+
+      - name: Build Site
+        run: make site/out/index.html
+
+      - name: Build Linux and Windows Binaries
+        run: |
+          set -euo pipefail
+          go mod download
+
+          mkdir -p ./dist
+          # build slim binaries
+          ./scripts/build_go_slim.sh \
+            --output ./dist/ \
+            --compress 22 \
+            linux:amd64,armv7,arm64 \
+            windows:amd64,arm64 \
+            darwin:amd64,arm64
+
+          # build linux and windows binaries
+          ./scripts/build_go_matrix.sh \
+            --output ./dist/ \
+            --archive \
+            --package-linux \
+            linux:amd64,armv7,arm64 \
+            windows:amd64,arm64
+
+      - name: Build Linux Docker images
+        run: |
+          set -euxo pipefail
+
+          # build and (maybe) push Docker images for each architecture
+          images=()
+          for arch in amd64 armv7 arm64; do
+            img="$(
+              ./scripts/build_docker.sh \
+                ${{ (!github.event.inputs.dry_run && !github.event.inputs.snapshot) && '--push' || '' }} \
+                --arch "$arch" \
+                ./dist/coder_*_linux_"$arch"
+            )"
+            images+=("$img")
+          done
+
+          # we can't build multi-arch if the images aren't pushed, so quit now
+          # if dry-running
+          if [[ "$CODER_RELEASE" != *t* ]]; then
+            echo Skipping multi-arch docker builds due to dry-run.
+            exit 0
+          fi
+
+          # build and push multi-arch manifest
+          ./scripts/build_docker_multiarch.sh \
+            --push \
+            "${images[@]}"
+
+          # if the current version is equal to the highest (according to semver)
+          # version in the repo, also create a multi-arch image as ":latest" and
+          # push it
+          if [[ "$(git tag | grep '^v' | grep -vE '(rc|dev|-|\+|\/)' | sort -r --version-sort | head -n1)" == "v$(./scripts/version.sh)" ]]; then
+            ./scripts/build_docker_multiarch.sh \
+              --push \
+              --target "$(./scripts/image_tag.sh --version latest)" \
+              "${images[@]}"
+          fi
+
+      - name: Upload binary artifacts
+        uses: actions/upload-artifact@v3
         with:
-          version: latest
-          args: release --rm-dist
+          name: linux
+          path: |
+            dist/*.zip
+            dist/*.tar.gz
+            dist/*.apk
+            dist/*.deb
+            dist/*.rpm
+
+  # The mac binaries get built on mac runners because they need to be signed,
+  # and the signing tool only runs on mac. This darwin job only builds the Mac
+  # binaries and uploads them as job artifacts used by the publish step.
+  darwin:
+    runs-on: macos-latest
+    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
+
+      - uses: actions/setup-go@v3
+        with:
+          go-version: "~1.18"
+
+      - name: Import Signing Certificates
+        uses: Apple-Actions/import-codesign-certs@v1
+        with:
+          p12-file-base64: ${{ secrets.AC_CERTIFICATE_P12_BASE64 }}
+          p12-password: ${{ secrets.AC_CERTIFICATE_PASSWORD }}
+
+      - 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 dependencies
+        run: |
+          set -euo pipefail
+          # The version of bash that macOS ships with is too old
+          brew install bash
+
+          # The version of make that macOS ships with is too old
+          brew install make
+          echo "$(brew --prefix)/opt/make/libexec/gnubin" >> $GITHUB_PATH
+
+          # BSD getopt is incompatible with the build scripts
+          brew install gnu-getopt
+          echo "$(brew --prefix)/opt/gnu-getopt/bin" >> $GITHUB_PATH
+
+          # Used for notarizing the binaries
+          brew tap mitchellh/gon
+          brew install mitchellh/gon/gon
+
+          # Used for compressing embedded slim binaries
+          brew install zstd
+
+      - name: Build Site
+        run: make site/out/index.html
+
+      - name: Build darwin Binaries (with signatures)
+        run: |
+          set -euo pipefail
+          go mod download
+
+          mkdir -p ./dist
+          # build slim binaries
+          ./scripts/build_go_slim.sh \
+            --output ./dist/ \
+            --compress 22 \
+            linux:amd64,armv7,arm64 \
+            windows:amd64,arm64 \
+            darwin:amd64,arm64
+
+          # build darwin binaries
+          ./scripts/build_go_matrix.sh \
+            --output ./dist/ \
+            --archive \
+            --sign-darwin \
+            darwin:amd64,arm64
+        env:
+          AC_USERNAME: ${{ secrets.AC_USERNAME }}
+          AC_PASSWORD: ${{ secrets.AC_PASSWORD }}
+          AC_APPLICATION_IDENTITY: BDB050EB749EDD6A80C6F119BF1382ECA119CCCC
+
+      - name: Upload Binary Artifacts
+        uses: actions/upload-artifact@v3
+        with:
+          name: darwin
+          path: ./dist/coder_*.zip
+
+  publish:
+    runs-on: ubuntu-latest
+    needs:
+      - linux-windows
+      - darwin
+    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: mkdir artifacts
+        run: mkdir artifacts
+
+      - name: Download darwin Artifacts
+        uses: actions/download-artifact@v3
+        with:
+          name: darwin
+          path: artifacts
+
+      - name: Download Linux and Windows Artifacts
+        uses: actions/download-artifact@v3
+        with:
+          name: linux
+          path: artifacts
+
+      - name: ls artifacts
+        run: ls artifacts
+
+      - name: Publish Helm
+        run: |
+          set -euxo pipefail
+          ./scripts/helm.sh --push
+          mv ./dist/*.tgz ./artifacts/
+
+      - name: Publish Release
+        run: |
+          ./scripts/publish_release.sh \
+            ${{ (github.event.inputs.dry_run || github.event.inputs.snapshot) && '--dry-run' }} \
+            ./artifacts/*.zip \
+            ./artifacts/*.tar.gz \
+            ./artifacts/*.tgz \
+            ./artifacts/*.apk \
+            ./artifacts/*.deb \
+            ./artifacts/*.rpm
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/stale.yaml

@@ -0,0 +1,35 @@
+name: Stale Issue Cron
+on:
+  schedule:
+    # Every day at midnight
+    - cron: "0 0 * * *"
+  workflow_dispatch:
+jobs:
+  stale:
+    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@v5.0.0
+        with:
+          stale-issue-label: stale
+          stale-pr-label: stale
+          # 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, 
+            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 
+            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

.github/workflows/typos.toml

@@ -0,0 +1,19 @@
+[default.extend-identifiers]
+alog = "alog"
+Jetbrains = "JetBrains"
+IST = "IST"
+MacOS = "macOS"
+
+[default.extend-words]
+
+[files]
+extend-exclude = [
+    "**.svg",
+    "**.png",
+    "**.lock",
+    "go.sum",
+    "go.mod",
+    # These files contain base64 strings that confuse the detector
+    "**XService**.ts",
+    "**identity.go",
+]

.gitignore

@@ -13,7 +13,9 @@ node_modules
 vendor
 .eslintcache
 yarn-error.log
+gotests.coverage
 .idea
+.DS_Store
 
 # Front-end ignore
 .next/
@@ -32,6 +34,11 @@ dist/
 site/out/
 
 *.tfstate
+*.tfstate.backup
 *.tfplan
 *.lock.hcl
 .terraform/
+
+.vscode/*.log
+**/*.swp
+.coderv2/*

.golangci.yaml

@@ -77,7 +77,7 @@ linters-settings:
       # - sloppyReassign
       - sloppyTypeAssert
       - sortSlice
-      # - sprintfQuotedString
+      - sprintfQuotedString
       - sqlQuery
       # - stringConcatSimplify
       # - stringXbytes
@@ -103,7 +103,14 @@ linters-settings:
     settings:
       ruleguard:
         failOn: all
-        rules: rules.go
+        rules: '${configDir}/scripts/rules.go'
+
+  staticcheck:
+    # https://staticcheck.io/docs/options#checks
+    # We disable SA1019 because it gets angry about our usage of xerrors. We
+    # intentionally xerrors because stack frame support didn't make it into the
+    # stdlib port.
+    checks: ["all", "-SA1019"]
 
   goimports:
     local-prefixes: coder.com,cdr.dev,go.coder.com,github.com/cdr,github.com/coder
@@ -194,6 +201,8 @@ run:
   concurrency: 4
   skip-dirs:
     - node_modules
+  skip-files:
+    - scripts/rules.go
   timeout: 5m
 
 # Over time, add more and more linters from
@@ -235,7 +244,7 @@ linters:
     # without testing any exported functions. This is enabled to promote
     # decomposing a package before testing it's internals. A function caller
     # should be able to test most of the functionality from exported functions.
-    # 
+    #
     # There are edge-cases to this rule, but they should be carefully considered
     # to avoid structural inconsistency.
     - testpackage

.goreleaser.yaml

@@ -1,64 +0,0 @@
-archives:
-  - id: coder
-    builds:
-      - coder
-    files:
-      - src: docs/README.md
-        dst: README.md
-    format_overrides:
-      - goos: windows
-        format: zip
-
-before:
-  hooks:
-    - go mod tidy
-    - rm -f site/out/bin/coder*
-
-builds:
-  - id: coder-slim
-    dir: cmd/coder
-    ldflags: ["-s -w -X github.com/coder/coder/cli/buildinfo.tag={{ .Version }}"]
-    env: [CGO_ENABLED=0]
-    goos: [darwin, linux, windows]
-    goarch: [amd64]
-    hooks:
-      # The "trimprefix" appends ".exe" on Windows.
-      post: |
-        cp {{.Path}} site/out/bin/coder-{{ .Os }}-{{ .Arch }}{{ trimprefix .Name "coder" }}
-
-  - id: coder
-    dir: cmd/coder
-    flags: [-tags=embed]
-    ldflags: ["-s -w -X github.com/coder/coder/cli/buildinfo.tag={{ .Version }}"]
-    env: [CGO_ENABLED=0]
-    goos: [darwin, linux, windows]
-    goarch: [amd64, arm64]
-
-nfpms:
-  - id: packages
-    vendor: Coder
-    homepage: https://coder.com
-    maintainer: Coder <support@coder.com>
-    description: |
-      Provision development environments with infrastructure with code
-    formats:
-      - apk
-      - deb
-      - rpm
-    suggests:
-      - postgresql
-    builds:
-      - coder
-    bindir: /usr/bin
-    contents:
-      - src: coder.env
-        dst: /etc/coder.d/coder.env
-        type: "config|noreplace"
-      - src: coder.service
-        dst: /usr/lib/systemd/system/coder.service
-
-release:
-  ids: [coder, packages]
-
-snapshot:
-  name_template: '{{ .Version }}-devel+{{ .ShortCommit }}'

.vscode/extensions.json

@@ -7,6 +7,8 @@
     "emeraldwalk.runonsave",
     "zxh404.vscode-proto3",
     "redhat.vscode-yaml",
-    "streetsidesoftware.code-spell-checker"
+    "streetsidesoftware.code-spell-checker",
+    "dbaeumer.vscode-eslint",
+    "EditorConfig.EditorConfig"
   ]
 }

.vscode/settings.json

@@ -1,10 +1,18 @@
 {
   "cSpell.words": [
+    "apps",
+    "awsidentity",
+    "bodyclose",
+    "buildinfo",
+    "buildname",
+    "circbuf",
     "cliflag",
     "cliui",
     "coderd",
     "coderdtest",
     "codersdk",
+    "cronstrue",
+    "databasefake",
     "devel",
     "drpc",
     "drpcconn",
@@ -12,32 +20,43 @@
     "drpcserver",
     "Dsts",
     "fatih",
+    "Formik",
+    "gitsshkey",
     "goarch",
     "gographviz",
     "goleak",
     "gossh",
+    "gsyslog",
     "hashicorp",
     "hclsyntax",
+    "httpapi",
     "httpmw",
     "idtoken",
     "Iflag",
     "incpatch",
     "isatty",
     "Jobf",
+    "Keygen",
     "kirsle",
+    "Kubernetes",
     "ldflags",
     "manifoldco",
+    "mapstructure",
     "mattn",
     "mitchellh",
     "moby",
+    "namesgenerator",
     "nfpms",
     "nhooyr",
     "nolint",
     "nosec",
     "ntqry",
+    "OIDC",
     "oneof",
+    "paralleltest",
     "parameterscopeid",
     "pqtype",
+    "prometheusmetrics",
     "promptui",
     "protobuf",
     "provisionerd",
@@ -45,18 +64,41 @@
     "ptty",
     "ptytest",
     "retrier",
+    "rpty",
     "sdkproto",
+    "sdktrace",
+    "Signup",
+    "sourcemapped",
+    "Srcs",
     "stretchr",
     "TCGETS",
     "tcpip",
     "TCSETS",
+    "templateversions",
+    "testdata",
+    "testid",
+    "testutil",
     "tfexec",
+    "tfjson",
+    "tfplan",
     "tfstate",
+    "tparallel",
     "trimprefix",
+    "turnconn",
+    "typegen",
     "unconvert",
     "Untar",
+    "VMID",
+    "weblinks",
     "webrtc",
+    "workspaceagent",
+    "workspaceapp",
+    "workspaceapps",
+    "workspacebuilds",
+    "workspacename",
+    "wsconncache",
     "xerrors",
+    "xstate",
     "yamux"
   ],
   "emeraldwalk.runonsave": {
@@ -64,6 +106,10 @@
       {
         "match": "database/queries/*.sql",
         "cmd": "make gen"
+      },
+      {
+        "match": "provisionerd/proto/provisionerd.proto",
+        "cmd": "make provisionerd/proto/provisionerd.pb.go"
       }
     ]
   },
@@ -79,7 +125,9 @@
   "go.coverOnSave": true,
   // The codersdk is used by coderd another other packages extensively.
   // To reduce redundancy in tests, it's covered by other packages.
-  "go.testFlags": ["-short", "-coverpkg=./.,github.com/coder/coder/codersdk"],
+  // Since package coverage pairing can't be defined, all packages cover
+  // all other packages.
+  "go.testFlags": ["-short", "-coverpkg=./..."],
   "go.coverageDecorator": {
     "type": "gutter",
     "coveredHighlightColor": "rgba(64,128,128,0.5)",
@@ -91,5 +139,5 @@
   },
   // 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"
 }

Dockerfile

@@ -0,0 +1,30 @@
+# This is the multi-arch Dockerfile used for Coder. Since it's multi-arch and
+# cross-compiled, it cannot have ANY "RUN" commands. All binaries are built
+# using the go toolchain on the host and then copied into the build context by
+# scripts/build_docker.sh.
+FROM alpine:latest
+
+# LABEL doesn't add any real layers so it's fine (and easier) to do it here than
+# in the build script.
+ARG CODER_VERSION
+LABEL \
+	org.opencontainers.image.title="Coder" \
+	org.opencontainers.image.description="A tool for provisioning self-hosted development environments with Terraform." \
+	org.opencontainers.image.url="https://github.com/coder/coder" \
+	org.opencontainers.image.source="https://github.com/coder/coder" \
+	org.opencontainers.image.version="$CODER_VERSION" \
+	org.opencontainers.image.licenses="AGPL-3.0"
+
+# The coder binary is injected by scripts/build_docker.sh.
+COPY --chown=coder:coder --chmod=755 coder /opt/coder
+
+# Create coder group and user. We cannot use `addgroup` and `adduser` because
+# they won't work if we're building the image for a different architecture.
+COPY --chown=root:root --chmod=644 group passwd /etc/
+COPY --chown=coder:coder --chmod=700 empty-dir /home/coder
+
+USER coder:coder
+ENV HOME=/home/coder
+WORKDIR /home/coder
+
+ENTRYPOINT [ "/opt/coder", "server" ]

LICENSE.enterprise

@@ -0,0 +1,9 @@
+LICENSE (GNU Affero General Public License) applies to
+all files in this repository, except for those in or under
+any directory named "enterprise", which are Copyright Coder
+Technologies, Inc., All Rights Reserved.
+
+We plan to release an enterprise license covering these files
+as soon as possible.  Watch this space.
+
+

Makefile

@@ -1,105 +1,206 @@
+.DEFAULT_GOAL := build
+
+# Use a single bash shell for each job, and immediately exit on failure
+SHELL := bash
+.SHELLFLAGS = -ceu
+.ONESHELL:
+
+# This doesn't work on directories.
+# See https://stackoverflow.com/questions/25752543/make-delete-on-error-for-directory-targets
+.DELETE_ON_ERROR:
+
 INSTALL_DIR=$(shell go env GOPATH)/bin
 GOOS=$(shell go env GOOS)
 GOARCH=$(shell go env GOARCH)
+VERSION=$(shell ./scripts/version.sh)
 
-bin:
-	goreleaser build --snapshot --rm-dist
+bin: $(shell find . -not -path './vendor/*' -type f -name '*.go') go.mod go.sum $(shell find ./examples/templates)
+	@echo "== This builds slim binaries for command-line usage."
+	@echo "== Use \"make build\" to embed the site."
+
+	mkdir -p ./dist
+	rm -rf ./dist/coder-slim_*
+	rm -f ./site/out/bin/coder*
+	./scripts/build_go_slim.sh \
+		--compress 6 \
+		--version "$(VERSION)" \
+		--output ./dist/ \
+		linux:amd64,armv7,arm64 \
+		windows:amd64,arm64 \
+		darwin:amd64,arm64
 .PHONY: bin
 
-build: site/out bin
+build: site/out/index.html $(shell find . -not -path './vendor/*' -type f -name '*.go') go.mod go.sum $(shell find ./examples/templates)
+	rm -rf ./dist
+	mkdir -p ./dist
+	rm -f ./site/out/bin/coder*
+
+	# build slim artifacts and copy them to the site output directory
+	./scripts/build_go_slim.sh \
+		--version "$(VERSION)" \
+		--compress 6 \
+		--output ./dist/ \
+		linux:amd64,armv7,arm64 \
+		windows:amd64,arm64 \
+		darwin:amd64,arm64
+
+	# build not-so-slim artifacts with the default name format
+	./scripts/build_go_matrix.sh \
+		--version "$(VERSION)" \
+		--output ./dist/ \
+		--archive \
+		--package-linux \
+		linux:amd64,armv7,arm64 \
+		windows:amd64,arm64 \
+		darwin:amd64,arm64
 .PHONY: build
 
 # Runs migrations to output a dump of the database.
-coderd/database/dump.sql: $(wildcard coderd/database/migrations/*.sql)
+coderd/database/dump.sql: coderd/database/dump/main.go $(wildcard coderd/database/migrations/*.sql)
 	go run coderd/database/dump/main.go
-.PHONY: coderd/database/dump.sql
 
 # Generates Go code for querying the database.
-coderd/database/generate: fmt/sql coderd/database/dump.sql $(wildcard coderd/database/queries/*.sql)
+coderd/database/querier.go: coderd/database/sqlc.yaml coderd/database/dump.sql $(wildcard coderd/database/queries/*.sql)
 	coderd/database/generate.sh
-.PHONY: coderd/database/generate
 
 fmt/prettier:
 	@echo "--- prettier"
+	cd site
 # Avoid writing files in CI to reduce file write activity
 ifdef CI
-	cd site && yarn run format:check
+	yarn run format:check
 else
-	cd site && yarn run format:write
+	yarn run format:write
 endif
 .PHONY: fmt/prettier
 
-fmt/sql: $(wildcard coderd/database/queries/*.sql)
-	# TODO: this is slightly slow
-	for fi in coderd/database/queries/*.sql; do \
-		npx sql-formatter \
-			--language postgresql \
-			--lines-between-queries 2 \
-			--tab-indent \
-			$$fi \
-			--output $$fi; \
-	done
-
-	sed -i 's/@ /@/g' ./coderd/database/queries/*.sql
-
 fmt/terraform: $(wildcard *.tf)
 	terraform fmt -recursive
+.PHONY: fmt/terraform
 
-fmt: fmt/prettier fmt/sql fmt/terraform
+fmt/shfmt: $(shell shfmt -f .)
+	@echo "--- shfmt"
+# Only do diff check in CI, errors on diff.
+ifdef CI
+	shfmt -d $(shell shfmt -f .)
+else
+	shfmt -w $(shell shfmt -f .)
+endif
+.PHONY: fmt/shfmt
+
+fmt: fmt/prettier fmt/terraform fmt/shfmt
 .PHONY: fmt
 
-gen: coderd/database/generate peerbroker/proto provisionersdk/proto provisionerd/proto
+gen: coderd/database/querier.go peerbroker/proto/peerbroker.pb.go provisionersdk/proto/provisioner.pb.go provisionerd/proto/provisionerd.pb.go site/src/api/typesGenerated.ts
 .PHONY: gen
 
-install: bin
-	@echo "--- Copying from bin to $(INSTALL_DIR)"
-	cp -r ./dist/coder_$(GOOS)_$(GOARCH)/* $(INSTALL_DIR)
-	@echo "-- CLI available at $(shell ls $(INSTALL_DIR)/coder*)"
+install: site/out/index.html $(shell find . -not -path './vendor/*' -type f -name '*.go') go.mod go.sum $(shell find ./examples/templates)
+	@output_file="$(INSTALL_DIR)/coder"
+
+	@if [[ "$(GOOS)" == "windows" ]]; then
+		@output_file="$${output_file}.exe"
+	@fi
+
+	@echo "-- Building CLI for $(GOOS) $(GOARCH) at $$output_file"
+
+	./scripts/build_go.sh \
+		--version "$(VERSION)" \
+		--output "$$output_file" \
+		--os "$(GOOS)" \
+		--arch "$(GOARCH)"
+
+	@echo
 .PHONY: install
 
-lint:
-	golangci-lint run
+lint: lint/shellcheck lint/go
 .PHONY: lint
 
-peerbroker/proto: peerbroker/proto/peerbroker.proto
+lint/go:
+	./scripts/check_enterprise_imports.sh
+	golangci-lint run
+.PHONY: lint/go
+
+# Use shfmt to determine the shell files, takes editorconfig into consideration.
+lint/shellcheck: $(shell shfmt -f .)
+	@echo "--- shellcheck"
+	shellcheck --external-sources $(shell shfmt -f .)
+.PHONY: lint/shellcheck
+
+peerbroker/proto/peerbroker.pb.go: peerbroker/proto/peerbroker.proto
 	protoc \
 		--go_out=. \
 		--go_opt=paths=source_relative \
 		--go-drpc_out=. \
 		--go-drpc_opt=paths=source_relative \
 		./peerbroker/proto/peerbroker.proto
-.PHONY: peerbroker/proto
 
-provisionerd/proto: provisionerd/proto/provisionerd.proto
+provisionerd/proto/provisionerd.pb.go: provisionerd/proto/provisionerd.proto
 	protoc \
 		--go_out=. \
 		--go_opt=paths=source_relative \
 		--go-drpc_out=. \
 		--go-drpc_opt=paths=source_relative \
 		./provisionerd/proto/provisionerd.proto
-.PHONY: provisionerd/proto
 
-provisionersdk/proto: provisionersdk/proto/provisioner.proto
+provisionersdk/proto/provisioner.pb.go: provisionersdk/proto/provisioner.proto
 	protoc \
 		--go_out=. \
 		--go_opt=paths=source_relative \
 		--go-drpc_out=. \
 		--go-drpc_opt=paths=source_relative \
 		./provisionersdk/proto/provisioner.proto
-.PHONY: provisionersdk/proto
 
-release: site/out
-	goreleaser release --snapshot --rm-dist
-.PHONY: release
-
-site/out:
+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
 	./scripts/yarn_install.sh
-	cd site && yarn typegen
-	cd site && yarn build
+	cd site
+	yarn typegen
+	yarn build
 	# Restores GITKEEP files!
-	git checkout HEAD site/out
-.PHONY: site/out
+	git checkout HEAD out
 
-test:
+site/src/api/typesGenerated.ts: scripts/apitypings/main.go $(shell find codersdk -type f -name '*.go')
+	go run scripts/apitypings/main.go > site/src/api/typesGenerated.ts
+	cd site
+	yarn run format:types
+
+test: test-clean
 	gotestsum -- -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="./..." -- \
+		-covermode=atomic -coverprofile="gotests.coverage" -timeout=20m \
+		-coverpkg=./... \
+		-count=1 -race -failfast
+.PHONY: test-postgres
+
+test-postgres-docker:
+	docker rm -f test-postgres-docker || true
+	docker run \
+		--env POSTGRES_PASSWORD=postgres \
+		--env POSTGRES_USER=postgres \
+		--env POSTGRES_DB=postgres \
+		--env PGDATA=/tmp \
+		--tmpfs /tmp \
+		--publish 5432:5432 \
+		--name test-postgres-docker \
+		--restart no \
+		--detach \
+		postgres:13 \
+		-c shared_buffers=1GB \
+		-c max_connections=1000 \
+		-c fsync=off \
+		-c synchronous_commit=off \
+		-c full_page_writes=off
+	while ! pg_isready -h 127.0.0.1
+	do
+		echo "$(date) - waiting for database to start"
+		sleep 0.5
+	done
+.PHONY: test-postgres-docker
+
+test-clean:
+	go clean -testcache
+.PHONY: test-clean

README.md

@@ -0,0 +1,100 @@
+# Coder
+
+[!["Join us on
+Discord"](https://img.shields.io/badge/join-us%20on%20Discord-gray.svg?longCache=true&logo=discord&colorB=green)](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)
+
+Coder creates remote development machines so your team can develop from anywhere.
+
+<p align="center">
+  <img src="./docs/images/hero-image.png">
+</p>
+
+**Manage less**
+
+- 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
+
+**Code more**
+
+- 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
+
+## Getting Started
+
+> **Note**:
+> Coder is in a beta state. [Report issues here](https://github.com/coder/coder/issues/new).
+
+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:
+
+```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
+```
+
+> See [install](docs/install.md) for additional methods.
+
+Once installed, you can start a production deployment<sup>1</sup> with a single command:
+
+```sh
+# Automatically sets up an external access URL on *.try.coder.app
+coder server --tunnel
+
+# Requires a PostgreSQL instance 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.
+
+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.
+
+## Documentation
+
+Visit our docs [here](https://coder.com/docs/coder-oss).
+
+## 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_
+
+## Community and Support
+
+Join our community on [Discord](https://discord.gg/coder) and [Twitter](https://twitter.com/coderhq)!
+
+[Suggest improvements and report problems](https://github.com/coder/coder/issues/new/choose)
+
+## Contributing
+
+Read the [contributing docs](https://coder.com/docs/coder-oss/latest/CONTRIBUTING).
+
+Find our list of contributors [here](https://github.com/coder/coder/graphs/contributors).

agent/agent.go

@@ -4,67 +4,133 @@ import (
 	"context"
 	"crypto/rand"
 	"crypto/rsa"
+	"encoding/json"
 	"errors"
 	"fmt"
 	"io"
 	"net"
+	"net/url"
 	"os"
 	"os/exec"
 	"os/user"
+	"path/filepath"
+	"runtime"
+	"strconv"
+	"strings"
 	"sync"
 	"time"
 
+	"github.com/armon/circbuf"
+	"github.com/gliderlabs/ssh"
+	"github.com/google/uuid"
+	"github.com/pkg/sftp"
+	"go.uber.org/atomic"
+	gossh "golang.org/x/crypto/ssh"
+	"golang.org/x/xerrors"
+	"inet.af/netaddr"
+	"tailscale.com/types/key"
+
 	"cdr.dev/slog"
 	"github.com/coder/coder/agent/usershell"
 	"github.com/coder/coder/peer"
+	"github.com/coder/coder/peer/peerwg"
 	"github.com/coder/coder/peerbroker"
 	"github.com/coder/coder/pty"
 	"github.com/coder/retry"
+)
 
-	"github.com/pkg/sftp"
+const (
+	ProtocolReconnectingPTY = "reconnecting-pty"
+	ProtocolSSH             = "ssh"
+	ProtocolDial            = "dial"
 
-	"github.com/gliderlabs/ssh"
-	gossh "golang.org/x/crypto/ssh"
-	"golang.org/x/xerrors"
+	// 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
 )
 
 type Options struct {
-	Logger slog.Logger
+	EnableWireguard        bool
+	UploadWireguardKeys    UploadWireguardKeys
+	ListenWireguardPeers   ListenWireguardPeers
+	ReconnectingPTYTimeout time.Duration
+	EnvironmentVariables   map[string]string
+	Logger                 slog.Logger
 }
 
-type Dialer func(ctx context.Context, options *peer.ConnOptions) (*peerbroker.Listener, error)
+type Metadata struct {
+	WireguardAddresses   []netaddr.IPPrefix `json:"addresses"`
+	EnvironmentVariables map[string]string  `json:"environment_variables"`
+	StartupScript        string             `json:"startup_script"`
+	Directory            string             `json:"directory"`
+}
 
-func New(dialer Dialer, options *peer.ConnOptions) io.Closer {
+type WireguardPublicKeys struct {
+	Public key.NodePublic  `json:"public"`
+	Disco  key.DiscoPublic `json:"disco"`
+}
+
+type Dialer func(ctx context.Context, logger slog.Logger) (Metadata, *peerbroker.Listener, error)
+type UploadWireguardKeys func(ctx context.Context, keys WireguardPublicKeys) error
+type ListenWireguardPeers func(ctx context.Context, logger slog.Logger) (<-chan peerwg.Handshake, func(), error)
+
+func New(dialer Dialer, options *Options) io.Closer {
+	if options == nil {
+		options = &Options{}
+	}
+	if options.ReconnectingPTYTimeout == 0 {
+		options.ReconnectingPTYTimeout = 5 * time.Minute
+	}
 	ctx, cancelFunc := context.WithCancel(context.Background())
 	server := &agent{
-		clientDialer: dialer,
-		options:      options,
-		closeCancel:  cancelFunc,
-		closed:       make(chan struct{}),
+		dialer:                 dialer,
+		reconnectingPTYTimeout: options.ReconnectingPTYTimeout,
+		logger:                 options.Logger,
+		closeCancel:            cancelFunc,
+		closed:                 make(chan struct{}),
+		envVars:                options.EnvironmentVariables,
+		enableWireguard:        options.EnableWireguard,
+		postKeys:               options.UploadWireguardKeys,
+		listenWireguardPeers:   options.ListenWireguardPeers,
 	}
 	server.init(ctx)
 	return server
 }
 
 type agent struct {
-	clientDialer Dialer
-	options      *peer.ConnOptions
+	dialer Dialer
+	logger slog.Logger
+
+	reconnectingPTYs       sync.Map
+	reconnectingPTYTimeout time.Duration
 
 	connCloseWait sync.WaitGroup
 	closeCancel   context.CancelFunc
 	closeMutex    sync.Mutex
 	closed        chan struct{}
 
-	sshServer *ssh.Server
+	envVars map[string]string
+	// metadata is atomic because values can change after reconnection.
+	metadata      atomic.Value
+	startupScript atomic.Bool
+	sshServer     *ssh.Server
+
+	enableWireguard      bool
+	network              *peerwg.Network
+	postKeys             UploadWireguardKeys
+	listenWireguardPeers ListenWireguardPeers
 }
 
 func (a *agent) run(ctx context.Context) {
+	var metadata Metadata
 	var peerListener *peerbroker.Listener
 	var err error
 	// An exponential back-off occurs when the connection is failing to dial.
 	// This is to prevent server spam in case of a coderd outage.
 	for retrier := retry.New(50*time.Millisecond, 10*time.Second); retrier.Wait(ctx); {
-		peerListener, err = a.clientDialer(ctx, a.options)
+		a.logger.Info(ctx, "connecting")
+		metadata, peerListener, err = a.dialer(ctx, a.logger)
 		if err != nil {
 			if errors.Is(err, context.Canceled) {
 				return
@@ -72,10 +138,10 @@ func (a *agent) run(ctx context.Context) {
 			if a.isClosed() {
 				return
 			}
-			a.options.Logger.Warn(context.Background(), "failed to dial", slog.Error(err))
+			a.logger.Warn(context.Background(), "failed to dial", slog.Error(err))
 			continue
 		}
-		a.options.Logger.Info(context.Background(), "connected")
+		a.logger.Info(context.Background(), "connected")
 		break
 	}
 	select {
@@ -83,6 +149,27 @@ func (a *agent) run(ctx context.Context) {
 		return
 	default:
 	}
+	a.metadata.Store(metadata)
+
+	if a.startupScript.CAS(false, true) {
+		// The startup script has not ran yet!
+		go func() {
+			err := a.runStartupScript(ctx, metadata.StartupScript)
+			if errors.Is(err, context.Canceled) {
+				return
+			}
+			if err != nil {
+				a.logger.Warn(ctx, "agent script failed", slog.Error(err))
+			}
+		}()
+	}
+
+	if a.enableWireguard {
+		err = a.startWireguard(ctx, metadata.WireguardAddresses)
+		if err != nil {
+			a.logger.Error(ctx, "start wireguard", slog.Error(err))
+		}
+	}
 
 	for {
 		conn, err := peerListener.Accept()
@@ -90,7 +177,7 @@ func (a *agent) run(ctx context.Context) {
 			if a.isClosed() {
 				return
 			}
-			a.options.Logger.Debug(ctx, "peer listener accept exited; restarting connection", slog.Error(err))
+			a.logger.Debug(ctx, "peer listener accept exited; restarting connection", slog.Error(err))
 			a.run(ctx)
 			return
 		}
@@ -101,14 +188,45 @@ func (a *agent) run(ctx context.Context) {
 	}
 }
 
+func (a *agent) runStartupScript(ctx context.Context, script string) error {
+	if script == "" {
+		return nil
+	}
+
+	writer, err := os.OpenFile(filepath.Join(os.TempDir(), "coder-startup-script.log"), os.O_CREATE|os.O_RDWR, 0600)
+	if err != nil {
+		return xerrors.Errorf("open startup script log file: %w", err)
+	}
+	defer func() {
+		_ = writer.Close()
+	}()
+
+	cmd, err := a.createCommand(ctx, script, nil)
+	if err != nil {
+		return xerrors.Errorf("create command: %w", err)
+	}
+	cmd.Stdout = writer
+	cmd.Stderr = writer
+	err = cmd.Run()
+	if err != nil {
+		// cmd.Run does not return a context canceled error, it returns "signal: killed".
+		if ctx.Err() != nil {
+			return ctx.Err()
+		}
+
+		return xerrors.Errorf("run: %w", err)
+	}
+
+	return nil
+}
+
 func (a *agent) handlePeerConn(ctx context.Context, conn *peer.Conn) {
 	go func() {
 		select {
 		case <-a.closed:
-			_ = conn.Close()
 		case <-conn.Closed():
 		}
-		<-conn.Closed()
+		_ = conn.Close()
 		a.connCloseWait.Done()
 	}()
 	for {
@@ -117,15 +235,19 @@ func (a *agent) handlePeerConn(ctx context.Context, conn *peer.Conn) {
 			if errors.Is(err, peer.ErrClosed) || a.isClosed() {
 				return
 			}
-			a.options.Logger.Debug(ctx, "accept channel from peer connection", slog.Error(err))
+			a.logger.Debug(ctx, "accept channel from peer connection", slog.Error(err))
 			return
 		}
 
 		switch channel.Protocol() {
-		case "ssh":
+		case ProtocolSSH:
 			go a.sshServer.HandleConn(channel.NetConn())
+		case ProtocolReconnectingPTY:
+			go a.handleReconnectingPTY(ctx, channel.Label(), channel.NetConn())
+		case ProtocolDial:
+			go a.handleDial(ctx, channel.Label(), channel.NetConn())
 		default:
-			a.options.Logger.Warn(ctx, "unhandled protocol from channel",
+			a.logger.Warn(ctx, "unhandled protocol from channel",
 				slog.F("protocol", channel.Protocol()),
 				slog.F("label", channel.Label()),
 			)
@@ -134,6 +256,7 @@ func (a *agent) handlePeerConn(ctx context.Context, conn *peer.Conn) {
 }
 
 func (a *agent) init(ctx context.Context) {
+	a.logger.Info(ctx, "generating host key")
 	// Clients' should ignore the host key when connecting.
 	// The agent needs to authenticate with coderd to SSH,
 	// so SSH authentication doesn't improve security.
@@ -145,7 +268,7 @@ func (a *agent) init(ctx context.Context) {
 	if err != nil {
 		panic(err)
 	}
-	sshLogger := a.options.Logger.Named("ssh-server")
+	sshLogger := a.logger.Named("ssh-server")
 	forwardHandler := &ssh.ForwardedTCPHandler{}
 	a.sshServer = &ssh.Server{
 		ChannelHandlers: map[string]ssh.ChannelHandler{
@@ -157,9 +280,17 @@ func (a *agent) init(ctx context.Context) {
 		},
 		Handler: func(session ssh.Session) {
 			err := a.handleSSHSession(session)
+			var exitError *exec.ExitError
+			if xerrors.As(err, &exitError) {
+				a.logger.Debug(ctx, "ssh session returned", slog.Error(exitError))
+				_ = session.Exit(exitError.ExitCode())
+				return
+			}
 			if err != nil {
-				a.options.Logger.Warn(ctx, "ssh session failed", slog.Error(err))
-				_ = session.Exit(1)
+				a.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
 			}
 		},
@@ -194,7 +325,7 @@ func (a *agent) init(ctx context.Context) {
 			"sftp": func(session ssh.Session) {
 				server, err := sftp.NewServer(session)
 				if err != nil {
-					a.options.Logger.Debug(session.Context(), "initialize sftp server", slog.Error(err))
+					a.logger.Debug(session.Context(), "initialize sftp server", slog.Error(err))
 					return
 				}
 				defer server.Close()
@@ -202,7 +333,7 @@ func (a *agent) init(ctx context.Context) {
 				if errors.Is(err, io.EOF) {
 					return
 				}
-				a.options.Logger.Debug(session.Context(), "sftp server exited with error", slog.Error(err))
+				a.logger.Debug(session.Context(), "sftp server exited with error", slog.Error(err))
 			},
 		},
 	}
@@ -210,47 +341,140 @@ func (a *agent) init(ctx context.Context) {
 	go a.run(ctx)
 }
 
-func (a *agent) handleSSHSession(session ssh.Session) error {
+// createCommand processes raw command input with OpenSSH-like behavior.
+// If the rawCommand provided is empty, it will default to the users shell.
+// This injects environment variables specified by the user at launch too.
+func (a *agent) createCommand(ctx context.Context, rawCommand string, env []string) (*exec.Cmd, error) {
 	currentUser, err := user.Current()
 	if err != nil {
-		return xerrors.Errorf("get current user: %w", err)
+		return nil, xerrors.Errorf("get current user: %w", err)
 	}
 	username := currentUser.Username
 
 	shell, err := usershell.Get(username)
 	if err != nil {
-		return xerrors.Errorf("get user shell: %w", err)
+		return nil, xerrors.Errorf("get user shell: %w", err)
+	}
+
+	rawMetadata := a.metadata.Load()
+	if rawMetadata == nil {
+		return nil, xerrors.Errorf("no metadata was provided: %w", err)
+	}
+	metadata, valid := rawMetadata.(Metadata)
+	if !valid {
+		return nil, xerrors.Errorf("metadata is the wrong type: %T", metadata)
 	}
 
 	// gliderlabs/ssh returns a command slice of zero
 	// when a shell is requested.
-	command := session.RawCommand()
-	if len(session.Command()) == 0 {
+	command := rawCommand
+	if len(command) == 0 {
 		command = shell
+		if runtime.GOOS != "windows" {
+			// On Linux and macOS, we should start a login
+			// shell to consume juicy environment variables!
+			command += " -l"
+		}
 	}
 
 	// OpenSSH executes all commands with the users current shell.
 	// We replicate that behavior for IDE support.
-	cmd := exec.CommandContext(session.Context(), shell, "-c", command)
-	cmd.Env = append(os.Environ(), session.Environ()...)
+	caller := "-c"
+	if runtime.GOOS == "windows" {
+		caller = "/c"
+	}
+	cmd := exec.CommandContext(ctx, shell, caller, command)
+	cmd.Dir = metadata.Directory
+	if cmd.Dir == "" {
+		// Default to $HOME if a directory is not set!
+		cmd.Dir = os.Getenv("HOME")
+	}
+	cmd.Env = append(os.Environ(), env...)
 	executablePath, err := os.Executable()
 	if err != nil {
-		return xerrors.Errorf("getting os executable: %w", err)
+		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))
+
+	// 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))
+
+	// Load environment variables passed via the agent.
+	// These should override all variables we manually specify.
+	for envKey, value := range metadata.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 a.envVars {
+		cmd.Env = append(cmd.Env, fmt.Sprintf("%s=%s", envKey, value))
+	}
+
+	return cmd, nil
+}
+
+func (a *agent) handleSSHSession(session ssh.Session) (retErr error) {
+	cmd, err := a.createCommand(session.Context(), session.RawCommand(), session.Environ())
+	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()))
 	}
-	cmd.Env = append(cmd.Env, fmt.Sprintf(`GIT_SSH_COMMAND="%s gitssh --"`, executablePath))
 
 	sshPty, windowSize, isPty := session.Pty()
 	if isPty {
 		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)
 		if err != nil {
 			return xerrors.Errorf("start command: %w", err)
 		}
+		defer func() {
+			closeErr := ptty.Close()
+			if closeErr != nil {
+				a.logger.Warn(context.Background(), "failed to close tty",
+					slog.Error(closeErr))
+				if retErr == nil {
+					retErr = closeErr
+				}
+			}
+		}()
+		err = ptty.Resize(uint16(sshPty.Window.Height), uint16(sshPty.Window.Width))
+		if err != nil {
+			return xerrors.Errorf("resize ptty: %w", err)
+		}
 		go func() {
 			for win := range windowSize {
-				err = ptty.Resize(uint16(win.Width), uint16(win.Height))
-				if err != nil {
-					a.options.Logger.Warn(context.Background(), "failed to resize tty", slog.Error(err))
+				resizeErr := ptty.Resize(uint16(win.Height), uint16(win.Width))
+				if resizeErr != nil {
+					a.logger.Warn(context.Background(), "failed to resize tty", slog.Error(resizeErr))
 				}
 			}
 		}()
@@ -260,9 +484,15 @@ func (a *agent) handleSSHSession(session ssh.Session) error {
 		go func() {
 			_, _ = io.Copy(session, ptty.Output())
 		}()
-		_, _ = process.Wait()
-		_ = ptty.Close()
-		return nil
+		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) {
+			a.logger.Warn(context.Background(), "wait error",
+				slog.Error(err))
+		}
+		return err
 	}
 
 	cmd.Stdout = session
@@ -275,6 +505,7 @@ func (a *agent) handleSSHSession(session ssh.Session) error {
 	}
 	go func() {
 		_, _ = io.Copy(stdinPipe, session)
+		_ = stdinPipe.Close()
 	}()
 	err = cmd.Start()
 	if err != nil {
@@ -283,6 +514,262 @@ func (a *agent) handleSSHSession(session ssh.Session) error {
 	return cmd.Wait()
 }
 
+func (a *agent) handleReconnectingPTY(ctx context.Context, rawID string, conn net.Conn) {
+	defer conn.Close()
+
+	// The ID format is referenced in conn.go.
+	// <uuid>:<height>:<width>
+	idParts := strings.SplitN(rawID, ":", 4)
+	if len(idParts) != 4 {
+		a.logger.Warn(ctx, "client sent invalid id format", slog.F("raw-id", rawID))
+		return
+	}
+	id := idParts[0]
+	// Enforce a consistent format for IDs.
+	_, err := uuid.Parse(id)
+	if err != nil {
+		a.logger.Warn(ctx, "client sent reconnection token that isn't a uuid", slog.F("id", id), slog.Error(err))
+		return
+	}
+	// Parse the initial terminal dimensions.
+	height, err := strconv.Atoi(idParts[1])
+	if err != nil {
+		a.logger.Warn(ctx, "client sent invalid height", slog.F("id", id), slog.F("height", idParts[1]))
+		return
+	}
+	width, err := strconv.Atoi(idParts[2])
+	if err != nil {
+		a.logger.Warn(ctx, "client sent invalid width", slog.F("id", id), slog.F("width", idParts[2]))
+		return
+	}
+
+	var rpty *reconnectingPTY
+	rawRPTY, ok := a.reconnectingPTYs.Load(id)
+	if ok {
+		rpty, ok = rawRPTY.(*reconnectingPTY)
+		if !ok {
+			a.logger.Warn(ctx, "found invalid type in reconnecting pty map", slog.F("id", id))
+		}
+	} else {
+		// Empty command will default to the users shell!
+		cmd, err := a.createCommand(ctx, idParts[3], nil)
+		if err != nil {
+			a.logger.Warn(ctx, "create reconnecting pty command", slog.Error(err))
+			return
+		}
+		cmd.Env = append(cmd.Env, "TERM=xterm-256color")
+
+		ptty, process, err := pty.Start(cmd)
+		if err != nil {
+			a.logger.Warn(ctx, "start reconnecting pty command", slog.F("id", id))
+		}
+
+		// Default to buffer 64KiB.
+		circularBuffer, err := circbuf.NewBuffer(64 << 10)
+		if err != nil {
+			a.logger.Warn(ctx, "create circular buffer", slog.Error(err))
+			return
+		}
+
+		a.closeMutex.Lock()
+		a.connCloseWait.Add(1)
+		a.closeMutex.Unlock()
+		ctx, cancelFunc := context.WithCancel(ctx)
+		rpty = &reconnectingPTY{
+			activeConns: make(map[string]net.Conn),
+			ptty:        ptty,
+			// Timeouts created with an after func can be reset!
+			timeout:        time.AfterFunc(a.reconnectingPTYTimeout, cancelFunc),
+			circularBuffer: circularBuffer,
+		}
+		a.reconnectingPTYs.Store(id, rpty)
+		go func() {
+			// CommandContext isn't respected for Windows PTYs right now,
+			// so we need to manually track the lifecycle.
+			// When the context has been completed either:
+			// 1. The timeout completed.
+			// 2. The parent context was canceled.
+			<-ctx.Done()
+			_ = process.Kill()
+		}()
+		go func() {
+			// If the process dies randomly, we should
+			// close the pty.
+			_ = process.Wait()
+			rpty.Close()
+		}()
+		go func() {
+			buffer := make([]byte, 1024)
+			for {
+				read, err := rpty.ptty.Output().Read(buffer)
+				if err != nil {
+					// When the PTY is closed, this is triggered.
+					break
+				}
+				part := buffer[:read]
+				rpty.circularBufferMutex.Lock()
+				_, err = rpty.circularBuffer.Write(part)
+				rpty.circularBufferMutex.Unlock()
+				if err != nil {
+					a.logger.Error(ctx, "reconnecting pty write buffer", slog.Error(err), slog.F("id", id))
+					break
+				}
+				rpty.activeConnsMutex.Lock()
+				for _, conn := range rpty.activeConns {
+					_, _ = conn.Write(part)
+				}
+				rpty.activeConnsMutex.Unlock()
+			}
+
+			// Cleanup the process, PTY, and delete it's
+			// ID from memory.
+			_ = process.Kill()
+			rpty.Close()
+			a.reconnectingPTYs.Delete(id)
+			a.connCloseWait.Done()
+		}()
+	}
+	// Resize the PTY to initial height + width.
+	err = rpty.ptty.Resize(uint16(height), uint16(width))
+	if err != nil {
+		// We can continue after this, it's not fatal!
+		a.logger.Error(ctx, "resize reconnecting pty", slog.F("id", id), slog.Error(err))
+	}
+	// Write any previously stored data for the TTY.
+	rpty.circularBufferMutex.RLock()
+	_, err = conn.Write(rpty.circularBuffer.Bytes())
+	rpty.circularBufferMutex.RUnlock()
+	if err != nil {
+		a.logger.Warn(ctx, "write reconnecting pty buffer", slog.F("id", id), slog.Error(err))
+		return
+	}
+	connectionID := uuid.NewString()
+	// Multiple connections to the same TTY are permitted.
+	// This could easily be used for terminal sharing, but
+	// we do it because it's a nice user experience to
+	// copy/paste a terminal URL and have it _just work_.
+	rpty.activeConnsMutex.Lock()
+	rpty.activeConns[connectionID] = conn
+	rpty.activeConnsMutex.Unlock()
+	// Resetting this timeout prevents the PTY from exiting.
+	rpty.timeout.Reset(a.reconnectingPTYTimeout)
+
+	ctx, cancelFunc := context.WithCancel(ctx)
+	defer cancelFunc()
+	heartbeat := time.NewTicker(a.reconnectingPTYTimeout / 2)
+	defer heartbeat.Stop()
+	go func() {
+		// Keep updating the activity while this
+		// connection is alive!
+		for {
+			select {
+			case <-ctx.Done():
+				return
+			case <-heartbeat.C:
+			}
+			rpty.timeout.Reset(a.reconnectingPTYTimeout)
+		}
+	}()
+	defer func() {
+		// After this connection ends, remove it from
+		// the PTYs active connections. If it isn't
+		// removed, all PTY data will be sent to it.
+		rpty.activeConnsMutex.Lock()
+		delete(rpty.activeConns, connectionID)
+		rpty.activeConnsMutex.Unlock()
+	}()
+	decoder := json.NewDecoder(conn)
+	var req ReconnectingPTYRequest
+	for {
+		err = decoder.Decode(&req)
+		if xerrors.Is(err, io.EOF) {
+			return
+		}
+		if err != nil {
+			a.logger.Warn(ctx, "reconnecting pty buffer read error", slog.F("id", id), slog.Error(err))
+			return
+		}
+		_, err = rpty.ptty.Input().Write([]byte(req.Data))
+		if err != nil {
+			a.logger.Warn(ctx, "write to reconnecting pty", slog.F("id", id), slog.Error(err))
+			return
+		}
+		// Check if a resize needs to happen!
+		if req.Height == 0 || req.Width == 0 {
+			continue
+		}
+		err = rpty.ptty.Resize(req.Height, req.Width)
+		if err != nil {
+			// We can continue after this, it's not fatal!
+			a.logger.Error(ctx, "resize reconnecting pty", slog.F("id", id), slog.Error(err))
+		}
+	}
+}
+
+// dialResponse is written to datachannels with protocol "dial" by the agent as
+// the first packet to signify whether the dial succeeded or failed.
+type dialResponse struct {
+	Error string `json:"error,omitempty"`
+}
+
+func (a *agent) handleDial(ctx context.Context, label string, conn net.Conn) {
+	defer conn.Close()
+
+	writeError := func(responseError error) error {
+		msg := ""
+		if responseError != nil {
+			msg = responseError.Error()
+			if !xerrors.Is(responseError, io.EOF) {
+				a.logger.Warn(ctx, "handle dial", slog.F("label", label), slog.Error(responseError))
+			}
+		}
+		b, err := json.Marshal(dialResponse{
+			Error: msg,
+		})
+		if err != nil {
+			a.logger.Warn(ctx, "write dial response", slog.F("label", label), slog.Error(err))
+			return xerrors.Errorf("marshal agent webrtc dial response: %w", err)
+		}
+
+		_, err = conn.Write(b)
+		return err
+	}
+
+	u, err := url.Parse(label)
+	if err != nil {
+		_ = writeError(xerrors.Errorf("parse URL %q: %w", label, err))
+		return
+	}
+
+	network := u.Scheme
+	addr := u.Host + u.Path
+	if strings.HasPrefix(network, "unix") {
+		if runtime.GOOS == "windows" {
+			_ = writeError(xerrors.New("Unix forwarding is not supported from Windows workspaces"))
+			return
+		}
+		addr, err = ExpandRelativeHomePath(addr)
+		if err != nil {
+			_ = writeError(xerrors.Errorf("expand path %q: %w", addr, err))
+			return
+		}
+	}
+
+	d := net.Dialer{Timeout: 3 * time.Second}
+	nconn, err := d.DialContext(ctx, network, addr)
+	if err != nil {
+		_ = writeError(xerrors.Errorf("dial '%v://%v': %w", network, addr, err))
+		return
+	}
+
+	err = writeError(nil)
+	if err != nil {
+		return
+	}
+
+	Bicopy(ctx, conn, nconn)
+}
+
 // isClosed returns whether the API is closed or not.
 func (a *agent) isClosed() bool {
 	select {
@@ -305,3 +792,75 @@ func (a *agent) Close() error {
 	a.connCloseWait.Wait()
 	return nil
 }
+
+type reconnectingPTY struct {
+	activeConnsMutex sync.Mutex
+	activeConns      map[string]net.Conn
+
+	circularBuffer      *circbuf.Buffer
+	circularBufferMutex sync.RWMutex
+	timeout             *time.Timer
+	ptty                pty.PTY
+}
+
+// Close ends all connections to the reconnecting
+// PTY and clear the circular buffer.
+func (r *reconnectingPTY) Close() {
+	r.activeConnsMutex.Lock()
+	defer r.activeConnsMutex.Unlock()
+	for _, conn := range r.activeConns {
+		_ = conn.Close()
+	}
+	_ = r.ptty.Close()
+	r.circularBufferMutex.Lock()
+	r.circularBuffer.Reset()
+	r.circularBufferMutex.Unlock()
+	r.timeout.Stop()
+}
+
+// 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) {
+	defer c1.Close()
+	defer c2.Close()
+
+	var wg sync.WaitGroup
+	copyFunc := func(dst io.WriteCloser, src io.Reader) {
+		defer wg.Done()
+		_, _ = 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:
+	}
+}
+
+// ExpandRelativeHomePath expands the tilde at the beginning of a path to the
+// current user's home directory and returns a full absolute path.
+func ExpandRelativeHomePath(in string) (string, error) {
+	usr, err := user.Current()
+	if err != nil {
+		return "", xerrors.Errorf("get current user details: %w", err)
+	}
+
+	if in == "~" {
+		in = usr.HomeDir
+	} else if strings.HasPrefix(in, "~/") {
+		in = filepath.Join(usr.HomeDir, in[2:])
+	}
+
+	return filepath.Abs(in)
+}

agent/agent_test.go

@@ -1,7 +1,9 @@
 package agent_test
 
 import (
+	"bufio"
 	"context"
+	"encoding/json"
 	"fmt"
 	"io"
 	"net"
@@ -12,12 +14,21 @@ import (
 	"strconv"
 	"strings"
 	"testing"
+	"time"
 
+	"golang.org/x/xerrors"
+
+	scp "github.com/bramvdbogaerde/go-scp"
+	"github.com/google/uuid"
+	"github.com/pion/udp"
 	"github.com/pion/webrtc/v3"
 	"github.com/pkg/sftp"
+	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 	"go.uber.org/goleak"
 	"golang.org/x/crypto/ssh"
+	"golang.org/x/text/encoding/unicode"
+	"golang.org/x/text/transform"
 
 	"cdr.dev/slog"
 	"cdr.dev/slog/sloggers/slogtest"
@@ -27,6 +38,7 @@ import (
 	"github.com/coder/coder/peerbroker/proto"
 	"github.com/coder/coder/provisionersdk"
 	"github.com/coder/coder/pty/ptytest"
+	"github.com/coder/coder/testutil"
 )
 
 func TestMain(m *testing.M) {
@@ -37,7 +49,7 @@ func TestAgent(t *testing.T) {
 	t.Parallel()
 	t.Run("SessionExec", func(t *testing.T) {
 		t.Parallel()
-		session := setupSSHSession(t)
+		session := setupSSHSession(t, agent.Metadata{})
 
 		command := "echo test"
 		if runtime.GOOS == "windows" {
@@ -50,24 +62,28 @@ func TestAgent(t *testing.T) {
 
 	t.Run("GitSSH", func(t *testing.T) {
 		t.Parallel()
-		session := setupSSHSession(t)
+		session := setupSSHSession(t, agent.Metadata{})
 		command := "sh -c 'echo $GIT_SSH_COMMAND'"
 		if runtime.GOOS == "windows" {
 			command = "cmd.exe /c echo %GIT_SSH_COMMAND%"
 		}
 		output, err := session.Output(command)
 		require.NoError(t, err)
-		require.Contains(t, string(output), "gitssh --")
+		require.True(t, strings.HasSuffix(strings.TrimSpace(string(output)), "gitssh --"))
 	})
 
-	t.Run("SessionTTY", func(t *testing.T) {
+	t.Run("SessionTTYShell", func(t *testing.T) {
 		t.Parallel()
-		session := setupSSHSession(t)
-		prompt := "$"
+		if runtime.GOOS == "windows" {
+			// This might be our implementation, or ConPTY itself.
+			// It's difficult to find extensive tests for it, so
+			// it seems like it could be either.
+			t.Skip("ConPTY appears to be inconsistent on Windows.")
+		}
+		session := setupSSHSession(t, agent.Metadata{})
 		command := "bash"
 		if runtime.GOOS == "windows" {
 			command = "cmd.exe"
-			prompt = ">"
 		}
 		err := session.RequestPty("xterm", 128, 128, ssh.TerminalModes{})
 		require.NoError(t, err)
@@ -78,7 +94,11 @@ func TestAgent(t *testing.T) {
 		session.Stdin = ptty.Input()
 		err = session.Start(command)
 		require.NoError(t, err)
-		ptty.ExpectMatch(prompt)
+		caret := "$"
+		if runtime.GOOS == "windows" {
+			caret = ">"
+		}
+		ptty.ExpectMatch(caret)
 		ptty.WriteLine("echo test")
 		ptty.ExpectMatch("test")
 		ptty.WriteLine("exit")
@@ -86,6 +106,29 @@ func TestAgent(t *testing.T) {
 		require.NoError(t, err)
 	})
 
+	t.Run("SessionTTYExitCode", func(t *testing.T) {
+		t.Parallel()
+		session := setupSSHSession(t, agent.Metadata{})
+		command := "areallynotrealcommand"
+		err := session.RequestPty("xterm", 128, 128, ssh.TerminalModes{})
+		require.NoError(t, err)
+		ptty := ptytest.New(t)
+		require.NoError(t, err)
+		session.Stdout = ptty.Output()
+		session.Stderr = ptty.Output()
+		session.Stdin = ptty.Input()
+		err = session.Start(command)
+		require.NoError(t, err)
+		err = session.Wait()
+		exitErr := &ssh.ExitError{}
+		require.True(t, xerrors.As(err, &exitErr))
+		if runtime.GOOS == "windows" {
+			assert.Equal(t, 1, exitErr.ExitStatus())
+		} else {
+			assert.Equal(t, 127, exitErr.ExitStatus())
+		}
+	})
+
 	t.Run("LocalForwarding", func(t *testing.T) {
 		t.Parallel()
 		random, err := net.Listen("tcp", "127.0.0.1:0")
@@ -103,10 +146,12 @@ func TestAgent(t *testing.T) {
 		localPort := tcpAddr.Port
 		done := make(chan struct{})
 		go func() {
+			defer close(done)
 			conn, err := local.Accept()
-			require.NoError(t, err)
+			if !assert.NoError(t, err) {
+				return
+			}
 			_ = conn.Close()
-			close(done)
 		}()
 
 		err = setupSSHCommand(t, []string{"-L", fmt.Sprintf("%d:127.0.0.1:%d", randomPort, localPort)}, []string{"echo", "test"}).Start()
@@ -120,7 +165,7 @@ func TestAgent(t *testing.T) {
 
 	t.Run("SFTP", func(t *testing.T) {
 		t.Parallel()
-		sshClient, err := setupAgent(t).SSHClient()
+		sshClient, err := setupAgent(t, agent.Metadata{}, 0).SSHClient()
 		require.NoError(t, err)
 		client, err := sftp.NewClient(sshClient)
 		require.NoError(t, err)
@@ -132,22 +177,311 @@ func TestAgent(t *testing.T) {
 		_, err = os.Stat(tempFile)
 		require.NoError(t, err)
 	})
+
+	t.Run("SCP", func(t *testing.T) {
+		t.Parallel()
+		sshClient, err := setupAgent(t, agent.Metadata{}, 0).SSHClient()
+		require.NoError(t, err)
+		scpClient, err := scp.NewClientBySSH(sshClient)
+		require.NoError(t, err)
+		tempFile := filepath.Join(t.TempDir(), "scp")
+		content := "hello world"
+		err = scpClient.CopyFile(context.Background(), strings.NewReader(content), tempFile, "0755")
+		require.NoError(t, err)
+		_, err = os.Stat(tempFile)
+		require.NoError(t, err)
+	})
+
+	t.Run("EnvironmentVariables", func(t *testing.T) {
+		t.Parallel()
+		key := "EXAMPLE"
+		value := "value"
+		session := setupSSHSession(t, agent.Metadata{
+			EnvironmentVariables: map[string]string{
+				key: value,
+			},
+		})
+		command := "sh -c 'echo $" + key + "'"
+		if runtime.GOOS == "windows" {
+			command = "cmd.exe /c echo %" + key + "%"
+		}
+		output, err := session.Output(command)
+		require.NoError(t, err)
+		require.Equal(t, value, strings.TrimSpace(string(output)))
+	})
+
+	t.Run("EnvironmentVariableExpansion", func(t *testing.T) {
+		t.Parallel()
+		key := "EXAMPLE"
+		session := setupSSHSession(t, agent.Metadata{
+			EnvironmentVariables: map[string]string{
+				key: "$SOMETHINGNOTSET",
+			},
+		})
+		command := "sh -c 'echo $" + key + "'"
+		if runtime.GOOS == "windows" {
+			command = "cmd.exe /c echo %" + key + "%"
+		}
+		output, err := session.Output(command)
+		require.NoError(t, err)
+		expect := ""
+		if runtime.GOOS == "windows" {
+			expect = "%EXAMPLE%"
+		}
+		// Output should be empty, because the variable is not set!
+		require.Equal(t, expect, strings.TrimSpace(string(output)))
+	})
+
+	t.Run("Coder env vars", func(t *testing.T) {
+		t.Parallel()
+
+		for _, key := range []string{"CODER"} {
+			key := key
+			t.Run(key, func(t *testing.T) {
+				t.Parallel()
+
+				session := setupSSHSession(t, agent.Metadata{})
+				command := "sh -c 'echo $" + key + "'"
+				if runtime.GOOS == "windows" {
+					command = "cmd.exe /c echo %" + key + "%"
+				}
+				output, err := session.Output(command)
+				require.NoError(t, err)
+				require.NotEmpty(t, strings.TrimSpace(string(output)))
+			})
+		}
+	})
+
+	t.Run("SSH connection env vars", func(t *testing.T) {
+		t.Parallel()
+
+		// Note: the SSH_TTY environment variable should only be set for TTYs.
+		// For some reason this test produces a TTY locally and a non-TTY in CI
+		// so we don't test for the absence of SSH_TTY.
+		for _, key := range []string{"SSH_CONNECTION", "SSH_CLIENT"} {
+			key := key
+			t.Run(key, func(t *testing.T) {
+				t.Parallel()
+
+				session := setupSSHSession(t, agent.Metadata{})
+				command := "sh -c 'echo $" + key + "'"
+				if runtime.GOOS == "windows" {
+					command = "cmd.exe /c echo %" + key + "%"
+				}
+				output, err := session.Output(command)
+				require.NoError(t, err)
+				require.NotEmpty(t, strings.TrimSpace(string(output)))
+			})
+		}
+	})
+
+	t.Run("StartupScript", func(t *testing.T) {
+		t.Parallel()
+		tempPath := filepath.Join(t.TempDir(), "content.txt")
+		content := "somethingnice"
+		setupAgent(t, agent.Metadata{
+			StartupScript: fmt.Sprintf("echo %s > %s", content, tempPath),
+		}, 0)
+
+		var gotContent string
+		require.Eventually(t, func() bool {
+			content, err := os.ReadFile(tempPath)
+			if err != nil {
+				return false
+			}
+			if len(content) == 0 {
+				return false
+			}
+			if runtime.GOOS == "windows" {
+				// Windows uses UTF16! 🪟🪟🪟
+				content, _, err = transform.Bytes(unicode.UTF16(unicode.LittleEndian, unicode.UseBOM).NewDecoder(), content)
+				if !assert.NoError(t, err) {
+					return false
+				}
+			}
+			gotContent = string(content)
+			return true
+		}, testutil.WaitMedium, testutil.IntervalMedium)
+		require.Equal(t, content, strings.TrimSpace(gotContent))
+	})
+
+	t.Run("ReconnectingPTY", func(t *testing.T) {
+		t.Parallel()
+		if runtime.GOOS == "windows" {
+			// This might be our implementation, or ConPTY itself.
+			// It's difficult to find extensive tests for it, so
+			// it seems like it could be either.
+			t.Skip("ConPTY appears to be inconsistent on Windows.")
+		}
+
+		conn := setupAgent(t, agent.Metadata{}, 0)
+		id := uuid.NewString()
+		netConn, err := conn.ReconnectingPTY(id, 100, 100, "/bin/bash")
+		require.NoError(t, err)
+		bufRead := bufio.NewReader(netConn)
+
+		// Brief pause to reduce the likelihood that we send keystrokes while
+		// the shell is simultaneously sending a prompt.
+		time.Sleep(100 * time.Millisecond)
+
+		data, err := json.Marshal(agent.ReconnectingPTYRequest{
+			Data: "echo test\r\n",
+		})
+		require.NoError(t, err)
+		_, err = netConn.Write(data)
+		require.NoError(t, err)
+
+		expectLine := func(matcher func(string) bool) {
+			for {
+				line, err := bufRead.ReadString('\n')
+				require.NoError(t, err)
+				if matcher(line) {
+					break
+				}
+			}
+		}
+
+		matchEchoCommand := func(line string) bool {
+			return strings.Contains(line, "echo test")
+		}
+		matchEchoOutput := func(line string) bool {
+			return strings.Contains(line, "test") && !strings.Contains(line, "echo")
+		}
+
+		// Once for typing the command...
+		expectLine(matchEchoCommand)
+		// And another time for the actual output.
+		expectLine(matchEchoOutput)
+
+		_ = netConn.Close()
+		netConn, err = conn.ReconnectingPTY(id, 100, 100, "/bin/bash")
+		require.NoError(t, err)
+		bufRead = bufio.NewReader(netConn)
+
+		// Same output again!
+		expectLine(matchEchoCommand)
+		expectLine(matchEchoOutput)
+	})
+
+	t.Run("Dial", func(t *testing.T) {
+		t.Parallel()
+
+		cases := []struct {
+			name  string
+			setup func(t *testing.T) net.Listener
+		}{
+			{
+				name: "TCP",
+				setup: func(t *testing.T) net.Listener {
+					l, err := net.Listen("tcp", "127.0.0.1:0")
+					require.NoError(t, err, "create TCP listener")
+					return l
+				},
+			},
+			{
+				name: "UDP",
+				setup: func(t *testing.T) net.Listener {
+					addr := net.UDPAddr{
+						IP:   net.ParseIP("127.0.0.1"),
+						Port: 0,
+					}
+					l, err := udp.Listen("udp", &addr)
+					require.NoError(t, err, "create UDP listener")
+					return l
+				},
+			},
+			{
+				name: "Unix",
+				setup: func(t *testing.T) net.Listener {
+					if runtime.GOOS == "windows" {
+						t.Skip("Unix socket forwarding isn't supported on Windows")
+					}
+
+					tmpDir := t.TempDir()
+					l, err := net.Listen("unix", filepath.Join(tmpDir, "test.sock"))
+					require.NoError(t, err, "create UDP listener")
+					return l
+				},
+			},
+		}
+
+		for _, c := range cases {
+			c := c
+			t.Run(c.name, func(t *testing.T) {
+				t.Parallel()
+
+				// Setup listener
+				l := c.setup(t)
+				defer l.Close()
+				go func() {
+					for {
+						c, err := l.Accept()
+						if err != nil {
+							return
+						}
+
+						go testAccept(t, c)
+					}
+				}()
+
+				// Dial the listener over WebRTC twice and test out of order
+				conn := setupAgent(t, agent.Metadata{}, 0)
+				conn1, err := conn.DialContext(context.Background(), l.Addr().Network(), l.Addr().String())
+				require.NoError(t, err)
+				defer conn1.Close()
+				conn2, err := conn.DialContext(context.Background(), l.Addr().Network(), l.Addr().String())
+				require.NoError(t, err)
+				defer conn2.Close()
+				testDial(t, conn2)
+				testDial(t, conn1)
+			})
+		}
+	})
+
+	t.Run("DialError", func(t *testing.T) {
+		t.Parallel()
+
+		if runtime.GOOS == "windows" {
+			// This test uses Unix listeners so we can very easily ensure that
+			// no other tests decide to listen on the same random port we
+			// picked.
+			t.Skip("this test is unsupported on Windows")
+			return
+		}
+
+		tmpDir, err := os.MkdirTemp("", "coderd_agent_test_")
+		require.NoError(t, err, "create temp dir")
+		t.Cleanup(func() {
+			_ = os.RemoveAll(tmpDir)
+		})
+
+		// Try to dial the non-existent Unix socket over WebRTC
+		conn := setupAgent(t, agent.Metadata{}, 0)
+		netConn, err := conn.DialContext(context.Background(), "unix", filepath.Join(tmpDir, "test.sock"))
+		require.Error(t, err)
+		require.ErrorContains(t, err, "remote dial error")
+		require.ErrorContains(t, err, "no such file")
+		require.Nil(t, netConn)
+	})
 }
 
 func setupSSHCommand(t *testing.T, beforeArgs []string, afterArgs []string) *exec.Cmd {
-	agentConn := setupAgent(t)
+	agentConn := setupAgent(t, agent.Metadata{}, 0)
 	listener, err := net.Listen("tcp", "127.0.0.1:0")
 	require.NoError(t, err)
 	go func() {
+		defer listener.Close()
 		for {
 			conn, err := listener.Accept()
 			if err != nil {
 				return
 			}
 			ssh, err := agentConn.SSH()
-			require.NoError(t, err)
-			go io.Copy(conn, ssh)
-			go io.Copy(ssh, conn)
+			if !assert.NoError(t, err) {
+				_ = conn.Close()
+				return
+			}
+			go agent.Bicopy(context.Background(), conn, ssh)
 		}
 	}()
 	t.Cleanup(func() {
@@ -163,20 +497,22 @@ func setupSSHCommand(t *testing.T, beforeArgs []string, afterArgs []string) *exe
 	return exec.Command("ssh", args...)
 }
 
-func setupSSHSession(t *testing.T) *ssh.Session {
-	sshClient, err := setupAgent(t).SSHClient()
+func setupSSHSession(t *testing.T, options agent.Metadata) *ssh.Session {
+	sshClient, err := setupAgent(t, options, 0).SSHClient()
 	require.NoError(t, err)
 	session, err := sshClient.NewSession()
 	require.NoError(t, err)
 	return session
 }
 
-func setupAgent(t *testing.T) *agent.Conn {
+func setupAgent(t *testing.T, metadata agent.Metadata, ptyTimeout time.Duration) *agent.Conn {
 	client, server := provisionersdk.TransportPipe()
-	closer := agent.New(func(ctx context.Context, opts *peer.ConnOptions) (*peerbroker.Listener, error) {
-		return peerbroker.Listen(server, nil, opts)
-	}, &peer.ConnOptions{
-		Logger: slogtest.Make(t, nil).Leveled(slog.LevelDebug),
+	closer := agent.New(func(ctx context.Context, logger slog.Logger) (agent.Metadata, *peerbroker.Listener, error) {
+		listener, err := peerbroker.Listen(server, nil)
+		return metadata, listener, err
+	}, &agent.Options{
+		Logger:                 slogtest.Make(t, nil).Leveled(slog.LevelDebug),
+		ReconnectingPTYTimeout: ptyTimeout,
 	})
 	t.Cleanup(func() {
 		_ = client.Close()
@@ -185,7 +521,7 @@ func setupAgent(t *testing.T) *agent.Conn {
 	})
 	api := proto.NewDRPCPeerBrokerClient(provisionersdk.Conn(client))
 	stream, err := api.NegotiateConnection(context.Background())
-	require.NoError(t, err)
+	assert.NoError(t, err)
 	conn, err := peerbroker.Dial(stream, []webrtc.ICEServer{}, &peer.ConnOptions{
 		Logger: slogtest.Make(t, nil),
 	})
@@ -199,3 +535,34 @@ func setupAgent(t *testing.T) *agent.Conn {
 		Conn:       conn,
 	}
 }
+
+var dialTestPayload = []byte("dean-was-here123")
+
+func testDial(t *testing.T, c net.Conn) {
+	t.Helper()
+
+	assertWritePayload(t, c, dialTestPayload)
+	assertReadPayload(t, c, dialTestPayload)
+}
+
+func testAccept(t *testing.T, c net.Conn) {
+	t.Helper()
+	defer c.Close()
+
+	assertReadPayload(t, c, dialTestPayload)
+	assertWritePayload(t, c, dialTestPayload)
+}
+
+func assertReadPayload(t *testing.T, r io.Reader, payload []byte) {
+	b := make([]byte, len(payload)+16)
+	n, err := r.Read(b)
+	assert.NoError(t, err, "read payload")
+	assert.Equal(t, len(payload), n, "read payload length does not match")
+	assert.Equal(t, payload, b[:n])
+}
+
+func assertWritePayload(t *testing.T, w io.Writer, payload []byte) {
+	n, err := w.Write(payload)
+	assert.NoError(t, err, "write payload")
+	assert.Equal(t, len(payload), n, "payload length does not match")
+}

agent/conn.go

@@ -2,7 +2,11 @@ package agent
 
 import (
 	"context"
+	"encoding/json"
+	"fmt"
 	"net"
+	"net/url"
+	"strings"
 
 	"golang.org/x/crypto/ssh"
 	"golang.org/x/xerrors"
@@ -11,6 +15,14 @@ import (
 	"github.com/coder/coder/peerbroker/proto"
 )
 
+// ReconnectingPTYRequest is sent from the client to the server
+// to pipe data to a PTY.
+type ReconnectingPTYRequest struct {
+	Data   string `json:"data"`
+	Height uint16 `json:"height"`
+	Width  uint16 `json:"width"`
+}
+
 // Conn wraps a peer connection with helper functions to
 // communicate with the agent.
 type Conn struct {
@@ -20,10 +32,24 @@ type Conn struct {
 	*peer.Conn
 }
 
+// ReconnectingPTY returns a connection serving a TTY that can
+// be reconnected to via ID.
+//
+// The command is optional and defaults to start a shell.
+func (c *Conn) ReconnectingPTY(id string, height, width uint16, command string) (net.Conn, error) {
+	channel, err := c.CreateChannel(context.Background(), fmt.Sprintf("%s:%d:%d:%s", id, height, width, command), &peer.ChannelOptions{
+		Protocol: ProtocolReconnectingPTY,
+	})
+	if err != nil {
+		return nil, xerrors.Errorf("pty: %w", err)
+	}
+	return channel.NetConn(), nil
+}
+
 // SSH dials the built-in SSH server.
 func (c *Conn) SSH() (net.Conn, error) {
-	channel, err := c.Dial(context.Background(), "ssh", &peer.ChannelOptions{
-		Protocol: "ssh",
+	channel, err := c.CreateChannel(context.Background(), "ssh", &peer.ChannelOptions{
+		Protocol: ProtocolSSH,
 	})
 	if err != nil {
 		return nil, xerrors.Errorf("dial: %w", err)
@@ -50,6 +76,42 @@ func (c *Conn) SSHClient() (*ssh.Client, error) {
 	return ssh.NewClient(sshConn, channels, requests), nil
 }
 
+// DialContext dials an arbitrary protocol+address from inside the workspace and
+// proxies it through the provided net.Conn.
+func (c *Conn) DialContext(ctx context.Context, network string, addr string) (net.Conn, error) {
+	u := &url.URL{
+		Scheme: network,
+	}
+	if strings.HasPrefix(network, "unix") {
+		u.Path = addr
+	} else {
+		u.Host = addr
+	}
+
+	channel, err := c.CreateChannel(ctx, u.String(), &peer.ChannelOptions{
+		Protocol:  ProtocolDial,
+		Unordered: strings.HasPrefix(network, "udp"),
+	})
+	if err != nil {
+		return nil, xerrors.Errorf("create datachannel: %w", err)
+	}
+
+	// The first message written from the other side is a JSON payload
+	// containing the dial error.
+	dec := json.NewDecoder(channel)
+	var res dialResponse
+	err = dec.Decode(&res)
+	if err != nil {
+		return nil, xerrors.Errorf("decode agent dial response: %w", err)
+	}
+	if res.Error != "" {
+		_ = channel.Close()
+		return nil, xerrors.Errorf("remote dial error: %v", res.Error)
+	}
+
+	return channel.NetConn(), nil
+}
+
 func (c *Conn) Close() error {
 	_ = c.Negotiator.DRPCConn().Close()
 	return c.Conn.Close()

agent/reaper/doc.go

@@ -0,0 +1,4 @@
+// Package reaper contains logic for reaping subprocesses. It is
+// specifically used in the agent to avoid the accumulation of
+// zombie processes.
+package reaper

agent/reaper/reaper.go

@@ -0,0 +1,28 @@
+package reaper
+
+import "github.com/hashicorp/go-reap"
+
+type Option func(o *options)
+
+// WithExecArgs specifies the exec arguments for the fork exec call.
+// By default the same arguments as the parent are used as dictated by
+// os.Args. Since ForkReap calls a fork-exec it is the responsibility of
+// the caller to avoid fork-bombing oneself.
+func WithExecArgs(args ...string) Option {
+	return func(o *options) {
+		o.ExecArgs = args
+	}
+}
+
+// WithPIDCallback sets the channel that reaped child process PIDs are pushed
+// onto.
+func WithPIDCallback(ch reap.PidCh) Option {
+	return func(o *options) {
+		o.PIDs = ch
+	}
+}
+
+type options struct {
+	ExecArgs []string
+	PIDs     reap.PidCh
+}

agent/reaper/reaper_stub.go

@@ -0,0 +1,12 @@
+//go:build !linux
+
+package reaper
+
+// IsInitProcess returns true if the current process's PID is 1.
+func IsInitProcess() bool {
+	return false
+}
+
+func ForkReap(_ ...Option) error {
+	return nil
+}

agent/reaper/reaper_test.go

@@ -0,0 +1,66 @@
+//go:build linux
+
+package reaper_test
+
+import (
+	"os"
+	"os/exec"
+	"testing"
+	"time"
+
+	"github.com/hashicorp/go-reap"
+	"github.com/stretchr/testify/require"
+
+	"github.com/coder/coder/agent/reaper"
+	"github.com/coder/coder/testutil"
+)
+
+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 {
+		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)
+
+		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)
+
+		err = cmd.Process.Kill()
+		require.NoError(t, err)
+
+		err = cmd2.Process.Kill()
+		require.NoError(t, err)
+
+		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)
+			}
+		}
+	})
+}

agent/reaper/reaper_unix.go

@@ -0,0 +1,63 @@
+//go:build linux
+
+package reaper
+
+import (
+	"os"
+	"syscall"
+
+	"github.com/hashicorp/go-reap"
+	"golang.org/x/xerrors"
+)
+
+// IsInitProcess returns true if the current process's PID is 1.
+func IsInitProcess() bool {
+	return os.Getpid() == 1
+}
+
+// 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
+// the reaper and an exec.Command waiting for its process to complete.
+// The provided 'pids' channel may be nil if the caller does not care about the
+// reaped children PIDs.
+func ForkReap(opt ...Option) error {
+	opts := &options{
+		ExecArgs: os.Args,
+	}
+
+	for _, o := range opt {
+		o(opts)
+	}
+
+	go reap.ReapChildren(opts.PIDs, nil, nil, nil)
+
+	pwd, err := os.Getwd()
+	if err != nil {
+		return xerrors.Errorf("get wd: %w", err)
+	}
+
+	pattrs := &syscall.ProcAttr{
+		Dir: pwd,
+		Env: os.Environ(),
+		Sys: &syscall.SysProcAttr{
+			Setsid: true,
+		},
+		Files: []uintptr{
+			uintptr(syscall.Stdin),
+			uintptr(syscall.Stdout),
+			uintptr(syscall.Stderr),
+		},
+	}
+
+	//#nosec G204
+	pid, _ := syscall.ForkExec(opts.ExecArgs[0], opts.ExecArgs, pattrs)
+
+	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
+}

agent/usershell/usershell_darwin.go

@@ -3,8 +3,6 @@ package usershell
 import "os"
 
 // Get returns the $SHELL environment variable.
-// TODO: This should use "dscl" to fetch the proper value. See:
-// https://stackoverflow.com/questions/16375519/how-to-get-the-default-shell
-func Get(username string) (string, error) {
+func Get(_ string) (string, error) {
 	return os.Getenv("SHELL"), nil
 }

agent/wireguard.go

@@ -0,0 +1,97 @@
+package agent
+
+import (
+	"context"
+	"net"
+	"strconv"
+
+	"golang.org/x/xerrors"
+	"inet.af/netaddr"
+
+	"cdr.dev/slog"
+	"github.com/coder/coder/peer/peerwg"
+)
+
+func (a *agent) startWireguard(ctx context.Context, addrs []netaddr.IPPrefix) error {
+	if a.network != nil {
+		_ = a.network.Close()
+		a.network = nil
+	}
+
+	// We can't create a wireguard network without these.
+	if len(addrs) == 0 || a.listenWireguardPeers == nil || a.postKeys == nil {
+		return xerrors.New("wireguard is enabled, but no addresses were provided or necessary functions were not provided")
+	}
+
+	wg, err := peerwg.New(a.logger.Named("wireguard"), addrs)
+	if err != nil {
+		return xerrors.Errorf("create wireguard network: %w", err)
+	}
+
+	// A new keypair is generated on each agent start.
+	// This keypair must be sent to Coder to allow for incoming connections.
+	err = a.postKeys(ctx, WireguardPublicKeys{
+		Public: wg.NodePrivateKey.Public(),
+		Disco:  wg.DiscoPublicKey,
+	})
+	if err != nil {
+		a.logger.Warn(ctx, "post keys", slog.Error(err))
+	}
+
+	go func() {
+		for {
+			ch, listenClose, err := a.listenWireguardPeers(ctx, a.logger)
+			if err != nil {
+				a.logger.Warn(ctx, "listen wireguard peers", slog.Error(err))
+				return
+			}
+
+			for {
+				peer, ok := <-ch
+				if !ok {
+					break
+				}
+
+				err := wg.AddPeer(peer)
+				a.logger.Info(ctx, "added wireguard peer", slog.F("peer", peer.NodePublicKey.ShortString()), slog.Error(err))
+			}
+
+			listenClose()
+		}
+	}()
+
+	a.startWireguardListeners(ctx, wg, []handlerPort{
+		{port: 12212, handler: a.sshServer.HandleConn},
+	})
+
+	a.network = wg
+	return nil
+}
+
+type handlerPort struct {
+	handler func(conn net.Conn)
+	port    uint16
+}
+
+func (a *agent) startWireguardListeners(ctx context.Context, network *peerwg.Network, handlers []handlerPort) {
+	for _, h := range handlers {
+		go func(h handlerPort) {
+			a.logger.Debug(ctx, "starting wireguard listener", slog.F("port", h.port))
+
+			listener, err := network.Listen("tcp", net.JoinHostPort("", strconv.Itoa(int(h.port))))
+			if err != nil {
+				a.logger.Warn(ctx, "listen wireguard", slog.F("port", h.port), slog.Error(err))
+				return
+			}
+
+			for {
+				conn, err := listener.Accept()
+				if err != nil {
+					return
+				}
+
+				go h.handler(conn)
+			}
+		}(h)
+	}
+}

buildinfo/buildinfo.go

@@ -1,8 +1,9 @@
 package buildinfo
 
 import (
-	"path"
+	"fmt"
 	"runtime/debug"
+	"strings"
 	"sync"
 	"time"
 
@@ -14,36 +15,73 @@ var (
 	buildInfoValid bool
 	readBuildInfo  sync.Once
 
+	externalURL     string
+	readExternalURL sync.Once
+
+	version     string
+	readVersion sync.Once
+
 	// Injected with ldflags at build!
 	tag string
 )
 
+const (
+	// develPrefix is prefixed to developer versions of the application.
+	develPrefix = "v0.0.0-devel"
+)
+
 // Version returns the semantic version of the build.
 // Use golang.org/x/mod/semver to compare versions.
 func Version() string {
-	revision, valid := revision()
-	if valid {
-		revision = "+" + revision[:7]
+	readVersion.Do(func() {
+		revision, valid := revision()
+		if valid {
+			revision = "+" + revision[:7]
+		}
+		if tag == "" {
+			// This occurs when the tag hasn't been injected,
+			// like when using "go run".
+			version = develPrefix + revision
+			return
+		}
+		version = "v" + tag
+		// The tag must be prefixed with "v" otherwise the
+		// semver library will return an empty string.
+		if semver.Build(version) == "" {
+			version += revision
+		}
+	})
+	return version
+}
+
+// VersionsMatch compares the two versions. It assumes the versions match if
+// the major and the minor versions are equivalent. Patch versions are
+// disregarded. If it detects that either version is a developer build it
+// returns true.
+func VersionsMatch(v1, v2 string) bool {
+	// Developer versions are disregarded...hopefully they know what they are
+	// doing.
+	if strings.HasPrefix(v1, develPrefix) || strings.HasPrefix(v2, develPrefix) {
+		return true
 	}
-	if tag == "" {
-		return "v0.0.0-devel" + revision
-	}
-	if semver.Build(tag) == "" {
-		tag += revision
-	}
-	return "v" + tag
+
+	return semver.MajorMinor(v1) == semver.MajorMinor(v2)
 }
 
 // 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.
 func ExternalURL() string {
-	repo := "https://github.com/coder/coder"
-	revision, valid := revision()
-	if !valid {
-		return repo
-	}
-	return path.Join(repo, "commit", revision)
+	readExternalURL.Do(func() {
+		repo := "https://github.com/coder/coder"
+		revision, valid := revision()
+		if !valid {
+			externalURL = repo
+			return
+		}
+		externalURL = fmt.Sprintf("%s/commit/%s", repo, revision)
+	})
+	return externalURL
 }
 
 // Time returns when the Git revision was published.

buildinfo/buildinfo_test.go

@@ -1,6 +1,7 @@
 package buildinfo_test
 
 import (
+	"fmt"
 	"testing"
 
 	"github.com/stretchr/testify/require"
@@ -29,4 +30,70 @@ func TestBuildInfo(t *testing.T) {
 		_, valid := buildinfo.Time()
 		require.False(t, valid)
 	})
+
+	t.Run("VersionsMatch", func(t *testing.T) {
+		t.Parallel()
+
+		type testcase struct {
+			name        string
+			v1          string
+			v2          string
+			expectMatch bool
+		}
+
+		cases := []testcase{
+			{
+				name:        "OK",
+				v1:          "v1.2.3",
+				v2:          "v1.2.3",
+				expectMatch: true,
+			},
+			// Test that we return true if a developer version is detected.
+			// Developers do not need to be warned of mismatched versions.
+			{
+				name:        "DevelIgnored",
+				v1:          "v0.0.0-devel+123abac",
+				v2:          "v1.2.3",
+				expectMatch: true,
+			},
+			// Our CI instance uses a "-devel" prerelease
+			// flag. This is not the same as a developer WIP build.
+			{
+				name:        "DevelPreleaseNotIgnored",
+				v1:          "v1.1.1-devel+123abac",
+				v2:          "v1.2.3",
+				expectMatch: false,
+			},
+			{
+				name:        "MajorMismatch",
+				v1:          "v1.2.3",
+				v2:          "v0.1.2",
+				expectMatch: false,
+			},
+			{
+				name:        "MinorMismatch",
+				v1:          "v1.2.3",
+				v2:          "v1.3.2",
+				expectMatch: false,
+			},
+			// Different patches are ok, breaking changes are not allowed
+			// in patches.
+			{
+				name:        "PatchMismatch",
+				v1:          "v1.2.3+hash.whocares",
+				v2:          "v1.2.4+somestuff.hm.ok",
+				expectMatch: true,
+			},
+		}
+
+		for _, c := range cases {
+			c := c
+			t.Run(c.name, func(t *testing.T) {
+				t.Parallel()
+				require.Equal(t, c.expectMatch, buildinfo.VersionsMatch(c.v1, c.v2),
+					fmt.Sprintf("expected match=%v for version %s and %s", c.expectMatch, c.v1, c.v2),
+				)
+			})
+		}
+	})
 }

cli/agent.go

@@ -0,0 +1,197 @@
+package cli
+
+import (
+	"context"
+	"fmt"
+	"net/http"
+	_ "net/http/pprof" //nolint: gosec
+	"net/url"
+	"os"
+	"path/filepath"
+	"runtime"
+	"time"
+
+	"cloud.google.com/go/compute/metadata"
+	"github.com/spf13/cobra"
+	"golang.org/x/xerrors"
+	"gopkg.in/natefinch/lumberjack.v2"
+
+	"cdr.dev/slog"
+	"cdr.dev/slog/sloggers/sloghuman"
+	"github.com/coder/coder/agent"
+	"github.com/coder/coder/agent/reaper"
+	"github.com/coder/coder/cli/cliflag"
+	"github.com/coder/coder/codersdk"
+	"github.com/coder/retry"
+)
+
+func workspaceAgent() *cobra.Command {
+	var (
+		auth         string
+		pprofEnabled bool
+		pprofAddress string
+		noReap       bool
+		wireguard    bool
+	)
+	cmd := &cobra.Command{
+		Use: "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)
+			}
+
+			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)
+
+			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")
+				// 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...))
+				if err != nil {
+					logger.Error(cmd.Context(), "failed to reap", slog.Error(err))
+					return xerrors.Errorf("fork reap: %w", err)
+				}
+
+				logger.Info(cmd.Context(), "reaper process exiting")
+				return nil
+			}
+
+			logger.Info(cmd.Context(), "starting agent", slog.F("url", coderURL), slog.F("auth", auth))
+			client := codersdk.New(coderURL)
+
+			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()
+			}
+
+			// 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)
+			switch auth {
+			case "token":
+				token, err := cmd.Flags().GetString(varAgentToken)
+				if err != nil {
+					return xerrors.Errorf("CODER_AGENT_TOKEN must be set for token auth: %w", err)
+				}
+				client.SessionToken = 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")
+				if gcpClientRaw != nil {
+					gcpClient, _ = gcpClientRaw.(*metadata.Client)
+				}
+				exchangeToken = func(ctx context.Context) (codersdk.WorkspaceAgentAuthenticateResponse, error) {
+					return client.AuthWorkspaceGoogleInstanceIdentity(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")
+				if awsClientRaw != nil {
+					awsClient, _ = awsClientRaw.(*http.Client)
+					if awsClient != nil {
+						client.HTTPClient = awsClient
+					}
+				}
+				exchangeToken = func(ctx context.Context) (codersdk.WorkspaceAgentAuthenticateResponse, error) {
+					return client.AuthWorkspaceAWSInstanceIdentity(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")
+				if azureClientRaw != nil {
+					azureClient, _ = azureClientRaw.(*http.Client)
+					if azureClient != nil {
+						client.HTTPClient = azureClient
+					}
+				}
+				exchangeToken = func(ctx context.Context) (codersdk.WorkspaceAgentAuthenticateResponse, error) {
+					return client.AuthWorkspaceAzureInstanceIdentity(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)
+				}
+			}
+
+			executablePath, err := os.Executable()
+			if err != nil {
+				return xerrors.Errorf("getting os executable: %w", err)
+			}
+			err = os.Setenv("PATH", fmt.Sprintf("%s%c%s", os.Getenv("PATH"), filepath.ListSeparator, filepath.Dir(executablePath)))
+			if err != nil {
+				return xerrors.Errorf("add executable to $PATH: %w", err)
+			}
+
+			closer := agent.New(client.ListenWorkspaceAgent, &agent.Options{
+				Logger: logger,
+				EnvironmentVariables: map[string]string{
+					// Override the "CODER_AGENT_TOKEN" variable in all
+					// shells so "gitssh" works!
+					"CODER_AGENT_TOKEN": client.SessionToken,
+				},
+				EnableWireguard:      wireguard,
+				UploadWireguardKeys:  client.UploadWorkspaceAgentKeys,
+				ListenWireguardPeers: client.WireguardPeerListener,
+			})
+			<-cmd.Context().Done()
+			return closer.Close()
+		},
+	}
+
+	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.")
+	cliflag.BoolVarP(cmd.Flags(), &wireguard, "wireguard", "", "CODER_AGENT_WIREGUARD", true, "Whether to start the Wireguard interface.")
+	return cmd
+}

cli/agent_test.go

@@ -8,22 +8,21 @@ import (
 
 	"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"
 )
 
 func TestWorkspaceAgent(t *testing.T) {
 	t.Parallel()
-	t.Run("AWS", func(t *testing.T) {
+	t.Run("Azure", func(t *testing.T) {
 		t.Parallel()
 		instanceID := "instanceidentifier"
-		certificates, metadataClient := coderdtest.NewAWSInstanceIdentity(t, instanceID)
+		certificates, metadataClient := coderdtest.NewAzureInstanceIdentity(t, instanceID)
 		client := coderdtest.New(t, &coderdtest.Options{
-			AWSInstanceIdentity: certificates,
+			AzureCertificates:   certificates,
+			IncludeProvisionerD: true,
 		})
 		user := coderdtest.CreateFirstUser(t, client)
-		coderdtest.NewProvisionerDaemon(t, client)
 		version := coderdtest.CreateTemplateVersion(t, client, user.OrganizationID, &echo.Responses{
 			Parse: echo.ParseComplete,
 			Provision: []*proto.Provision_Response{{
@@ -44,29 +43,85 @@ func TestWorkspaceAgent(t *testing.T) {
 		})
 		template := coderdtest.CreateTemplate(t, client, user.OrganizationID, version.ID)
 		coderdtest.AwaitTemplateVersionJob(t, client, version.ID)
-		workspace := coderdtest.CreateWorkspace(t, client, codersdk.Me, template.ID)
+		workspace := coderdtest.CreateWorkspace(t, client, user.OrganizationID, template.ID)
 		coderdtest.AwaitWorkspaceBuildJob(t, client, workspace.LatestBuild.ID)
 
-		cmd, _ := clitest.New(t, "workspaces", "agent", "--auth", "aws-instance-identity", "--url", client.URL.String())
+		cmd, _ := clitest.New(t, "agent", "--auth", "azure-instance-identity", "--agent-url", client.URL.String(), "--wireguard=false")
 		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,
-			// but it seems reasonable for a one-off test.
-			// nolint
-			ctx = context.WithValue(ctx, "aws-client", metadataClient)
-			err := cmd.ExecuteContext(ctx)
-			require.NoError(t, err)
+			// 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)
 		}()
 		coderdtest.AwaitWorkspaceAgents(t, client, workspace.LatestBuild.ID)
 		resources, err := client.WorkspaceResourcesByBuild(ctx, workspace.LatestBuild.ID)
 		require.NoError(t, err)
-		dialer, err := client.DialWorkspaceAgent(ctx, resources[0].Agents[0].ID, nil, nil)
+		dialer, err := client.DialWorkspaceAgent(ctx, resources[0].Agents[0].ID, nil)
 		require.NoError(t, err)
 		defer dialer.Close()
 		_, err = dialer.Ping()
 		require.NoError(t, err)
 		cancelFunc()
+		err = <-errC
+		require.NoError(t, err)
+	})
+
+	t.Run("AWS", func(t *testing.T) {
+		t.Parallel()
+		instanceID := "instanceidentifier"
+		certificates, metadataClient := coderdtest.NewAWSInstanceIdentity(t, instanceID)
+		client := coderdtest.New(t, &coderdtest.Options{
+			AWSCertificates:     certificates,
+			IncludeProvisionerD: true,
+		})
+		user := coderdtest.CreateFirstUser(t, client)
+		version := coderdtest.CreateTemplateVersion(t, client, user.OrganizationID, &echo.Responses{
+			Parse: echo.ParseComplete,
+			Provision: []*proto.Provision_Response{{
+				Type: &proto.Provision_Response_Complete{
+					Complete: &proto.Provision_Complete{
+						Resources: []*proto.Resource{{
+							Name: "somename",
+							Type: "someinstance",
+							Agents: []*proto.Agent{{
+								Auth: &proto.Agent_InstanceId{
+									InstanceId: instanceID,
+								},
+							}},
+						}},
+					},
+				},
+			}},
+		})
+		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)
+
+		cmd, _ := clitest.New(t, "agent", "--auth", "aws-instance-identity", "--agent-url", client.URL.String(), "--wireguard=false")
+		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)
+		}()
+		coderdtest.AwaitWorkspaceAgents(t, client, workspace.LatestBuild.ID)
+		resources, err := client.WorkspaceResourcesByBuild(ctx, workspace.LatestBuild.ID)
+		require.NoError(t, err)
+		dialer, err := client.DialWorkspaceAgent(ctx, resources[0].Agents[0].ID, nil)
+		require.NoError(t, err)
+		defer dialer.Close()
+		_, err = dialer.Ping()
+		require.NoError(t, err)
+		cancelFunc()
+		err = <-errC
+		require.NoError(t, err)
 	})
 
 	t.Run("GoogleCloud", func(t *testing.T) {
@@ -74,10 +129,10 @@ func TestWorkspaceAgent(t *testing.T) {
 		instanceID := "instanceidentifier"
 		validator, metadata := coderdtest.NewGoogleInstanceIdentity(t, instanceID, false)
 		client := coderdtest.New(t, &coderdtest.Options{
-			GoogleInstanceIdentity: validator,
+			GoogleTokenValidator: validator,
+			IncludeProvisionerD:  true,
 		})
 		user := coderdtest.CreateFirstUser(t, client)
-		coderdtest.NewProvisionerDaemon(t, client)
 		version := coderdtest.CreateTemplateVersion(t, client, user.OrganizationID, &echo.Responses{
 			Parse: echo.ParseComplete,
 			Provision: []*proto.Provision_Response{{
@@ -98,28 +153,29 @@ func TestWorkspaceAgent(t *testing.T) {
 		})
 		template := coderdtest.CreateTemplate(t, client, user.OrganizationID, version.ID)
 		coderdtest.AwaitTemplateVersionJob(t, client, version.ID)
-		workspace := coderdtest.CreateWorkspace(t, client, codersdk.Me, template.ID)
+		workspace := coderdtest.CreateWorkspace(t, client, user.OrganizationID, template.ID)
 		coderdtest.AwaitWorkspaceBuildJob(t, client, workspace.LatestBuild.ID)
 
-		cmd, _ := clitest.New(t, "workspaces", "agent", "--auth", "google-instance-identity", "--url", client.URL.String())
+		cmd, _ := clitest.New(t, "agent", "--auth", "google-instance-identity", "--agent-url", client.URL.String(), "--wireguard=false")
 		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,
-			// but it seems reasonable for a one-off test.
-			// nolint
-			ctx = context.WithValue(ctx, "gcp-client", metadata)
-			err := cmd.ExecuteContext(ctx)
-			require.NoError(t, err)
+			// 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)
 		}()
 		coderdtest.AwaitWorkspaceAgents(t, client, workspace.LatestBuild.ID)
 		resources, err := client.WorkspaceResourcesByBuild(ctx, workspace.LatestBuild.ID)
 		require.NoError(t, err)
-		dialer, err := client.DialWorkspaceAgent(ctx, resources[0].Agents[0].ID, nil, nil)
+		dialer, err := client.DialWorkspaceAgent(ctx, resources[0].Agents[0].ID, nil)
 		require.NoError(t, err)
 		defer dialer.Close()
 		_, err = dialer.Ping()
 		require.NoError(t, err)
 		cancelFunc()
+		err = <-errC
+		require.NoError(t, err)
 	})
 }

cli/agent_unix.go

@@ -0,0 +1,38 @@
+//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

@@ -0,0 +1,12 @@
+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/cliflag/cliflag.go

@@ -6,18 +6,52 @@
 //
 // 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")
-//
+//	-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"
 )
 
+// 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)
@@ -27,6 +61,18 @@ func StringVarP(flagset *pflag.FlagSet, p *string, name string, shorthand string
 	flagset.StringVarP(p, name, shorthand, v, 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)
@@ -44,6 +90,22 @@ func Uint8VarP(flagset *pflag.FlagSet, ptr *uint8, name string, shorthand string
 	flagset.Uint8VarP(ptr, name, shorthand, uint8(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)
@@ -61,10 +123,32 @@ func BoolVarP(flagset *pflag.FlagSet, ptr *bool, name string, shorthand string,
 	flagset.BoolVarP(ptr, name, shorthand, valb, fmtUsage(usage, env))
 }
 
-func fmtUsage(u string, env string) string {
-	if env == "" {
-		return fmt.Sprintf("%s.", u)
+// 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
 	}
 
-	return fmt.Sprintf("%s - consumes $%s.", u, env)
+	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\nConsumes $%s", u, dot, env)
+	}
+
+	return u
 }

cli/cliflag/cliflag_test.go

@@ -4,6 +4,7 @@ import (
 	"fmt"
 	"strconv"
 	"testing"
+	"time"
 
 	"github.com/spf13/pflag"
 	"github.com/stretchr/testify/require"
@@ -13,9 +14,32 @@ import (
 )
 
 // 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)
@@ -25,10 +49,10 @@ func TestCliflag(t *testing.T) {
 		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))
+		require.Contains(t, flagset.FlagUsages(), fmt.Sprintf("Consumes $%s", env))
 	})
 
-	t.Run("StringEnvVar", func(t *testing.T) {
+	t.Run("StringVarPEnvVar", func(t *testing.T) {
 		var ptr string
 		flagset, name, shorthand, env, usage := randomFlag()
 		envValue, _ := cryptorand.String(10)
@@ -51,7 +75,37 @@ func TestCliflag(t *testing.T) {
 		require.NoError(t, err)
 		require.Equal(t, def, got)
 		require.Contains(t, flagset.FlagUsages(), usage)
-		require.NotContains(t, flagset.FlagUsages(), " - consumes")
+		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("IntDefault", func(t *testing.T) {
@@ -64,7 +118,7 @@ func TestCliflag(t *testing.T) {
 		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))
+		require.Contains(t, flagset.FlagUsages(), fmt.Sprintf("Consumes $%s", env))
 	})
 
 	t.Run("IntEnvVar", func(t *testing.T) {
@@ -103,7 +157,7 @@ func TestCliflag(t *testing.T) {
 		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))
+		require.Contains(t, flagset.FlagUsages(), fmt.Sprintf("Consumes $%s", env))
 	})
 
 	t.Run("BoolEnvVar", func(t *testing.T) {
@@ -131,6 +185,45 @@ func TestCliflag(t *testing.T) {
 		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) {

cli/clitest/clitest.go

@@ -21,10 +21,22 @@ import (
 // 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) {
-	cmd := cli.Root()
+	return NewWithSubcommands(t, cli.AGPL(), 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...))
+
+	// We could consider using writers
+	// that log via t.Log here instead.
+	cmd.SetOut(io.Discard)
+	cmd.SetErr(io.Discard)
+
 	return cmd, root
 }
 

cli/clitest/clitest_test.go

@@ -3,7 +3,6 @@ package clitest_test
 import (
 	"testing"
 
-	"github.com/stretchr/testify/require"
 	"go.uber.org/goleak"
 
 	"github.com/coder/coder/cli/clitest"
@@ -25,8 +24,7 @@ func TestCli(t *testing.T) {
 	cmd.SetIn(pty.Input())
 	cmd.SetOut(pty.Output())
 	go func() {
-		err := cmd.Execute()
-		require.NoError(t, err)
+		_ = cmd.Execute()
 	}()
 	pty.ExpectMatch("coder")
 }

cli/cliui/agent.go

@@ -4,6 +4,8 @@ import (
 	"context"
 	"fmt"
 	"io"
+	"os"
+	"os/signal"
 	"sync"
 	"time"
 
@@ -46,6 +48,23 @@ func Agent(ctx context.Context, writer io.Writer, opts AgentOptions) error {
 	spin.Start()
 	defer spin.Stop()
 
+	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)
@@ -60,7 +79,7 @@ func Agent(ctx context.Context, writer io.Writer, opts AgentOptions) error {
 		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 run: " + Styles.Code.Render("coder workspaces rebuild "+opts.WorkspaceName)
+			message = "The workspace agent lost connection! Wait for it to reconnect or restart your workspace."
 		}
 		// This saves the cursor position, then defers clearing from the cursor
 		// position to the end of the screen.

cli/cliui/agent_test.go

@@ -6,7 +6,7 @@ import (
 	"time"
 
 	"github.com/spf13/cobra"
-	"github.com/stretchr/testify/require"
+	"github.com/stretchr/testify/assert"
 	"go.uber.org/atomic"
 
 	"github.com/coder/coder/cli/cliui"
@@ -43,7 +43,7 @@ func TestAgent(t *testing.T) {
 	go func() {
 		defer close(done)
 		err := cmd.Execute()
-		require.NoError(t, err)
+		assert.NoError(t, err)
 	}()
 	ptty.ExpectMatch("lost connection")
 	disconnected.Store(true)

cli/cliui/cliui.go

@@ -26,6 +26,7 @@ var Styles = struct {
 	Checkmark,
 	Code,
 	Crossmark,
+	DateTimeStamp,
 	Error,
 	Field,
 	Keyword,
@@ -33,7 +34,7 @@ var Styles = struct {
 	Placeholder,
 	Prompt,
 	FocusedPrompt,
-	Fuschia,
+	Fuchsia,
 	Logo,
 	Warn,
 	Wrap lipgloss.Style
@@ -42,15 +43,16 @@ var Styles = struct {
 	Checkmark:     defaultStyles.Checkmark,
 	Code:          defaultStyles.Code,
 	Crossmark:     defaultStyles.Error.Copy().SetString("✘"),
+	DateTimeStamp: defaultStyles.LabelDim,
 	Error:         defaultStyles.Error,
 	Field:         defaultStyles.Code.Copy().Foreground(lipgloss.AdaptiveColor{Light: "#000000", Dark: "#FFFFFF"}),
 	Keyword:       defaultStyles.Keyword,
 	Paragraph:     defaultStyles.Paragraph,
-	Placeholder:   lipgloss.NewStyle().Foreground(lipgloss.Color("240")),
+	Placeholder:   lipgloss.NewStyle().Foreground(lipgloss.AdaptiveColor{Light: "#585858", Dark: "#005fff"}),
 	Prompt:        defaultStyles.Prompt.Foreground(lipgloss.AdaptiveColor{Light: "#9B9B9B", Dark: "#5C5C5C"}),
 	FocusedPrompt: defaultStyles.FocusedPrompt.Foreground(lipgloss.Color("#651fff")),
-	Fuschia:       defaultStyles.SelectedMenuItem.Copy(),
+	Fuchsia:       defaultStyles.SelectedMenuItem.Copy(),
 	Logo:          defaultStyles.Logo.SetString("Coder"),
 	Warn:          lipgloss.NewStyle().Foreground(lipgloss.AdaptiveColor{Light: "#04B575", Dark: "#ECFD65"}),
-	Wrap:          defaultStyles.Wrap,
+	Wrap:          lipgloss.NewStyle().Width(80),
 }

cli/cliui/cliui_darwin.go

@@ -1,31 +0,0 @@
-//go:build darwin
-// +build darwin
-
-package cliui
-
-import (
-	"golang.org/x/sys/unix"
-
-	"golang.org/x/xerrors"
-)
-
-func removeLineLengthLimit(inputFD int) (func(), error) {
-	termios, err := unix.IoctlGetTermios(inputFD, unix.TIOCGETA)
-	if err != nil {
-		return nil, xerrors.Errorf("get termios: %w", err)
-	}
-	newState := *termios
-	// MacOS has a default line limit of 1024. See:
-	// https://unix.stackexchange.com/questions/204815/terminal-does-not-accept-pasted-or-typed-lines-of-more-than-1024-characters
-	//
-	// This removes canonical input processing, so deletes will not function
-	// as expected. This _seems_ fine for most use-cases, but is unfortunate.
-	newState.Lflag &^= unix.ICANON
-	err = unix.IoctlSetTermios(inputFD, unix.TIOCSETA, &newState)
-	if err != nil {
-		return nil, xerrors.Errorf("set termios: %w", err)
-	}
-	return func() {
-		_ = unix.IoctlSetTermios(inputFD, unix.TIOCSETA, termios)
-	}, nil
-}

cli/cliui/cliui_other.go

@@ -1,10 +0,0 @@
-//go:build !darwin
-// +build !darwin
-
-package cliui
-
-import "golang.org/x/xerrors"
-
-func removeLineLengthLimit(_ int) (func(), error) {
-	return nil, xerrors.New("not implemented")
-}

cli/cliui/parameter.go

@@ -10,7 +10,7 @@ import (
 	"github.com/coder/coder/codersdk"
 )
 
-func ParameterSchema(cmd *cobra.Command, parameterSchema codersdk.TemplateVersionParameterSchema) (string, error) {
+func ParameterSchema(cmd *cobra.Command, parameterSchema codersdk.ParameterSchema) (string, error) {
 	_, _ = fmt.Fprintln(cmd.OutOrStdout(), Styles.Bold.Render("var."+parameterSchema.Name))
 	if parameterSchema.Description != "" {
 		_, _ = fmt.Fprintln(cmd.OutOrStdout(), "  "+strings.TrimSpace(strings.Join(strings.Split(parameterSchema.Description, "\n"), "\n  "))+"\n")
@@ -30,6 +30,7 @@ func ParameterSchema(cmd *cobra.Command, parameterSchema codersdk.TemplateVersio
 		_, _ = fmt.Fprint(cmd.OutOrStdout(), "\033[1A")
 		value, err = Select(cmd, SelectOptions{
 			Options:    options,
+			Default:    parameterSchema.DefaultSourceValue,
 			HideSearch: true,
 		})
 		if err == nil {
@@ -37,9 +38,25 @@ func ParameterSchema(cmd *cobra.Command, parameterSchema codersdk.TemplateVersio
 			_, _ = fmt.Fprintln(cmd.OutOrStdout(), "  "+Styles.Prompt.String()+Styles.Field.Render(value))
 		}
 	} else {
+		text := "Enter a value"
+		if parameterSchema.DefaultSourceValue != "" {
+			text += fmt.Sprintf(" (default: %q)", parameterSchema.DefaultSourceValue)
+		}
+		text += ":"
+
 		value, err = Prompt(cmd, PromptOptions{
-			Text: Styles.Bold.Render("Enter a value:"),
+			Text: Styles.Bold.Render(text),
 		})
+		value = strings.TrimSpace(value)
 	}
-	return value, err
+	if err != nil {
+		return "", err
+	}
+
+	// If they didn't specify anything, use the default value if set.
+	if len(options) == 0 && value == "" {
+		value = parameterSchema.DefaultSourceValue
+	}
+
+	return value, nil
 }

cli/cliui/prompt.go

@@ -7,7 +7,6 @@ import (
 	"fmt"
 	"os"
 	"os/signal"
-	"runtime"
 	"strings"
 
 	"github.com/bgentry/speakeasy"
@@ -25,18 +24,45 @@ type PromptOptions struct {
 	Validate  func(string) error
 }
 
+const skipPromptFlag = "yes"
+
+func AllowSkipPrompt(cmd *cobra.Command) {
+	cmd.Flags().BoolP(skipPromptFlag, "y", false, "Bypass prompts")
+}
+
+const (
+	ConfirmYes = "yes"
+	ConfirmNo  = "no"
+)
+
 // Prompt asks the user for input.
 func Prompt(cmd *cobra.Command, 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 {
+			return ConfirmYes, nil
+		}
+	}
+
 	_, _ = fmt.Fprint(cmd.OutOrStdout(), Styles.FocusedPrompt.String()+opts.Text+" ")
 	if opts.IsConfirm {
-		opts.Default = "yes"
-		_, _ = fmt.Fprint(cmd.OutOrStdout(), Styles.Placeholder.Render("("+Styles.Bold.Render("yes")+Styles.Placeholder.Render("/no) ")))
+		if len(opts.Default) == 0 {
+			opts.Default = ConfirmYes
+		}
+		renderedYes := Styles.Placeholder.Render(ConfirmYes)
+		renderedNo := Styles.Placeholder.Render(ConfirmNo)
+		if opts.Default == ConfirmYes {
+			renderedYes = Styles.Bold.Render(ConfirmYes)
+		} else {
+			renderedNo = Styles.Bold.Render(ConfirmNo)
+		}
+		_, _ = fmt.Fprint(cmd.OutOrStdout(), Styles.Placeholder.Render("("+renderedYes+Styles.Placeholder.Render("/"+renderedNo+Styles.Placeholder.Render(") "))))
 	} else if opts.Default != "" {
 		_, _ = fmt.Fprint(cmd.OutOrStdout(), Styles.Placeholder.Render("("+opts.Default+") "))
 	}
 	interrupt := make(chan os.Signal, 1)
-	signal.Notify(interrupt, os.Interrupt)
-	defer signal.Stop(interrupt)
 
 	errCh := make(chan error, 1)
 	lineCh := make(chan string)
@@ -46,17 +72,11 @@ func Prompt(cmd *cobra.Command, opts PromptOptions) (string, error) {
 
 		inFile, isInputFile := cmd.InOrStdin().(*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("")
 		} else {
-			if !opts.IsConfirm && runtime.GOOS == "darwin" && isInputFile {
-				var restore func()
-				restore, err = removeLineLengthLimit(int(inFile.Fd()))
-				if err != nil {
-					errCh <- err
-					return
-				}
-				defer restore()
-			}
+			signal.Notify(interrupt, os.Interrupt)
+			defer signal.Stop(interrupt)
 
 			reader := bufio.NewReader(cmd.InOrStdin())
 			line, err = reader.ReadString('\n')

cli/cliui/prompt_test.go

@@ -1,14 +1,21 @@
 package cliui_test
 
 import (
+	"bytes"
 	"context"
+	"io"
+	"os"
+	"os/exec"
 	"testing"
 
 	"github.com/spf13/cobra"
+	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 
 	"github.com/coder/coder/cli/cliui"
+	"github.com/coder/coder/pty"
 	"github.com/coder/coder/pty/ptytest"
+	"github.com/coder/coder/testutil"
 )
 
 func TestPrompt(t *testing.T) {
@@ -20,8 +27,8 @@ func TestPrompt(t *testing.T) {
 		go func() {
 			resp, err := newPrompt(ptty, cliui.PromptOptions{
 				Text: "Example",
-			})
-			require.NoError(t, err)
+			}, nil)
+			assert.NoError(t, err)
 			msgChan <- resp
 		}()
 		ptty.ExpectMatch("Example")
@@ -37,8 +44,8 @@ func TestPrompt(t *testing.T) {
 			resp, err := newPrompt(ptty, cliui.PromptOptions{
 				Text:      "Example",
 				IsConfirm: true,
-			})
-			require.NoError(t, err)
+			}, nil)
+			assert.NoError(t, err)
 			doneChan <- resp
 		}()
 		ptty.ExpectMatch("Example")
@@ -46,6 +53,47 @@ func TestPrompt(t *testing.T) {
 		require.Equal(t, "yes", <-doneChan)
 	})
 
+	t.Run("Skip", func(t *testing.T) {
+		t.Parallel()
+		ptty := ptytest.New(t)
+		var buf bytes.Buffer
+
+		// Copy all data written out to a buffer. When we close the ptty, we can
+		// no longer read from the ptty.Output(), but we can read what was
+		// written to the buffer.
+		dataRead, doneReading := context.WithTimeout(context.Background(), testutil.WaitShort)
+		go func() {
+			// This will throw an error sometimes. The underlying ptty
+			// has its own cleanup routines in t.Cleanup. Instead of
+			// trying to control the close perfectly, just let the ptty
+			// double close. This error isn't important, we just
+			// want to know the ptty is done sending output.
+			_, _ = io.Copy(&buf, ptty.Output())
+			doneReading()
+		}()
+
+		doneChan := make(chan string)
+		go func() {
+			resp, err := newPrompt(ptty, cliui.PromptOptions{
+				Text:      "ShouldNotSeeThis",
+				IsConfirm: true,
+			}, func(cmd *cobra.Command) {
+				cliui.AllowSkipPrompt(cmd)
+				cmd.SetArgs([]string{"-y"})
+			})
+			assert.NoError(t, err)
+			doneChan <- resp
+		}()
+
+		require.Equal(t, "yes", <-doneChan)
+		// Close the reader to end the io.Copy
+		require.NoError(t, ptty.Close(), "close eof reader")
+		// Wait for the IO copy to finish
+		<-dataRead.Done()
+		// Timeout error means the output was hanging
+		require.ErrorIs(t, dataRead.Err(), context.Canceled, "should be canceled")
+		require.Len(t, buf.Bytes(), 0, "expect no output")
+	})
 	t.Run("JSON", func(t *testing.T) {
 		t.Parallel()
 		ptty := ptytest.New(t)
@@ -53,8 +101,8 @@ func TestPrompt(t *testing.T) {
 		go func() {
 			resp, err := newPrompt(ptty, cliui.PromptOptions{
 				Text: "Example",
-			})
-			require.NoError(t, err)
+			}, nil)
+			assert.NoError(t, err)
 			doneChan <- resp
 		}()
 		ptty.ExpectMatch("Example")
@@ -69,8 +117,8 @@ func TestPrompt(t *testing.T) {
 		go func() {
 			resp, err := newPrompt(ptty, cliui.PromptOptions{
 				Text: "Example",
-			})
-			require.NoError(t, err)
+			}, nil)
+			assert.NoError(t, err)
 			doneChan <- resp
 		}()
 		ptty.ExpectMatch("Example")
@@ -85,8 +133,8 @@ func TestPrompt(t *testing.T) {
 		go func() {
 			resp, err := newPrompt(ptty, cliui.PromptOptions{
 				Text: "Example",
-			})
-			require.NoError(t, err)
+			}, nil)
+			assert.NoError(t, err)
 			doneChan <- resp
 		}()
 		ptty.ExpectMatch("Example")
@@ -97,7 +145,7 @@ func TestPrompt(t *testing.T) {
 	})
 }
 
-func newPrompt(ptty *ptytest.PTY, opts cliui.PromptOptions) (string, error) {
+func newPrompt(ptty *ptytest.PTY, opts cliui.PromptOptions, cmdOpt func(cmd *cobra.Command)) (string, error) {
 	value := ""
 	cmd := &cobra.Command{
 		RunE: func(cmd *cobra.Command, args []string) error {
@@ -106,7 +154,67 @@ func newPrompt(ptty *ptytest.PTY, opts cliui.PromptOptions) (string, error) {
 			return err
 		},
 	}
-	cmd.SetOutput(ptty.Output())
+	// Optionally modify the cmd
+	if cmdOpt != nil {
+		cmdOpt(cmd)
+	}
+	cmd.SetOut(ptty.Output())
+	cmd.SetErr(ptty.Output())
 	cmd.SetIn(ptty.Input())
 	return value, cmd.ExecuteContext(context.Background())
 }
+
+func TestPasswordTerminalState(t *testing.T) {
+	if os.Getenv("TEST_SUBPROCESS") == "1" {
+		passwordHelper()
+		return
+	}
+	t.Parallel()
+
+	ptty := ptytest.New(t)
+	ptyWithFlags, ok := ptty.PTY.(pty.WithFlags)
+	if !ok {
+		t.Skip("unable to check PTY local echo on this platform")
+	}
+
+	cmd := exec.Command(os.Args[0], "-test.run=TestPasswordTerminalState") //nolint:gosec
+	cmd.Env = append(os.Environ(), "TEST_SUBPROCESS=1")
+	// connect the child process's stdio to the PTY directly, not via a pipe
+	cmd.Stdin = ptty.Input().Reader
+	cmd.Stdout = ptty.Output().Writer
+	cmd.Stderr = ptty.Output().Writer
+	err := cmd.Start()
+	require.NoError(t, err)
+	process := cmd.Process
+	defer process.Kill()
+
+	ptty.ExpectMatch("Password: ")
+
+	require.Eventually(t, func() bool {
+		echo, err := ptyWithFlags.EchoEnabled()
+		return err == nil && !echo
+	}, testutil.WaitShort, testutil.IntervalMedium, "echo is on while reading password")
+
+	err = process.Signal(os.Interrupt)
+	require.NoError(t, err)
+	_, err = process.Wait()
+	require.NoError(t, err)
+
+	require.Eventually(t, func() bool {
+		echo, err := ptyWithFlags.EchoEnabled()
+		return err == nil && echo
+	}, testutil.WaitShort, testutil.IntervalMedium, "echo is off after reading password")
+}
+
+// nolint:unused
+func passwordHelper() {
+	cmd := &cobra.Command{
+		Run: func(cmd *cobra.Command, args []string) {
+			cliui.Prompt(cmd, cliui.PromptOptions{
+				Text:   "Password:",
+				Secret: true,
+			})
+		},
+	}
+	cmd.ExecuteContext(context.Background())
+}

cli/cliui/provisionerjob.go

@@ -1,6 +1,7 @@
 package cliui
 
 import (
+	"bytes"
 	"context"
 	"fmt"
 	"io"
@@ -12,7 +13,6 @@ import (
 	"github.com/google/uuid"
 	"golang.org/x/xerrors"
 
-	"github.com/coder/coder/coderd/database"
 	"github.com/coder/coder/codersdk"
 )
 
@@ -36,6 +36,9 @@ type ProvisionerJobOptions struct {
 	FetchInterval time.Duration
 	// Verbose determines whether debug and trace logs will be shown.
 	Verbose bool
+	// Silent determines whether log output will be shown unless there is an
+	// error.
+	Silent bool
 }
 
 // ProvisionerJob renders a provisioner job with interactive cancellation.
@@ -134,12 +137,30 @@ func ProvisionerJob(ctx context.Context, writer io.Writer, opts ProvisionerJobOp
 		return xerrors.Errorf("logs: %w", err)
 	}
 
+	var (
+		// logOutput is where log output is written
+		logOutput = writer
+		// logBuffer is where logs are buffered if opts.Silent is true
+		logBuffer = &bytes.Buffer{}
+	)
+	if opts.Silent {
+		logOutput = logBuffer
+	}
+	flushLogBuffer := func() {
+		if opts.Silent {
+			_, _ = io.Copy(writer, logBuffer)
+		}
+	}
+
 	ticker := time.NewTicker(opts.FetchInterval)
+	defer ticker.Stop()
 	for {
 		select {
 		case err = <-errChan:
+			flushLogBuffer()
 			return err
 		case <-ctx.Done():
+			flushLogBuffer()
 			return ctx.Err()
 		case <-ticker.C:
 			updateJob()
@@ -161,30 +182,35 @@ func ProvisionerJob(ctx context.Context, writer io.Writer, opts ProvisionerJobOp
 				}
 				err = xerrors.New(job.Error)
 				jobMutex.Unlock()
+				flushLogBuffer()
 				return err
 			}
+
 			output := ""
 			switch log.Level {
-			case database.LogLevelTrace, database.LogLevelDebug:
+			case codersdk.LogLevelTrace, codersdk.LogLevelDebug:
 				if !opts.Verbose {
 					continue
 				}
 				output = Styles.Placeholder.Render(log.Output)
-			case database.LogLevelError:
+			case codersdk.LogLevelError:
 				output = defaultStyles.Error.Render(log.Output)
-			case database.LogLevelWarn:
+			case codersdk.LogLevelWarn:
 				output = Styles.Warn.Render(log.Output)
-			case database.LogLevelInfo:
+			case codersdk.LogLevelInfo:
 				output = log.Output
 			}
+
 			jobMutex.Lock()
 			if log.Stage != currentStage && log.Stage != "" {
 				updateStage(log.Stage, log.CreatedAt)
 				jobMutex.Unlock()
 				continue
 			}
-			_, _ = fmt.Fprintf(writer, "%s %s\n", Styles.Placeholder.Render(" "), output)
-			didLogBetweenStage = true
+			_, _ = fmt.Fprintf(logOutput, "%s %s\n", Styles.Placeholder.Render(" "), output)
+			if !opts.Silent {
+				didLogBetweenStage = true
+			}
 			jobMutex.Unlock()
 		}
 	}

cli/cliui/provisionerjob_test.go

@@ -9,7 +9,7 @@ import (
 	"time"
 
 	"github.com/spf13/cobra"
-	"github.com/stretchr/testify/require"
+	"github.com/stretchr/testify/assert"
 
 	"github.com/coder/coder/cli/cliui"
 	"github.com/coder/coder/coderd/database"
@@ -90,9 +90,9 @@ func TestProvisionerJob(t *testing.T) {
 		go func() {
 			<-test.Next
 			currentProcess, err := os.FindProcess(os.Getpid())
-			require.NoError(t, err)
+			assert.NoError(t, err)
 			err = currentProcess.Signal(os.Interrupt)
-			require.NoError(t, err)
+			assert.NoError(t, err)
 			<-test.Next
 			test.JobMutex.Lock()
 			test.Job.Status = codersdk.ProvisionerJobCanceled
@@ -150,7 +150,7 @@ func newProvisionerJob(t *testing.T) provisionerJobTest {
 		defer close(done)
 		err := cmd.ExecuteContext(context.Background())
 		if err != nil {
-			require.ErrorIs(t, err, cliui.Canceled)
+			assert.ErrorIs(t, err, cliui.Canceled)
 		}
 	}()
 	t.Cleanup(func() {

cli/cliui/resources.go

@@ -9,6 +9,7 @@ import (
 	"github.com/jedib0t/go-pretty/v6/table"
 
 	"github.com/coder/coder/coderd/database"
+
 	"github.com/coder/coder/codersdk"
 )
 
@@ -23,12 +24,12 @@ type WorkspaceResourcesOptions struct {
 // ┌────────────────────────────────────────────────────────────────────────────┐
 // │ RESOURCE                     STATUS               ACCESS                   │
 // ├────────────────────────────────────────────────────────────────────────────┤
-// │ google_compute_disk.root     persistent                                    │
+// │ google_compute_disk.root                                                   │
 // ├────────────────────────────────────────────────────────────────────────────┤
-// │ google_compute_instance.dev  ephemeral                                     │
+// │ google_compute_instance.dev                                                │
 // │ └─ dev (linux, amd64)        ⦾ connecting [10s]    coder ssh dev.dev       │
 // ├────────────────────────────────────────────────────────────────────────────┤
-// │ kubernetes_pod.dev           ephemeral                                     │
+// │ kubernetes_pod.dev                                                         │
 // │ ├─ go (linux, amd64)         ⦿ connected           coder ssh dev.go        │
 // │ └─ postgres (linux, amd64)   ⦾ disconnected [4s]   coder ssh dev.postgres  │
 // └────────────────────────────────────────────────────────────────────────────┘
@@ -38,26 +39,16 @@ func WorkspaceResources(writer io.Writer, resources []codersdk.WorkspaceResource
 		return resources[i].Type < resources[j].Type
 	})
 
-	// Address on stop indexes whether a resource still exists when in the stopped transition.
-	addressOnStop := map[string]codersdk.WorkspaceResource{}
-	for _, resource := range resources {
-		if resource.Transition != database.WorkspaceTransitionStop {
-			continue
-		}
-		addressOnStop[resource.Address] = resource
-	}
-	// Displayed stores whether a resource has already been shown.
-	// Resources can be stored with numerous states, which we
-	// process prior to display.
-	displayed := map[string]struct{}{}
-
 	tableWriter := table.NewWriter()
 	if options.Title != "" {
 		tableWriter.SetTitle(options.Title)
 	}
 	tableWriter.SetStyle(table.StyleLight)
 	tableWriter.Style().Options.SeparateColumns = false
-	row := table.Row{"Resource", "Status"}
+	row := table.Row{"Resource"}
+	if !options.HideAgentState {
+		row = append(row, "Status")
+	}
 	if !options.HideAccess {
 		row = append(row, "Access")
 	}
@@ -75,50 +66,21 @@ func WorkspaceResources(writer io.Writer, resources []codersdk.WorkspaceResource
 			// callers to hide resources eventually.
 			continue
 		}
-		if _, shown := displayed[resource.Address]; shown {
-			// The same resource can have multiple transitions.
-			continue
-		}
-		displayed[resource.Address] = struct{}{}
+		resourceAddress := resource.Type + "." + resource.Name
 
 		// Sort agents by name for consistent output.
 		sort.Slice(resource.Agents, func(i, j int) bool {
 			return resource.Agents[i].Name < resource.Agents[j].Name
 		})
-		_, existsOnStop := addressOnStop[resource.Address]
-		resourceState := "ephemeral"
-		if existsOnStop {
-			resourceState = "persistent"
-		}
+
 		// Display a line for the resource.
 		tableWriter.AppendRow(table.Row{
-			Styles.Bold.Render(resource.Type + "." + resource.Name),
-			Styles.Placeholder.Render(resourceState),
+			Styles.Bold.Render(resourceAddress),
+			"",
 			"",
 		})
 		// Display all agents associated with the resource.
 		for index, agent := range resource.Agents {
-			sshCommand := "coder ssh " + options.WorkspaceName
-			if totalAgents > 1 {
-				sshCommand += "." + agent.Name
-			}
-			sshCommand = Styles.Code.Render(sshCommand)
-			var agentStatus string
-			if !options.HideAgentState {
-				switch agent.Status {
-				case codersdk.WorkspaceAgentConnecting:
-					since := database.Now().Sub(agent.CreatedAt)
-					agentStatus = Styles.Warn.Render("⦾ connecting") + " " +
-						Styles.Placeholder.Render("["+strconv.Itoa(int(since.Seconds()))+"s]")
-				case codersdk.WorkspaceAgentDisconnected:
-					since := database.Now().Sub(*agent.DisconnectedAt)
-					agentStatus = Styles.Error.Render("⦾ disconnected") + " " +
-						Styles.Placeholder.Render("["+strconv.Itoa(int(since.Seconds()))+"s]")
-				case codersdk.WorkspaceAgentConnected:
-					agentStatus = Styles.Keyword.Render("⦿ connected")
-				}
-			}
-
 			pipe := "├"
 			if index == len(resource.Agents)-1 {
 				pipe = "└"
@@ -126,9 +88,31 @@ func WorkspaceResources(writer io.Writer, resources []codersdk.WorkspaceResource
 			row := table.Row{
 				// These tree from a resource!
 				fmt.Sprintf("%s─ %s (%s, %s)", pipe, agent.Name, agent.OperatingSystem, agent.Architecture),
-				agentStatus,
+			}
+			if !options.HideAgentState {
+				var agentStatus string
+				if !options.HideAgentState {
+					switch agent.Status {
+					case codersdk.WorkspaceAgentConnecting:
+						since := database.Now().Sub(agent.CreatedAt)
+						agentStatus = Styles.Warn.Render("⦾ connecting") + " " +
+							Styles.Placeholder.Render("["+strconv.Itoa(int(since.Seconds()))+"s]")
+					case codersdk.WorkspaceAgentDisconnected:
+						since := database.Now().Sub(*agent.DisconnectedAt)
+						agentStatus = Styles.Error.Render("⦾ disconnected") + " " +
+							Styles.Placeholder.Render("["+strconv.Itoa(int(since.Seconds()))+"s]")
+					case codersdk.WorkspaceAgentConnected:
+						agentStatus = Styles.Keyword.Render("⦿ connected")
+					}
+				}
+				row = append(row, agentStatus)
 			}
 			if !options.HideAccess {
+				sshCommand := "coder ssh " + options.WorkspaceName
+				if totalAgents > 1 {
+					sshCommand += "." + agent.Name
+				}
+				sshCommand = Styles.Code.Render(sshCommand)
 				row = append(row, sshCommand)
 			}
 			tableWriter.AppendRow(row)

cli/cliui/resources_test.go

@@ -4,7 +4,7 @@ import (
 	"testing"
 	"time"
 
-	"github.com/stretchr/testify/require"
+	"github.com/stretchr/testify/assert"
 
 	"github.com/coder/coder/cli/cliui"
 	"github.com/coder/coder/coderd/database"
@@ -17,11 +17,12 @@ func TestWorkspaceResources(t *testing.T) {
 	t.Run("SingleAgentSSH", func(t *testing.T) {
 		t.Parallel()
 		ptty := ptytest.New(t)
+		done := make(chan struct{})
 		go func() {
 			err := cliui.WorkspaceResources(ptty.Output(), []codersdk.WorkspaceResource{{
 				Type:       "google_compute_instance",
 				Name:       "dev",
-				Transition: database.WorkspaceTransitionStart,
+				Transition: codersdk.WorkspaceTransitionStart,
 				Agents: []codersdk.WorkspaceAgent{{
 					Name:            "dev",
 					Status:          codersdk.WorkspaceAgentConnected,
@@ -31,29 +32,29 @@ func TestWorkspaceResources(t *testing.T) {
 			}}, cliui.WorkspaceResourcesOptions{
 				WorkspaceName: "example",
 			})
-			require.NoError(t, err)
+			assert.NoError(t, err)
+			close(done)
 		}()
 		ptty.ExpectMatch("coder ssh example")
+		<-done
 	})
 
 	t.Run("MultipleStates", func(t *testing.T) {
 		t.Parallel()
 		ptty := ptytest.New(t)
 		disconnected := database.Now().Add(-4 * time.Second)
+		done := make(chan struct{})
 		go func() {
 			err := cliui.WorkspaceResources(ptty.Output(), []codersdk.WorkspaceResource{{
-				Address:    "disk",
-				Transition: database.WorkspaceTransitionStart,
+				Transition: codersdk.WorkspaceTransitionStart,
 				Type:       "google_compute_disk",
 				Name:       "root",
 			}, {
-				Address:    "disk",
-				Transition: database.WorkspaceTransitionStop,
+				Transition: codersdk.WorkspaceTransitionStop,
 				Type:       "google_compute_disk",
 				Name:       "root",
 			}, {
-				Address:    "another",
-				Transition: database.WorkspaceTransitionStart,
+				Transition: codersdk.WorkspaceTransitionStart,
 				Type:       "google_compute_instance",
 				Name:       "dev",
 				Agents: []codersdk.WorkspaceAgent{{
@@ -64,7 +65,7 @@ func TestWorkspaceResources(t *testing.T) {
 					Architecture:    "amd64",
 				}},
 			}, {
-				Transition: database.WorkspaceTransitionStart,
+				Transition: codersdk.WorkspaceTransitionStart,
 				Type:       "kubernetes_pod",
 				Name:       "dev",
 				Agents: []codersdk.WorkspaceAgent{{
@@ -84,10 +85,12 @@ func TestWorkspaceResources(t *testing.T) {
 				HideAgentState: false,
 				HideAccess:     false,
 			})
-			require.NoError(t, err)
+			assert.NoError(t, err)
+			close(done)
 		}()
 		ptty.ExpectMatch("google_compute_disk.root")
 		ptty.ExpectMatch("google_compute_instance.dev")
 		ptty.ExpectMatch("coder ssh dev.postgres")
+		<-done
 	})
 }

cli/cliui/select.go

@@ -35,7 +35,9 @@ func init() {
 }
 
 type SelectOptions struct {
-	Options    []string
+	Options []string
+	// Default will be highlighted first if it's a valid option.
+	Default    string
 	Size       int
 	HideSearch bool
 }
@@ -50,9 +52,16 @@ func Select(cmd *cobra.Command, opts SelectOptions) (string, error) {
 	if flag.Lookup("test.v") != nil {
 		return opts.Options[0], nil
 	}
+
+	var defaultOption interface{}
+	if opts.Default != "" {
+		defaultOption = opts.Default
+	}
+
 	var value string
 	err := survey.AskOne(&survey.Select{
 		Options:  opts.Options,
+		Default:  defaultOption,
 		PageSize: opts.Size,
 	}, &value, survey.WithIcons(func(is *survey.IconSet) {
 		is.Help.Text = "Type to search"

cli/cliui/select_test.go

@@ -5,6 +5,7 @@ import (
 	"testing"
 
 	"github.com/spf13/cobra"
+	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 
 	"github.com/coder/coder/cli/cliui"
@@ -21,7 +22,7 @@ func TestSelect(t *testing.T) {
 			resp, err := newSelect(ptty, cliui.SelectOptions{
 				Options: []string{"First", "Second"},
 			})
-			require.NoError(t, err)
+			assert.NoError(t, err)
 			msgChan <- resp
 		}()
 		require.Equal(t, "First", <-msgChan)

cli/cliui/table.go

@@ -0,0 +1,307 @@
+package cliui
+
+import (
+	"fmt"
+	"reflect"
+	"strings"
+	"time"
+
+	"github.com/fatih/structtag"
+	"github.com/jedib0t/go-pretty/v6/table"
+	"golang.org/x/xerrors"
+)
+
+// Table creates a new table with standardized styles.
+func Table() table.Writer {
+	tableWriter := table.NewWriter()
+	tableWriter.Style().Box.PaddingLeft = ""
+	tableWriter.Style().Box.PaddingRight = "  "
+	tableWriter.Style().Options.DrawBorder = false
+	tableWriter.Style().Options.SeparateHeader = false
+	tableWriter.Style().Options.SeparateColumns = false
+	return tableWriter
+}
+
+// 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 {
+	if len(columns) == 0 {
+		return nil
+	}
+	columnConfigs := make([]table.ColumnConfig, 0)
+	for _, headerTextRaw := range header {
+		headerText, _ := headerTextRaw.(string)
+		hidden := true
+		for _, column := range columns {
+			if strings.EqualFold(strings.ReplaceAll(column, "_", " "), headerText) {
+				hidden = false
+				break
+			}
+		}
+		columnConfigs = append(columnConfigs, table.ColumnConfig{
+			Name:   headerText,
+			Hidden: hidden,
+		})
+	}
+	return columnConfigs
+}
+
+// DisplayTable renders a table as a string. The input argument must be a slice
+// of structs. At least one field in the struct must have a `table:""` tag
+// containing the name of the column in the outputted table.
+//
+// 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
+// a pointer to a struct, this function will return an error (even with an empty
+// input slice).
+//
+// If sort is empty, the input order will be used. If filterColumns is empty or
+// nil, all available columns are included.
+func DisplayTable(out any, sort string, filterColumns []string) (string, error) {
+	v := reflect.Indirect(reflect.ValueOf(out))
+
+	if v.Kind() != reflect.Slice {
+		return "", xerrors.Errorf("DisplayTable called with a non-slice type")
+	}
+
+	// Get the list of table column headers.
+	headersRaw, 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`)
+	}
+	headers := make(table.Row, len(headersRaw))
+	for i, header := range headersRaw {
+		headers[i] = header
+	}
+
+	// Verify that the given sort column and filter columns are valid.
+	if sort != "" || len(filterColumns) != 0 {
+		headersMap := make(map[string]string, len(headersRaw))
+		for _, header := range headersRaw {
+			headersMap[strings.ToLower(header)] = header
+		}
+
+		if sort != "" {
+			sort = strings.ToLower(strings.ReplaceAll(sort, "_", " "))
+			h, ok := headersMap[sort]
+			if !ok {
+				return "", xerrors.Errorf(`specified sort column %q not found in table headers, available columns are "%v"`, sort, strings.Join(headersRaw, `", "`))
+			}
+
+			// Autocorrect
+			sort = h
+		}
+
+		for i, column := range filterColumns {
+			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, `", "`))
+			}
+
+			// Autocorrect
+			filterColumns[i] = h
+		}
+	}
+
+	// Verify that the given sort column is valid.
+	if sort != "" {
+		sort = strings.ReplaceAll(sort, "_", " ")
+		found := false
+		for _, header := range headersRaw {
+			if strings.EqualFold(sort, header) {
+				found = true
+				sort = header
+				break
+			}
+		}
+		if !found {
+			return "", xerrors.Errorf("specified sort column %q not found in table headers, available columns are %q", sort, strings.Join(headersRaw, `", "`))
+		}
+	}
+
+	// Setup the table formatter.
+	tw := Table()
+	tw.AppendHeader(headers)
+	tw.SetColumnConfigs(FilterTableColumns(headers, filterColumns))
+	if sort != "" {
+		tw.SortBy([]table.SortBy{{
+			Name: sort,
+		}})
+	}
+
+	// Write each struct to the table.
+	for i := 0; i < v.Len(); i++ {
+		// Format the row as a slice.
+		rowMap, err := valueToTableMap(v.Index(i))
+		if err != nil {
+			return "", xerrors.Errorf("get table row map %v: %w", i, err)
+		}
+
+		rowSlice := make([]any, len(headers))
+		for i, h := range headersRaw {
+			v, ok := rowMap[h]
+			if !ok {
+				v = nil
+			}
+
+			// Special type formatting.
+			switch val := v.(type) {
+			case time.Time:
+				v = val.Format(time.Stamp)
+			case *time.Time:
+				if val != nil {
+					v = val.Format(time.Stamp)
+				}
+			case fmt.Stringer:
+				if val != nil {
+					v = val.String()
+				}
+			}
+
+			rowSlice[i] = v
+		}
+
+		tw.AppendRow(table.Row(rowSlice))
+	}
+
+	return tw.Render(), nil
+}
+
+// parseTableStructTag returns the name of the field according to the `table`
+// struct tag. If the table tag does not exist or is "-", an empty string is
+// 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) {
+	tags, err := structtag.Parse(string(field.Tag))
+	if err != nil {
+		return "", 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
+	}
+
+	recursive := false
+	for _, opt := range tag.Options {
+		if opt == "recursive" {
+			recursive = true
+			continue
+		}
+
+		return "", false, xerrors.Errorf("unknown option %q in struct field tag", opt)
+	}
+
+	return strings.ReplaceAll(tag.Name, "_", " "), recursive, nil
+}
+
+func isStructOrStructPointer(t reflect.Type) bool {
+	return t.Kind() == reflect.Struct || (t.Kind() == reflect.Pointer && t.Elem().Kind() == reflect.Struct)
+}
+
+// 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) {
+	if !isStructOrStructPointer(t) {
+		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{}
+	for i := 0; i < t.NumField(); i++ {
+		field := t.Field(i)
+		name, 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)
+		}
+		if name == "" {
+			continue
+		}
+
+		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())
+			}
+
+			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)
+			}
+			for _, childName := range childNames {
+				headers = append(headers, fmt.Sprintf("%s %s", name, childName))
+			}
+			continue
+		}
+
+		headers = append(headers, name)
+	}
+
+	return headers, nil
+}
+
+// valueToTableMap converts a struct to a map of column name to value. 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 valueToTableMap(val reflect.Value) (map[string]any, error) {
+	if !isStructOrStructPointer(val.Type()) {
+		return nil, xerrors.Errorf("valueToTableMap called with a non-struct or a non-pointer-to-a-struct type")
+	}
+	if val.Kind() == reflect.Pointer {
+		if val.IsNil() {
+			// No data for this struct, so return an empty map. All values will
+			// be rendered as nil in the resulting table.
+			return map[string]any{}, nil
+		}
+
+		val = val.Elem()
+	}
+
+	row := map[string]any{}
+	for i := 0; i < val.NumField(); i++ {
+		field := val.Type().Field(i)
+		fieldVal := val.Field(i)
+		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)
+		}
+		if name == "" {
+			continue
+		}
+
+		// Recurse if it's a struct.
+		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, fieldType.String())
+			}
+
+			// valueToTableMap does nothing on pointers so we don't need to
+			// filter here.
+			childMap, err := valueToTableMap(fieldVal)
+			if err != nil {
+				return nil, xerrors.Errorf("get child field values for field %q in type %q: %w", field.Name, fieldType.String(), err)
+			}
+			for childName, childValue := range childMap {
+				row[fmt.Sprintf("%s %s", name, childName)] = childValue
+			}
+			continue
+		}
+
+		// Otherwise, we just use the field value.
+		row[name] = val.Field(i).Interface()
+	}
+
+	return row, nil
+}

cli/cliui/table_test.go

@@ -0,0 +1,352 @@
+package cliui_test
+
+import (
+	"fmt"
+	"log"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/coder/coder/cli/cliui"
+)
+
+type stringWrapper struct {
+	str string
+}
+
+var _ fmt.Stringer = stringWrapper{}
+
+func (s stringWrapper) String() string {
+	return s.str
+}
+
+type tableTest1 struct {
+	Name        string      `table:"name"`
+	NotIncluded string      // no table tag
+	Age         int         `table:"age"`
+	Roles       []string    `table:"roles"`
+	Sub1        tableTest2  `table:"sub_1,recursive"`
+	Sub2        *tableTest2 `table:"sub_2,recursive"`
+	Sub3        tableTest3  `table:"sub 3,recursive"`
+	Sub4        tableTest2  `table:"sub 4"` // not recursive
+
+	// Types with special formatting.
+	Time    time.Time  `table:"time"`
+	TimePtr *time.Time `table:"time_ptr"`
+}
+
+type tableTest2 struct {
+	Name        stringWrapper `table:"name"`
+	Age         int           `table:"age"`
+	NotIncluded string        `table:"-"`
+}
+
+type tableTest3 struct {
+	NotIncluded string     // no table tag
+	Sub         tableTest2 `table:"inner,recursive"`
+}
+
+func Test_DisplayTable(t *testing.T) {
+	t.Parallel()
+
+	someTime := time.Date(2022, 8, 2, 15, 49, 10, 0, time.Local)
+	in := []tableTest1{
+		{
+			Name:  "foo",
+			Age:   10,
+			Roles: []string{"a", "b", "c"},
+			Sub1: tableTest2{
+				Name: stringWrapper{str: "foo1"},
+				Age:  11,
+			},
+			Sub2: &tableTest2{
+				Name: stringWrapper{str: "foo2"},
+				Age:  12,
+			},
+			Sub3: tableTest3{
+				Sub: tableTest2{
+					Name: stringWrapper{str: "foo3"},
+					Age:  13,
+				},
+			},
+			Sub4: tableTest2{
+				Name: stringWrapper{str: "foo4"},
+				Age:  14,
+			},
+			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,
+			Roles: nil,
+			Sub1: tableTest2{
+				Name: stringWrapper{str: "baz1"},
+				Age:  31,
+			},
+			Sub2: nil,
+			Sub3: tableTest3{
+				Sub: tableTest2{
+					Name: stringWrapper{str: "baz3"},
+					Age:  33,
+				},
+			},
+			Sub4: tableTest2{
+				Name: stringWrapper{str: "baz4"},
+				Age:  34,
+			},
+			Time:    someTime,
+			TimePtr: nil,
+		},
+	}
+
+	// This test tests skipping fields without table tags, recursion, pointer
+	// dereferencing, and nil pointer skipping.
+	t.Run("OK", 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 }  Aug  2 15:49:10  Aug  2 15:49:10
+bar    20  [a]      bar1               21  <nil>       <nil>      bar3                           23  {bar4 24 }  Aug  2 15:49:10  <nil>
+baz    30  []       baz1               31  <nil>       <nil>      baz3                           33  {baz4 34 }  Aug  2 15:49:10  <nil>
+		`
+
+		// Test with non-pointer values.
+		out, err := cliui.DisplayTable(in, "", nil)
+		log.Println("rendered table:\n" + out)
+		require.NoError(t, err)
+		compareTables(t, expected, out)
+
+		// Test with pointer values.
+		inPtr := make([]*tableTest1, len(in))
+		for i, v := range in {
+			v := v
+			inPtr[i] = &v
+		}
+		out, err = cliui.DisplayTable(inPtr, "", nil)
+		require.NoError(t, err)
+		compareTables(t, expected, out)
+	})
+
+	t.Run("Sort", 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
+bar    20  [a]      bar1               21  <nil>       <nil>      bar3                           23  {bar4 24 }  Aug  2 15:49:10  <nil>
+baz    30  []       baz1               31  <nil>       <nil>      baz3                           33  {baz4 34 }  Aug  2 15:49:10  <nil>
+foo    10  [a b c]  foo1               11  foo2        12         foo3                           13  {foo4 14 }  Aug  2 15:49:10  Aug  2 15:49:10
+		`
+
+		out, err := cliui.DisplayTable(in, "name", nil)
+		log.Println("rendered table:\n" + out)
+		require.NoError(t, err)
+		compareTables(t, expected, out)
+	})
+
+	t.Run("Filter", func(t *testing.T) {
+		t.Parallel()
+
+		expected := `
+NAME  SUB 1 NAME  SUB 3 INNER NAME  TIME
+foo   foo1        foo3              Aug  2 15:49:10
+bar   bar1        bar3              Aug  2 15:49:10
+baz   baz1        baz3              Aug  2 15:49:10
+		`
+
+		out, err := cliui.DisplayTable(in, "", []string{"name", "sub_1_name", "sub_3 inner name", "time"})
+		log.Println("rendered table:\n" + out)
+		require.NoError(t, err)
+		compareTables(t, expected, out)
+	})
+
+	// This test ensures that safeties against invalid use of `table` tags
+	// causes errors (even without data).
+	t.Run("Errors", func(t *testing.T) {
+		t.Parallel()
+
+		t.Run("NotSlice", func(t *testing.T) {
+			t.Parallel()
+
+			var in string
+			_, err := cliui.DisplayTable(in, "", nil)
+			require.Error(t, err)
+		})
+
+		t.Run("BadSortColumn", func(t *testing.T) {
+			t.Parallel()
+
+			_, err := cliui.DisplayTable(in, "bad_column_does_not_exist", nil)
+			require.Error(t, err)
+		})
+
+		t.Run("BadFilterColumns", func(t *testing.T) {
+			t.Parallel()
+
+			_, err := cliui.DisplayTable(in, "", []string{"name", "bad_column_does_not_exist"})
+			require.Error(t, err)
+		})
+
+		t.Run("Interfaces", func(t *testing.T) {
+			t.Parallel()
+
+			t.Run("WithoutData", func(t *testing.T) {
+				t.Parallel()
+
+				var in []any
+				_, err := cliui.DisplayTable(in, "", nil)
+				require.Error(t, err)
+			})
+
+			t.Run("WithData", func(t *testing.T) {
+				t.Parallel()
+
+				in := []any{tableTest1{}}
+				_, err := cliui.DisplayTable(in, "", nil)
+				require.Error(t, err)
+			})
+		})
+
+		t.Run("NotStruct", func(t *testing.T) {
+			t.Parallel()
+
+			t.Run("WithoutData", func(t *testing.T) {
+				t.Parallel()
+
+				var in []string
+				_, err := cliui.DisplayTable(in, "", nil)
+				require.Error(t, err)
+			})
+
+			t.Run("WithData", func(t *testing.T) {
+				t.Parallel()
+
+				in := []string{"foo", "bar", "baz"}
+				_, err := cliui.DisplayTable(in, "", nil)
+				require.Error(t, err)
+			})
+		})
+
+		t.Run("NoTableTags", func(t *testing.T) {
+			t.Parallel()
+
+			type noTableTagsTest struct {
+				Field string `json:"field"`
+			}
+
+			t.Run("WithoutData", func(t *testing.T) {
+				t.Parallel()
+
+				var in []noTableTagsTest
+				_, err := cliui.DisplayTable(in, "", nil)
+				require.Error(t, err)
+			})
+
+			t.Run("WithData", func(t *testing.T) {
+				t.Parallel()
+
+				in := []noTableTagsTest{{Field: "hi"}}
+				_, err := cliui.DisplayTable(in, "", nil)
+				require.Error(t, err)
+			})
+		})
+
+		t.Run("InvalidTag/NoName", func(t *testing.T) {
+			t.Parallel()
+
+			type noNameTest struct {
+				Field string `table:""`
+			}
+
+			t.Run("WithoutData", func(t *testing.T) {
+				t.Parallel()
+
+				var in []noNameTest
+				_, err := cliui.DisplayTable(in, "", nil)
+				require.Error(t, err)
+			})
+
+			t.Run("WithData", func(t *testing.T) {
+				t.Parallel()
+
+				in := []noNameTest{{Field: "test"}}
+				_, err := cliui.DisplayTable(in, "", nil)
+				require.Error(t, err)
+			})
+		})
+
+		t.Run("InvalidTag/BadSyntax", func(t *testing.T) {
+			t.Parallel()
+
+			type invalidSyntaxTest struct {
+				Field string `table:"asda,asdjada"`
+			}
+
+			t.Run("WithoutData", func(t *testing.T) {
+				t.Parallel()
+
+				var in []invalidSyntaxTest
+				_, err := cliui.DisplayTable(in, "", nil)
+				require.Error(t, err)
+			})
+
+			t.Run("WithData", func(t *testing.T) {
+				t.Parallel()
+
+				in := []invalidSyntaxTest{{Field: "test"}}
+				_, err := cliui.DisplayTable(in, "", nil)
+				require.Error(t, err)
+			})
+		})
+	})
+}
+
+// compareTables normalizes the incoming table lines
+func compareTables(t *testing.T, expected, out string) {
+	t.Helper()
+
+	expectedLines := strings.Split(strings.TrimSpace(expected), "\n")
+	gotLines := strings.Split(strings.TrimSpace(out), "\n")
+	assert.Equal(t, len(expectedLines), len(gotLines), "expected line count does not match generated line count")
+
+	// Map the expected and got lines to normalize them.
+	expectedNormalized := make([]string, len(expectedLines))
+	gotNormalized := make([]string, len(gotLines))
+	normalizeLine := func(s string) string {
+		return strings.Join(strings.Fields(strings.TrimSpace(s)), " ")
+	}
+	for i, s := range expectedLines {
+		expectedNormalized[i] = normalizeLine(s)
+	}
+	for i, s := range gotLines {
+		gotNormalized[i] = normalizeLine(s)
+	}
+
+	require.Equal(t, expectedNormalized, gotNormalized, "expected lines to match generated lines")
+}

cli/config/file.go

@@ -21,8 +21,20 @@ func (r Root) Organization() File {
 	return File(filepath.Join(string(r), "organization"))
 }
 
-func (r Root) AgentSession() File {
-	return File(filepath.Join(string(r), "agentsession"))
+func (r Root) DotfilesURL() File {
+	return File(filepath.Join(string(r), "dotfilesurl"))
+}
+
+func (r Root) PostgresPath() string {
+	return filepath.Join(string(r), "postgres")
+}
+
+func (r Root) PostgresPassword() File {
+	return File(filepath.Join(r.PostgresPath(), "password"))
+}
+
+func (r Root) PostgresPort() File {
+	return File(filepath.Join(r.PostgresPath(), "port"))
 }
 
 // File provides convenience methods for interacting with *os.File.

cli/configssh.go

@@ -1,145 +1,490 @@
 package cli
 
 import (
+	"bufio"
+	"bytes"
+	"context"
+	"errors"
 	"fmt"
+	"io"
+	"io/fs"
 	"os"
 	"path/filepath"
 	"runtime"
+	"sort"
 	"strings"
-	"sync"
 
 	"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/cliui"
-	"github.com/coder/coder/coderd/database"
 	"github.com/coder/coder/codersdk"
 )
 
-const sshStartToken = "# ------------START-CODER-----------"
-const sshStartMessage = `# This was generated by "coder config-ssh".
+const (
+	sshDefaultConfigFileName = "~/.ssh/config"
+	sshStartToken            = "# ------------START-CODER-----------"
+	sshEndToken              = "# ------------END-CODER------------"
+	sshConfigSectionHeader   = "# This section is managed by coder. DO NOT EDIT."
+	sshConfigDocsHeader      = `
 #
-# To remove this blob, run:
-#
-#    coder config-ssh --remove
-#
-# You should not hand-edit this section, unless you are deleting it.`
-const sshEndToken = "# ------------END-CODER------------"
+# You should not hand-edit this section unless you are removing it, all
+# changes will be lost when running "coder config-ssh".
+`
+	sshConfigOptionsHeader = `#
+# Last config-ssh options:
+`
+)
+
+// sshConfigOptions represents options that can be stored and read
+// from the coder config in ~/.ssh/coder.
+type sshConfigOptions struct {
+	sshOptions []string
+}
+
+func (o sshConfigOptions) equal(other sshConfigOptions) bool {
+	// Compare without side-effects or regard to order.
+	opt1 := slices.Clone(o.sshOptions)
+	sort.Strings(opt1)
+	opt2 := slices.Clone(other.sshOptions)
+	sort.Strings(opt2)
+	return slices.Equal(opt1, opt2)
+}
+
+func (o sshConfigOptions) asList() (list []string) {
+	for _, opt := range o.sshOptions {
+		list = append(list, fmt.Sprintf("ssh-option: %s", opt))
+	}
+	return list
+}
+
+type sshWorkspaceConfig struct {
+	Name  string
+	Hosts []string
+}
+
+func sshFetchWorkspaceConfigs(ctx context.Context, client *codersdk.Client) ([]sshWorkspaceConfig, error) {
+	workspaces, err := client.Workspaces(ctx, codersdk.WorkspaceFilter{
+		Owner: codersdk.Me,
+	})
+	if err != nil {
+		return nil, err
+	}
+
+	var errGroup errgroup.Group
+	workspaceConfigs := make([]sshWorkspaceConfig, len(workspaces))
+	for i, workspace := range workspaces {
+		i := i
+		workspace := workspace
+		errGroup.Go(func() error {
+			resources, err := client.TemplateVersionResources(ctx, workspace.LatestBuild.TemplateVersionID)
+			if err != nil {
+				return err
+			}
+
+			wc := sshWorkspaceConfig{Name: workspace.Name}
+			var agents []codersdk.WorkspaceAgent
+			for _, resource := range resources {
+				if resource.Transition != codersdk.WorkspaceTransitionStart {
+					continue
+				}
+				agents = append(agents, resource.Agents...)
+			}
+
+			// handle both WORKSPACE and WORKSPACE.AGENT syntax
+			if len(agents) == 1 {
+				wc.Hosts = append(wc.Hosts, workspace.Name)
+			}
+			for _, agent := range agents {
+				hostname := workspace.Name + "." + agent.Name
+				wc.Hosts = append(wc.Hosts, hostname)
+			}
+
+			workspaceConfigs[i] = wc
+
+			return nil
+		})
+	}
+	err = errGroup.Wait()
+	if err != nil {
+		return nil, err
+	}
+
+	return workspaceConfigs, nil
+}
+
+func sshPrepareWorkspaceConfigs(ctx context.Context, client *codersdk.Client) (receive func() ([]sshWorkspaceConfig, error)) {
+	wcC := make(chan []sshWorkspaceConfig, 1)
+	errC := make(chan error, 1)
+	go func() {
+		wc, err := sshFetchWorkspaceConfigs(ctx, client)
+		wcC <- wc
+		errC <- err
+	}()
+	return func() ([]sshWorkspaceConfig, error) {
+		return <-wcC, <-errC
+	}
+}
 
 func configSSH() *cobra.Command {
 	var (
 		sshConfigFile    string
-		sshOptions       []string
+		sshConfigOpts    sshConfigOptions
+		usePreviousOpts  bool
+		dryRun           bool
 		skipProxyCommand bool
+		wireguard        bool
 	)
 	cmd := &cobra.Command{
-		Use: "config-ssh",
-		RunE: func(cmd *cobra.Command, args []string) error {
-			client, err := createClient(cmd)
+		Annotations: workspaceCommand,
+		Use:         "config-ssh",
+		Short:       "Populate your SSH config with Host entries for all of your workspaces",
+		Example: 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",
+			},
+			example{
+				Description: "You can use --dry-run (or -n) to see the changes that would be made",
+				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
 			}
+
+			recvWorkspaceConfigs := sshPrepareWorkspaceConfigs(cmd.Context(), client)
+
+			out := cmd.OutOrStdout()
+			if dryRun {
+				// Print everything except diff to stderr so
+				// that it's possible to capture the diff.
+				out = cmd.OutOrStderr()
+			}
+			binaryFile, err := currentBinPath(out)
+			if err != nil {
+				return err
+			}
+
+			homedir, err := os.UserHomeDir()
+			if err != nil {
+				return xerrors.Errorf("user home dir failed: %w", err)
+			}
+
 			if strings.HasPrefix(sshConfigFile, "~/") {
-				dirname, _ := os.UserHomeDir()
-				sshConfigFile = filepath.Join(dirname, sshConfigFile[2:])
-			}
-			// Doesn't matter if this fails, because we write the file anyways.
-			sshConfigContentRaw, _ := os.ReadFile(sshConfigFile)
-			sshConfigContent := string(sshConfigContentRaw)
-			startIndex := strings.Index(sshConfigContent, sshStartToken)
-			endIndex := strings.Index(sshConfigContent, sshEndToken)
-			if startIndex != -1 && endIndex != -1 {
-				sshConfigContent = sshConfigContent[:startIndex-1] + sshConfigContent[endIndex+len(sshEndToken):]
+				sshConfigFile = filepath.Join(homedir, sshConfigFile[2:])
 			}
 
-			workspaces, err := client.WorkspacesByUser(cmd.Context(), codersdk.Me)
-			if err != nil {
-				return err
-			}
-			if len(workspaces) == 0 {
-				return xerrors.New("You don't have any workspaces!")
+			// Only allow not-exist errors to avoid trashing
+			// the users SSH config.
+			configRaw, err := os.ReadFile(sshConfigFile)
+			if err != nil && !errors.Is(err, fs.ErrNotExist) {
+				return xerrors.Errorf("read ssh config failed: %w", err)
 			}
 
-			binaryFile, err := currentBinPath(cmd)
-			if err != nil {
-				return err
+			// Keep track of changes we are making.
+			var changes []string
+
+			// Parse the previous configuration only if config-ssh
+			// has been run previously.
+			var lastConfig *sshConfigOptions
+			if section, ok := sshConfigGetCoderSection(configRaw); ok {
+				c := sshConfigParseLastOptions(bytes.NewReader(section))
+				lastConfig = &c
 			}
 
-			root := createConfig(cmd)
-			sshConfigContent += "\n" + sshStartToken + "\n" + sshStartMessage + "\n\n"
-			sshConfigContentMutex := sync.Mutex{}
-			var errGroup errgroup.Group
-			for _, workspace := range workspaces {
-				workspace := workspace
-				errGroup.Go(func() error {
-					resources, err := client.TemplateVersionResources(cmd.Context(), workspace.LatestBuild.TemplateVersionID)
-					if err != nil {
-						return err
-					}
-					for _, resource := range resources {
-						if resource.Transition != database.WorkspaceTransitionStart {
-							continue
-						}
-						for _, agent := range resource.Agents {
-							sshConfigContentMutex.Lock()
-							hostname := workspace.Name
-							if len(resource.Agents) > 1 {
-								hostname += "." + agent.Name
-							}
-							configOptions := []string{
-								"Host coder." + hostname,
-							}
-							for _, option := range sshOptions {
-								configOptions = append(configOptions, "\t"+option)
-							}
-							configOptions = append(configOptions,
-								"\tHostName coder."+hostname,
-								"\tConnectTimeout=0",
-								"\tStrictHostKeyChecking=no",
-							)
-							if !skipProxyCommand {
-								configOptions = append(configOptions, fmt.Sprintf("\tProxyCommand %q --global-config %q ssh --stdio %s", binaryFile, root, hostname))
-							}
-							sshConfigContent += strings.Join(configOptions, "\n") + "\n"
-							sshConfigContentMutex.Unlock()
-						}
-					}
-					return nil
+			// Avoid prompting in diff mode (unexpected behavior)
+			// or when a previous config does not exist.
+			if usePreviousOpts && lastConfig != nil {
+				sshConfigOpts = *lastConfig
+			} else if lastConfig != nil && !sshConfigOpts.equal(*lastConfig) {
+				newOpts := sshConfigOpts.asList()
+				newOptsMsg := "\n\n  New options: none"
+				if len(newOpts) > 0 {
+					newOptsMsg = fmt.Sprintf("\n\n  New options:\n    * %s", strings.Join(newOpts, "\n    * "))
+				}
+				oldOpts := lastConfig.asList()
+				oldOptsMsg := "\n\n  Previous options: none"
+				if len(oldOpts) > 0 {
+					oldOptsMsg = fmt.Sprintf("\n\n  Previous options:\n    * %s", strings.Join(oldOpts, "\n    * "))
+				}
+
+				line, err := cliui.Prompt(cmd, cliui.PromptOptions{
+					Text:      fmt.Sprintf("New options differ from previous options:%s%s\n\n  Use new options?", newOptsMsg, oldOptsMsg),
+					IsConfirm: true,
 				})
+				if err != nil {
+					if line == "" && xerrors.Is(err, cliui.Canceled) {
+						return nil
+					}
+					// Selecting "no" will use the last config.
+					sshConfigOpts = *lastConfig
+				} else {
+					changes = append(changes, "Use new SSH options")
+				}
+				// Only print when prompts are shown.
+				if yes, _ := cmd.Flags().GetBool("yes"); !yes {
+					_, _ = fmt.Fprint(out, "\n")
+				}
 			}
-			err = errGroup.Wait()
+
+			configModified := configRaw
+			root := createConfig(cmd)
+
+			buf := &bytes.Buffer{}
+			before, after := sshConfigSplitOnCoderSection(configModified)
+			// Write the first half of the users config file to buf.
+			_, _ = buf.Write(before)
+
+			// Write comment and store the provided options as part
+			// of the config for future (re)use.
+			newline := len(before) > 0
+			sshConfigWriteSectionHeader(buf, newline, sshConfigOpts)
+
+			workspaceConfigs, err := recvWorkspaceConfigs()
 			if err != nil {
-				return err
+				return xerrors.Errorf("fetch workspace configs failed: %w", err)
 			}
-			sshConfigContent += "\n" + sshEndToken
-			err = os.MkdirAll(filepath.Dir(sshConfigFile), os.ModePerm)
-			if err != nil {
-				return err
+			// Ensure stable sorting of output.
+			slices.SortFunc(workspaceConfigs, func(a, b sshWorkspaceConfig) bool {
+				return a.Name < b.Name
+			})
+			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",
+						// Without this, the "REMOTE HOST IDENTITY CHANGED"
+						// message will appear.
+						"\tUserKnownHostsFile=/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 {
+						if !wireguard {
+							configOptions = append(configOptions, fmt.Sprintf("\tProxyCommand %q --global-config %q ssh --stdio %s", binaryFile, root, hostname))
+						} else {
+							configOptions = append(configOptions, fmt.Sprintf("\tProxyCommand %q --global-config %q ssh --wireguard --stdio %s", binaryFile, root, hostname))
+						}
+					}
+
+					_, _ = buf.WriteString(strings.Join(configOptions, "\n"))
+					_ = buf.WriteByte('\n')
+				}
 			}
-			err = os.WriteFile(sshConfigFile, []byte(sshConfigContent), os.ModePerm)
-			if err != nil {
-				return err
+
+			sshConfigWriteSectionEnd(buf)
+
+			// Write the remainder of the users config file to buf.
+			_, _ = buf.Write(after)
+
+			if !bytes.Equal(configModified, buf.Bytes()) {
+				changes = append(changes, fmt.Sprintf("Update the coder section in %s", sshConfigFile))
+				configModified = buf.Bytes()
+			}
+
+			if len(changes) == 0 {
+				_, _ = fmt.Fprintf(out, "No changes to make.\n")
+				return nil
+			}
+
+			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)
+				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)
+				}
+
+				return nil
+			}
+
+			if len(changes) > 0 {
+				_, err = cliui.Prompt(cmd, 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,
+				})
+				if err != nil {
+					return nil
+				}
+				// Only print when prompts are shown.
+				if yes, _ := cmd.Flags().GetBool("yes"); !yes {
+					_, _ = fmt.Fprint(out, "\n")
+				}
+			}
+
+			if !bytes.Equal(configRaw, configModified) {
+				err = writeWithTempFileAndMove(sshConfigFile, bytes.NewReader(configModified))
+				if err != nil {
+					return xerrors.Errorf("write ssh config failed: %w", err)
+				}
+			}
+
+			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)
+			} else {
+				_, _ = fmt.Fprint(out, "You don't have any workspaces yet, try creating one with:\n\n\t$ coder create <workspace>\n")
 			}
-			_, _ = fmt.Fprintf(cmd.OutOrStdout(), "An auto-generated ssh config was written to %q\n", sshConfigFile)
-			_, _ = fmt.Fprintln(cmd.OutOrStdout(), "You should now be able to ssh into your workspace")
-			_, _ = fmt.Fprintf(cmd.OutOrStdout(), "For example, try running\n\n\t$ ssh coder.%s\n\n", workspaces[0].Name)
 			return nil
 		},
 	}
-	cliflag.StringVarP(cmd.Flags(), &sshConfigFile, "ssh-config-file", "", "CODER_SSH_CONFIG_FILE", "~/.ssh/config", "Specifies the path to an SSH config.")
-	cmd.Flags().StringArrayVarP(&sshOptions, "ssh-option", "o", []string{}, "Specifies additional SSH options to embed in each host stanza.")
+	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.")
+	cliflag.BoolVarP(cmd.Flags(), &wireguard, "wireguard", "", "CODER_CONFIG_SSH_WIREGUARD", false, "Whether to use Wireguard for SSH tunneling.")
+	_ = cmd.Flags().MarkHidden("wireguard")
+
+	cliui.AllowSkipPrompt(cmd)
 
 	return cmd
 }
 
+//nolint:revive
+func sshConfigWriteSectionHeader(w io.Writer, addNewline bool, o sshConfigOptions) {
+	nl := "\n"
+	if !addNewline {
+		nl = ""
+	}
+	_, _ = fmt.Fprint(w, nl+sshStartToken+"\n")
+	_, _ = fmt.Fprint(w, sshConfigSectionHeader)
+	_, _ = fmt.Fprint(w, sshConfigDocsHeader)
+	if len(o.sshOptions) > 0 {
+		_, _ = fmt.Fprint(w, sshConfigOptionsHeader)
+		for _, opt := range o.sshOptions {
+			_, _ = fmt.Fprintf(w, "# :%s=%s\n", "ssh-option", opt)
+		}
+	}
+	_, _ = fmt.Fprint(w, "#\n")
+}
+
+func sshConfigWriteSectionEnd(w io.Writer) {
+	_, _ = fmt.Fprint(w, sshEndToken+"\n")
+}
+
+func sshConfigParseLastOptions(r io.Reader) (o sshConfigOptions) {
+	s := bufio.NewScanner(r)
+	for s.Scan() {
+		line := s.Text()
+		if strings.HasPrefix(line, "# :") {
+			line = strings.TrimPrefix(line, "# :")
+			parts := strings.SplitN(line, "=", 2)
+			switch parts[0] {
+			case "ssh-option":
+				o.sshOptions = append(o.sshOptions, parts[1])
+			default:
+				// Unknown option, ignore.
+			}
+		}
+	}
+	if err := s.Err(); err != nil {
+		panic(err)
+	}
+
+	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
+	}
+	return nil, false
+}
+
+// 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) {
+	startIndex := bytes.Index(data, []byte(sshStartToken))
+	endIndex := bytes.Index(data, []byte(sshEndToken))
+	if startIndex != -1 && endIndex != -1 {
+		// We use -1 and +1 here to also include the preceding
+		// and trailing newline, where applicable.
+		start := startIndex
+		if start > 0 {
+			start--
+		}
+		end := endIndex + len(sshEndToken)
+		if end < len(data) {
+			end++
+		}
+		return data[:start], data[end:]
+	}
+
+	return data, nil
+}
+
+// writeWithTempFileAndMove writes to a temporary file in the same
+// directory as path and renames the temp file to the file provided in
+// path. This ensure we avoid trashing the file we are writing due to
+// unforeseen circumstance like filesystem full, command killed, etc.
+func writeWithTempFileAndMove(path string, r io.Reader) (err error) {
+	dir := filepath.Dir(path)
+	name := filepath.Base(path)
+
+	// Create a tempfile in the same directory for ensuring write
+	// operation does not fail.
+	f, err := os.CreateTemp(dir, fmt.Sprintf(".%s.", name))
+	if err != nil {
+		return xerrors.Errorf("create temp file failed: %w", err)
+	}
+	defer func() {
+		if err != nil {
+			_ = os.Remove(f.Name()) // Cleanup in case a step failed.
+		}
+	}()
+
+	_, err = io.Copy(f, r)
+	if err != nil {
+		_ = f.Close()
+		return xerrors.Errorf("write temp file failed: %w", err)
+	}
+
+	err = f.Close()
+	if err != nil {
+		return xerrors.Errorf("close temp file failed: %w", err)
+	}
+
+	err = os.Rename(f.Name(), path)
+	if err != nil {
+		return xerrors.Errorf("rename temp file failed: %w", err)
+	}
+
+	return nil
+}
+
 // currentBinPath returns the path to the coder binary suitable for use in ssh
 // ProxyCommand.
-func currentBinPath(cmd *cobra.Command) (string, error) {
+func currentBinPath(w io.Writer) (string, error) {
 	exePath, err := os.Executable()
 	if err != nil {
 		return "", xerrors.Errorf("get executable path: %w", err)
@@ -155,11 +500,12 @@ func currentBinPath(cmd *cobra.Command) (string, error) {
 	// correctly. Check if the current executable is in $PATH, and warn the user
 	// if it isn't.
 	if err != nil && runtime.GOOS == "windows" {
-		cliui.Warn(cmd.OutOrStdout(),
+		cliui.Warn(w,
 			"The current executable is not in $PATH.",
 			"This may lead to problems connecting to your workspace via SSH.",
 			fmt.Sprintf("Please move %q to a location in your $PATH (such as System32) and run `%s config-ssh` again.", binName, binName),
 		)
+		_, _ = fmt.Fprint(w, "\n")
 		// Return the exePath so SSH at least works outside of Msys2.
 		return exePath, nil
 	}
@@ -167,13 +513,39 @@ func currentBinPath(cmd *cobra.Command) (string, error) {
 	// Warn the user if the current executable is not the same as the one in
 	// $PATH.
 	if filepath.Clean(pathPath) != filepath.Clean(exePath) {
-		cliui.Warn(cmd.OutOrStdout(),
+		cliui.Warn(w,
 			"The current executable path does not match the executable path found in $PATH.",
 			"This may cause issues connecting to your workspace via SSH.",
 			fmt.Sprintf("\tCurrent executable path: %q", exePath),
 			fmt.Sprintf("\tExecutable path in $PATH: %q", pathPath),
 		)
+		_, _ = fmt.Fprint(w, "\n")
 	}
 
-	return binName, nil
+	return exePath, nil
+}
+
+// diffBytes takes two byte slices and diffs them as if they were in a
+// file named name.
+// nolint: revive // Color is an option, not a control coupling.
+func diffBytes(name string, b1, b2 []byte, color bool) ([]byte, error) {
+	var buf bytes.Buffer
+	var opts []write.Option
+	if color {
+		opts = append(opts, write.TerminalColor())
+	}
+	err := diff.Text(name, name, b1, b2, &buf, opts...)
+	if err != nil {
+		return nil, err
+	}
+	b := buf.Bytes()
+	// Check if diff only output two lines, if yes, there's no diff.
+	//
+	// Example:
+	// 	--- /home/user/.ssh/config
+	// 	+++ /home/user/.ssh/config
+	if bytes.Count(b, []byte{'\n'}) == 2 {
+		b = nil
+	}
+	return b, nil
 }

cli/configssh_test.go

@@ -1,16 +1,21 @@
 package cli_test
 
 import (
+	"bufio"
+	"bytes"
 	"context"
+	"fmt"
 	"io"
 	"net"
 	"os"
 	"os/exec"
+	"path/filepath"
 	"strconv"
 	"strings"
 	"testing"
 
 	"github.com/google/uuid"
+	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 
 	"cdr.dev/slog/sloggers/slogtest"
@@ -19,18 +24,45 @@ import (
 	"github.com/coder/coder/cli/clitest"
 	"github.com/coder/coder/coderd/coderdtest"
 	"github.com/coder/coder/codersdk"
-	"github.com/coder/coder/peer"
 	"github.com/coder/coder/provisioner/echo"
 	"github.com/coder/coder/provisionersdk/proto"
 	"github.com/coder/coder/pty/ptytest"
 )
 
+func sshConfigFileName(t *testing.T) (sshConfig string) {
+	t.Helper()
+	tmpdir := t.TempDir()
+	dotssh := filepath.Join(tmpdir, ".ssh")
+	err := os.Mkdir(dotssh, 0o700)
+	require.NoError(t, err)
+	n := filepath.Join(dotssh, "config")
+	return n
+}
+
+func sshConfigFileCreate(t *testing.T, name string, data io.Reader) {
+	t.Helper()
+	t.Logf("Writing %s", name)
+	f, err := os.Create(name)
+	require.NoError(t, err)
+	n, err := io.Copy(f, data)
+	t.Logf("Wrote %d", n)
+	require.NoError(t, err)
+	err = f.Close()
+	require.NoError(t, err)
+}
+
+func sshConfigFileRead(t *testing.T, name string) string {
+	t.Helper()
+	b, err := os.ReadFile(name)
+	require.NoError(t, err)
+	return string(b)
+}
+
 func TestConfigSSH(t *testing.T) {
 	t.Parallel()
 
-	client := coderdtest.New(t, nil)
+	client := coderdtest.New(t, &coderdtest.Options{IncludeProvisionerD: true})
 	user := coderdtest.CreateFirstUser(t, client)
-	coderdtest.NewProvisionerDaemon(t, client)
 	authToken := uuid.NewString()
 	version := coderdtest.CreateTemplateVersion(t, client, user.OrganizationID, &echo.Responses{
 		Parse: echo.ParseComplete,
@@ -68,29 +100,26 @@ func TestConfigSSH(t *testing.T) {
 	})
 	coderdtest.AwaitTemplateVersionJob(t, client, version.ID)
 	template := coderdtest.CreateTemplate(t, client, user.OrganizationID, version.ID)
-	workspace := coderdtest.CreateWorkspace(t, client, codersdk.Me, template.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
-	agentCloser := agent.New(agentClient.ListenWorkspaceAgent, &peer.ConnOptions{
+	agentCloser := agent.New(agentClient.ListenWorkspaceAgent, &agent.Options{
 		Logger: slogtest.Make(t, nil),
 	})
-	t.Cleanup(func() {
+	defer func() {
 		_ = agentCloser.Close()
-	})
-	tempFile, err := os.CreateTemp(t.TempDir(), "")
-	require.NoError(t, err)
-	_ = tempFile.Close()
+	}()
 	resources := coderdtest.AwaitWorkspaceAgents(t, client, workspace.LatestBuild.ID)
-	agentConn, err := client.DialWorkspaceAgent(context.Background(), resources[0].Agents[0].ID, nil, nil)
+	agentConn, err := client.DialWorkspaceAgent(context.Background(), resources[0].Agents[0].ID, nil)
 	require.NoError(t, err)
 	defer agentConn.Close()
 
 	listener, err := net.Listen("tcp", "127.0.0.1:0")
 	require.NoError(t, err)
-	t.Cleanup(func() {
+	defer func() {
 		_ = listener.Close()
-	})
+	}()
 	go func() {
 		for {
 			conn, err := listener.Accept()
@@ -98,21 +127,20 @@ func TestConfigSSH(t *testing.T) {
 				return
 			}
 			ssh, err := agentConn.SSH()
-			require.NoError(t, err)
+			assert.NoError(t, err)
 			go io.Copy(conn, ssh)
 			go io.Copy(ssh, conn)
 		}
 	}()
-	t.Cleanup(func() {
-		_ = listener.Close()
-	})
+
+	sshConfigFile := sshConfigFileName(t)
 
 	tcpAddr, valid := listener.Addr().(*net.TCPAddr)
 	require.True(t, valid)
 	cmd, root := clitest.New(t, "config-ssh",
 		"--ssh-option", "HostName "+tcpAddr.IP.String(),
 		"--ssh-option", "Port "+strconv.Itoa(tcpAddr.Port),
-		"--ssh-config-file", tempFile.Name(),
+		"--ssh-config-file", sshConfigFile,
 		"--skip-proxy-command")
 	clitest.SetupConfig(t, client, root)
 	doneChan := make(chan struct{})
@@ -122,15 +150,568 @@ func TestConfigSSH(t *testing.T) {
 	go func() {
 		defer close(doneChan)
 		err := cmd.Execute()
-		require.NoError(t, err)
+		assert.NoError(t, err)
 	}()
+
+	matches := []struct {
+		match, write string
+	}{
+		{match: "Continue?", write: "yes"},
+	}
+	for _, m := range matches {
+		pty.ExpectMatch(m.match)
+		pty.WriteLine(m.write)
+	}
+
 	<-doneChan
 
-	t.Log(tempFile.Name())
+	home := filepath.Dir(filepath.Dir(sshConfigFile))
 	// #nosec
-	sshCmd := exec.Command("ssh", "-F", tempFile.Name(), "coder."+workspace.Name, "echo", "test")
-	sshCmd.Stderr = os.Stderr
+	sshCmd := exec.Command("ssh", "-F", sshConfigFile, "coder."+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()
 	data, err := sshCmd.Output()
 	require.NoError(t, err)
 	require.Equal(t, "test", strings.TrimSpace(string(data)))
 }
+
+func TestConfigSSH_FileWriteAndOptionsFlow(t *testing.T) {
+	t.Parallel()
+
+	headerStart := strings.Join([]string{
+		"# ------------START-CODER-----------",
+		"# This section is managed by coder. DO NOT EDIT.",
+		"#",
+		"# You should not hand-edit this section unless you are removing it, all",
+		"# changes will be lost when running \"coder config-ssh\".",
+		"#",
+	}, "\n")
+	headerEnd := "# ------------END-CODER------------"
+	baseHeader := strings.Join([]string{
+		headerStart,
+		headerEnd,
+	}, "\n")
+
+	type writeConfig struct {
+		ssh string
+	}
+	type wantConfig struct {
+		ssh string
+	}
+	type match struct {
+		match, write string
+	}
+	tests := []struct {
+		name        string
+		args        []string
+		matches     []match
+		writeConfig writeConfig
+		wantConfig  wantConfig
+		wantErr     bool
+	}{
+		{
+			name: "Config file is created",
+			matches: []match{
+				{match: "Continue?", write: "yes"},
+			},
+			wantConfig: wantConfig{
+				ssh: strings.Join([]string{
+					baseHeader,
+					"",
+				}, "\n"),
+			},
+		},
+		{
+			name: "Section is written after user content",
+			writeConfig: writeConfig{
+				ssh: strings.Join([]string{
+					"Host myhost",
+					"	HostName myhost",
+				}, "\n"),
+			},
+			wantConfig: wantConfig{
+				ssh: strings.Join([]string{
+					"Host myhost",
+					"	HostName myhost",
+					baseHeader,
+					"",
+				}, "\n"),
+			},
+			matches: []match{
+				{match: "Continue?", write: "yes"},
+			},
+		},
+		{
+			name: "Section is not moved on re-run",
+			writeConfig: writeConfig{
+				ssh: strings.Join([]string{
+					"Host myhost",
+					"	HostName myhost",
+					"",
+					baseHeader,
+					"",
+					"Host otherhost",
+					"	HostName otherhost",
+					"",
+				}, "\n"),
+			},
+			wantConfig: wantConfig{
+				ssh: strings.Join([]string{
+					"Host myhost",
+					"	HostName myhost",
+					"",
+					baseHeader,
+					"",
+					"Host otherhost",
+					"	HostName otherhost",
+					"",
+				}, "\n"),
+			},
+		},
+		{
+			name: "Section is not moved on re-run with new options",
+			writeConfig: writeConfig{
+				ssh: strings.Join([]string{
+					"Host myhost",
+					"	HostName myhost",
+					"",
+					baseHeader,
+					"",
+					"Host otherhost",
+					"	HostName otherhost",
+					"",
+				}, "\n"),
+			},
+			wantConfig: wantConfig{
+				ssh: strings.Join([]string{
+					"Host myhost",
+					"	HostName myhost",
+					"",
+					headerStart,
+					"# Last config-ssh options:",
+					"# :ssh-option=ForwardAgent=yes",
+					"#",
+					headerEnd,
+					"",
+					"Host otherhost",
+					"	HostName otherhost",
+					"",
+				}, "\n"),
+			},
+			args: []string{
+				"--ssh-option", "ForwardAgent=yes",
+			},
+			matches: []match{
+				{match: "Use new options?", write: "yes"},
+				{match: "Continue?", write: "yes"},
+			},
+		},
+		{
+			name: "Adds newline at EOF",
+			writeConfig: writeConfig{
+				ssh: strings.Join([]string{
+					baseHeader,
+				}, "\n"),
+			},
+			wantConfig: wantConfig{
+				ssh: strings.Join([]string{
+					baseHeader,
+					"",
+				}, "\n"),
+			},
+			matches: []match{
+				{match: "Continue?", write: "yes"},
+			},
+		},
+		{
+			name: "Do not prompt for new options on first run",
+			writeConfig: writeConfig{
+				ssh: "",
+			},
+			wantConfig: wantConfig{
+				ssh: strings.Join([]string{
+					headerStart,
+					"# Last config-ssh options:",
+					"# :ssh-option=ForwardAgent=yes",
+					"#",
+					headerEnd,
+					"",
+				}, "\n"),
+			},
+			args: []string{"--ssh-option", "ForwardAgent=yes"},
+			matches: []match{
+				{match: "Continue?", write: "yes"},
+			},
+		},
+		{
+			name: "Prompt for new options when there are no previous options",
+			writeConfig: writeConfig{
+				ssh: strings.Join([]string{
+					baseHeader,
+				}, "\n"),
+			},
+			wantConfig: wantConfig{
+				ssh: strings.Join([]string{
+					headerStart,
+					"# Last config-ssh options:",
+					"# :ssh-option=ForwardAgent=yes",
+					"#",
+					headerEnd,
+					"",
+				}, "\n"),
+			},
+			args: []string{"--ssh-option", "ForwardAgent=yes"},
+			matches: []match{
+				{match: "Use new options?", write: "yes"},
+				{match: "Continue?", write: "yes"},
+			},
+		},
+		{
+			name: "Prompt for new options when there are previous options",
+			writeConfig: writeConfig{
+				ssh: strings.Join([]string{
+					headerStart,
+					"# Last config-ssh options:",
+					"# :ssh-option=ForwardAgent=yes",
+					"#",
+					headerEnd,
+				}, "\n"),
+			},
+			wantConfig: wantConfig{
+				ssh: strings.Join([]string{
+					baseHeader,
+					"",
+				}, "\n"),
+			},
+			matches: []match{
+				{match: "Use new options?", write: "yes"},
+				{match: "Continue?", write: "yes"},
+			},
+		},
+		{
+			name: "No prompt on no changes",
+			writeConfig: writeConfig{
+				ssh: strings.Join([]string{
+					headerStart,
+					"# Last config-ssh options:",
+					"# :ssh-option=ForwardAgent=yes",
+					"#",
+					headerEnd,
+					"",
+				}, "\n"),
+			},
+			wantConfig: wantConfig{
+				ssh: strings.Join([]string{
+					headerStart,
+					"# Last config-ssh options:",
+					"# :ssh-option=ForwardAgent=yes",
+					"#",
+					headerEnd,
+					"",
+				}, "\n"),
+			},
+			args: []string{"--ssh-option", "ForwardAgent=yes"},
+		},
+		{
+			name: "No changes when continue = no",
+			writeConfig: writeConfig{
+				ssh: strings.Join([]string{
+					headerStart,
+					"# Last config-ssh options:",
+					"# :ssh-option=ForwardAgent=yes",
+					"#",
+					headerEnd,
+					"",
+				}, "\n"),
+			},
+			wantConfig: wantConfig{
+				ssh: strings.Join([]string{
+					headerStart,
+					"# Last config-ssh options:",
+					"# :ssh-option=ForwardAgent=yes",
+					"#",
+					headerEnd,
+					"",
+				}, "\n"),
+			},
+			args: []string{"--ssh-option", "ForwardAgent=no"},
+			matches: []match{
+				{match: "Use new options?", write: "yes"},
+				{match: "Continue?", write: "no"},
+			},
+		},
+		{
+			name: "Do not prompt when using --yes",
+			writeConfig: writeConfig{
+				ssh: strings.Join([]string{
+					headerStart,
+					"# Last config-ssh options:",
+					"# :ssh-option=ForwardAgent=yes",
+					"#",
+					headerEnd,
+					"",
+				}, "\n"),
+			},
+			wantConfig: wantConfig{
+				ssh: strings.Join([]string{
+					// Last options overwritten.
+					baseHeader,
+					"",
+				}, "\n"),
+			},
+			args: []string{"--yes"},
+		},
+		{
+			name: "Do not prompt for new options when prev opts flag is set",
+			writeConfig: writeConfig{
+				ssh: strings.Join([]string{
+					headerStart,
+					"# Last config-ssh options:",
+					"# :ssh-option=ForwardAgent=yes",
+					"#",
+					headerEnd,
+					"",
+				}, "\n"),
+			},
+			wantConfig: wantConfig{
+				ssh: strings.Join([]string{
+					headerStart,
+					"# Last config-ssh options:",
+					"# :ssh-option=ForwardAgent=yes",
+					"#",
+					headerEnd,
+					"",
+				}, "\n"),
+			},
+			args: []string{
+				"--use-previous-options",
+				"--yes",
+			},
+		},
+		{
+			name: "Do not overwrite config when using --dry-run",
+			writeConfig: writeConfig{
+				ssh: strings.Join([]string{
+					baseHeader,
+					"",
+				}, "\n"),
+			},
+			wantConfig: wantConfig{
+				ssh: strings.Join([]string{
+					baseHeader,
+					"",
+				}, "\n"),
+			},
+			args: []string{
+				"--ssh-option", "ForwardAgent=yes",
+				"--dry-run",
+				"--yes",
+			},
+		},
+	}
+	for _, tt := range tests {
+		tt := tt
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			var (
+				client    = coderdtest.New(t, &coderdtest.Options{IncludeProvisionerD: true})
+				user      = coderdtest.CreateFirstUser(t, client)
+				version   = coderdtest.CreateTemplateVersion(t, client, user.OrganizationID, nil)
+				_         = coderdtest.AwaitTemplateVersionJob(t, client, version.ID)
+				project   = coderdtest.CreateTemplate(t, client, user.OrganizationID, version.ID)
+				workspace = coderdtest.CreateWorkspace(t, client, user.OrganizationID, project.ID)
+				_         = coderdtest.AwaitWorkspaceBuildJob(t, client, workspace.LatestBuild.ID)
+			)
+
+			// Prepare ssh config files.
+			sshConfigName := sshConfigFileName(t)
+			if tt.writeConfig.ssh != "" {
+				sshConfigFileCreate(t, sshConfigName, strings.NewReader(tt.writeConfig.ssh))
+			}
+
+			args := []string{
+				"config-ssh",
+				"--ssh-config-file", sshConfigName,
+			}
+			args = append(args, tt.args...)
+			cmd, root := clitest.New(t, args...)
+			clitest.SetupConfig(t, client, root)
+
+			pty := ptytest.New(t)
+			cmd.SetIn(pty.Input())
+			cmd.SetOut(pty.Output())
+			done := tGo(t, func() {
+				err := cmd.Execute()
+				if !tt.wantErr {
+					assert.NoError(t, err)
+				} else {
+					assert.Error(t, err)
+				}
+			})
+
+			for _, m := range tt.matches {
+				pty.ExpectMatch(m.match)
+				pty.WriteLine(m.write)
+			}
+
+			<-done
+
+			if tt.wantConfig.ssh != "" {
+				got := sshConfigFileRead(t, sshConfigName)
+				assert.Equal(t, tt.wantConfig.ssh, got)
+			}
+		})
+	}
+}
+
+func TestConfigSSH_Hostnames(t *testing.T) {
+	t.Parallel()
+
+	type resourceSpec struct {
+		name   string
+		agents []string
+	}
+	tests := []struct {
+		name      string
+		resources []resourceSpec
+		expected  []string
+	}{
+		{
+			name: "one resource with one agent",
+			resources: []resourceSpec{
+				{name: "foo", agents: []string{"agent1"}},
+			},
+			expected: []string{"coder.@", "coder.@.agent1"},
+		},
+		{
+			name: "one resource with two agents",
+			resources: []resourceSpec{
+				{name: "foo", agents: []string{"agent1", "agent2"}},
+			},
+			expected: []string{"coder.@.agent1", "coder.@.agent2"},
+		},
+		{
+			name: "two resources with one agent",
+			resources: []resourceSpec{
+				{name: "foo", agents: []string{"agent1"}},
+				{name: "bar"},
+			},
+			expected: []string{"coder.@", "coder.@.agent1"},
+		},
+		{
+			name: "two resources with two agents",
+			resources: []resourceSpec{
+				{name: "foo", agents: []string{"agent1"}},
+				{name: "bar", agents: []string{"agent2"}},
+			},
+			expected: []string{"coder.@.agent1", "coder.@.agent2"},
+		},
+	}
+
+	for _, tt := range tests {
+		tt := tt
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			var resources []*proto.Resource
+			for _, resourceSpec := range tt.resources {
+				resource := &proto.Resource{
+					Name: resourceSpec.name,
+					Type: "aws_instance",
+				}
+				for _, agentName := range resourceSpec.agents {
+					resource.Agents = append(resource.Agents, &proto.Agent{
+						Id:   uuid.NewString(),
+						Name: agentName,
+					})
+				}
+				resources = append(resources, resource)
+			}
+
+			provisionResponse := []*proto.Provision_Response{{
+				Type: &proto.Provision_Response_Complete{
+					Complete: &proto.Provision_Complete{
+						Resources: resources,
+					},
+				},
+			}}
+
+			client := coderdtest.New(t, &coderdtest.Options{IncludeProvisionerD: true})
+			user := coderdtest.CreateFirstUser(t, client)
+			// authToken := uuid.NewString()
+			version := coderdtest.CreateTemplateVersion(t, client, user.OrganizationID, &echo.Responses{
+				Parse:           echo.ParseComplete,
+				ProvisionDryRun: provisionResponse,
+				Provision:       provisionResponse,
+			})
+			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)
+
+			sshConfigFile := sshConfigFileName(t)
+
+			cmd, 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)
+			}()
+
+			matches := []struct {
+				match, write string
+			}{
+				{match: "Continue?", write: "yes"},
+			}
+			for _, m := range matches {
+				pty.ExpectMatch(m.match)
+				pty.WriteLine(m.write)
+			}
+
+			<-doneChan
+
+			var expectedHosts []string
+			for _, hostnamePattern := range tt.expected {
+				hostname := strings.ReplaceAll(hostnamePattern, "@", workspace.Name)
+				expectedHosts = append(expectedHosts, hostname)
+			}
+
+			hosts := sshConfigFileParseHosts(t, sshConfigFile)
+			require.ElementsMatch(t, expectedHosts, hosts)
+		})
+	}
+}
+
+// sshConfigFileParseHosts reads a file in the format of .ssh/config and extracts
+// the hostnames that are listed in "Host" directives.
+func sshConfigFileParseHosts(t *testing.T, name string) []string {
+	t.Helper()
+	b, err := os.ReadFile(name)
+	require.NoError(t, err)
+
+	var result []string
+	lineScanner := bufio.NewScanner(bytes.NewBuffer(b))
+	for lineScanner.Scan() {
+		line := lineScanner.Text()
+		line = strings.TrimSpace(line)
+
+		tokenScanner := bufio.NewScanner(bytes.NewBufferString(line))
+		tokenScanner.Split(bufio.ScanWords)
+		ok := tokenScanner.Scan()
+		if ok && tokenScanner.Text() == "Host" {
+			for tokenScanner.Scan() {
+				result = append(result, tokenScanner.Text())
+			}
+		}
+	}
+
+	return result
+}

cli/constants.go

@@ -0,0 +1,6 @@
+package cli
+
+const (
+	timeFormat = "3:04PM MST"
+	dateFormat = "Jan 2, 2006"
+)

cli/create.go

@@ -0,0 +1,284 @@
+package cli
+
+import (
+	"fmt"
+	"time"
+
+	"github.com/spf13/cobra"
+	"golang.org/x/exp/slices"
+	"golang.org/x/xerrors"
+
+	"github.com/coder/coder/cli/cliflag"
+	"github.com/coder/coder/cli/cliui"
+	"github.com/coder/coder/coderd/util/ptr"
+	"github.com/coder/coder/codersdk"
+)
+
+func create() *cobra.Command {
+	var (
+		parameterFile string
+		templateName  string
+		startAt       string
+		stopAfter     time.Duration
+		workspaceName string
+	)
+	cmd := &cobra.Command{
+		Annotations: workspaceCommand,
+		Use:         "create [name]",
+		Short:       "Create a workspace from a template",
+		RunE: func(cmd *cobra.Command, args []string) error {
+			client, err := CreateClient(cmd)
+			if err != nil {
+				return err
+			}
+
+			organization, err := currentOrganization(cmd, client)
+			if err != nil {
+				return err
+			}
+
+			if len(args) >= 1 {
+				workspaceName = args[0]
+			}
+
+			if workspaceName == "" {
+				workspaceName, err = cliui.Prompt(cmd, cliui.PromptOptions{
+					Text: "Specify a name for your workspace:",
+					Validate: func(workspaceName string) error {
+						_, err = client.WorkspaceByOwnerAndName(cmd.Context(), codersdk.Me, workspaceName, codersdk.WorkspaceOptions{})
+						if err == nil {
+							return xerrors.Errorf("A workspace already exists named %q!", workspaceName)
+						}
+						return nil
+					},
+				})
+				if err != nil {
+					return err
+				}
+			}
+
+			_, err = client.WorkspaceByOwnerAndName(cmd.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:"))
+
+				templates, err := client.TemplatesByOrganization(cmd.Context(), organization.ID)
+				if err != nil {
+					return err
+				}
+
+				slices.SortFunc(templates, func(a, b codersdk.Template) bool {
+					return a.WorkspaceOwnerCount > b.WorkspaceOwnerCount
+				})
+
+				templateNames := make([]string, 0, len(templates))
+				templateByName := make(map[string]codersdk.Template, len(templates))
+
+				for _, template := range templates {
+					templateName := template.Name
+
+					if template.WorkspaceOwnerCount > 0 {
+						developerText := "developer"
+						if template.WorkspaceOwnerCount != 1 {
+							developerText = "developers"
+						}
+
+						templateName += cliui.Styles.Placeholder.Render(fmt.Sprintf(" (used by %d %s)", template.WorkspaceOwnerCount, developerText))
+					}
+
+					templateNames = append(templateNames, templateName)
+					templateByName[templateName] = template
+				}
+
+				// Move the cursor up a single line for nicer display!
+				option, err := cliui.Select(cmd, cliui.SelectOptions{
+					Options:    templateNames,
+					HideSearch: true,
+				})
+				if err != nil {
+					return err
+				}
+
+				template = templateByName[option]
+			} else {
+				template, err = client.TemplateByName(cmd.Context(), organization.ID, templateName)
+				if err != nil {
+					return xerrors.Errorf("get template by name: %w", err)
+				}
+			}
+
+			var schedSpec *string
+			if startAt != "" {
+				sched, err := parseCLISchedule(startAt)
+				if err != nil {
+					return err
+				}
+				schedSpec = ptr.Ref(sched.String())
+			}
+
+			parameters, err := prepWorkspaceBuild(cmd, client, prepWorkspaceBuildArgs{
+				Template:         template,
+				ExistingParams:   []codersdk.Parameter{},
+				ParameterFile:    parameterFile,
+				NewWorkspaceName: workspaceName,
+			})
+			if err != nil {
+				return err
+			}
+
+			_, err = cliui.Prompt(cmd, cliui.PromptOptions{
+				Text:      "Confirm create?",
+				IsConfirm: true,
+			})
+			if err != nil {
+				return err
+			}
+
+			after := time.Now()
+			workspace, err := client.CreateWorkspace(cmd.Context(), organization.ID, codersdk.CreateWorkspaceRequest{
+				TemplateID:        template.ID,
+				Name:              workspaceName,
+				AutostartSchedule: schedSpec,
+				TTLMillis:         ptr.Ref(stopAfter.Milliseconds()),
+				ParameterValues:   parameters,
+			})
+			if err != nil {
+				return err
+			}
+
+			err = cliui.WorkspaceBuild(cmd.Context(), cmd.OutOrStdout(), client, workspace.LatestBuild.ID, after)
+			if err != nil {
+				return 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)))
+			return nil
+		},
+	}
+
+	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
+}
+
+// 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()
+	templateVersion, err := client.TemplateVersion(ctx, args.Template.ActiveVersionID)
+	if err != nil {
+		return nil, err
+	}
+	parameterSchemas, err := client.TemplateVersionSchema(ctx, templateVersion.ID)
+	if err != nil {
+		return nil, err
+	}
+
+	// parameterMapFromFile can be nil if parameter file is not specified
+	var parameterMapFromFile map[string]string
+	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")
+		parameterMapFromFile, err = createParameterMapFromFile(args.ParameterFile)
+		if err != nil {
+			return nil, err
+		}
+	}
+	disclaimerPrinted := false
+	parameters := 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")
+			disclaimerPrinted = true
+		}
+
+		// Param file is all or nothing
+		if !useParamFile {
+			for _, e := range args.ExistingParams {
+				if e.Name == parameterSchema.Name {
+					// If the param already exists, we do not need to prompt it again.
+					// The workspace scope will reuse params for each build.
+					continue PromptParamLoop
+				}
+			}
+		}
+
+		parameterValue, err := getParameterValueFromMapOrInput(cmd, parameterMapFromFile, parameterSchema)
+		if err != nil {
+			return nil, err
+		}
+
+		parameters = append(parameters, codersdk.CreateParameterRequest{
+			Name:              parameterSchema.Name,
+			SourceValue:       parameterValue,
+			SourceScheme:      codersdk.ParameterSourceSchemeData,
+			DestinationScheme: parameterSchema.DefaultDestinationScheme,
+		})
+	}
+	_, _ = fmt.Fprintln(cmd.OutOrStdout())
+
+	// 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,
+	})
+	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{
+		Fetch: func() (codersdk.ProvisionerJob, error) {
+			return client.TemplateVersionDryRun(cmd.Context(), templateVersion.ID, dryRun.ID)
+		},
+		Cancel: func() error {
+			return client.CancelTemplateVersionDryRun(cmd.Context(), templateVersion.ID, dryRun.ID)
+		},
+		Logs: func() (<-chan codersdk.ProvisionerJobLog, error) {
+			return client.TemplateVersionDryRunLogsAfter(cmd.Context(), templateVersion.ID, dryRun.ID, after)
+		},
+		// Don't show log output for the dry-run unless there's an error.
+		Silent: true,
+	})
+	if err != nil {
+		// TODO (Dean): reprompt for parameter values if we deem it to
+		// be a validation error
+		return nil, xerrors.Errorf("dry-run workspace: %w", err)
+	}
+
+	resources, err := client.TemplateVersionDryRunResources(cmd.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{
+		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 parameters, nil
+}

cli/create_test.go

@@ -0,0 +1,334 @@
+package cli_test
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"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/pty/ptytest"
+	"github.com/coder/coder/testutil"
+)
+
+func TestCreate(t *testing.T) {
+	t.Parallel()
+	t.Run("Create", func(t *testing.T) {
+		t.Parallel()
+		client := coderdtest.New(t, &coderdtest.Options{IncludeProvisionerD: true})
+		user := coderdtest.CreateFirstUser(t, client)
+		version := coderdtest.CreateTemplateVersion(t, client, user.OrganizationID, &echo.Responses{
+			Parse:           echo.ParseComplete,
+			Provision:       provisionCompleteWithAgent,
+			ProvisionDryRun: provisionCompleteWithAgent,
+		})
+		coderdtest.AwaitTemplateVersionJob(t, client, version.ID)
+		template := coderdtest.CreateTemplate(t, client, user.OrganizationID, version.ID)
+		args := []string{
+			"create",
+			"my-workspace",
+			"--template", template.Name,
+			"--start-at", "9:30AM Mon-Fri US/Central",
+			"--stop-after", "8h",
+		}
+		cmd, root := clitest.New(t, args...)
+		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)
+		}()
+		matches := []struct {
+			match string
+			write string
+		}{
+			{match: "compute.main"},
+			{match: "smith (linux, i386)"},
+			{match: "Confirm create", write: "yes"},
+		}
+		for _, m := range matches {
+			pty.ExpectMatch(m.match)
+			if len(m.write) > 0 {
+				pty.WriteLine(m.write)
+			}
+		}
+		<-doneChan
+
+		ws, err := client.WorkspaceByOwnerAndName(context.Background(), "testuser", "my-workspace", codersdk.WorkspaceOptions{})
+		if assert.NoError(t, err, "expected workspace to be created") {
+			assert.Equal(t, ws.TemplateName, template.Name)
+			if assert.NotNil(t, ws.AutostartSchedule) {
+				assert.Equal(t, *ws.AutostartSchedule, "CRON_TZ=US/Central 30 9 * * Mon-Fri")
+			}
+			if assert.NotNil(t, ws.TTLMillis) {
+				assert.Equal(t, *ws.TTLMillis, 8*time.Hour.Milliseconds())
+			}
+		}
+	})
+
+	t.Run("CreateFromListWithSkip", func(t *testing.T) {
+		t.Parallel()
+		client := coderdtest.New(t, &coderdtest.Options{IncludeProvisionerD: true})
+		user := coderdtest.CreateFirstUser(t, client)
+		version := coderdtest.CreateTemplateVersion(t, client, user.OrganizationID, nil)
+		coderdtest.AwaitTemplateVersionJob(t, client, version.ID)
+		_ = coderdtest.CreateTemplate(t, client, user.OrganizationID, version.ID)
+		cmd, root := clitest.New(t, "create", "my-workspace", "-y")
+
+		member := coderdtest.CreateAnotherUser(t, client, user.OrganizationID)
+		clitest.SetupConfig(t, member, root)
+		cmdCtx, done := context.WithTimeout(context.Background(), testutil.WaitLong)
+		go func() {
+			defer done()
+			err := cmd.ExecuteContext(cmdCtx)
+			assert.NoError(t, err)
+		}()
+		// No pty interaction needed since we use the -y skip prompt flag
+		<-cmdCtx.Done()
+		require.ErrorIs(t, cmdCtx.Err(), context.Canceled)
+	})
+
+	t.Run("FromNothing", func(t *testing.T) {
+		t.Parallel()
+		client := coderdtest.New(t, &coderdtest.Options{IncludeProvisionerD: true})
+		user := coderdtest.CreateFirstUser(t, client)
+		version := coderdtest.CreateTemplateVersion(t, client, user.OrganizationID, nil)
+		coderdtest.AwaitTemplateVersionJob(t, client, version.ID)
+		template := coderdtest.CreateTemplate(t, client, user.OrganizationID, version.ID)
+		cmd, root := clitest.New(t, "create", "")
+		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)
+		}()
+		matches := []string{
+			"Specify a name", "my-workspace",
+			"Confirm create?", "yes",
+		}
+		for i := 0; i < len(matches); i += 2 {
+			match := matches[i]
+			value := matches[i+1]
+			pty.ExpectMatch(match)
+			pty.WriteLine(value)
+		}
+		<-doneChan
+
+		ws, err := client.WorkspaceByOwnerAndName(cmd.Context(), "testuser", "my-workspace", codersdk.WorkspaceOptions{})
+		if assert.NoError(t, err, "expected workspace to be created") {
+			assert.Equal(t, ws.TemplateName, template.Name)
+			assert.Nil(t, ws.AutostartSchedule, "expected workspace autostart schedule to be nil")
+		}
+	})
+
+	t.Run("WithParameter", func(t *testing.T) {
+		t.Parallel()
+		client := coderdtest.New(t, &coderdtest.Options{IncludeProvisionerD: true})
+		user := coderdtest.CreateFirstUser(t, client)
+
+		defaultValue := "something"
+		version := coderdtest.CreateTemplateVersion(t, client, user.OrganizationID, &echo.Responses{
+			Parse:           createTestParseResponseWithDefault(defaultValue),
+			Provision:       echo.ProvisionComplete,
+			ProvisionDryRun: echo.ProvisionComplete,
+		})
+
+		coderdtest.AwaitTemplateVersionJob(t, client, version.ID)
+		_ = coderdtest.CreateTemplate(t, client, user.OrganizationID, version.ID)
+		cmd, root := clitest.New(t, "create", "")
+		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)
+		}()
+
+		matches := []string{
+			"Specify a name", "my-workspace",
+			fmt.Sprintf("Enter a value (default: %q):", defaultValue), "bingo",
+			"Enter a value:", "boingo",
+			"Confirm create?", "yes",
+		}
+		for i := 0; i < len(matches); i += 2 {
+			match := matches[i]
+			value := matches[i+1]
+			pty.ExpectMatch(match)
+			pty.WriteLine(value)
+		}
+		<-doneChan
+	})
+
+	t.Run("WithParameterFileContainingTheValue", func(t *testing.T) {
+		t.Parallel()
+		client := coderdtest.New(t, &coderdtest.Options{IncludeProvisionerD: true})
+		user := coderdtest.CreateFirstUser(t, client)
+
+		defaultValue := "something"
+		version := coderdtest.CreateTemplateVersion(t, client, user.OrganizationID, &echo.Responses{
+			Parse:           createTestParseResponseWithDefault(defaultValue),
+			Provision:       echo.ProvisionComplete,
+			ProvisionDryRun: echo.ProvisionComplete,
+		})
+
+		coderdtest.AwaitTemplateVersionJob(t, client, version.ID)
+		_ = coderdtest.CreateTemplate(t, client, user.OrganizationID, version.ID)
+		tempDir := t.TempDir()
+		removeTmpDirUntilSuccessAfterTest(t, tempDir)
+		parameterFile, _ := os.CreateTemp(tempDir, "testParameterFile*.yaml")
+		_, _ = parameterFile.WriteString("region: \"bingo\"\nusername: \"boingo\"")
+		cmd, root := clitest.New(t, "create", "", "--parameter-file", parameterFile.Name())
+		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)
+		}()
+
+		matches := []string{
+			"Specify a name", "my-workspace",
+			"Confirm create?", "yes",
+		}
+		for i := 0; i < len(matches); i += 2 {
+			match := matches[i]
+			value := matches[i+1]
+			pty.ExpectMatch(match)
+			pty.WriteLine(value)
+		}
+		<-doneChan
+	})
+
+	t.Run("WithParameterFileNotContainingTheValue", func(t *testing.T) {
+		t.Parallel()
+		client := coderdtest.New(t, &coderdtest.Options{IncludeProvisionerD: true})
+		user := coderdtest.CreateFirstUser(t, client)
+
+		defaultValue := "something"
+		version := coderdtest.CreateTemplateVersion(t, client, user.OrganizationID, &echo.Responses{
+			Parse:           createTestParseResponseWithDefault(defaultValue),
+			Provision:       echo.ProvisionComplete,
+			ProvisionDryRun: echo.ProvisionComplete,
+		})
+		coderdtest.AwaitTemplateVersionJob(t, client, version.ID)
+		template := coderdtest.CreateTemplate(t, client, user.OrganizationID, version.ID)
+		tempDir := t.TempDir()
+		removeTmpDirUntilSuccessAfterTest(t, tempDir)
+		parameterFile, _ := os.CreateTemp(tempDir, "testParameterFile*.yaml")
+		_, _ = parameterFile.WriteString("zone: \"bananas\"")
+		cmd, root := clitest.New(t, "create", "my-workspace", "--template", template.Name, "--parameter-file", parameterFile.Name())
+		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.EqualError(t, err, "Parameter value absent in parameter file for \"region\"!")
+		}()
+		<-doneChan
+	})
+
+	t.Run("FailedDryRun", func(t *testing.T) {
+		t.Parallel()
+		client := coderdtest.New(t, &coderdtest.Options{IncludeProvisionerD: true})
+		user := coderdtest.CreateFirstUser(t, client)
+		version := coderdtest.CreateTemplateVersion(t, client, user.OrganizationID, &echo.Responses{
+			Parse: []*proto.Parse_Response{{
+				Type: &proto.Parse_Response_Complete{
+					Complete: &proto.Parse_Complete{
+						ParameterSchemas: echo.ParameterSuccess,
+					},
+				},
+			}},
+			ProvisionDryRun: []*proto.Provision_Response{
+				{
+					Type: &proto.Provision_Response_Complete{
+						Complete: &proto.Provision_Complete{},
+					},
+				},
+			},
+		})
+
+		tempDir := t.TempDir()
+		parameterFile, err := os.CreateTemp(tempDir, "testParameterFile*.yaml")
+		require.NoError(t, err)
+		defer parameterFile.Close()
+		_, _ = parameterFile.WriteString(fmt.Sprintf("%s: %q", echo.ParameterExecKey, echo.ParameterError("fail")))
+
+		// The template import job should end up failed, but we need it to be
+		// succeeded so the dry-run can begin.
+		version = coderdtest.AwaitTemplateVersionJob(t, client, version.ID)
+		require.Equal(t, codersdk.ProvisionerJobSucceeded, version.Job.Status, "job is not failed")
+
+		_ = coderdtest.CreateTemplate(t, client, user.OrganizationID, version.ID)
+		cmd, root := clitest.New(t, "create", "test", "--parameter-file", parameterFile.Name())
+		clitest.SetupConfig(t, client, root)
+		pty := ptytest.New(t)
+		cmd.SetIn(pty.Input())
+		cmd.SetOut(pty.Output())
+
+		err = cmd.Execute()
+		require.Error(t, err)
+		require.ErrorContains(t, err, "dry-run workspace")
+	})
+}
+
+func createTestParseResponseWithDefault(defaultValue string) []*proto.Parse_Response {
+	return []*proto.Parse_Response{{
+		Type: &proto.Parse_Response_Complete{
+			Complete: &proto.Parse_Complete{
+				ParameterSchemas: []*proto.ParameterSchema{
+					{
+						AllowOverrideSource: true,
+						Name:                "region",
+						Description:         "description 1",
+						DefaultSource: &proto.ParameterSource{
+							Scheme: proto.ParameterSource_DATA,
+							Value:  defaultValue,
+						},
+						DefaultDestination: &proto.ParameterDestination{
+							Scheme: proto.ParameterDestination_PROVISIONER_VARIABLE,
+						},
+					},
+					{
+						AllowOverrideSource: true,
+						Name:                "username",
+						Description:         "description 2",
+						DefaultSource: &proto.ParameterSource{
+							Scheme: proto.ParameterSource_DATA,
+							// No default value
+							Value: "",
+						},
+						DefaultDestination: &proto.ParameterDestination{
+							Scheme: proto.ParameterDestination_PROVISIONER_VARIABLE,
+						},
+					},
+				},
+			},
+		},
+	}}
+}

cli/delete.go

@@ -0,0 +1,58 @@
+package cli
+
+import (
+	"fmt"
+	"time"
+
+	"github.com/spf13/cobra"
+
+	"github.com/coder/coder/cli/cliui"
+	"github.com/coder/coder/codersdk"
+)
+
+// nolint
+func deleteWorkspace() *cobra.Command {
+	cmd := &cobra.Command{
+		Annotations: workspaceCommand,
+		Use:         "delete <workspace>",
+		Short:       "Delete a workspace",
+		Aliases:     []string{"rm"},
+		Args:        cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			_, err := cliui.Prompt(cmd, cliui.PromptOptions{
+				Text:      "Confirm delete workspace?",
+				IsConfirm: true,
+				Default:   cliui.ConfirmNo,
+			})
+			if err != nil {
+				return err
+			}
+
+			client, err := CreateClient(cmd)
+			if err != nil {
+				return err
+			}
+			workspace, err := namedWorkspace(cmd, client, args[0])
+			if err != nil {
+				return err
+			}
+			before := time.Now()
+			build, err := client.CreateWorkspaceBuild(cmd.Context(), workspace.ID, codersdk.CreateWorkspaceBuildRequest{
+				Transition: codersdk.WorkspaceTransitionDelete,
+			})
+			if err != nil {
+				return err
+			}
+
+			err = cliui.WorkspaceBuild(cmd.Context(), cmd.OutOrStdout(), client, build.ID, before)
+			if err != nil {
+				return err
+			}
+
+			_, _ = fmt.Fprintf(cmd.OutOrStdout(), "\nThe %s workspace has been deleted at %s!\n", cliui.Styles.Keyword.Render(workspace.Name), cliui.Styles.DateTimeStamp.Render(time.Now().Format(time.Stamp)))
+			return nil
+		},
+	}
+	cliui.AllowSkipPrompt(cmd)
+	return cmd
+}

cli/delete_test.go

@@ -0,0 +1,96 @@
+package cli_test
+
+import (
+	"context"
+	"io"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/coder/coder/cli/clitest"
+	"github.com/coder/coder/coderd/coderdtest"
+	"github.com/coder/coder/codersdk"
+	"github.com/coder/coder/pty/ptytest"
+)
+
+func TestDelete(t *testing.T) {
+	t.Parallel()
+	t.Run("WithParameter", func(t *testing.T) {
+		t.Parallel()
+		client := coderdtest.New(t, &coderdtest.Options{IncludeProvisionerD: true})
+		user := coderdtest.CreateFirstUser(t, client)
+		version := coderdtest.CreateTemplateVersion(t, client, user.OrganizationID, nil)
+		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)
+		cmd, root := clitest.New(t, "delete", workspace.Name, "-y")
+		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()
+			// When running with the race detector on, we sometimes get an EOF.
+			if err != nil {
+				assert.ErrorIs(t, err, io.EOF)
+			}
+		}()
+		pty.ExpectMatch("Cleaning Up")
+		<-doneChan
+	})
+
+	t.Run("DifferentUser", func(t *testing.T) {
+		t.Parallel()
+		adminClient := coderdtest.New(t, &coderdtest.Options{IncludeProvisionerD: true})
+		adminUser := coderdtest.CreateFirstUser(t, adminClient)
+		orgID := adminUser.OrganizationID
+		client := coderdtest.CreateAnotherUser(t, adminClient, orgID)
+		user, err := client.User(context.Background(), codersdk.Me)
+		require.NoError(t, err)
+
+		version := coderdtest.CreateTemplateVersion(t, adminClient, orgID, nil)
+		coderdtest.AwaitTemplateVersionJob(t, adminClient, version.ID)
+		template := coderdtest.CreateTemplate(t, adminClient, orgID, version.ID)
+		workspace := coderdtest.CreateWorkspace(t, client, orgID, template.ID)
+		coderdtest.AwaitWorkspaceBuildJob(t, client, workspace.LatestBuild.ID)
+
+		cmd, root := clitest.New(t, "delete", user.Username+"/"+workspace.Name, "-y")
+		clitest.SetupConfig(t, adminClient, 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()
+			// When running with the race detector on, we sometimes get an EOF.
+			if err != nil {
+				assert.ErrorIs(t, err, io.EOF)
+			}
+		}()
+
+		pty.ExpectMatch("Cleaning Up")
+		<-doneChan
+
+		workspace, err = client.Workspace(context.Background(), workspace.ID)
+		require.ErrorContains(t, err, "was deleted")
+	})
+
+	t.Run("InvalidWorkspaceIdentifier", func(t *testing.T) {
+		t.Parallel()
+		client := coderdtest.New(t, nil)
+		cmd, root := clitest.New(t, "delete", "a/b/c", "-y")
+		clitest.SetupConfig(t, client, root)
+		doneChan := make(chan struct{})
+		go func() {
+			defer close(doneChan)
+			err := cmd.Execute()
+			assert.ErrorContains(t, err, "invalid workspace name: \"a/b/c\"")
+		}()
+		<-doneChan
+	})
+}

cli/dotfiles.go

@@ -0,0 +1,282 @@
+package cli
+
+import (
+	"errors"
+	"fmt"
+	"io/fs"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"time"
+
+	"github.com/spf13/cobra"
+	"golang.org/x/xerrors"
+
+	"github.com/coder/coder/cli/cliflag"
+	"github.com/coder/coder/cli/cliui"
+)
+
+func dotfiles() *cobra.Command {
+	var symlinkDir string
+	cmd := &cobra.Command{
+		Use:   "dotfiles [git_repo_url]",
+		Args:  cobra.ExactArgs(1),
+		Short: "Check out and install a dotfiles repository.",
+		Example: formatExamples(
+			example{
+				Description: "Check out and install a dotfiles repository without prompts",
+				Command:     "coder dotfiles --yes git@github.com:example/dotfiles.git",
+			},
+		),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			var (
+				dotfilesRepoDir = "dotfiles"
+				gitRepo         = args[0]
+				cfg             = createConfig(cmd)
+				cfgDir          = string(cfg)
+				dotfilesDir     = filepath.Join(cfgDir, dotfilesRepoDir)
+				// This follows the same pattern outlined by others in the market:
+				// https://github.com/coder/coder/pull/1696#issue-1245742312
+				installScriptSet = []string{
+					"install.sh",
+					"install",
+					"bootstrap.sh",
+					"bootstrap",
+					"script/bootstrap",
+					"setup.sh",
+					"setup",
+					"script/setup",
+				}
+			)
+
+			_, _ = fmt.Fprint(cmd.OutOrStdout(), "Checking if dotfiles repository already exists...\n")
+			dotfilesExists, err := dirExists(dotfilesDir)
+			if err != nil {
+				return xerrors.Errorf("checking dir %s: %w", dotfilesDir, err)
+			}
+
+			moved := false
+			if dotfilesExists {
+				du, err := cfg.DotfilesURL().Read()
+				if err != nil && !errors.Is(err, os.ErrNotExist) {
+					return xerrors.Errorf("reading dotfiles url config: %w", err)
+				}
+				// if the git url has changed we create a backup and clone fresh
+				if gitRepo != du {
+					backupDir := fmt.Sprintf("%s_backup_%s", dotfilesDir, time.Now().Format(time.RFC3339))
+					_, err = cliui.Prompt(cmd, cliui.PromptOptions{
+						Text:      fmt.Sprintf("The dotfiles URL has changed from %q to %q.\n  Coder will backup the existing repo to %s.\n\n  Continue?", du, gitRepo, backupDir),
+						IsConfirm: true,
+					})
+					if err != nil {
+						return err
+					}
+
+					err = os.Rename(dotfilesDir, backupDir)
+					if err != nil {
+						return xerrors.Errorf("renaming dir %s: %w", dotfilesDir, err)
+					}
+					_, _ = fmt.Fprint(cmd.OutOrStdout(), "Done backup up dotfiles.\n")
+					dotfilesExists = false
+					moved = true
+				}
+			}
+
+			var (
+				gitCmdDir   string
+				subcommands []string
+				promptText  string
+			)
+			if dotfilesExists {
+				_, _ = fmt.Fprintf(cmd.OutOrStdout(), "Found dotfiles repository at %s\n", dotfilesDir)
+				gitCmdDir = dotfilesDir
+				subcommands = []string{"pull", "--ff-only"}
+				promptText = fmt.Sprintf("Pulling latest from %s into directory %s.\n  Continue?", gitRepo, dotfilesDir)
+			} else {
+				if !moved {
+					_, _ = fmt.Fprintf(cmd.OutOrStdout(), "Did not find dotfiles repository at %s\n", dotfilesDir)
+				}
+				gitCmdDir = cfgDir
+				subcommands = []string{"clone", args[0], dotfilesRepoDir}
+				promptText = fmt.Sprintf("Cloning %s into directory %s.\n\n  Continue?", gitRepo, dotfilesDir)
+			}
+
+			_, err = cliui.Prompt(cmd, cliui.PromptOptions{
+				Text:      promptText,
+				IsConfirm: true,
+			})
+			if err != nil {
+				return err
+			}
+
+			// ensure command dir exists
+			err = os.MkdirAll(gitCmdDir, 0750)
+			if err != nil {
+				return xerrors.Errorf("ensuring dir at %s: %w", gitCmdDir, err)
+			}
+
+			// check if git ssh command already exists so we can just wrap it
+			gitsshCmd := os.Getenv("GIT_SSH_COMMAND")
+			if gitsshCmd == "" {
+				gitsshCmd = "ssh"
+			}
+
+			// clone or pull repo
+			c := exec.CommandContext(cmd.Context(), "git", subcommands...)
+			c.Dir = gitCmdDir
+			c.Env = append(os.Environ(), fmt.Sprintf(`GIT_SSH_COMMAND=%s -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no`, gitsshCmd))
+			c.Stdout = cmd.OutOrStdout()
+			c.Stderr = cmd.ErrOrStderr()
+			err = c.Run()
+			if err != nil {
+				if !dotfilesExists {
+					return err
+				}
+				// if the repo exists we soft fail the update operation and try to continue
+				_, _ = fmt.Fprintln(cmd.OutOrStdout(), cliui.Styles.Error.Render("Failed to update repo, continuing..."))
+			}
+
+			// save git repo url so we can detect changes next time
+			err = cfg.DotfilesURL().Write(gitRepo)
+			if err != nil {
+				return xerrors.Errorf("writing dotfiles url config: %w", err)
+			}
+
+			files, err := os.ReadDir(dotfilesDir)
+			if err != nil {
+				return xerrors.Errorf("reading files in dir %s: %w", dotfilesDir, err)
+			}
+
+			var dotfiles []string
+			for _, f := range files {
+				// make sure we do not copy `.git*` files
+				if strings.HasPrefix(f.Name(), ".") && !strings.HasPrefix(f.Name(), ".git") {
+					dotfiles = append(dotfiles, f.Name())
+				}
+			}
+
+			script := findScript(installScriptSet, files)
+			if script != "" {
+				_, err = cliui.Prompt(cmd, cliui.PromptOptions{
+					Text:      fmt.Sprintf("Running install script %s.\n\n  Continue?", script),
+					IsConfirm: true,
+				})
+				if err != nil {
+					return err
+				}
+
+				_, _ = fmt.Fprintf(cmd.OutOrStdout(), "Running %s...\n", script)
+				// it is safe to use a variable command here because it's from
+				// a filtered list of pre-approved install scripts
+				// nolint:gosec
+				scriptCmd := exec.CommandContext(cmd.Context(), filepath.Join(dotfilesDir, script))
+				scriptCmd.Dir = dotfilesDir
+				scriptCmd.Stdout = cmd.OutOrStdout()
+				scriptCmd.Stderr = cmd.ErrOrStderr()
+				err = scriptCmd.Run()
+				if err != nil {
+					return xerrors.Errorf("running %s: %w", script, err)
+				}
+
+				_, _ = fmt.Fprintln(cmd.OutOrStdout(), "Dotfiles installation complete.")
+				return nil
+			}
+
+			if len(dotfiles) == 0 {
+				_, _ = fmt.Fprintln(cmd.OutOrStdout(), "No install scripts or dotfiles found, nothing to do.")
+				return nil
+			}
+
+			_, err = cliui.Prompt(cmd, cliui.PromptOptions{
+				Text:      "No install scripts found, symlinking dotfiles to home directory.\n\n  Continue?",
+				IsConfirm: true,
+			})
+			if err != nil {
+				return err
+			}
+
+			if symlinkDir == "" {
+				symlinkDir, err = os.UserHomeDir()
+				if err != nil {
+					return xerrors.Errorf("getting user home: %w", err)
+				}
+			}
+
+			for _, df := range dotfiles {
+				from := filepath.Join(dotfilesDir, df)
+				to := filepath.Join(symlinkDir, df)
+				_, _ = fmt.Fprintf(cmd.OutOrStdout(), "Symlinking %s to %s...\n", from, to)
+
+				isRegular, err := isRegular(to)
+				if err != nil {
+					return xerrors.Errorf("checking symlink for %s: %w", to, err)
+				}
+				// move conflicting non-symlink files to file.ext.bak
+				if isRegular {
+					backup := fmt.Sprintf("%s.bak", to)
+					_, _ = fmt.Fprintf(cmd.OutOrStdout(), "Moving %s to %s...\n", to, backup)
+					err = os.Rename(to, backup)
+					if err != nil {
+						return xerrors.Errorf("renaming dir %s: %w", to, err)
+					}
+				}
+
+				err = os.Symlink(from, to)
+				if err != nil {
+					return xerrors.Errorf("symlinking %s to %s: %w", from, to, err)
+				}
+			}
+
+			_, _ = fmt.Fprintln(cmd.OutOrStdout(), "Dotfiles installation complete.")
+			return nil
+		},
+	}
+	cliui.AllowSkipPrompt(cmd)
+	cliflag.StringVarP(cmd.Flags(), &symlinkDir, "symlink-dir", "", "CODER_SYMLINK_DIR", "", "Specifies the directory for the dotfiles symlink destinations. If empty will use $HOME.")
+
+	return cmd
+}
+
+// dirExists checks if the path exists and is a directory.
+func dirExists(name string) (bool, error) {
+	fi, err := os.Stat(name)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return false, nil
+		}
+
+		return false, xerrors.Errorf("stat dir: %w", err)
+	}
+	if !fi.IsDir() {
+		return false, xerrors.New("exists but not a directory")
+	}
+
+	return true, nil
+}
+
+// findScript will find the first file that matches the script set.
+func findScript(scriptSet []string, files []fs.DirEntry) string {
+	for _, i := range scriptSet {
+		for _, f := range files {
+			if f.Name() == i {
+				return f.Name()
+			}
+		}
+	}
+
+	return ""
+}
+
+// isRegular detects if the file exists and is not a symlink.
+func isRegular(to string) (bool, error) {
+	fi, err := os.Lstat(to)
+	if err != nil {
+		if errors.Is(err, os.ErrNotExist) {
+			return false, nil
+		}
+		return false, xerrors.Errorf("lstat %s: %w", to, err)
+	}
+
+	return fi.Mode().IsRegular(), nil
+}

cli/dotfiles_test.go

@@ -0,0 +1,141 @@
+package cli_test
+
+import (
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"runtime"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+
+	"github.com/coder/coder/cli/clitest"
+	"github.com/coder/coder/cli/config"
+	"github.com/coder/coder/cryptorand"
+)
+
+// nolint:paralleltest
+func TestDotfiles(t *testing.T) {
+	t.Run("MissingArg", func(t *testing.T) {
+		cmd, _ := clitest.New(t, "dotfiles")
+		err := cmd.Execute()
+		require.Error(t, err)
+	})
+	t.Run("NoInstallScript", func(t *testing.T) {
+		_, root := clitest.New(t)
+		testRepo := testGitRepo(t, root)
+
+		// nolint:gosec
+		err := os.WriteFile(filepath.Join(testRepo, ".bashrc"), []byte("wow"), 0750)
+		require.NoError(t, err)
+
+		c := exec.Command("git", "add", ".bashrc")
+		c.Dir = testRepo
+		err = c.Run()
+		require.NoError(t, err)
+
+		c = exec.Command("git", "commit", "-m", `"add .bashrc"`)
+		c.Dir = testRepo
+		out, err := c.CombinedOutput()
+		require.NoError(t, err, string(out))
+
+		cmd, _ := clitest.New(t, "dotfiles", "--global-config", string(root), "--symlink-dir", string(root), "-y", testRepo)
+		err = cmd.Execute()
+		require.NoError(t, err)
+
+		b, err := os.ReadFile(filepath.Join(string(root), ".bashrc"))
+		require.NoError(t, err)
+		require.Equal(t, string(b), "wow")
+	})
+	t.Run("InstallScript", func(t *testing.T) {
+		if runtime.GOOS == "windows" {
+			t.Skip("install scripts on windows require sh and aren't very practical")
+		}
+		_, root := clitest.New(t)
+		testRepo := testGitRepo(t, root)
+
+		// nolint:gosec
+		err := os.WriteFile(filepath.Join(testRepo, "install.sh"), []byte("#!/bin/bash\necho wow > "+filepath.Join(string(root), ".bashrc")), 0750)
+		require.NoError(t, err)
+
+		c := exec.Command("git", "add", "install.sh")
+		c.Dir = testRepo
+		err = c.Run()
+		require.NoError(t, err)
+
+		c = exec.Command("git", "commit", "-m", `"add install.sh"`)
+		c.Dir = testRepo
+		err = c.Run()
+		require.NoError(t, err)
+
+		cmd, _ := clitest.New(t, "dotfiles", "--global-config", string(root), "--symlink-dir", string(root), "-y", testRepo)
+		err = cmd.Execute()
+		require.NoError(t, err)
+
+		b, err := os.ReadFile(filepath.Join(string(root), ".bashrc"))
+		require.NoError(t, err)
+		require.Equal(t, string(b), "wow\n")
+	})
+	t.Run("SymlinkBackup", func(t *testing.T) {
+		_, root := clitest.New(t)
+		testRepo := testGitRepo(t, root)
+
+		// nolint:gosec
+		err := os.WriteFile(filepath.Join(testRepo, ".bashrc"), []byte("wow"), 0750)
+		require.NoError(t, err)
+
+		// add a conflicting file at destination
+		// nolint:gosec
+		err = os.WriteFile(filepath.Join(string(root), ".bashrc"), []byte("backup"), 0750)
+		require.NoError(t, err)
+
+		c := exec.Command("git", "add", ".bashrc")
+		c.Dir = testRepo
+		err = c.Run()
+		require.NoError(t, err)
+
+		c = exec.Command("git", "commit", "-m", `"add .bashrc"`)
+		c.Dir = testRepo
+		out, err := c.CombinedOutput()
+		require.NoError(t, err, string(out))
+
+		cmd, _ := clitest.New(t, "dotfiles", "--global-config", string(root), "--symlink-dir", string(root), "-y", testRepo)
+		err = cmd.Execute()
+		require.NoError(t, err)
+
+		b, err := os.ReadFile(filepath.Join(string(root), ".bashrc"))
+		require.NoError(t, err)
+		require.Equal(t, string(b), "wow")
+
+		// check for backup file
+		b, err = os.ReadFile(filepath.Join(string(root), ".bashrc.bak"))
+		require.NoError(t, err)
+		require.Equal(t, string(b), "backup")
+	})
+}
+
+func testGitRepo(t *testing.T, root config.Root) string {
+	r, err := cryptorand.String(8)
+	require.NoError(t, err)
+	dir := filepath.Join(string(root), fmt.Sprintf("test-repo-%s", r))
+	err = os.MkdirAll(dir, 0750)
+	require.NoError(t, err)
+
+	c := exec.Command("git", "init")
+	c.Dir = dir
+	err = c.Run()
+	require.NoError(t, err)
+
+	c = exec.Command("git", "config", "user.email", "ci@coder.com")
+	c.Dir = dir
+	err = c.Run()
+	require.NoError(t, err)
+
+	c = exec.Command("git", "config", "user.name", "C I")
+	c.Dir = dir
+	err = c.Run()
+	require.NoError(t, err)
+
+	return dir
+}

cli/features.go

@@ -0,0 +1,102 @@
+package cli
+
+import (
+	"encoding/json"
+	"fmt"
+	"strings"
+
+	"github.com/spf13/cobra"
+	"golang.org/x/xerrors"
+
+	"github.com/coder/coder/cli/cliui"
+	"github.com/coder/coder/codersdk"
+)
+
+var featureColumns = []string{"Name", "Entitlement", "Enabled", "Limit", "Actual"}
+
+func features() *cobra.Command {
+	cmd := &cobra.Command{
+		Short:   "List features",
+		Use:     "features",
+		Aliases: []string{"feature"},
+	}
+	cmd.AddCommand(
+		featuresList(),
+	)
+	return cmd
+}
+
+func featuresList() *cobra.Command {
+	var (
+		columns      []string
+		outputFormat string
+	)
+
+	cmd := &cobra.Command{
+		Use:     "list",
+		Aliases: []string{"ls"},
+		RunE: func(cmd *cobra.Command, args []string) error {
+			client, err := CreateClient(cmd)
+			if err != nil {
+				return err
+			}
+			entitlements, err := client.Entitlements(cmd.Context())
+			if err != nil {
+				return err
+			}
+
+			out := ""
+			switch outputFormat {
+			case "table", "":
+				out, err = displayFeatures(columns, entitlements.Features)
+				if err != nil {
+					return xerrors.Errorf("render table: %w", err)
+				}
+			case "json":
+				outBytes, err := json.Marshal(entitlements)
+				if err != nil {
+					return xerrors.Errorf("marshal features to JSON: %w", err)
+				}
+
+				out = string(outBytes)
+			default:
+				return xerrors.Errorf(`unknown output format %q, only "table" and "json" are supported`, outputFormat)
+			}
+
+			_, err = fmt.Fprintln(cmd.OutOrStdout(), out)
+			return err
+		},
+	}
+
+	cmd.Flags().StringArrayVarP(&columns, "column", "c", featureColumns,
+		fmt.Sprintf("Specify a column to filter in the table. Available columns are: %s",
+			strings.Join(featureColumns, ", ")))
+	cmd.Flags().StringVarP(&outputFormat, "output", "o", "table", "Output format. Available formats are: table, json.")
+	return cmd
+}
+
+type featureRow struct {
+	Name        string `table:"name"`
+	Entitlement string `table:"entitlement"`
+	Enabled     bool   `table:"enabled"`
+	Limit       *int64 `table:"limit"`
+	Actual      *int64 `table:"actual"`
+}
+
+// displayFeatures will return a table displaying all features passed in.
+// filterColumns must be a subset of the feature fields and will determine which
+// columns to display
+func displayFeatures(filterColumns []string, features map[string]codersdk.Feature) (string, error) {
+	rows := make([]featureRow, 0, len(features))
+	for name, feat := range features {
+		rows = append(rows, featureRow{
+			Name:        name,
+			Entitlement: string(feat.Entitlement),
+			Enabled:     feat.Enabled,
+			Limit:       feat.Limit,
+			Actual:      feat.Actual,
+		})
+	}
+
+	return cliui.DisplayTable(rows, "name", filterColumns)
+}

cli/features_test.go

@@ -0,0 +1,66 @@
+package cli_test
+
+import (
+	"bytes"
+	"encoding/json"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/coder/coder/cli/clitest"
+	"github.com/coder/coder/coderd/coderdtest"
+	"github.com/coder/coder/codersdk"
+	"github.com/coder/coder/pty/ptytest"
+)
+
+func TestFeaturesList(t *testing.T) {
+	t.Parallel()
+	t.Run("Table", func(t *testing.T) {
+		t.Parallel()
+		client := coderdtest.New(t, nil)
+		coderdtest.CreateFirstUser(t, client)
+		cmd, root := clitest.New(t, "features", "list")
+		clitest.SetupConfig(t, client, root)
+		pty := ptytest.New(t)
+		cmd.SetIn(pty.Input())
+		cmd.SetOut(pty.Output())
+		errC := make(chan error)
+		go func() {
+			errC <- cmd.Execute()
+		}()
+		require.NoError(t, <-errC)
+		pty.ExpectMatch("user_limit")
+		pty.ExpectMatch("not_entitled")
+	})
+	t.Run("JSON", func(t *testing.T) {
+		t.Parallel()
+
+		client := coderdtest.New(t, nil)
+		coderdtest.CreateFirstUser(t, client)
+		cmd, root := clitest.New(t, "features", "list", "-o", "json")
+		clitest.SetupConfig(t, client, root)
+		doneChan := make(chan struct{})
+
+		buf := bytes.NewBuffer(nil)
+		cmd.SetOut(buf)
+		go func() {
+			defer close(doneChan)
+			err := cmd.Execute()
+			assert.NoError(t, err)
+		}()
+
+		<-doneChan
+
+		var entitlements codersdk.Entitlements
+		err := json.Unmarshal(buf.Bytes(), &entitlements)
+		require.NoError(t, err, "unmarshal JSON output")
+		assert.Len(t, entitlements.Features, 2)
+		assert.Empty(t, entitlements.Warnings)
+		assert.Equal(t, codersdk.EntitlementNotEntitled,
+			entitlements.Features[codersdk.FeatureUserLimit].Entitlement)
+		assert.Equal(t, codersdk.EntitlementNotEntitled,
+			entitlements.Features[codersdk.FeatureAuditLog].Entitlement)
+		assert.False(t, entitlements.HasLicense)
+	})
+}

cli/gitssh.go

@@ -1,11 +1,15 @@
 package cli
 
 import (
+	"fmt"
 	"os"
 	"os/exec"
+	"strings"
 
 	"github.com/spf13/cobra"
 	"golang.org/x/xerrors"
+
+	"github.com/coder/coder/cli/cliui"
 )
 
 func gitssh() *cobra.Command {
@@ -14,17 +18,10 @@ func gitssh() *cobra.Command {
 		Hidden: true,
 		Short:  `Wraps the "ssh" command and uses the coder gitssh key for authentication`,
 		RunE: func(cmd *cobra.Command, args []string) error {
-			client, err := createClient(cmd)
+			client, err := createAgentClient(cmd)
 			if err != nil {
-				return xerrors.Errorf("create codersdk client: %w", err)
+				return xerrors.Errorf("create agent client: %w", err)
 			}
-			cfg := createConfig(cmd)
-			session, err := cfg.AgentSession().Read()
-			if err != nil {
-				return xerrors.Errorf("read agent session from config: %w", err)
-			}
-			client.SessionToken = session
-
 			key, err := client.AgentGitSSHKey(cmd.Context())
 			if err != nil {
 				return xerrors.Errorf("get agent git ssh token: %w", err)
@@ -47,12 +44,25 @@ func gitssh() *cobra.Command {
 				return xerrors.Errorf("close temp gitsshkey file: %w", err)
 			}
 
-			a := append([]string{"-i", privateKeyFile.Name()}, args...)
-			c := exec.CommandContext(cmd.Context(), "ssh", a...)
+			args = append([]string{"-i", privateKeyFile.Name()}, args...)
+			c := exec.CommandContext(cmd.Context(), "ssh", args...)
+			c.Stderr = cmd.ErrOrStderr()
 			c.Stdout = cmd.OutOrStdout()
 			c.Stdin = cmd.InOrStdin()
 			err = c.Run()
 			if err != nil {
+				exitErr := &exec.ExitError{}
+				if xerrors.As(err, &exitErr) && exitErr.ExitCode() == 255 {
+					_, _ = fmt.Fprintln(cmd.ErrOrStderr(),
+						"\n"+cliui.Styles.Wrap.Render("Coder authenticates with "+cliui.Styles.Field.Render("git")+
+							" using the public key below. All clones with SSH are authenticated automatically 🪄.")+"\n")
+					_, _ = fmt.Fprintln(cmd.ErrOrStderr(), cliui.Styles.Code.Render(strings.TrimSpace(key.PublicKey))+"\n")
+					_, _ = fmt.Fprintln(cmd.ErrOrStderr(), "Add to GitHub and GitLab:")
+					_, _ = fmt.Fprintln(cmd.ErrOrStderr(), cliui.Styles.Prompt.String()+"https://github.com/settings/ssh/new")
+					_, _ = fmt.Fprintln(cmd.ErrOrStderr(), cliui.Styles.Prompt.String()+"https://gitlab.com/-/profile/keys")
+					_, _ = fmt.Fprintln(cmd.ErrOrStderr())
+					return err
+				}
 				return xerrors.Errorf("run ssh command: %w", err)
 			}
 

cli/gitssh_test.go

@@ -6,15 +6,13 @@ import (
 	"net"
 	"sync/atomic"
 	"testing"
-	"time"
 
 	"github.com/gliderlabs/ssh"
-	"github.com/spf13/cobra"
+	"github.com/google/uuid"
 	"github.com/stretchr/testify/require"
 	gossh "golang.org/x/crypto/ssh"
 
 	"github.com/coder/coder/cli/clitest"
-	"github.com/coder/coder/cli/config"
 	"github.com/coder/coder/coderd/coderdtest"
 	"github.com/coder/coder/codersdk"
 	"github.com/coder/coder/provisioner/echo"
@@ -24,25 +22,21 @@ import (
 func TestGitSSH(t *testing.T) {
 	t.Parallel()
 	t.Run("Dial", func(t *testing.T) {
-		ctx, cancel := context.WithTimeout(context.Background(), time.Second*5)
-		defer cancel()
-		instanceID := "instanceidentifier"
-		certificates, metadataClient := coderdtest.NewAWSInstanceIdentity(t, instanceID)
-		client := coderdtest.New(t, &coderdtest.Options{
-			AWSInstanceIdentity: certificates,
-		})
+		t.Parallel()
+		client := coderdtest.New(t, &coderdtest.Options{IncludeProvisionerD: true})
 		user := coderdtest.CreateFirstUser(t, client)
 
 		// get user public key
-		keypair, err := client.GitSSHKey(ctx, codersdk.Me)
+		keypair, err := client.GitSSHKey(context.Background(), codersdk.Me)
 		require.NoError(t, err)
 		publicKey, _, _, _, err := gossh.ParseAuthorizedKey([]byte(keypair.PublicKey))
 		require.NoError(t, err)
 
-		// setup provisioner
-		coderdtest.NewProvisionerDaemon(t, client)
+		// setup template
+		agentToken := uuid.NewString()
 		version := coderdtest.CreateTemplateVersion(t, client, user.OrganizationID, &echo.Responses{
-			Parse: echo.ParseComplete,
+			Parse:           echo.ParseComplete,
+			ProvisionDryRun: echo.ProvisionComplete,
 			Provision: []*proto.Provision_Response{{
 				Type: &proto.Provision_Response_Complete{
 					Complete: &proto.Provision_Complete{
@@ -50,8 +44,8 @@ func TestGitSSH(t *testing.T) {
 							Name: "somename",
 							Type: "someinstance",
 							Agents: []*proto.Agent{{
-								Auth: &proto.Agent_InstanceId{
-									InstanceId: instanceID,
+								Auth: &proto.Agent_Token{
+									Token: agentToken,
 								},
 							}},
 						}},
@@ -61,27 +55,24 @@ func TestGitSSH(t *testing.T) {
 		})
 		template := coderdtest.CreateTemplate(t, client, user.OrganizationID, version.ID)
 		coderdtest.AwaitTemplateVersionJob(t, client, version.ID)
-		workspace := coderdtest.CreateWorkspace(t, client, codersdk.Me, template.ID)
+		workspace := coderdtest.CreateWorkspace(t, client, user.OrganizationID, template.ID)
 		coderdtest.AwaitWorkspaceBuildJob(t, client, workspace.LatestBuild.ID)
 
 		// start workspace agent
-		cmd, root := clitest.New(t, "workspaces", "agent", "--auth", "aws-instance-identity", "--url", client.URL.String())
-		agentClient := &*client
+		cmd, root := clitest.New(t, "agent", "--agent-token", agentToken, "--agent-url", client.URL.String(), "--wireguard=false")
+		agentClient := client
 		clitest.SetupConfig(t, agentClient, root)
 		ctx, cancelFunc := context.WithCancel(context.Background())
 		defer cancelFunc()
+		agentErrC := make(chan error)
 		go func() {
-			// A linting error occurs for weakly typing the context value here,
-			// but it seems reasonable for a one-off test.
-			// nolint
-			ctx = context.WithValue(ctx, "aws-client", metadataClient)
-			err := cmd.ExecuteContext(ctx)
-			require.NoError(t, err)
+			agentErrC <- cmd.ExecuteContext(ctx)
 		}()
+
 		coderdtest.AwaitWorkspaceAgents(t, client, workspace.LatestBuild.ID)
-		resources, err := client.WorkspaceResourcesByBuild(ctx, workspace.LatestBuild.ID)
+		resources, err := client.WorkspaceResourcesByBuild(context.Background(), workspace.LatestBuild.ID)
 		require.NoError(t, err)
-		dialer, err := client.DialWorkspaceAgent(ctx, resources[0].Agents[0].ID, nil, nil)
+		dialer, err := client.DialWorkspaceAgent(context.Background(), resources[0].Agents[0].ID, nil)
 		require.NoError(t, err)
 		defer dialer.Close()
 		_, err = dialer.Ping()
@@ -95,35 +86,30 @@ func TestGitSSH(t *testing.T) {
 			return ssh.KeysEqual(publicKey, key)
 		})
 		var inc int64
+		sshErrC := make(chan error)
 		go func() {
 			// as long as we get a successful session we don't care if the server errors
 			_ = ssh.Serve(l, func(s ssh.Session) {
 				atomic.AddInt64(&inc, 1)
-				t.Log("got authenticated sesion")
-				err := s.Exit(0)
-				require.NoError(t, err)
+				t.Log("got authenticated session")
+				sshErrC <- s.Exit(0)
 			}, publicKeyOption)
 		}()
 
 		// start ssh session
 		addr, ok := l.Addr().(*net.TCPAddr)
 		require.True(t, ok)
-		cfgDir := createConfig(cmd)
 		// set to agent config dir
-		cmd, root = clitest.New(t, "gitssh", "--global-config="+string(cfgDir), "--", fmt.Sprintf("-p%d", addr.Port), "-o", "StrictHostKeyChecking=no", "127.0.0.1")
-		clitest.SetupConfig(t, agentClient, root)
-
-		err = cmd.ExecuteContext(ctx)
+		gitsshCmd, _ := clitest.New(t, "gitssh", "--agent-url", agentClient.URL.String(), "--agent-token", agentToken, "--", fmt.Sprintf("-p%d", addr.Port), "-o", "StrictHostKeyChecking=no", "-o", "IdentitiesOnly=yes", "127.0.0.1")
+		err = gitsshCmd.ExecuteContext(context.Background())
 		require.NoError(t, err)
 		require.EqualValues(t, 1, inc)
+
+		err = <-sshErrC
+		require.NoError(t, err, "error in ssh session exit")
+
+		cancelFunc()
+		err = <-agentErrC
+		require.NoError(t, err, "error in agent execute")
 	})
 }
-
-// createConfig consumes the global configuration flag to produce a config root.
-func createConfig(cmd *cobra.Command) config.Root {
-	globalRoot, err := cmd.Flags().GetString("global-config")
-	if err != nil {
-		panic(err)
-	}
-	return config.Root(globalRoot)
-}

cli/list.go

@@ -0,0 +1,126 @@
+package cli
+
+import (
+	"fmt"
+	"time"
+
+	"github.com/google/uuid"
+	"github.com/spf13/cobra"
+
+	"github.com/coder/coder/cli/cliui"
+	"github.com/coder/coder/coderd/autobuild/schedule"
+	"github.com/coder/coder/coderd/util/ptr"
+	"github.com/coder/coder/codersdk"
+)
+
+type workspaceListRow struct {
+	Workspace  string `table:"workspace"`
+	Template   string `table:"template"`
+	Status     string `table:"status"`
+	LastBuilt  string `table:"last built"`
+	Outdated   bool   `table:"outdated"`
+	StartsAt   string `table:"starts at"`
+	StopsAfter string `table:"stops after"`
+}
+
+func workspaceListRowFromWorkspace(now time.Time, usersByID map[uuid.UUID]codersdk.User, workspace codersdk.Workspace) workspaceListRow {
+	status := codersdk.WorkspaceDisplayStatus(workspace.LatestBuild.Job.Status, workspace.LatestBuild.Transition)
+
+	lastBuilt := now.UTC().Sub(workspace.LatestBuild.Job.CreatedAt).Truncate(time.Second)
+	autostartDisplay := "-"
+	if !ptr.NilOrEmpty(workspace.AutostartSchedule) {
+		if sched, err := schedule.Weekly(*workspace.AutostartSchedule); err == nil {
+			autostartDisplay = fmt.Sprintf("%s %s (%s)", sched.Time(), sched.DaysOfWeek(), sched.Location())
+		}
+	}
+
+	autostopDisplay := "-"
+	if !ptr.NilOrZero(workspace.TTLMillis) {
+		dur := time.Duration(*workspace.TTLMillis) * time.Millisecond
+		autostopDisplay = durationDisplay(dur)
+		if !workspace.LatestBuild.Deadline.IsZero() && workspace.LatestBuild.Deadline.Time.After(now) && status == "Running" {
+			remaining := time.Until(workspace.LatestBuild.Deadline.Time)
+			autostopDisplay = fmt.Sprintf("%s (%s)", autostopDisplay, relative(remaining))
+		}
+	}
+
+	user := usersByID[workspace.OwnerID]
+	return workspaceListRow{
+		Workspace:  user.Username + "/" + workspace.Name,
+		Template:   workspace.TemplateName,
+		Status:     status,
+		LastBuilt:  durationDisplay(lastBuilt),
+		Outdated:   workspace.Outdated,
+		StartsAt:   autostartDisplay,
+		StopsAfter: autostopDisplay,
+	}
+}
+
+func list() *cobra.Command {
+	var (
+		columns     []string
+		searchQuery string
+		me          bool
+	)
+	cmd := &cobra.Command{
+		Annotations: workspaceCommand,
+		Use:         "list",
+		Short:       "List all workspaces",
+		Aliases:     []string{"ls"},
+		Args:        cobra.ExactArgs(0),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			client, err := CreateClient(cmd)
+			if err != nil {
+				return err
+			}
+			filter := codersdk.WorkspaceFilter{
+				FilterQuery: searchQuery,
+			}
+			if me {
+				myUser, err := client.User(cmd.Context(), codersdk.Me)
+				if err != nil {
+					return err
+				}
+				filter.Owner = myUser.Username
+			}
+			workspaces, err := client.Workspaces(cmd.Context(), filter)
+			if err != nil {
+				return err
+			}
+			if len(workspaces) == 0 {
+				_, _ = fmt.Fprintln(cmd.ErrOrStderr(), cliui.Styles.Prompt.String()+"No workspaces found! Create one:")
+				_, _ = fmt.Fprintln(cmd.ErrOrStderr())
+				_, _ = fmt.Fprintln(cmd.ErrOrStderr(), "  "+cliui.Styles.Code.Render("coder create <name>"))
+				_, _ = fmt.Fprintln(cmd.ErrOrStderr())
+				return nil
+			}
+			users, err := client.Users(cmd.Context(), codersdk.UsersRequest{})
+			if err != nil {
+				return err
+			}
+			usersByID := map[uuid.UUID]codersdk.User{}
+			for _, user := range users {
+				usersByID[user.ID] = user
+			}
+
+			now := time.Now()
+			displayWorkspaces := make([]workspaceListRow, len(workspaces))
+			for i, workspace := range workspaces {
+				displayWorkspaces[i] = workspaceListRowFromWorkspace(now, usersByID, workspace)
+			}
+
+			out, err := cliui.DisplayTable(displayWorkspaces, "workspace", columns)
+			if err != nil {
+				return err
+			}
+
+			_, err = fmt.Fprintln(cmd.OutOrStdout(), out)
+			return err
+		},
+	}
+	cmd.Flags().StringArrayVarP(&columns, "column", "c", nil,
+		"Specify a column to filter in the table.")
+	cmd.Flags().StringVar(&searchQuery, "search", "", "Search for a workspace with a query.")
+	cmd.Flags().BoolVar(&me, "me", false, "Only show workspaces owned by the current user.")
+	return cmd
+}

cli/list_test.go

@@ -0,0 +1,45 @@
+package cli_test
+
+import (
+	"context"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+
+	"github.com/coder/coder/cli/clitest"
+	"github.com/coder/coder/coderd/coderdtest"
+	"github.com/coder/coder/pty/ptytest"
+	"github.com/coder/coder/testutil"
+)
+
+func TestList(t *testing.T) {
+	t.Parallel()
+	t.Run("Single", func(t *testing.T) {
+		t.Parallel()
+		client := coderdtest.New(t, &coderdtest.Options{IncludeProvisionerD: true})
+		user := coderdtest.CreateFirstUser(t, client)
+		version := coderdtest.CreateTemplateVersion(t, client, user.OrganizationID, nil)
+		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)
+		cmd, root := clitest.New(t, "ls")
+		clitest.SetupConfig(t, client, root)
+		pty := ptytest.New(t)
+		cmd.SetIn(pty.Input())
+		cmd.SetOut(pty.Output())
+
+		ctx, cancelFunc := context.WithTimeout(context.Background(), testutil.WaitLong)
+		defer cancelFunc()
+		done := make(chan any)
+		go func() {
+			errC := cmd.ExecuteContext(ctx)
+			assert.NoError(t, errC)
+			close(done)
+		}()
+		pty.ExpectMatch(workspace.Name)
+		pty.ExpectMatch("Started")
+		cancelFunc()
+		<-done
+	})
+}

cli/login.go

@@ -8,6 +8,7 @@ import (
 	"os"
 	"os/exec"
 	"os/user"
+	"path"
 	"runtime"
 	"strings"
 
@@ -16,6 +17,7 @@ import (
 	"github.com/spf13/cobra"
 	"golang.org/x/xerrors"
 
+	"github.com/coder/coder/cli/cliflag"
 	"github.com/coder/coder/cli/cliui"
 	"github.com/coder/coder/codersdk"
 )
@@ -36,9 +38,15 @@ func init() {
 }
 
 func login() *cobra.Command {
-	return &cobra.Command{
-		Use:  "login <url>",
-		Args: cobra.ExactArgs(1),
+	var (
+		email    string
+		username string
+		password string
+	)
+	cmd := &cobra.Command{
+		Use:   "login <url>",
+		Short: "Authenticate with a Coder deployment",
+		Args:  cobra.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			rawURL := args[0]
 
@@ -59,63 +67,96 @@ func login() *cobra.Command {
 			}
 
 			client := codersdk.New(serverURL)
+
+			// Try to check the version of the server prior to logging in.
+			// It may be useful to warn the user if they are trying to login
+			// on a very old client.
+			err = checkVersions(cmd, client)
+			if err != nil {
+				// Checking versions isn't a fatal error so we print a warning
+				// and proceed.
+				_, _ = fmt.Fprintln(cmd.ErrOrStderr(), cliui.Styles.Warn.Render(err.Error()))
+			}
+
 			hasInitialUser, err := client.HasFirstUser(cmd.Context())
 			if err != nil {
 				return xerrors.Errorf("has initial user: %w", err)
 			}
 			if !hasInitialUser {
-				if !isTTY(cmd) {
-					return xerrors.New("the initial user cannot be created in non-interactive mode. use the API")
-				}
 				_, _ = fmt.Fprintf(cmd.OutOrStdout(), caret+"Your Coder deployment hasn't been set up!\n")
 
-				_, err := cliui.Prompt(cmd, cliui.PromptOptions{
-					Text:      "Would you like to create the first user?",
-					Default:   "yes",
-					IsConfirm: true,
-				})
-				if errors.Is(err, cliui.Canceled) {
-					return nil
-				}
-				if err != nil {
-					return err
-				}
-				currentUser, err := user.Current()
-				if err != nil {
-					return xerrors.Errorf("get current user: %w", err)
-				}
-				username, err := cliui.Prompt(cmd, cliui.PromptOptions{
-					Text:    "What " + cliui.Styles.Field.Render("username") + " would you like?",
-					Default: currentUser.Username,
-				})
-				if errors.Is(err, cliui.Canceled) {
-					return nil
-				}
-				if err != nil {
-					return xerrors.Errorf("pick username prompt: %w", err)
-				}
-
-				email, err := cliui.Prompt(cmd, cliui.PromptOptions{
-					Text: "What's your " + cliui.Styles.Field.Render("email") + "?",
-					Validate: func(s string) error {
-						err := validator.New().Var(s, "email")
-						if err != nil {
-							return xerrors.New("That's not a valid email address!")
-						}
+				if username == "" {
+					if !isTTY(cmd) {
+						return xerrors.New("the initial user cannot be created in non-interactive mode. use the API")
+					}
+					_, err := cliui.Prompt(cmd, cliui.PromptOptions{
+						Text:      "Would you like to create the first user?",
+						Default:   cliui.ConfirmYes,
+						IsConfirm: true,
+					})
+					if errors.Is(err, cliui.Canceled) {
+						return nil
+					}
+					if err != nil {
 						return err
-					},
-				})
-				if err != nil {
-					return xerrors.Errorf("specify email prompt: %w", err)
+					}
+					currentUser, err := user.Current()
+					if err != nil {
+						return xerrors.Errorf("get current user: %w", err)
+					}
+					username, err = cliui.Prompt(cmd, cliui.PromptOptions{
+						Text:    "What " + cliui.Styles.Field.Render("username") + " would you like?",
+						Default: currentUser.Username,
+					})
+					if errors.Is(err, cliui.Canceled) {
+						return nil
+					}
+					if err != nil {
+						return xerrors.Errorf("pick username prompt: %w", err)
+					}
 				}
 
-				password, err := cliui.Prompt(cmd, cliui.PromptOptions{
-					Text:     "Enter a " + cliui.Styles.Field.Render("password") + ":",
-					Secret:   true,
-					Validate: cliui.ValidateNotEmpty,
-				})
-				if err != nil {
-					return xerrors.Errorf("specify password prompt: %w", err)
+				if email == "" {
+					email, err = cliui.Prompt(cmd, cliui.PromptOptions{
+						Text: "What's your " + cliui.Styles.Field.Render("email") + "?",
+						Validate: func(s string) error {
+							err := validator.New().Var(s, "email")
+							if err != nil {
+								return xerrors.New("That's not a valid email address!")
+							}
+							return err
+						},
+					})
+					if err != nil {
+						return xerrors.Errorf("specify email prompt: %w", err)
+					}
+				}
+
+				if password == "" {
+					var matching bool
+
+					for !matching {
+						password, err = cliui.Prompt(cmd, cliui.PromptOptions{
+							Text:     "Enter a " + cliui.Styles.Field.Render("password") + ":",
+							Secret:   true,
+							Validate: cliui.ValidateNotEmpty,
+						})
+						if err != nil {
+							return xerrors.Errorf("specify password prompt: %w", err)
+						}
+						confirm, err := cliui.Prompt(cmd, cliui.PromptOptions{
+							Text:   "Confirm " + cliui.Styles.Field.Render("password") + ":",
+							Secret: true,
+						})
+						if err != nil {
+							return xerrors.Errorf("confirm password prompt: %w", err)
+						}
+
+						matching = confirm == password
+						if !matching {
+							_, _ = fmt.Fprintln(cmd.OutOrStdout(), cliui.Styles.Error.Render("Passwords do not match"))
+						}
+					}
 				}
 
 				_, err = client.CreateFirstUser(cmd.Context(), codersdk.CreateFirstUserRequest{
@@ -150,32 +191,37 @@ func login() *cobra.Command {
 					cliui.Styles.Paragraph.Render(fmt.Sprintf("Welcome to Coder, %s! You're authenticated.", cliui.Styles.Keyword.Render(username)))+"\n")
 
 				_, _ = fmt.Fprintf(cmd.OutOrStdout(),
-					cliui.Styles.Paragraph.Render("Get started by creating a template: "+cliui.Styles.Code.Render("coder templates create"))+"\n")
+					cliui.Styles.Paragraph.Render("Get started by creating a template: "+cliui.Styles.Code.Render("coder templates init"))+"\n")
 				return nil
 			}
 
-			authURL := *serverURL
-			authURL.Path = serverURL.Path + "/cli-auth"
-			if err := openURL(cmd, authURL.String()); err != nil {
-				_, _ = fmt.Fprintf(cmd.OutOrStdout(), "Open the following in your browser:\n\n\t%s\n\n", authURL.String())
-			} else {
-				_, _ = fmt.Fprintf(cmd.OutOrStdout(), "Your browser has been opened to visit:\n\n\t%s\n\n", authURL.String())
-			}
+			sessionToken, _ := cmd.Flags().GetString(varToken)
+			if sessionToken == "" {
+				authURL := *serverURL
+				// Don't use filepath.Join, we don't want to use the os separator
+				// for a url.
+				authURL.Path = path.Join(serverURL.Path, "/cli-auth")
+				if err := openURL(cmd, authURL.String()); err != nil {
+					_, _ = fmt.Fprintf(cmd.OutOrStdout(), "Open the following in your browser:\n\n\t%s\n\n", authURL.String())
+				} else {
+					_, _ = fmt.Fprintf(cmd.OutOrStdout(), "Your browser has been opened to visit:\n\n\t%s\n\n", authURL.String())
+				}
 
-			sessionToken, err := cliui.Prompt(cmd, cliui.PromptOptions{
-				Text:   "Paste your token here:",
-				Secret: true,
-				Validate: func(token string) error {
-					client.SessionToken = token
-					_, err := client.User(cmd.Context(), codersdk.Me)
-					if err != nil {
-						return xerrors.New("That's not a valid token!")
-					}
-					return err
-				},
-			})
-			if err != nil {
-				return xerrors.Errorf("paste token prompt: %w", err)
+				sessionToken, err = cliui.Prompt(cmd, cliui.PromptOptions{
+					Text:   "Paste your token here:",
+					Secret: true,
+					Validate: func(token string) error {
+						client.SessionToken = token
+						_, err := client.User(cmd.Context(), codersdk.Me)
+						if err != nil {
+							return xerrors.New("That's not a valid token!")
+						}
+						return err
+					},
+				})
+				if err != nil {
+					return xerrors.Errorf("paste token prompt: %w", err)
+				}
 			}
 
 			// Login to get user data - verify it is OK before persisting
@@ -199,6 +245,10 @@ func login() *cobra.Command {
 			return nil
 		},
 	}
+	cliflag.StringVarP(cmd.Flags(), &email, "email", "e", "CODER_EMAIL", "", "Specifies an email address to authenticate with.")
+	cliflag.StringVarP(cmd.Flags(), &username, "username", "u", "CODER_USERNAME", "", "Specifies a username to authenticate with.")
+	cliflag.StringVarP(cmd.Flags(), &password, "password", "p", "CODER_PASSWORD", "", "Specifies a password to authenticate with.")
+	return cmd
 }
 
 // isWSL determines if coder-cli is running within Windows Subsystem for Linux

cli/login_test.go

@@ -4,9 +4,11 @@ import (
 	"context"
 	"testing"
 
+	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 
 	"github.com/coder/coder/cli/clitest"
+	"github.com/coder/coder/cli/cliui"
 	"github.com/coder/coder/coderd/coderdtest"
 	"github.com/coder/coder/pty/ptytest"
 )
@@ -35,7 +37,7 @@ func TestLogin(t *testing.T) {
 		go func() {
 			defer close(doneChan)
 			err := root.Execute()
-			require.NoError(t, err)
+			assert.NoError(t, err)
 		}()
 
 		matches := []string{
@@ -43,6 +45,7 @@ func TestLogin(t *testing.T) {
 			"username", "testuser",
 			"email", "user@coder.com",
 			"password", "password",
+			"password", "password", // Confirm.
 		}
 		for i := 0; i < len(matches); i += 2 {
 			match := matches[i]
@@ -54,6 +57,70 @@ func TestLogin(t *testing.T) {
 		<-doneChan
 	})
 
+	t.Run("InitialUserFlags", func(t *testing.T) {
+		t.Parallel()
+		client := coderdtest.New(t, nil)
+		// The --force-tty flag is required on Windows, because the `isatty` library does not
+		// accurately detect Windows ptys when they are not attached to a process:
+		// https://github.com/mattn/go-isatty/issues/59
+		doneChan := make(chan struct{})
+		root, _ := clitest.New(t, "login", client.URL.String(), "--username", "testuser", "--email", "user@coder.com", "--password", "password")
+		pty := ptytest.New(t)
+		root.SetIn(pty.Input())
+		root.SetOut(pty.Output())
+		go func() {
+			defer close(doneChan)
+			err := root.Execute()
+			assert.NoError(t, err)
+		}()
+		pty.ExpectMatch("Welcome to Coder")
+		<-doneChan
+	})
+
+	t.Run("InitialUserTTYConfirmPasswordFailAndReprompt", func(t *testing.T) {
+		t.Parallel()
+		ctx, cancel := context.WithCancel(context.Background())
+		defer cancel()
+		client := coderdtest.New(t, nil)
+		// The --force-tty flag is required on Windows, because the `isatty` library does not
+		// accurately detect Windows ptys when they are not attached to a process:
+		// https://github.com/mattn/go-isatty/issues/59
+		doneChan := make(chan struct{})
+		root, _ := clitest.New(t, "login", "--force-tty", client.URL.String())
+		pty := ptytest.New(t)
+		root.SetIn(pty.Input())
+		root.SetOut(pty.Output())
+		go func() {
+			defer close(doneChan)
+			err := root.ExecuteContext(ctx)
+			assert.NoError(t, err)
+		}()
+
+		matches := []string{
+			"first user?", "yes",
+			"username", "testuser",
+			"email", "user@coder.com",
+			"password", "mypass",
+			"password", "wrongpass", // Confirm.
+		}
+		for i := 0; i < len(matches); i += 2 {
+			match := matches[i]
+			value := matches[i+1]
+			pty.ExpectMatch(match)
+			pty.WriteLine(value)
+		}
+
+		// Validate that we reprompt for matching passwords.
+		pty.ExpectMatch("Passwords do not match")
+		pty.ExpectMatch("Enter a " + cliui.Styles.Field.Render("password"))
+
+		pty.WriteLine("pass")
+		pty.ExpectMatch("Confirm")
+		pty.WriteLine("pass")
+		pty.ExpectMatch("Welcome to Coder")
+		<-doneChan
+	})
+
 	t.Run("ExistingUserValidTokenTTY", func(t *testing.T) {
 		t.Parallel()
 		client := coderdtest.New(t, nil)
@@ -67,7 +134,7 @@ func TestLogin(t *testing.T) {
 		go func() {
 			defer close(doneChan)
 			err := root.Execute()
-			require.NoError(t, err)
+			assert.NoError(t, err)
 		}()
 
 		pty.ExpectMatch("Paste your token here:")
@@ -92,7 +159,7 @@ func TestLogin(t *testing.T) {
 			defer close(doneChan)
 			err := root.ExecuteContext(ctx)
 			// An error is expected in this case, since the login wasn't successful:
-			require.Error(t, err)
+			assert.Error(t, err)
 		}()
 
 		pty.ExpectMatch("Paste your token here:")
@@ -101,4 +168,16 @@ func TestLogin(t *testing.T) {
 		cancelFunc()
 		<-doneChan
 	})
+
+	t.Run("TokenFlag", func(t *testing.T) {
+		t.Parallel()
+		client := coderdtest.New(t, nil)
+		coderdtest.CreateFirstUser(t, client)
+		root, cfg := clitest.New(t, "login", client.URL.String(), "--token", client.SessionToken)
+		err := root.Execute()
+		require.NoError(t, err)
+		sessionFile, err := cfg.Session().Read()
+		require.NoError(t, err)
+		require.Equal(t, client.SessionToken, sessionFile)
+	})
 }

cli/logout.go

@@ -0,0 +1,77 @@
+package cli
+
+import (
+	"fmt"
+	"os"
+	"strings"
+
+	"github.com/spf13/cobra"
+	"golang.org/x/xerrors"
+
+	"github.com/coder/coder/cli/cliui"
+)
+
+func logout() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "logout",
+		Short: "Remove the local authenticated session",
+		RunE: func(cmd *cobra.Command, args []string) error {
+			client, err := CreateClient(cmd)
+			if err != nil {
+				return err
+			}
+
+			var errors []error
+
+			config := createConfig(cmd)
+
+			_, err = cliui.Prompt(cmd, cliui.PromptOptions{
+				Text:      "Are you sure you want to log out?",
+				IsConfirm: true,
+				Default:   cliui.ConfirmYes,
+			})
+			if err != nil {
+				return err
+			}
+
+			err = client.Logout(cmd.Context())
+			if err != nil {
+				errors = append(errors, xerrors.Errorf("logout api: %w", err))
+			}
+
+			err = config.URL().Delete()
+			// Only throw error if the URL configuration file is present,
+			// otherwise the user is already logged out, and we proceed
+			if err != nil && !os.IsNotExist(err) {
+				errors = append(errors, xerrors.Errorf("remove URL file: %w", err))
+			}
+
+			err = config.Session().Delete()
+			// Only throw error if the session configuration file is present,
+			// otherwise the user is already logged out, and we proceed
+			if err != nil && !os.IsNotExist(err) {
+				errors = append(errors, xerrors.Errorf("remove session file: %w", err))
+			}
+
+			err = config.Organization().Delete()
+			// If the organization configuration file is absent, we still proceed
+			if err != nil && !os.IsNotExist(err) {
+				errors = append(errors, xerrors.Errorf("remove organization file: %w", err))
+			}
+
+			if len(errors) > 0 {
+				var errorStringBuilder strings.Builder
+				for _, err := range errors {
+					_, _ = fmt.Fprint(&errorStringBuilder, "\t"+err.Error()+"\n")
+				}
+				errorString := strings.TrimRight(errorStringBuilder.String(), "\n")
+				return xerrors.New("Failed to log out.\n" + errorString)
+			}
+			_, _ = fmt.Fprintf(cmd.OutOrStdout(), caret+"You are no longer logged in. You can log in using 'coder login <url>'.\n")
+			return nil
+		},
+	}
+
+	cliui.AllowSkipPrompt(cmd)
+	return cmd
+}

cli/logout_test.go

@@ -0,0 +1,217 @@
+package cli_test
+
+import (
+	"fmt"
+	"os"
+	"regexp"
+	"runtime"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/coder/coder/cli/clitest"
+	"github.com/coder/coder/cli/config"
+	"github.com/coder/coder/coderd/coderdtest"
+	"github.com/coder/coder/pty/ptytest"
+)
+
+func TestLogout(t *testing.T) {
+	t.Parallel()
+	t.Run("Logout", func(t *testing.T) {
+		t.Parallel()
+
+		pty := ptytest.New(t)
+		config := login(t, pty)
+
+		// Ensure session files exist.
+		require.FileExists(t, string(config.URL()))
+		require.FileExists(t, string(config.Session()))
+
+		logoutChan := make(chan struct{})
+		logout, _ := clitest.New(t, "logout", "--global-config", string(config))
+		logout.SetIn(pty.Input())
+		logout.SetOut(pty.Output())
+
+		go func() {
+			defer close(logoutChan)
+			err := logout.Execute()
+			assert.NoError(t, err)
+			assert.NoFileExists(t, string(config.URL()))
+			assert.NoFileExists(t, string(config.Session()))
+		}()
+
+		pty.ExpectMatch("Are you sure you want to log out?")
+		pty.WriteLine("yes")
+		pty.ExpectMatch("You are no longer logged in. You can log in using 'coder login <url>'.")
+		<-logoutChan
+	})
+	t.Run("SkipPrompt", func(t *testing.T) {
+		t.Parallel()
+
+		pty := ptytest.New(t)
+		config := login(t, pty)
+
+		// Ensure session files exist.
+		require.FileExists(t, string(config.URL()))
+		require.FileExists(t, string(config.Session()))
+
+		logoutChan := make(chan struct{})
+		logout, _ := clitest.New(t, "logout", "--global-config", string(config), "-y")
+		logout.SetIn(pty.Input())
+		logout.SetOut(pty.Output())
+
+		go func() {
+			defer close(logoutChan)
+			err := logout.Execute()
+			assert.NoError(t, err)
+			assert.NoFileExists(t, string(config.URL()))
+			assert.NoFileExists(t, string(config.Session()))
+		}()
+
+		pty.ExpectMatch("You are no longer logged in. You can log in using 'coder login <url>'.")
+		<-logoutChan
+	})
+	t.Run("NoURLFile", func(t *testing.T) {
+		t.Parallel()
+
+		pty := ptytest.New(t)
+		config := login(t, pty)
+
+		// Ensure session files exist.
+		require.FileExists(t, string(config.URL()))
+		require.FileExists(t, string(config.Session()))
+
+		err := os.Remove(string(config.URL()))
+		require.NoError(t, err)
+
+		logoutChan := make(chan struct{})
+		logout, _ := clitest.New(t, "logout", "--global-config", string(config))
+
+		logout.SetIn(pty.Input())
+		logout.SetOut(pty.Output())
+
+		go func() {
+			defer close(logoutChan)
+			err := logout.Execute()
+			assert.EqualError(t, err, "You are not logged in. Try logging in using 'coder login <url>'.")
+		}()
+
+		<-logoutChan
+	})
+	t.Run("NoSessionFile", func(t *testing.T) {
+		t.Parallel()
+
+		pty := ptytest.New(t)
+		config := login(t, pty)
+
+		// Ensure session files exist.
+		require.FileExists(t, string(config.URL()))
+		require.FileExists(t, string(config.Session()))
+
+		err := os.Remove(string(config.Session()))
+		require.NoError(t, err)
+
+		logoutChan := make(chan struct{})
+		logout, _ := clitest.New(t, "logout", "--global-config", string(config))
+
+		logout.SetIn(pty.Input())
+		logout.SetOut(pty.Output())
+
+		go func() {
+			defer close(logoutChan)
+			err = logout.Execute()
+			assert.EqualError(t, err, "You are not logged in. Try logging in using 'coder login <url>'.")
+		}()
+
+		<-logoutChan
+	})
+	t.Run("CannotDeleteFiles", func(t *testing.T) {
+		t.Parallel()
+
+		pty := ptytest.New(t)
+		config := login(t, pty)
+
+		// Ensure session files exist.
+		require.FileExists(t, string(config.URL()))
+		require.FileExists(t, string(config.Session()))
+
+		var (
+			err         error
+			urlFile     *os.File
+			sessionFile *os.File
+		)
+		if runtime.GOOS == "windows" {
+			// Opening the files so Windows does not allow deleting them.
+			urlFile, err = os.Open(string(config.URL()))
+			require.NoError(t, err)
+			sessionFile, err = os.Open(string(config.Session()))
+			require.NoError(t, err)
+		} else {
+			// Changing the permissions to throw error during deletion.
+			err = os.Chmod(string(config), 0500)
+			require.NoError(t, err)
+		}
+		defer func() {
+			if runtime.GOOS == "windows" {
+				// Closing the opened files for cleanup.
+				err = urlFile.Close()
+				assert.NoError(t, err)
+				err = sessionFile.Close()
+				assert.NoError(t, err)
+			} else {
+				// Setting the permissions back for cleanup.
+				err = os.Chmod(string(config), 0o700)
+				assert.NoError(t, err)
+			}
+		}()
+
+		logoutChan := make(chan struct{})
+		logout, _ := clitest.New(t, "logout", "--global-config", string(config))
+
+		logout.SetIn(pty.Input())
+		logout.SetOut(pty.Output())
+
+		go func() {
+			defer close(logoutChan)
+			err := logout.Execute()
+			assert.NotNil(t, err)
+			var errorMessage string
+			if runtime.GOOS == "windows" {
+				errorMessage = "The process cannot access the file because it is being used by another process."
+			} else {
+				errorMessage = "permission denied"
+			}
+			errRegex := regexp.MustCompile(fmt.Sprintf("Failed to log out.\n\tremove URL file: .+: %s\n\tremove session file: .+: %s", errorMessage, errorMessage))
+			assert.Regexp(t, errRegex, err.Error())
+		}()
+
+		pty.ExpectMatch("Are you sure you want to log out?")
+		pty.WriteLine("yes")
+		<-logoutChan
+	})
+}
+
+func login(t *testing.T, pty *ptytest.PTY) config.Root {
+	t.Helper()
+
+	client := coderdtest.New(t, nil)
+	coderdtest.CreateFirstUser(t, client)
+
+	doneChan := make(chan struct{})
+	root, cfg := clitest.New(t, "login", "--force-tty", client.URL.String(), "--no-open")
+	root.SetIn(pty.Input())
+	root.SetOut(pty.Output())
+	go func() {
+		defer close(doneChan)
+		err := root.Execute()
+		assert.NoError(t, err)
+	}()
+
+	pty.ExpectMatch("Paste your token here:")
+	pty.WriteLine(client.SessionToken)
+	pty.ExpectMatch("Welcome to Coder")
+	<-doneChan
+
+	return cfg
+}

cli/parameter.go

@@ -0,0 +1,57 @@
+package cli
+
+import (
+	"os"
+
+	"golang.org/x/xerrors"
+	"gopkg.in/yaml.v3"
+
+	"github.com/spf13/cobra"
+
+	"github.com/coder/coder/cli/cliui"
+	"github.com/coder/coder/codersdk"
+)
+
+// Reads a YAML file and populates a string -> string map.
+// Throws an error if the file name is empty.
+func createParameterMapFromFile(parameterFile string) (map[string]string, error) {
+	if parameterFile != "" {
+		parameterMap := make(map[string]string)
+
+		parameterFileContents, err := os.ReadFile(parameterFile)
+
+		if err != nil {
+			return nil, err
+		}
+
+		err = yaml.Unmarshal(parameterFileContents, &parameterMap)
+
+		if err != nil {
+			return nil, err
+		}
+
+		return parameterMap, nil
+	}
+
+	return nil, xerrors.Errorf("Parameter file name is not specified")
+}
+
+// Returns a parameter value from a given map, if the map exists, else takes input from the user.
+// Throws an error if the map exists but does not include a value for the parameter.
+func getParameterValueFromMapOrInput(cmd *cobra.Command, parameterMap map[string]string, parameterSchema codersdk.ParameterSchema) (string, error) {
+	var parameterValue string
+	if parameterMap != nil {
+		var ok bool
+		parameterValue, ok = parameterMap[parameterSchema.Name]
+		if !ok {
+			return "", xerrors.Errorf("Parameter value absent in parameter file for %q!", parameterSchema.Name)
+		}
+	} else {
+		var err error
+		parameterValue, err = cliui.ParameterSchema(cmd, parameterSchema)
+		if err != nil {
+			return "", err
+		}
+	}
+	return parameterValue, nil
+}

cli/parameter_internal_test.go

@@ -0,0 +1,79 @@
+package cli
+
+import (
+	"os"
+	"runtime"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestCreateParameterMapFromFile(t *testing.T) {
+	t.Parallel()
+	t.Run("CreateParameterMapFromFile", func(t *testing.T) {
+		t.Parallel()
+		tempDir := t.TempDir()
+		parameterFile, _ := os.CreateTemp(tempDir, "testParameterFile*.yaml")
+		_, _ = parameterFile.WriteString("region: \"bananas\"\ndisk: \"20\"\n")
+
+		parameterMapFromFile, err := createParameterMapFromFile(parameterFile.Name())
+
+		expectedMap := map[string]string{
+			"region": "bananas",
+			"disk":   "20",
+		}
+
+		assert.Equal(t, expectedMap, parameterMapFromFile)
+		assert.Nil(t, err)
+
+		removeTmpDirUntilSuccess(t, tempDir)
+	})
+	t.Run("WithEmptyFilename", func(t *testing.T) {
+		t.Parallel()
+
+		parameterMapFromFile, err := createParameterMapFromFile("")
+
+		assert.Nil(t, parameterMapFromFile)
+		assert.EqualError(t, err, "Parameter file name is not specified")
+	})
+	t.Run("WithInvalidFilename", func(t *testing.T) {
+		t.Parallel()
+
+		parameterMapFromFile, err := createParameterMapFromFile("invalidFile.yaml")
+
+		assert.Nil(t, parameterMapFromFile)
+
+		// On Unix based systems, it is: `open invalidFile.yaml: no such file or directory`
+		// On Windows, it is `open invalidFile.yaml: The system cannot find the file specified.`
+		if runtime.GOOS == "windows" {
+			assert.EqualError(t, err, "open invalidFile.yaml: The system cannot find the file specified.")
+		} else {
+			assert.EqualError(t, err, "open invalidFile.yaml: no such file or directory")
+		}
+	})
+	t.Run("WithInvalidYAML", func(t *testing.T) {
+		t.Parallel()
+		tempDir := t.TempDir()
+		parameterFile, _ := os.CreateTemp(tempDir, "testParameterFile*.yaml")
+		_, _ = parameterFile.WriteString("region = \"bananas\"\ndisk = \"20\"\n")
+
+		parameterMapFromFile, err := createParameterMapFromFile(parameterFile.Name())
+
+		assert.Nil(t, parameterMapFromFile)
+		assert.EqualError(t, err, "yaml: unmarshal errors:\n  line 1: cannot unmarshal !!str `region ...` into map[string]string")
+
+		removeTmpDirUntilSuccess(t, tempDir)
+	})
+}
+
+// Need this for Windows because of a known issue with Go:
+// https://github.com/golang/go/issues/52986
+func removeTmpDirUntilSuccess(t *testing.T, tempDir string) {
+	t.Helper()
+	t.Cleanup(func() {
+		err := os.RemoveAll(tempDir)
+		for err != nil {
+			err = os.RemoveAll(tempDir)
+		}
+	})
+}

cli/parametercreate.go

@@ -1,75 +0,0 @@
-package cli
-
-import (
-	"fmt"
-
-	"github.com/spf13/cobra"
-	"golang.org/x/xerrors"
-
-	"github.com/coder/coder/coderd/database"
-	"github.com/coder/coder/codersdk"
-)
-
-func parameterCreate() *cobra.Command {
-	var (
-		name   string
-		value  string
-		scheme string
-	)
-	cmd := &cobra.Command{
-		Use:     "create <scope> [name]",
-		Aliases: []string{"mk"},
-		Args:    cobra.ExactArgs(2),
-		RunE: func(cmd *cobra.Command, args []string) error {
-			client, err := createClient(cmd)
-			if err != nil {
-				return err
-			}
-			organization, err := currentOrganization(cmd, client)
-			if err != nil {
-				return err
-			}
-
-			scopeName := ""
-			if len(args) >= 2 {
-				scopeName = args[1]
-			}
-			scope, scopeID, err := parseScopeAndID(cmd.Context(), client, organization, args[0], scopeName)
-			if err != nil {
-				return err
-			}
-			scheme, err := parseParameterScheme(scheme)
-			if err != nil {
-				return err
-			}
-			_, err = client.CreateParameter(cmd.Context(), scope, scopeID, codersdk.CreateParameterRequest{
-				Name:              name,
-				SourceValue:       value,
-				SourceScheme:      database.ParameterSourceSchemeData,
-				DestinationScheme: scheme,
-			})
-			if err != nil {
-				return err
-			}
-			_, _ = fmt.Printf("Created!\n")
-			return nil
-		},
-	}
-	cmd.Flags().StringVarP(&name, "name", "n", "", "Name for a parameter.")
-	_ = cmd.MarkFlagRequired("name")
-	cmd.Flags().StringVarP(&value, "value", "v", "", "Value for a parameter.")
-	_ = cmd.MarkFlagRequired("value")
-	cmd.Flags().StringVarP(&scheme, "scheme", "s", "var", `Scheme for the parameter ("var" or "env").`)
-
-	return cmd
-}
-
-func parseParameterScheme(scheme string) (database.ParameterDestinationScheme, error) {
-	switch scheme {
-	case "env":
-		return database.ParameterDestinationSchemeEnvironmentVariable, nil
-	case "var":
-		return database.ParameterDestinationSchemeProvisionerVariable, nil
-	}
-	return database.ParameterDestinationSchemeNone, xerrors.Errorf("scheme %q not recognized", scheme)
-}

cli/parameterdelete.go

@@ -1,13 +0,0 @@
-package cli
-
-import "github.com/spf13/cobra"
-
-func parameterDelete() *cobra.Command {
-	return &cobra.Command{
-		Use:     "delete",
-		Aliases: []string{"rm"},
-		RunE: func(cmd *cobra.Command, args []string) error {
-			return nil
-		},
-	}
-}

cli/parameterlist.go

@@ -1,50 +0,0 @@
-package cli
-
-import (
-	"fmt"
-	"text/tabwriter"
-
-	"github.com/fatih/color"
-	"github.com/spf13/cobra"
-)
-
-func parameterList() *cobra.Command {
-	return &cobra.Command{
-		Use: "list <scope> <scope-id>",
-		RunE: func(cmd *cobra.Command, args []string) error {
-			client, err := createClient(cmd)
-			if err != nil {
-				return err
-			}
-			organization, err := currentOrganization(cmd, client)
-			if err != nil {
-				return err
-			}
-
-			name := ""
-			if len(args) >= 2 {
-				name = args[1]
-			}
-			scope, scopeID, err := parseScopeAndID(cmd.Context(), client, organization, args[0], name)
-			if err != nil {
-				return err
-			}
-			params, err := client.Parameters(cmd.Context(), scope, scopeID)
-			if err != nil {
-				return err
-			}
-			writer := tabwriter.NewWriter(cmd.OutOrStdout(), 0, 0, 4, ' ', 0)
-			_, _ = fmt.Fprintf(writer, "%s\t%s\t%s\n",
-				color.HiBlackString("Parameter"),
-				color.HiBlackString("Created"),
-				color.HiBlackString("Scheme"))
-			for _, param := range params {
-				_, _ = fmt.Fprintf(writer, "%s\t%s\t%s\n",
-					color.New(color.FgHiCyan).Sprint(param.Name),
-					color.WhiteString(param.UpdatedAt.Format("January 2, 2006")),
-					color.New(color.FgHiWhite).Sprint(param.DestinationScheme))
-			}
-			return writer.Flush()
-		},
-	}
-}

cli/parameters.go

@@ -1,78 +1,28 @@
 package cli
 
 import (
-	"context"
-
-	"github.com/google/uuid"
 	"github.com/spf13/cobra"
-	"golang.org/x/xerrors"
-
-	"github.com/coder/coder/codersdk"
 )
 
 func parameters() *cobra.Command {
 	cmd := &cobra.Command{
-		Use:     "parameters",
+		Short: "List parameters for a given scope",
+		Example: formatExamples(
+			example{
+				Command: "coder parameters list workspace my-workspace",
+			},
+		),
+		Use: "parameters",
+		// Currently hidden as this shows parameter values, not parameter
+		// schemes. Until we have a good way to distinguish the two, it's better
+		// not to add confusion or lock ourselves into a certain api.
+		// This cmd is still valuable debugging tool for devs to avoid
+		// constructing curl requests.
+		Hidden:  true,
 		Aliases: []string{"params"},
 	}
-
-	cmd.AddCommand(parameterCreate(), parameterList(), parameterDelete())
-
+	cmd.AddCommand(
+		parameterList(),
+	)
 	return cmd
 }
-
-func parseScopeAndID(ctx context.Context, client *codersdk.Client, organization codersdk.Organization, rawScope string, name string) (codersdk.ParameterScope, uuid.UUID, error) {
-	scope, err := parseParameterScope(rawScope)
-	if err != nil {
-		return scope, uuid.Nil, err
-	}
-
-	var scopeID uuid.UUID
-	switch scope {
-	case codersdk.ParameterOrganization:
-		if name == "" {
-			scopeID = organization.ID
-		} else {
-			org, err := client.OrganizationByName(ctx, codersdk.Me, name)
-			if err != nil {
-				return scope, uuid.Nil, err
-			}
-			scopeID = org.ID
-		}
-	case codersdk.ParameterTemplate:
-		template, err := client.TemplateByName(ctx, organization.ID, name)
-		if err != nil {
-			return scope, uuid.Nil, err
-		}
-		scopeID = template.ID
-	case codersdk.ParameterUser:
-		uid, _ := uuid.Parse(name)
-		user, err := client.User(ctx, uid)
-		if err != nil {
-			return scope, uuid.Nil, err
-		}
-		scopeID = user.ID
-	case codersdk.ParameterWorkspace:
-		workspace, err := client.WorkspaceByName(ctx, codersdk.Me, name)
-		if err != nil {
-			return scope, uuid.Nil, err
-		}
-		scopeID = workspace.ID
-	}
-
-	return scope, scopeID, nil
-}
-
-func parseParameterScope(scope string) (codersdk.ParameterScope, error) {
-	switch scope {
-	case string(codersdk.ParameterOrganization):
-		return codersdk.ParameterOrganization, nil
-	case string(codersdk.ParameterTemplate):
-		return codersdk.ParameterTemplate, nil
-	case string(codersdk.ParameterUser):
-		return codersdk.ParameterUser, nil
-	case string(codersdk.ParameterWorkspace):
-		return codersdk.ParameterWorkspace, nil
-	}
-	return codersdk.ParameterOrganization, xerrors.Errorf("no scope found by name %q", scope)
-}

cli/parameterslist.go

@@ -0,0 +1,86 @@
+package cli
+
+import (
+	"fmt"
+
+	"github.com/google/uuid"
+	"github.com/spf13/cobra"
+	"golang.org/x/xerrors"
+
+	"github.com/coder/coder/cli/cliui"
+	"github.com/coder/coder/codersdk"
+)
+
+func parameterList() *cobra.Command {
+	var (
+		columns []string
+	)
+	cmd := &cobra.Command{
+		Use:     "list",
+		Aliases: []string{"ls"},
+		Args:    cobra.ExactArgs(2),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			scope, name := args[0], args[1]
+
+			client, err := CreateClient(cmd)
+			if err != nil {
+				return err
+			}
+
+			organization, err := currentOrganization(cmd, client)
+			if err != nil {
+				return xerrors.Errorf("get current organization: %w", err)
+			}
+
+			var scopeID uuid.UUID
+			switch codersdk.ParameterScope(scope) {
+			case codersdk.ParameterWorkspace:
+				workspace, err := namedWorkspace(cmd, client, name)
+				if err != nil {
+					return err
+				}
+				scopeID = workspace.ID
+			case codersdk.ParameterTemplate:
+				template, err := client.TemplateByName(cmd.Context(), organization.ID, name)
+				if err != nil {
+					return xerrors.Errorf("get workspace template: %w", err)
+				}
+				scopeID = template.ID
+			case codersdk.ParameterImportJob, "template_version":
+				scope = string(codersdk.ParameterImportJob)
+				scopeID, err = uuid.Parse(name)
+				if err != nil {
+					return xerrors.Errorf("%q must be a uuid for this scope type", name)
+				}
+
+				// Could be a template_version id or a job id. Check for the
+				// version id.
+				tv, err := client.TemplateVersion(cmd.Context(), scopeID)
+				if err == nil {
+					scopeID = tv.Job.ID
+				}
+
+			default:
+				return xerrors.Errorf("%q is an unsupported scope, use %v", scope, []codersdk.ParameterScope{
+					codersdk.ParameterWorkspace, codersdk.ParameterTemplate, codersdk.ParameterImportJob,
+				})
+			}
+
+			params, err := client.Parameters(cmd.Context(), codersdk.ParameterScope(scope), scopeID)
+			if err != nil {
+				return xerrors.Errorf("fetch params: %w", err)
+			}
+
+			out, err := cliui.DisplayTable(params, "name", columns)
+			if err != nil {
+				return xerrors.Errorf("render table: %w", err)
+			}
+
+			_, err = fmt.Fprintln(cmd.OutOrStdout(), out)
+			return err
+		},
+	}
+	cmd.Flags().StringArrayVarP(&columns, "column", "c", []string{"name", "scope", "destination scheme"},
+		"Specify a column to filter in the table.")
+	return cmd
+}

cli/portforward.go

@@ -0,0 +1,380 @@
+package cli
+
+import (
+	"context"
+	"fmt"
+	"net"
+	"os"
+	"os/signal"
+	"runtime"
+	"strconv"
+	"strings"
+	"sync"
+	"syscall"
+
+	"github.com/pion/udp"
+	"github.com/spf13/cobra"
+	"golang.org/x/xerrors"
+
+	coderagent "github.com/coder/coder/agent"
+	"github.com/coder/coder/cli/cliui"
+	"github.com/coder/coder/codersdk"
+)
+
+func portForward() *cobra.Command {
+	var (
+		tcpForwards  []string // <port>:<port>
+		udpForwards  []string // <port>:<port>
+		unixForwards []string // <path>:<path> OR <port>:<path>
+	)
+	cmd := &cobra.Command{
+		Use:     "port-forward <workspace>",
+		Short:   "Forward one or more ports from the local machine to the remote workspace",
+		Aliases: []string{"tunnel"},
+		Args:    cobra.ExactArgs(1),
+		Example: formatExamples(
+			example{
+				Description: "Port forward a single TCP port from 1234 in the workspace to port 5678 on your local machine",
+				Command:     "coder port-forward <workspace> --tcp 5678:1234",
+			},
+			example{
+				Description: "Port forward a single UDP port from port 9000 to port 9000 on your local machine",
+				Command:     "coder port-forward <workspace> --udp 9000",
+			},
+			example{
+				Description: "Forward a Unix socket in the workspace to a local Unix socket",
+				Command:     "coder port-forward <workspace> --unix ./local.sock:~/remote.sock",
+			},
+			example{
+				Description: "Forward a Unix socket in the workspace to a local TCP port",
+				Command:     "coder port-forward <workspace> --unix 8080:~/remote.sock",
+			},
+			example{
+				Description: "Port forward multiple TCP ports and a UDP port",
+				Command:     "coder port-forward <workspace> --tcp 8080:8080 --tcp 9000:3000 --udp 5353:53",
+			},
+		),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			ctx, cancel := context.WithCancel(cmd.Context())
+			defer cancel()
+
+			specs, err := parsePortForwards(tcpForwards, udpForwards, unixForwards)
+			if err != nil {
+				return xerrors.Errorf("parse port-forward specs: %w", err)
+			}
+			if len(specs) == 0 {
+				err = cmd.Help()
+				if err != nil {
+					return xerrors.Errorf("generate help output: %w", err)
+				}
+				return xerrors.New("no port-forwards requested")
+			}
+
+			client, err := CreateClient(cmd)
+			if err != nil {
+				return err
+			}
+
+			workspace, agent, err := getWorkspaceAndAgent(ctx, cmd, client, codersdk.Me, args[0], false)
+			if err != nil {
+				return err
+			}
+			if workspace.LatestBuild.Transition != codersdk.WorkspaceTransitionStart {
+				return xerrors.New("workspace must be in start transition to port-forward")
+			}
+			if workspace.LatestBuild.Job.CompletedAt == nil {
+				err = cliui.WorkspaceBuild(ctx, cmd.ErrOrStderr(), client, workspace.LatestBuild.ID, workspace.CreatedAt)
+				if err != nil {
+					return err
+				}
+			}
+
+			err = cliui.Agent(ctx, cmd.ErrOrStderr(), cliui.AgentOptions{
+				WorkspaceName: workspace.Name,
+				Fetch: func(ctx context.Context) (codersdk.WorkspaceAgent, error) {
+					return client.WorkspaceAgent(ctx, agent.ID)
+				},
+			})
+			if err != nil {
+				return xerrors.Errorf("await agent: %w", err)
+			}
+
+			conn, err := client.DialWorkspaceAgent(ctx, agent.ID, nil)
+			if err != nil {
+				return xerrors.Errorf("dial workspace agent: %w", err)
+			}
+			defer conn.Close()
+
+			// Start all listeners.
+			var (
+				wg                = new(sync.WaitGroup)
+				listeners         = make([]net.Listener, len(specs))
+				closeAllListeners = func() {
+					for _, l := range listeners {
+						if l == nil {
+							continue
+						}
+						_ = l.Close()
+					}
+				}
+			)
+			defer closeAllListeners()
+
+			for i, spec := range specs {
+				l, err := listenAndPortForward(ctx, cmd, conn, wg, spec)
+				if err != nil {
+					return err
+				}
+				listeners[i] = l
+			}
+
+			// Wait for the context to be canceled or for a signal and close
+			// all listeners.
+			var closeErr error
+			wg.Add(1)
+			go func() {
+				defer wg.Done()
+
+				sigs := make(chan os.Signal, 1)
+				signal.Notify(sigs, syscall.SIGINT, syscall.SIGTERM)
+
+				select {
+				case <-ctx.Done():
+					closeErr = ctx.Err()
+				case <-sigs:
+					_, _ = fmt.Fprintln(cmd.OutOrStderr(), "Received signal, closing all listeners and active connections")
+					closeErr = xerrors.New("signal received")
+				}
+
+				cancel()
+				closeAllListeners()
+			}()
+
+			_, _ = fmt.Fprintln(cmd.OutOrStderr(), "Ready!")
+			wg.Wait()
+			return closeErr
+		},
+	}
+
+	cmd.Flags().StringArrayVarP(&tcpForwards, "tcp", "p", []string{}, "Forward a TCP port from the workspace to the local machine")
+	cmd.Flags().StringArrayVar(&udpForwards, "udp", []string{}, "Forward a UDP port from the workspace to the local machine. The UDP connection has TCP-like semantics to support stateful UDP protocols")
+	cmd.Flags().StringArrayVar(&unixForwards, "unix", []string{}, "Forward a Unix socket in the workspace to a local Unix socket or TCP port")
+
+	return cmd
+}
+
+func listenAndPortForward(ctx context.Context, cmd *cobra.Command, conn *coderagent.Conn, wg *sync.WaitGroup, spec portForwardSpec) (net.Listener, error) {
+	_, _ = fmt.Fprintf(cmd.OutOrStderr(), "Forwarding '%v://%v' locally to '%v://%v' in the workspace\n", spec.listenNetwork, spec.listenAddress, spec.dialNetwork, spec.dialAddress)
+
+	var (
+		l   net.Listener
+		err error
+	)
+	switch spec.listenNetwork {
+	case "tcp":
+		l, err = net.Listen(spec.listenNetwork, spec.listenAddress)
+	case "udp":
+		var host, port string
+		host, port, err = net.SplitHostPort(spec.listenAddress)
+		if err != nil {
+			return nil, xerrors.Errorf("split %q: %w", spec.listenAddress, err)
+		}
+
+		var portInt int
+		portInt, err = strconv.Atoi(port)
+		if err != nil {
+			return nil, xerrors.Errorf("parse port %v from %q as int: %w", port, spec.listenAddress, err)
+		}
+
+		l, err = udp.Listen(spec.listenNetwork, &net.UDPAddr{
+			IP:   net.ParseIP(host),
+			Port: portInt,
+		})
+	case "unix":
+		l, err = net.Listen(spec.listenNetwork, spec.listenAddress)
+	default:
+		return nil, xerrors.Errorf("unknown listen network %q", spec.listenNetwork)
+	}
+	if err != nil {
+		return nil, xerrors.Errorf("listen '%v://%v': %w", spec.listenNetwork, spec.listenAddress, err)
+	}
+
+	wg.Add(1)
+	go func(spec portForwardSpec) {
+		defer wg.Done()
+		for {
+			netConn, err := l.Accept()
+			if err != nil {
+				_, _ = fmt.Fprintf(cmd.OutOrStderr(), "Error accepting connection from '%v://%v': %+v\n", spec.listenNetwork, spec.listenAddress, err)
+				_, _ = fmt.Fprintln(cmd.OutOrStderr(), "Killing listener")
+				return
+			}
+
+			go func(netConn net.Conn) {
+				defer netConn.Close()
+				remoteConn, err := conn.DialContext(ctx, spec.dialNetwork, spec.dialAddress)
+				if err != nil {
+					_, _ = fmt.Fprintf(cmd.OutOrStderr(), "Failed to dial '%v://%v' in workspace: %s\n", spec.dialNetwork, spec.dialAddress, err)
+					return
+				}
+				defer remoteConn.Close()
+
+				coderagent.Bicopy(ctx, netConn, remoteConn)
+			}(netConn)
+		}
+	}(spec)
+
+	return l, nil
+}
+
+type portForwardSpec struct {
+	listenNetwork string // tcp, udp, unix
+	listenAddress string // <ip>:<port> or path
+
+	dialNetwork string // tcp, udp, unix
+	dialAddress string // <ip>:<port> or path
+}
+
+func parsePortForwards(tcpSpecs, udpSpecs, unixSpecs []string) ([]portForwardSpec, error) {
+	specs := []portForwardSpec{}
+
+	for _, spec := range tcpSpecs {
+		local, remote, err := parsePortPort(spec)
+		if err != nil {
+			return nil, xerrors.Errorf("failed to parse TCP port-forward specification %q: %w", spec, err)
+		}
+
+		specs = append(specs, portForwardSpec{
+			listenNetwork: "tcp",
+			listenAddress: fmt.Sprintf("127.0.0.1:%v", local),
+			dialNetwork:   "tcp",
+			dialAddress:   fmt.Sprintf("127.0.0.1:%v", remote),
+		})
+	}
+
+	for _, spec := range udpSpecs {
+		local, remote, err := parsePortPort(spec)
+		if err != nil {
+			return nil, xerrors.Errorf("failed to parse UDP port-forward specification %q: %w", spec, err)
+		}
+
+		specs = append(specs, portForwardSpec{
+			listenNetwork: "udp",
+			listenAddress: fmt.Sprintf("127.0.0.1:%v", local),
+			dialNetwork:   "udp",
+			dialAddress:   fmt.Sprintf("127.0.0.1:%v", remote),
+		})
+	}
+
+	for _, specStr := range unixSpecs {
+		localPath, localTCP, remotePath, err := parseUnixUnix(specStr)
+		if err != nil {
+			return nil, xerrors.Errorf("failed to parse Unix port-forward specification %q: %w", specStr, err)
+		}
+
+		spec := portForwardSpec{
+			dialNetwork: "unix",
+			dialAddress: remotePath,
+		}
+		if localPath == "" {
+			spec.listenNetwork = "tcp"
+			spec.listenAddress = fmt.Sprintf("127.0.0.1:%v", localTCP)
+		} else {
+			if runtime.GOOS == "windows" {
+				return nil, xerrors.Errorf("Unix port-forwarding is not supported on Windows")
+			}
+			spec.listenNetwork = "unix"
+			spec.listenAddress = localPath
+		}
+		specs = append(specs, spec)
+	}
+
+	// Check for duplicate entries.
+	locals := map[string]struct{}{}
+	for _, spec := range specs {
+		localStr := fmt.Sprintf("%v:%v", spec.listenNetwork, spec.listenAddress)
+		if _, ok := locals[localStr]; ok {
+			return nil, xerrors.Errorf("local %v %v is specified twice", spec.listenNetwork, spec.listenAddress)
+		}
+		locals[localStr] = struct{}{}
+	}
+
+	return specs, nil
+}
+
+func parsePort(in string) (uint16, error) {
+	port, err := strconv.ParseUint(strings.TrimSpace(in), 10, 16)
+	if err != nil {
+		return 0, xerrors.Errorf("parse port %q: %w", in, err)
+	}
+	if port == 0 {
+		return 0, xerrors.New("port cannot be 0")
+	}
+
+	return uint16(port), nil
+}
+
+func parseUnixPath(in string) (string, error) {
+	path, err := coderagent.ExpandRelativeHomePath(strings.TrimSpace(in))
+	if err != nil {
+		return "", xerrors.Errorf("tidy path %q: %w", in, err)
+	}
+
+	return path, nil
+}
+
+func parsePortPort(in string) (local uint16, remote uint16, err error) {
+	parts := strings.Split(in, ":")
+	if len(parts) > 2 {
+		return 0, 0, xerrors.Errorf("invalid port specification %q", in)
+	}
+	if len(parts) == 1 {
+		// Duplicate the single part
+		parts = append(parts, parts[0])
+	}
+
+	local, err = parsePort(parts[0])
+	if err != nil {
+		return 0, 0, xerrors.Errorf("parse local port from %q: %w", in, err)
+	}
+	remote, err = parsePort(parts[1])
+	if err != nil {
+		return 0, 0, xerrors.Errorf("parse remote port from %q: %w", in, err)
+	}
+
+	return local, remote, nil
+}
+
+func parsePortOrUnixPath(in string) (string, uint16, error) {
+	port, err := parsePort(in)
+	if err == nil {
+		return "", port, nil
+	}
+
+	path, err := parseUnixPath(in)
+	if err != nil {
+		return "", 0, xerrors.Errorf("could not parse port or unix path %q: %w", in, err)
+	}
+
+	return path, 0, nil
+}
+
+func parseUnixUnix(in string) (string, uint16, string, error) {
+	parts := strings.Split(in, ":")
+	if len(parts) > 2 {
+		return "", 0, "", xerrors.Errorf("invalid port-forward specification %q", in)
+	}
+	if len(parts) == 1 {
+		// Duplicate the single part
+		parts = append(parts, parts[0])
+	}
+
+	localPath, localPort, err := parsePortOrUnixPath(parts[0])
+	if err != nil {
+		return "", 0, "", xerrors.Errorf("parse local part of spec %q: %w", in, err)
+	}
+
+	// We don't really touch the remote path at all since it gets cleaned
+	// up/expanded on the remote.
+	return localPath, localPort, parts[1], nil
+}

cli/portforward_test.go

@@ -0,0 +1,546 @@
+package cli_test
+
+import (
+	"bytes"
+	"context"
+	"fmt"
+	"io"
+	"net"
+	"path/filepath"
+	"runtime"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/google/uuid"
+	"github.com/pion/udp"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"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"
+)
+
+func TestPortForward(t *testing.T) {
+	t.Parallel()
+
+	t.Run("None", func(t *testing.T) {
+		t.Parallel()
+
+		client := coderdtest.New(t, nil)
+		_ = coderdtest.CreateFirstUser(t, client)
+
+		cmd, root := clitest.New(t, "port-forward", "blah")
+		clitest.SetupConfig(t, client, root)
+		buf := newThreadSafeBuffer()
+		cmd.SetOut(buf)
+
+		err := cmd.Execute()
+		require.Error(t, err)
+		require.ErrorContains(t, err, "no port-forwards")
+
+		// Check that the help was printed.
+		require.Contains(t, buf.String(), "port-forward <workspace>")
+	})
+
+	cases := []struct {
+		name    string
+		network string
+		// The flag to pass to `coder port-forward X` to port-forward this type
+		// of connection. Has two format args (both strings), the first is the
+		// local address and the second is the remote address.
+		flag string
+		// setupRemote creates a "remote" listener to emulate a service in the
+		// workspace.
+		setupRemote func(t *testing.T) net.Listener
+		// setupLocal returns an available port or Unix socket path that the
+		// port-forward command will listen on "locally". Returns the address
+		// you pass to net.Dial, and the port/path you pass to `coder
+		// port-forward`.
+		setupLocal func(t *testing.T) (string, string)
+	}{
+		{
+			name:    "TCP",
+			network: "tcp",
+			flag:    "--tcp=%v:%v",
+			setupRemote: func(t *testing.T) net.Listener {
+				l, err := net.Listen("tcp", "127.0.0.1:0")
+				require.NoError(t, err, "create TCP listener")
+				return l
+			},
+			setupLocal: func(t *testing.T) (string, string) {
+				l, err := net.Listen("tcp", "127.0.0.1:0")
+				require.NoError(t, err, "create TCP listener to generate random port")
+				defer l.Close()
+
+				_, port, err := net.SplitHostPort(l.Addr().String())
+				require.NoErrorf(t, err, "split TCP address %q", l.Addr().String())
+				return l.Addr().String(), port
+			},
+		},
+		{
+			name:    "UDP",
+			network: "udp",
+			flag:    "--udp=%v:%v",
+			setupRemote: func(t *testing.T) net.Listener {
+				addr := net.UDPAddr{
+					IP:   net.ParseIP("127.0.0.1"),
+					Port: 0,
+				}
+				l, err := udp.Listen("udp", &addr)
+				require.NoError(t, err, "create UDP listener")
+				return l
+			},
+			setupLocal: func(t *testing.T) (string, string) {
+				addr := net.UDPAddr{
+					IP:   net.ParseIP("127.0.0.1"),
+					Port: 0,
+				}
+				l, err := udp.Listen("udp", &addr)
+				require.NoError(t, err, "create UDP listener to generate random port")
+				defer l.Close()
+
+				_, port, err := net.SplitHostPort(l.Addr().String())
+				require.NoErrorf(t, err, "split UDP address %q", l.Addr().String())
+				return l.Addr().String(), port
+			},
+		},
+		{
+			name:    "Unix",
+			network: "unix",
+			flag:    "--unix=%v:%v",
+			setupRemote: func(t *testing.T) net.Listener {
+				if runtime.GOOS == "windows" {
+					t.Skip("Unix socket forwarding isn't supported on Windows")
+				}
+
+				tmpDir := t.TempDir()
+				l, err := net.Listen("unix", filepath.Join(tmpDir, "test.sock"))
+				require.NoError(t, err, "create UDP listener")
+				return l
+			},
+			setupLocal: func(t *testing.T) (string, string) {
+				tmpDir := t.TempDir()
+				path := filepath.Join(tmpDir, "test.sock")
+				return path, path
+			},
+		},
+	}
+
+	// Setup agent once to be shared between test-cases (avoid expensive
+	// non-parallel setup).
+	var (
+		client       = coderdtest.New(t, &coderdtest.Options{IncludeProvisionerD: true})
+		user         = coderdtest.CreateFirstUser(t, client)
+		_, workspace = runAgent(t, client, user.UserID)
+	)
+
+	for _, c := range cases { //nolint:paralleltest // the `c := c` confuses the linter
+		c := c
+		// Delay parallel tests here because setupLocal reserves
+		// a free open port which is not guaranteed to be free
+		// between the listener closing and port-forward ready.
+		t.Run(c.name, func(t *testing.T) {
+			t.Run("OnePort", func(t *testing.T) {
+				p1 := setupTestListener(t, c.setupRemote(t))
+
+				// Create a flag that forwards from local to listener 1.
+				localAddress, localFlag := c.setupLocal(t)
+				flag := fmt.Sprintf(c.flag, localFlag, p1)
+
+				// Launch port-forward in a goroutine so we can start dialing
+				// the "local" listener.
+				cmd, root := clitest.New(t, "port-forward", workspace.Name, flag)
+				clitest.SetupConfig(t, client, root)
+				buf := newThreadSafeBuffer()
+				cmd.SetOut(buf)
+				ctx, cancel := context.WithCancel(context.Background())
+				defer cancel()
+				errC := make(chan error)
+				go func() {
+					errC <- cmd.ExecuteContext(ctx)
+				}()
+				waitForPortForwardReady(t, buf)
+
+				t.Parallel() // Port is reserved, enable parallel execution.
+
+				// Open two connections simultaneously and test them out of
+				// sync.
+				d := net.Dialer{Timeout: testutil.WaitShort}
+				c1, err := d.DialContext(ctx, c.network, localAddress)
+				require.NoError(t, err, "open connection 1 to 'local' listener")
+				defer c1.Close()
+				c2, err := d.DialContext(ctx, c.network, localAddress)
+				require.NoError(t, err, "open connection 2 to 'local' listener")
+				defer c2.Close()
+				testDial(t, c2)
+				testDial(t, c1)
+
+				cancel()
+				err = <-errC
+				require.ErrorIs(t, err, context.Canceled)
+			})
+
+			//nolint:paralleltest
+			t.Run("TwoPorts", func(t *testing.T) {
+				var (
+					p1 = setupTestListener(t, c.setupRemote(t))
+					p2 = setupTestListener(t, c.setupRemote(t))
+				)
+
+				// Create a flags for listener 1 and listener 2.
+				localAddress1, localFlag1 := c.setupLocal(t)
+				localAddress2, localFlag2 := c.setupLocal(t)
+				flag1 := fmt.Sprintf(c.flag, localFlag1, p1)
+				flag2 := fmt.Sprintf(c.flag, localFlag2, p2)
+
+				// Launch port-forward in a goroutine so we can start dialing
+				// the "local" listeners.
+				cmd, root := clitest.New(t, "port-forward", workspace.Name, flag1, flag2)
+				clitest.SetupConfig(t, client, root)
+				buf := newThreadSafeBuffer()
+				cmd.SetOut(buf)
+				ctx, cancel := context.WithCancel(context.Background())
+				defer cancel()
+				errC := make(chan error)
+				go func() {
+					errC <- cmd.ExecuteContext(ctx)
+				}()
+				waitForPortForwardReady(t, buf)
+
+				t.Parallel() // Port is reserved, enable parallel execution.
+
+				// Open a connection to both listener 1 and 2 simultaneously and
+				// then test them out of order.
+				d := net.Dialer{Timeout: testutil.WaitShort}
+				c1, err := d.DialContext(ctx, c.network, localAddress1)
+				require.NoError(t, err, "open connection 1 to 'local' listener 1")
+				defer c1.Close()
+				c2, err := d.DialContext(ctx, c.network, localAddress2)
+				require.NoError(t, err, "open connection 2 to 'local' listener 2")
+				defer c2.Close()
+				testDial(t, c2)
+				testDial(t, c1)
+
+				cancel()
+				err = <-errC
+				require.ErrorIs(t, err, context.Canceled)
+			})
+		})
+	}
+
+	// Test doing a TCP -> Unix forward.
+	//nolint:paralleltest
+	t.Run("TCP2Unix", func(t *testing.T) {
+		var (
+			// Find the TCP and Unix cases so we can use their setupLocal and
+			// setupRemote methods respectively.
+			tcpCase  = cases[0]
+			unixCase = cases[2]
+
+			// Setup remote Unix listener.
+			p1 = setupTestListener(t, unixCase.setupRemote(t))
+		)
+
+		// Create a flag that forwards from local TCP to Unix listener 1.
+		// Notably this is a --unix flag.
+		localAddress, localFlag := tcpCase.setupLocal(t)
+		flag := fmt.Sprintf(unixCase.flag, localFlag, p1)
+
+		// Launch port-forward in a goroutine so we can start dialing
+		// the "local" listener.
+		cmd, root := clitest.New(t, "port-forward", workspace.Name, flag)
+		clitest.SetupConfig(t, client, root)
+		buf := newThreadSafeBuffer()
+		cmd.SetOut(buf)
+		ctx, cancel := context.WithCancel(context.Background())
+		defer cancel()
+		errC := make(chan error)
+		go func() {
+			errC <- cmd.ExecuteContext(ctx)
+		}()
+		waitForPortForwardReady(t, buf)
+
+		t.Parallel() // Port is reserved, enable parallel execution.
+
+		// Open two connections simultaneously and test them out of
+		// sync.
+		d := net.Dialer{Timeout: testutil.WaitShort}
+		c1, err := d.DialContext(ctx, tcpCase.network, localAddress)
+		require.NoError(t, err, "open connection 1 to 'local' listener")
+		defer c1.Close()
+		c2, err := d.DialContext(ctx, tcpCase.network, localAddress)
+		require.NoError(t, err, "open connection 2 to 'local' listener")
+		defer c2.Close()
+		testDial(t, c2)
+		testDial(t, c1)
+
+		cancel()
+		err = <-errC
+		require.ErrorIs(t, err, context.Canceled)
+	})
+
+	// Test doing TCP, UDP and Unix at the same time.
+	//nolint:paralleltest
+	t.Run("All", func(t *testing.T) {
+		var (
+			// These aren't fixed size because we exclude Unix on Windows.
+			dials = []addr{}
+			flags = []string{}
+		)
+
+		// Start listeners and populate arrays with the cases.
+		for _, c := range cases {
+			if strings.HasPrefix(c.network, "unix") && runtime.GOOS == "windows" {
+				// Unix isn't supported on Windows, but we can still
+				// test other protocols together.
+				continue
+			}
+
+			p := setupTestListener(t, c.setupRemote(t))
+
+			localAddress, localFlag := c.setupLocal(t)
+			dials = append(dials, addr{
+				network: c.network,
+				addr:    localAddress,
+			})
+			flags = append(flags, fmt.Sprintf(c.flag, localFlag, p))
+		}
+
+		// Launch port-forward in a goroutine so we can start dialing
+		// the "local" listeners.
+		cmd, root := clitest.New(t, append([]string{"port-forward", workspace.Name}, flags...)...)
+		clitest.SetupConfig(t, client, root)
+		buf := newThreadSafeBuffer()
+		cmd.SetOut(buf)
+		ctx, cancel := context.WithCancel(context.Background())
+		defer cancel()
+		errC := make(chan error)
+		go func() {
+			errC <- cmd.ExecuteContext(ctx)
+		}()
+		waitForPortForwardReady(t, buf)
+
+		t.Parallel() // Port is reserved, enable parallel execution.
+
+		// Open connections to all items in the "dial" array.
+		var (
+			d     = net.Dialer{Timeout: testutil.WaitShort}
+			conns = make([]net.Conn, len(dials))
+		)
+		for i, a := range dials {
+			c, err := d.DialContext(ctx, a.network, a.addr)
+			require.NoErrorf(t, err, "open connection %v to 'local' listener %v", i+1, i+1)
+			t.Cleanup(func() {
+				_ = c.Close()
+			})
+			conns[i] = c
+		}
+
+		// Test each connection in reverse order.
+		for i := len(conns) - 1; i >= 0; i-- {
+			testDial(t, conns[i])
+		}
+
+		cancel()
+		err := <-errC
+		require.ErrorIs(t, err, context.Canceled)
+	})
+}
+
+// runAgent creates a fake workspace and starts an agent locally for that
+// workspace. The agent will be cleaned up on test completion.
+func runAgent(t *testing.T, client *codersdk.Client, userID uuid.UUID) ([]codersdk.WorkspaceResource, codersdk.Workspace) {
+	ctx := context.Background()
+	user, err := client.User(ctx, userID.String())
+	require.NoError(t, err, "specified user does not exist")
+	require.Greater(t, len(user.OrganizationIDs), 0, "user has no organizations")
+	orgID := user.OrganizationIDs[0]
+
+	// Setup template
+	agentToken := uuid.NewString()
+	version := coderdtest.CreateTemplateVersion(t, client, orgID, &echo.Responses{
+		Parse:           echo.ParseComplete,
+		ProvisionDryRun: echo.ProvisionComplete,
+		Provision: []*proto.Provision_Response{{
+			Type: &proto.Provision_Response_Complete{
+				Complete: &proto.Provision_Complete{
+					Resources: []*proto.Resource{{
+						Name: "somename",
+						Type: "someinstance",
+						Agents: []*proto.Agent{{
+							Auth: &proto.Agent_Token{
+								Token: agentToken,
+							},
+						}},
+					}},
+				},
+			},
+		}},
+	})
+
+	// Create template and workspace
+	template := coderdtest.CreateTemplate(t, client, orgID, version.ID)
+	coderdtest.AwaitTemplateVersionJob(t, client, version.ID)
+	workspace := coderdtest.CreateWorkspace(t, client, orgID, template.ID)
+	coderdtest.AwaitWorkspaceBuildJob(t, client, workspace.LatestBuild.ID)
+
+	// Start workspace agent in a goroutine
+	cmd, root := clitest.New(t, "agent", "--agent-token", agentToken, "--agent-url", client.URL.String(), "--wireguard=false")
+	clitest.SetupConfig(t, client, root)
+	errC := make(chan error)
+	agentCtx, agentCancel := context.WithCancel(ctx)
+	t.Cleanup(func() {
+		agentCancel()
+		err := <-errC
+		require.NoError(t, err)
+	})
+	go func() {
+		errC <- cmd.ExecuteContext(agentCtx)
+	}()
+
+	coderdtest.AwaitWorkspaceAgents(t, client, workspace.LatestBuild.ID)
+	resources, err := client.WorkspaceResourcesByBuild(context.Background(), workspace.LatestBuild.ID)
+	require.NoError(t, err)
+
+	return resources, workspace
+}
+
+// setupTestListener starts accepting connections and echoing a single packet.
+// Returns the listener and the listen port or Unix path.
+func setupTestListener(t *testing.T, l net.Listener) string {
+	t.Helper()
+
+	// Wait for listener to completely exit before releasing.
+	done := make(chan struct{})
+	t.Cleanup(func() {
+		_ = l.Close()
+		<-done
+	})
+	go func() {
+		defer close(done)
+		// Guard against testAccept running require after test completion.
+		var wg sync.WaitGroup
+		defer wg.Wait()
+
+		for {
+			c, err := l.Accept()
+			if err != nil {
+				_ = l.Close()
+				return
+			}
+
+			wg.Add(1)
+			go func() {
+				testAccept(t, c)
+				wg.Done()
+			}()
+		}
+	}()
+
+	addr := l.Addr().String()
+	if !strings.HasPrefix(l.Addr().Network(), "unix") {
+		_, port, err := net.SplitHostPort(addr)
+		require.NoErrorf(t, err, "split non-Unix listen path %q", addr)
+		addr = port
+	}
+
+	return addr
+}
+
+var dialTestPayload = []byte("dean-was-here123")
+
+func testDial(t *testing.T, c net.Conn) {
+	t.Helper()
+
+	assertWritePayload(t, c, dialTestPayload)
+	assertReadPayload(t, c, dialTestPayload)
+}
+
+func testAccept(t *testing.T, c net.Conn) {
+	t.Helper()
+	defer c.Close()
+
+	assertReadPayload(t, c, dialTestPayload)
+	assertWritePayload(t, c, dialTestPayload)
+}
+
+func assertReadPayload(t *testing.T, r io.Reader, payload []byte) {
+	t.Helper()
+	b := make([]byte, len(payload)+16)
+	n, err := r.Read(b)
+	assert.NoError(t, err, "read payload")
+	assert.Equal(t, len(payload), n, "read payload length does not match")
+	assert.Equal(t, payload, b[:n])
+}
+
+func assertWritePayload(t *testing.T, w io.Writer, payload []byte) {
+	t.Helper()
+	n, err := w.Write(payload)
+	assert.NoError(t, err, "write payload")
+	assert.Equal(t, len(payload), n, "payload length does not match")
+}
+
+func waitForPortForwardReady(t *testing.T, output *threadSafeBuffer) {
+	t.Helper()
+	for i := 0; i < 100; i++ {
+		time.Sleep(testutil.IntervalMedium)
+
+		data := output.String()
+		if strings.Contains(data, "Ready!") {
+			return
+		}
+	}
+
+	t.Fatal("port-forward command did not become ready in time")
+}
+
+type addr struct {
+	network string
+	addr    string
+}
+
+type threadSafeBuffer struct {
+	b   *bytes.Buffer
+	mut *sync.RWMutex
+}
+
+func newThreadSafeBuffer() *threadSafeBuffer {
+	return &threadSafeBuffer{
+		b:   bytes.NewBuffer(nil),
+		mut: new(sync.RWMutex),
+	}
+}
+
+var (
+	_ io.Reader = &threadSafeBuffer{}
+	_ io.Writer = &threadSafeBuffer{}
+)
+
+// Read implements io.Reader.
+func (b *threadSafeBuffer) Read(p []byte) (int, error) {
+	b.mut.RLock()
+	defer b.mut.RUnlock()
+
+	return b.b.Read(p)
+}
+
+// Write implements io.Writer.
+func (b *threadSafeBuffer) Write(p []byte) (int, error) {
+	b.mut.Lock()
+	defer b.mut.Unlock()
+
+	return b.b.Write(p)
+}
+
+func (b *threadSafeBuffer) String() string {
+	b.mut.RLock()
+	defer b.mut.RUnlock()
+
+	return b.b.String()
+}

cli/publickey.go

@@ -1,29 +1,70 @@
 package cli
 
 import (
+	"strings"
+
 	"github.com/spf13/cobra"
 	"golang.org/x/xerrors"
 
+	"github.com/coder/coder/cli/cliui"
 	"github.com/coder/coder/codersdk"
 )
 
 func publickey() *cobra.Command {
-	return &cobra.Command{
-		Use: "publickey",
+	var (
+		reset bool
+	)
+
+	cmd := &cobra.Command{
+		Use:     "publickey",
+		Aliases: []string{"pubkey"},
+		Short:   "Output your public key for Git operations",
 		RunE: func(cmd *cobra.Command, args []string) error {
-			client, err := createClient(cmd)
+			client, err := CreateClient(cmd)
 			if err != nil {
 				return xerrors.Errorf("create codersdk client: %w", err)
 			}
 
+			if reset {
+				// Confirm prompt if using --reset. We don't want to accidentally
+				// reset our public key.
+				_, err := cliui.Prompt(cmd, cliui.PromptOptions{
+					Text: "Confirm regenerate a new sshkey for your workspaces? This will require updating the key " +
+						"on any services it is registered with. This action cannot be reverted.",
+					IsConfirm: true,
+				})
+				if err != nil {
+					return err
+				}
+
+				// Reset the public key, let the retrieve re-read it.
+				_, err = client.RegenerateGitSSHKey(cmd.Context(), codersdk.Me)
+				if err != nil {
+					return err
+				}
+			}
+
 			key, err := client.GitSSHKey(cmd.Context(), codersdk.Me)
 			if err != nil {
 				return xerrors.Errorf("create codersdk client: %w", err)
 			}
 
-			cmd.Println(key.PublicKey)
+			cmd.Println(cliui.Styles.Wrap.Render(
+				"This is your public key for using " + cliui.Styles.Field.Render("git") + " in " +
+					"Coder. All clones with SSH will be authenticated automatically 🪄.",
+			))
+			cmd.Println()
+			cmd.Println(cliui.Styles.Code.Render(strings.TrimSpace(key.PublicKey)))
+			cmd.Println()
+			cmd.Println("Add to GitHub and GitLab:")
+			cmd.Println(cliui.Styles.Prompt.String() + "https://github.com/settings/ssh/new")
+			cmd.Println(cliui.Styles.Prompt.String() + "https://gitlab.com/-/profile/keys")
 
 			return nil
 		},
 	}
+	cmd.Flags().BoolVar(&reset, "reset", false, "Regenerate your public key. This will require updating the key on any services it's registered with.")
+	cliui.AllowSkipPrompt(cmd)
+
+	return cmd
 }

cli/publickey_test.go

@@ -13,6 +13,7 @@ import (
 func TestPublicKey(t *testing.T) {
 	t.Parallel()
 	t.Run("OK", func(t *testing.T) {
+		t.Parallel()
 		client := coderdtest.New(t, nil)
 		_ = coderdtest.CreateFirstUser(t, client)
 		cmd, root := clitest.New(t, "publickey")

cli/rename.go

@@ -0,0 +1,62 @@
+package cli
+
+import (
+	"fmt"
+
+	"github.com/spf13/cobra"
+	"golang.org/x/xerrors"
+
+	"github.com/coder/coder/cli/cliui"
+	"github.com/coder/coder/codersdk"
+)
+
+func rename() *cobra.Command {
+	cmd := &cobra.Command{
+		Annotations: workspaceCommand,
+		Use:         "rename <workspace> <new name>",
+		Short:       "Rename a workspace",
+		Args:        cobra.ExactArgs(2),
+		// Keep hidden until renaming is safe, see:
+		// * https://github.com/coder/coder/issues/3000
+		// * https://github.com/coder/coder/issues/3386
+		Hidden: true,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			client, err := CreateClient(cmd)
+			if err != nil {
+				return err
+			}
+			workspace, err := namedWorkspace(cmd, client, args[0])
+			if err != nil {
+				return xerrors.Errorf("get workspace: %w", err)
+			}
+
+			_, _ = fmt.Fprintf(cmd.OutOrStdout(), "%s\n\n",
+				cliui.Styles.Wrap.Render("WARNING: A rename can result in data loss if a resource references the workspace name in the template (e.g volumes)."),
+			)
+			_, err = cliui.Prompt(cmd, cliui.PromptOptions{
+				Text: fmt.Sprintf("Type %q to confirm rename:", workspace.Name),
+				Validate: func(s string) error {
+					if s == workspace.Name {
+						return nil
+					}
+					return xerrors.Errorf("Input %q does not match %q", s, workspace.Name)
+				},
+			})
+			if err != nil {
+				return err
+			}
+
+			err = client.UpdateWorkspace(cmd.Context(), workspace.ID, codersdk.UpdateWorkspaceRequest{
+				Name: args[1],
+			})
+			if err != nil {
+				return xerrors.Errorf("rename workspace: %w", err)
+			}
+			return nil
+		},
+	}
+
+	cliui.AllowSkipPrompt(cmd)
+
+	return cmd
+}

cli/rename_test.go

@@ -0,0 +1,52 @@
+package cli_test
+
+import (
+	"context"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/coder/coder/cli/clitest"
+	"github.com/coder/coder/coderd/coderdtest"
+	"github.com/coder/coder/pty/ptytest"
+	"github.com/coder/coder/testutil"
+)
+
+func TestRename(t *testing.T) {
+	t.Parallel()
+
+	client := coderdtest.New(t, &coderdtest.Options{IncludeProvisionerD: true})
+	user := coderdtest.CreateFirstUser(t, client)
+	version := coderdtest.CreateTemplateVersion(t, client, user.OrganizationID, nil)
+	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)
+
+	ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitLong)
+	defer cancel()
+
+	want := workspace.Name + "-test"
+	cmd, root := clitest.New(t, "rename", workspace.Name, want, "--yes")
+	clitest.SetupConfig(t, client, root)
+	pty := ptytest.New(t)
+	cmd.SetIn(pty.Input())
+	cmd.SetOut(pty.Output())
+
+	errC := make(chan error, 1)
+	go func() {
+		errC <- cmd.ExecuteContext(ctx)
+	}()
+
+	pty.ExpectMatch("confirm rename:")
+	pty.WriteLine(workspace.Name)
+
+	require.NoError(t, <-errC)
+
+	ws, err := client.Workspace(ctx, workspace.ID)
+	assert.NoError(t, err)
+
+	got := ws.Name
+	assert.Equal(t, want, got, "workspace name did not change")
+}

cli/resetpassword.go

@@ -0,0 +1,92 @@
+package cli
+
+import (
+	"database/sql"
+	"fmt"
+
+	"github.com/spf13/cobra"
+	"golang.org/x/xerrors"
+
+	"github.com/coder/coder/cli/cliflag"
+	"github.com/coder/coder/cli/cliui"
+	"github.com/coder/coder/coderd/database"
+	"github.com/coder/coder/coderd/userpassword"
+)
+
+func resetPassword() *cobra.Command {
+	var (
+		postgresURL string
+	)
+
+	root := &cobra.Command{
+		Use:   "reset-password <username>",
+		Short: "Reset a user's password by directly updating the database",
+		Args:  cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			username := args[0]
+
+			sqlDB, err := sql.Open("postgres", postgresURL)
+			if err != nil {
+				return xerrors.Errorf("dial postgres: %w", err)
+			}
+			defer sqlDB.Close()
+			err = sqlDB.Ping()
+			if err != nil {
+				return xerrors.Errorf("ping postgres: %w", err)
+			}
+
+			err = database.EnsureClean(sqlDB)
+			if err != nil {
+				return xerrors.Errorf("database needs migration: %w", err)
+			}
+			db := database.New(sqlDB)
+
+			user, err := db.GetUserByEmailOrUsername(cmd.Context(), database.GetUserByEmailOrUsernameParams{
+				Username: username,
+			})
+			if err != nil {
+				return xerrors.Errorf("retrieving user: %w", err)
+			}
+
+			password, err := cliui.Prompt(cmd, cliui.PromptOptions{
+				Text:     "Enter new " + cliui.Styles.Field.Render("password") + ":",
+				Secret:   true,
+				Validate: cliui.ValidateNotEmpty,
+			})
+			if err != nil {
+				return xerrors.Errorf("password prompt: %w", err)
+			}
+			confirmedPassword, err := cliui.Prompt(cmd, cliui.PromptOptions{
+				Text:     "Confirm " + cliui.Styles.Field.Render("password") + ":",
+				Secret:   true,
+				Validate: cliui.ValidateNotEmpty,
+			})
+			if err != nil {
+				return xerrors.Errorf("confirm password prompt: %w", err)
+			}
+			if password != confirmedPassword {
+				return xerrors.New("Passwords do not match")
+			}
+
+			hashedPassword, err := userpassword.Hash(password)
+			if err != nil {
+				return xerrors.Errorf("hash password: %w", err)
+			}
+
+			err = db.UpdateUserHashedPassword(cmd.Context(), database.UpdateUserHashedPasswordParams{
+				ID:             user.ID,
+				HashedPassword: []byte(hashedPassword),
+			})
+			if err != nil {
+				return xerrors.Errorf("updating password: %w", err)
+			}
+
+			_, _ = fmt.Fprintf(cmd.OutOrStdout(), "\nPassword has been reset for user %s!\n", cliui.Styles.Keyword.Render(user.Username))
+			return nil
+		},
+	}
+
+	cliflag.StringVarP(root.Flags(), &postgresURL, "postgres-url", "", "CODER_PG_CONNECTION_URL", "", "URL of a PostgreSQL database to connect to")
+
+	return root
+}

cli/resetpassword_test.go

@@ -0,0 +1,112 @@
+package cli_test
+
+import (
+	"context"
+	"net/url"
+	"runtime"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/coder/coder/cli/clitest"
+	"github.com/coder/coder/coderd/database/postgres"
+	"github.com/coder/coder/codersdk"
+	"github.com/coder/coder/pty/ptytest"
+	"github.com/coder/coder/testutil"
+)
+
+// nolint:paralleltest
+func TestResetPassword(t *testing.T) {
+	// postgres.Open() seems to be creating race conditions when run in parallel.
+	// t.Parallel()
+
+	if runtime.GOOS != "linux" || testing.Short() {
+		// Skip on non-Linux because it spawns a PostgreSQL instance.
+		t.SkipNow()
+	}
+
+	const email = "some@one.com"
+	const username = "example"
+	const oldPassword = "password"
+	const newPassword = "password2"
+
+	// start postgres and coder server processes
+
+	connectionURL, closeFunc, err := postgres.Open()
+	require.NoError(t, err)
+	defer closeFunc()
+	ctx, cancelFunc := context.WithCancel(context.Background())
+	serverDone := make(chan struct{})
+	serverCmd, cfg := clitest.New(t,
+		"server",
+		"--address", ":0",
+		"--postgres-url", connectionURL,
+		"--cache-dir", t.TempDir(),
+	)
+	go func() {
+		defer close(serverDone)
+		err = serverCmd.ExecuteContext(ctx)
+		assert.ErrorIs(t, err, context.Canceled)
+	}()
+	var rawURL string
+	require.Eventually(t, func() bool {
+		rawURL, err = cfg.URL().Read()
+		return err == nil && rawURL != ""
+	}, testutil.WaitLong, testutil.IntervalFast)
+	accessURL, err := url.Parse(rawURL)
+	require.NoError(t, err)
+	client := codersdk.New(accessURL)
+
+	_, err = client.CreateFirstUser(ctx, codersdk.CreateFirstUserRequest{
+		Email:            email,
+		Username:         username,
+		Password:         oldPassword,
+		OrganizationName: "example",
+	})
+	require.NoError(t, err)
+
+	// reset the password
+
+	resetCmd, cmdCfg := clitest.New(t, "reset-password", "--postgres-url", connectionURL, username)
+	clitest.SetupConfig(t, client, cmdCfg)
+	cmdDone := make(chan struct{})
+	pty := ptytest.New(t)
+	resetCmd.SetIn(pty.Input())
+	resetCmd.SetOut(pty.Output())
+	go func() {
+		defer close(cmdDone)
+		err = resetCmd.Execute()
+		assert.NoError(t, err)
+	}()
+
+	matches := []struct {
+		output string
+		input  string
+	}{
+		{"Enter new", newPassword},
+		{"Confirm", newPassword},
+	}
+	for _, match := range matches {
+		pty.ExpectMatch(match.output)
+		pty.WriteLine(match.input)
+	}
+	<-cmdDone
+
+	// now try logging in
+
+	_, err = client.LoginWithPassword(ctx, codersdk.LoginWithPasswordRequest{
+		Email:    email,
+		Password: oldPassword,
+	})
+	require.Error(t, err)
+
+	_, err = client.LoginWithPassword(ctx, codersdk.LoginWithPasswordRequest{
+		Email:    email,
+		Password: newPassword,
+	})
+	require.NoError(t, err)
+
+	cancelFunc()
+	<-serverDone
+}

cli/root.go

@@ -1,101 +1,235 @@
 package cli
 
 import (
+	"flag"
+	"fmt"
 	"net/url"
 	"os"
 	"strings"
+	"text/template"
 	"time"
 
+	"golang.org/x/xerrors"
+
 	"github.com/charmbracelet/lipgloss"
 	"github.com/kirsle/configdir"
 	"github.com/mattn/go-isatty"
 	"github.com/spf13/cobra"
 
 	"github.com/coder/coder/buildinfo"
+	"github.com/coder/coder/cli/cliflag"
 	"github.com/coder/coder/cli/cliui"
 	"github.com/coder/coder/cli/config"
+	"github.com/coder/coder/coderd"
 	"github.com/coder/coder/codersdk"
 )
 
 var (
 	caret = cliui.Styles.Prompt.String()
+
+	// Applied as annotations to workspace commands
+	// so they display in a separated "help" section.
+	workspaceCommand = map[string]string{
+		"workspaces": "",
+	}
 )
 
 const (
-	varGlobalConfig = "global-config"
-	varNoOpen       = "no-open"
-	varForceTty     = "force-tty"
+	varURL             = "url"
+	varToken           = "token"
+	varAgentToken      = "agent-token"
+	varAgentURL        = "agent-url"
+	varGlobalConfig    = "global-config"
+	varNoOpen          = "no-open"
+	varNoVersionCheck  = "no-version-warning"
+	varForceTty        = "force-tty"
+	varVerbose         = "verbose"
+	notLoggedInMessage = "You are not logged in. Try logging in using 'coder login <url>'."
+
+	envNoVersionCheck = "CODER_NO_VERSION_WARNING"
 )
 
-func Root() *cobra.Command {
+var (
+	errUnauthenticated = xerrors.New(notLoggedInMessage)
+	envSessionToken    = "CODER_SESSION_TOKEN"
+)
+
+func init() {
+	// Set cobra template functions in init to avoid conflicts in tests.
+	cobra.AddTemplateFuncs(templateFunctions)
+}
+
+func Core() []*cobra.Command {
+	return []*cobra.Command{
+		configSSH(),
+		create(),
+		deleteWorkspace(),
+		dotfiles(),
+		gitssh(),
+		list(),
+		login(),
+		logout(),
+		parameters(),
+		portForward(),
+		publickey(),
+		resetPassword(),
+		schedules(),
+		show(),
+		ssh(),
+		start(),
+		state(),
+		stop(),
+		rename(),
+		templates(),
+		update(),
+		users(),
+		versionCmd(),
+		wireguardPortForward(),
+		workspaceAgent(),
+		features(),
+	}
+}
+
+func AGPL() []*cobra.Command {
+	all := append(Core(), Server(coderd.New))
+	return all
+}
+
+func Root(subcommands []*cobra.Command) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:           "coder",
-		Version:       buildinfo.Version(),
 		SilenceErrors: true,
 		SilenceUsage:  true,
-		Long: `    ▄█▀    ▀█▄
-     ▄▄ ▀▀▀  █▌   ██▀▀█▄          ▐█
- ▄▄██▀▀█▄▄▄  ██  ██      █▀▀█ ▐█▀▀██ ▄█▀▀█ █▀▀
-█▌   ▄▌   ▐█ █▌  ▀█▄▄▄█▌ █  █ ▐█  ██ ██▀▀  █
-     ██████▀▄█    ▀▀▀▀   ▀▀▀▀  ▀▀▀▀▀  ▀▀▀▀ ▀
-  ` + lipgloss.NewStyle().Underline(true).Render("Self-hosted developer workspaces on your infra") + `
-
+		Long: `Coder — A tool for provisioning self-hosted development environments.
 `,
-		Example: cliui.Styles.Paragraph.Render(`Start Coder in "dev" mode. This dev-mode requires no further setup, and your local `+cliui.Styles.Code.Render("coder")+` CLI will be authenticated to talk to it. This makes it easy to experiment with Coder.`) + `
+		PersistentPreRun: func(cmd *cobra.Command, args []string) {
+			err := func() error {
+				if cliflag.IsSetBool(cmd, varNoVersionCheck) {
+					return nil
+				}
 
-    ` + cliui.Styles.Code.Render("$ coder start --dev") + `
-	` + cliui.Styles.Paragraph.Render("Get started by creating a template from an example.") + `
+				// Login handles checking the versions itself since it
+				// has a handle to an unauthenticated client.
+				// Server is skipped for obvious reasons.
+				if cmd.Name() == "login" || cmd.Name() == "server" || cmd.Name() == "gitssh" {
+					return nil
+				}
 
-    ` + cliui.Styles.Code.Render("$ coder templates init"),
+				client, err := CreateClient(cmd)
+				// If the client is unauthenticated we can ignore the check.
+				// The child commands should handle an unauthenticated client.
+				if xerrors.Is(err, errUnauthenticated) {
+					return nil
+				}
+				if err != nil {
+					return xerrors.Errorf("create client: %w", err)
+				}
+				return checkVersions(cmd, client)
+			}()
+			if err != nil {
+				// Just log the error here. We never want to fail a command
+				// due to a pre-run.
+				_, _ = fmt.Fprintf(cmd.ErrOrStderr(),
+					cliui.Styles.Warn.Render("check versions error: %s"), err)
+				_, _ = fmt.Fprintln(cmd.ErrOrStderr())
+			}
+		},
+		Example: formatExamples(
+			example{
+				Description: "Start a Coder server",
+				Command:     "coder server",
+			},
+			example{
+				Description: "Get started by creating a template from an example",
+				Command:     "coder templates init",
+			},
+		),
 	}
-	// Customizes the color of headings to make subcommands
-	// more visually appealing.
-	header := cliui.Styles.Placeholder
-	cmd.SetUsageTemplate(strings.NewReplacer(
-		`Usage:`, header.Render("Usage:"),
-		`Examples:`, header.Render("Examples:"),
-		`Available Commands:`, header.Render("Commands:"),
-		`Global Flags:`, header.Render("Global Flags:"),
-		`Flags:`, header.Render("Flags:"),
-		`Additional help topics:`, header.Render("Additional help:"),
-	).Replace(cmd.UsageTemplate()))
-	cmd.SetVersionTemplate(versionTemplate())
 
-	cmd.AddCommand(
-		configSSH(),
-		start(),
-		login(),
-		parameters(),
-		templates(),
-		users(),
-		workspaces(),
-		ssh(),
-		workspaceTunnel(),
-		gitssh(),
-		publickey(),
-	)
+	cmd.AddCommand(subcommands...)
 
-	cmd.PersistentFlags().String(varGlobalConfig, configdir.LocalConfig("coderv2"), "Path to the global `coder` config directory")
-	cmd.PersistentFlags().Bool(varForceTty, false, "Force the `coder` command to run as if connected to a TTY")
-	err := cmd.PersistentFlags().MarkHidden(varForceTty)
-	if err != nil {
-		// This should never return an error, because we just added the `--force-tty`` flag prior to calling MarkHidden.
-		panic(err)
-	}
+	cmd.SetUsageTemplate(usageTemplate())
+
+	cmd.PersistentFlags().String(varURL, "", "Specify the URL to your deployment.")
+	cliflag.Bool(cmd.PersistentFlags(), varNoVersionCheck, "", envNoVersionCheck, false, "Suppress warning when client and server versions do not match.")
+	cliflag.String(cmd.PersistentFlags(), varToken, "", envSessionToken, "", fmt.Sprintf("Specify an authentication token. For security reasons setting %s is preferred.", envSessionToken))
+	cliflag.String(cmd.PersistentFlags(), varAgentToken, "", "CODER_AGENT_TOKEN", "", "Specify an agent authentication token.")
+	_ = cmd.PersistentFlags().MarkHidden(varAgentToken)
+	cliflag.String(cmd.PersistentFlags(), varAgentURL, "", "CODER_AGENT_URL", "", "Specify the URL for an agent to access your deployment.")
+	_ = cmd.PersistentFlags().MarkHidden(varAgentURL)
+	cliflag.String(cmd.PersistentFlags(), varGlobalConfig, "", "CODER_CONFIG_DIR", configdir.LocalConfig("coderv2"), "Specify the path to the global `coder` config directory.")
+	cmd.PersistentFlags().Bool(varForceTty, false, "Force the `coder` command to run as if connected to a TTY.")
+	_ = cmd.PersistentFlags().MarkHidden(varForceTty)
 	cmd.PersistentFlags().Bool(varNoOpen, false, "Block automatically opening URLs in the browser.")
-	err = cmd.PersistentFlags().MarkHidden(varNoOpen)
-	if err != nil {
-		panic(err)
-	}
+	_ = cmd.PersistentFlags().MarkHidden(varNoOpen)
+	cliflag.Bool(cmd.PersistentFlags(), varVerbose, "v", "CODER_VERBOSE", false, "Enable verbose output")
 
 	return cmd
 }
 
-// createClient returns a new client from the command context.
-// The configuration directory will be read from the global flag.
-func createClient(cmd *cobra.Command) (*codersdk.Client, error) {
+// versionCmd prints the coder version
+func versionCmd() *cobra.Command {
+	return &cobra.Command{
+		Use:   "version",
+		Short: "Show coder version",
+		RunE: func(cmd *cobra.Command, args []string) error {
+			var str strings.Builder
+			_, _ = str.WriteString(fmt.Sprintf("Coder %s", buildinfo.Version()))
+			buildTime, valid := buildinfo.Time()
+			if valid {
+				_, _ = str.WriteString(" " + buildTime.Format(time.UnixDate))
+			}
+			_, _ = str.WriteString("\r\n" + buildinfo.ExternalURL() + "\r\n")
+
+			_, _ = fmt.Fprint(cmd.OutOrStdout(), str.String())
+			return nil
+		},
+	}
+}
+
+func isTest() bool {
+	return flag.Lookup("test.v") != nil
+}
+
+// CreateClient returns a new client from the command context.
+// It reads from global configuration files if flags are not set.
+func CreateClient(cmd *cobra.Command) (*codersdk.Client, error) {
 	root := createConfig(cmd)
-	rawURL, err := root.URL().Read()
+	rawURL, err := cmd.Flags().GetString(varURL)
+	if err != nil || rawURL == "" {
+		rawURL, err = root.URL().Read()
+		if err != nil {
+			// If the configuration files are absent, the user is logged out
+			if os.IsNotExist(err) {
+				return nil, errUnauthenticated
+			}
+			return nil, err
+		}
+	}
+	serverURL, err := url.Parse(strings.TrimSpace(rawURL))
+	if err != nil {
+		return nil, err
+	}
+	token, err := cmd.Flags().GetString(varToken)
+	if err != nil || token == "" {
+		token, err = root.Session().Read()
+		if err != nil {
+			// If the configuration files are absent, the user is logged out
+			if os.IsNotExist(err) {
+				return nil, errUnauthenticated
+			}
+			return nil, err
+		}
+	}
+	client := codersdk.New(serverURL)
+	client.SessionToken = strings.TrimSpace(token)
+	return client, nil
+}
+
+// createAgentClient returns a new client from the command context.
+// It works just like CreateClient, but uses the agent token and URL instead.
+func createAgentClient(cmd *cobra.Command) (*codersdk.Client, error) {
+	rawURL, err := cmd.Flags().GetString(varAgentURL)
 	if err != nil {
 		return nil, err
 	}
@@ -103,7 +237,7 @@ func createClient(cmd *cobra.Command) (*codersdk.Client, error) {
 	if err != nil {
 		return nil, err
 	}
-	token, err := root.Session().Read()
+	token, err := cmd.Flags().GetString(varAgentToken)
 	if err != nil {
 		return nil, err
 	}
@@ -123,6 +257,27 @@ func currentOrganization(cmd *cobra.Command, client *codersdk.Client) (codersdk.
 	return orgs[0], nil
 }
 
+// namedWorkspace fetches and returns a workspace by an identifier, which may be either
+// a bare name (for a workspace owned by the current user) or a "user/workspace" combination,
+// where user is either a username or UUID.
+func namedWorkspace(cmd *cobra.Command, client *codersdk.Client, identifier string) (codersdk.Workspace, error) {
+	parts := strings.Split(identifier, "/")
+
+	var owner, name string
+	switch len(parts) {
+	case 1:
+		owner = codersdk.Me
+		name = parts[0]
+	case 2:
+		owner = parts[0]
+		name = parts[1]
+	default:
+		return codersdk.Workspace{}, xerrors.Errorf("invalid workspace name: %q", identifier)
+	}
+
+	return client.WorkspaceByOwnerAndName(cmd.Context(), owner, name, codersdk.WorkspaceOptions{})
+}
+
 // createConfig consumes the global configuration flag to produce a config root.
 func createConfig(cmd *cobra.Command) config.Root {
 	globalRoot, err := cmd.Flags().GetString(varGlobalConfig)
@@ -150,13 +305,191 @@ func isTTY(cmd *cobra.Command) bool {
 	return isatty.IsTerminal(file.Fd())
 }
 
-func versionTemplate() string {
-	template := `Coder {{printf "%s" .Version}}`
-	buildTime, valid := buildinfo.Time()
-	if valid {
-		template += " " + buildTime.Format(time.UnixDate)
+// isTTYOut returns whether the passed reader is a TTY or not.
+// This accepts a reader to work with Cobra's "OutOrStdout"
+// function for simple testing.
+func isTTYOut(cmd *cobra.Command) bool {
+	// If the `--force-tty` command is available, and set,
+	// assume we're in a tty. This is primarily for cases on Windows
+	// where we may not be able to reliably detect this automatically (ie, tests)
+	forceTty, err := cmd.Flags().GetBool(varForceTty)
+	if forceTty && err == nil {
+		return true
 	}
-	template += "\r\n" + buildinfo.ExternalURL()
-	template += "\r\n"
-	return template
+	file, ok := cmd.OutOrStdout().(*os.File)
+	if !ok {
+		return false
+	}
+	return isatty.IsTerminal(file.Fd())
+}
+
+var templateFunctions = template.FuncMap{
+	"usageHeader":        usageHeader,
+	"isWorkspaceCommand": isWorkspaceCommand,
+}
+
+func usageHeader(s string) string {
+	// Customizes the color of headings to make subcommands more visually
+	// appealing.
+	return cliui.Styles.Placeholder.Render(s)
+}
+
+func isWorkspaceCommand(cmd *cobra.Command) bool {
+	if _, ok := cmd.Annotations["workspaces"]; ok {
+		return true
+	}
+	var ws bool
+	cmd.VisitParents(func(cmd *cobra.Command) {
+		if _, ok := cmd.Annotations["workspaces"]; ok {
+			ws = true
+		}
+	})
+	return ws
+}
+
+func usageTemplate() string {
+	// usageHeader is defined in init().
+	return `{{usageHeader "Usage:"}}
+{{- if .Runnable}}
+  {{.UseLine}}
+{{end}}
+{{- if .HasAvailableSubCommands}}
+  {{.CommandPath}} [command]
+{{end}}
+
+{{- if gt (len .Aliases) 0}}
+{{usageHeader "Aliases:"}}
+  {{.NameAndAliases}}
+{{end}}
+
+{{- if .HasExample}}
+{{usageHeader "Get Started:"}}
+{{.Example}}
+{{end}}
+
+{{- $isRootHelp := (not .HasParent)}}
+{{- if .HasAvailableSubCommands}}
+{{usageHeader "Commands:"}}
+  {{- range .Commands}}
+    {{- $isRootWorkspaceCommand := (and $isRootHelp (isWorkspaceCommand .))}}
+    {{- if (or (and .IsAvailableCommand (not $isRootWorkspaceCommand)) (eq .Name "help"))}}
+  {{rpad .Name .NamePadding }} {{.Short}}
+    {{- end}}
+  {{- end}}
+{{end}}
+
+{{- if (and $isRootHelp .HasAvailableSubCommands)}}
+{{usageHeader "Workspace Commands:"}}
+  {{- range .Commands}}
+    {{- if (and .IsAvailableCommand (isWorkspaceCommand .))}}
+  {{rpad .Name .NamePadding }} {{.Short}}
+    {{- end}}
+  {{- end}}
+{{end}}
+
+{{- if .HasAvailableLocalFlags}}
+{{usageHeader "Flags:"}}
+{{.LocalFlags.FlagUsagesWrapped 100 | trimTrailingWhitespaces}}
+{{end}}
+
+{{- if .HasAvailableInheritedFlags}}
+{{usageHeader "Global Flags:"}}
+{{.InheritedFlags.FlagUsagesWrapped 100 | trimTrailingWhitespaces}}
+{{end}}
+
+{{- if .HasHelpSubCommands}}
+{{usageHeader "Additional help topics:"}}
+  {{- range .Commands}}
+    {{- if .IsAdditionalHelpTopicCommand}}
+  {{rpad .CommandPath .CommandPathPadding}} {{.Short}}
+    {{- end}}
+  {{- end}}
+{{end}}
+
+{{- if .HasAvailableSubCommands}}
+Use "{{.CommandPath}} [command] --help" for more information about a command.
+{{end}}`
+}
+
+// example represents a standard example for command usage, to be used
+// with formatExamples.
+type example struct {
+	Description string
+	Command     string
+}
+
+// formatExamples formats the examples as width wrapped bulletpoint
+// descriptions with the command underneath.
+func formatExamples(examples ...example) string {
+	wrap := cliui.Styles.Wrap.Copy()
+	wrap.PaddingLeft(4)
+	var sb strings.Builder
+	for i, e := range examples {
+		if len(e.Description) > 0 {
+			_, _ = sb.WriteString("  - " + wrap.Render(e.Description + ":")[4:] + "\n\n    ")
+		}
+		// We add 1 space here because `cliui.Styles.Code` adds an extra
+		// space. This makes the code block align at an even 2 or 6
+		// spaces for symmetry.
+		_, _ = sb.WriteString(" " + cliui.Styles.Code.Render(fmt.Sprintf("$ %s", e.Command)))
+		if i < len(examples)-1 {
+			_, _ = sb.WriteString("\n\n")
+		}
+	}
+	return sb.String()
+}
+
+// FormatCobraError colorizes and adds "--help" docs to cobra commands.
+func FormatCobraError(err error, cmd *cobra.Command) string {
+	helpErrMsg := fmt.Sprintf("Run '%s --help' for usage.", cmd.CommandPath())
+
+	var (
+		httpErr *codersdk.Error
+		output  strings.Builder
+	)
+
+	if xerrors.As(err, &httpErr) {
+		_, _ = fmt.Fprintln(&output, httpErr.Friendly())
+	}
+
+	// If the httpErr is nil then we just have a regular error in which
+	// case we want to print out what's happening.
+	if httpErr == nil || cliflag.IsSetBool(cmd, varVerbose) {
+		_, _ = fmt.Fprintln(&output, err.Error())
+	}
+
+	_, _ = fmt.Fprint(&output, helpErrMsg)
+
+	return cliui.Styles.Error.Render(output.String())
+}
+
+func checkVersions(cmd *cobra.Command, client *codersdk.Client) error {
+	if cliflag.IsSetBool(cmd, varNoVersionCheck) {
+		return nil
+	}
+
+	clientVersion := buildinfo.Version()
+
+	info, err := client.BuildInfo(cmd.Context())
+	// Avoid printing errors that are connection-related.
+	if codersdk.IsConnectionErr(err) {
+		return nil
+	}
+
+	if err != nil {
+		return xerrors.Errorf("build info: %w", err)
+	}
+
+	fmtWarningText := `version mismatch: client %s, server %s
+download the server version with: 'curl -L https://coder.com/install.sh | sh -s -- --version %s'
+`
+
+	if !buildinfo.VersionsMatch(clientVersion, info.Version) {
+		warn := cliui.Styles.Warn.Copy().Align(lipgloss.Left)
+		// Trim the leading 'v', our install.sh script does not handle this case well.
+		_, _ = fmt.Fprintf(cmd.ErrOrStderr(), warn.Render(fmtWarningText), clientVersion, info.Version, strings.TrimPrefix(info.CanonicalVersion(), "v"))
+		_, _ = fmt.Fprintln(cmd.ErrOrStderr())
+	}
+
+	return nil
 }

cli/root_internal_test.go

@@ -0,0 +1,77 @@
+package cli
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/require"
+	"go.uber.org/goleak"
+)
+
+func Test_formatExamples(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name        string
+		examples    []example
+		wantMatches []string
+	}{
+		{
+			name:        "No examples",
+			examples:    nil,
+			wantMatches: nil,
+		},
+		{
+			name: "Output examples",
+			examples: []example{
+				{
+					Description: "Hello world",
+					Command:     "echo hello",
+				},
+				{
+					Description: "Bye bye",
+					Command:     "echo bye",
+				},
+			},
+			wantMatches: []string{
+				"Hello world", "echo hello",
+				"Bye bye", "echo bye",
+			},
+		},
+		{
+			name: "No description outputs commands",
+			examples: []example{
+				{
+					Command: "echo hello",
+				},
+			},
+			wantMatches: []string{
+				"echo hello",
+			},
+		},
+	}
+	for _, tt := range tests {
+		tt := tt
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			got := formatExamples(tt.examples...)
+			if len(tt.wantMatches) == 0 {
+				require.Empty(t, got)
+			} else {
+				for _, want := range tt.wantMatches {
+					require.Contains(t, got, want)
+				}
+			}
+		})
+	}
+}
+
+func TestMain(m *testing.M) {
+	goleak.VerifyTestMain(m,
+		// The lumberjack library is used by by agent and seems to leave
+		// goroutines after Close(), fails TestGitSSH tests.
+		// https://github.com/natefinch/lumberjack/pull/100
+		goleak.IgnoreTopFunction("gopkg.in/natefinch/lumberjack%2ev2.(*Logger).millRun"),
+		goleak.IgnoreTopFunction("gopkg.in/natefinch/lumberjack%2ev2.(*Logger).mill.func1"),
+	)
+}