From 45dcd7edfc7790ec1ab7f91729d233673acd103c Mon Sep 17 00:00:00 2001
From: Sas Swart <sas.swart.cdk@gmail.com>
Date: Wed, 17 Jun 2026 15:59:52 +0200
Subject: [PATCH] docs: document `coder exp sync list` in startup coordination
 guides (#26454)

Follow-up to #26443. Documents the new `coder exp sync list` command in
the startup coordination guides.

**troubleshooting.md:**
- New "List All Units" section after "Check Unit Status" with example
output
- Added `coder exp sync list` to the "Workspace startup script hangs"
checklist, since users debugging hanging scripts may not know which unit
to query

**usage.md:**
- New "Inspect Unit State" section covering `list`, `status`, and `ping`
- Updated "Test your changes" checklist to reference `coder exp sync
list`

> Generated by Coder Agents on behalf of @SasSwart
---
 .../startup-coordination/troubleshooting.md   | 24 +++++++++++++++++++
 .../templates/startup-coordination/usage.md   | 23 +++++++++++++++++-
 2 files changed, 46 insertions(+), 1 deletion(-)

diff --git a/docs/admin/templates/startup-coordination/troubleshooting.md b/docs/admin/templates/startup-coordination/troubleshooting.md
index 1f33388629..d75c0552ea 100644
--- a/docs/admin/templates/startup-coordination/troubleshooting.md
+++ b/docs/admin/templates/startup-coordination/troubleshooting.md
@@ -47,6 +47,29 @@ Dependencies:
 No dependencies found
 ```
 
+## List All Units
+
+If you are unsure which units are registered, or want a quick overview of every unit's state, use `coder exp sync list`:
+
+```bash
+coder exp sync list
+```
+
+This displays all registered units, their statuses, and whether they are ready to start:
+
+```bash
+UNIT           STATUS     READY
+git-clone      completed  true
+env-setup      started    true
+ide-configure  pending    false
+```
+
+You can also get JSON output for scripting:
+
+```bash
+coder exp sync list --output json
+```
+
 ## Common Issues
 
 ### Workspace startup script hangs
@@ -56,6 +79,7 @@ If the workspace startup scripts appear to 'hang', one or more of your startup s
 * Inside the workspace, review `/tmp/coder-script-*.log` for more details on your script's execution.
     > **Tip:** add `set -x` to the top of your script to enable debug mode and update/restart the workspace.
 * Review your template and verify that `coder exp sync complete <unit>` is called after the script completes e.g. with an exit trap.
+* List all units to identify which ones are blocked: `coder exp sync list`.
 * View the unit status using `coder exp sync status <unit>`.
 
 ### Workspace startup scripts fail
diff --git a/docs/admin/templates/startup-coordination/usage.md b/docs/admin/templates/startup-coordination/usage.md
index f2a8f9a0a2..694ed694c5 100644
--- a/docs/admin/templates/startup-coordination/usage.md
+++ b/docs/admin/templates/startup-coordination/usage.md
@@ -87,6 +87,27 @@ coder exp sync complete "$UNIT_NAME"
 
 </div>
 
+## Inspect Unit State
+
+Use `coder exp sync list` to see all registered units and their current state:
+
+```bash
+coder exp sync list
+```
+
+Example output:
+
+```bash
+UNIT           STATUS     READY
+git-clone      completed  true
+env-setup      started    true
+ide-configure  pending    false
+```
+
+To inspect a single unit and its dependencies in detail, use `coder exp sync status <unit>`.
+
+To verify the agent socket is reachable, use `coder exp sync ping`.
+
 ## Best Practices
 
 ### Test your changes before rolling out to all users
@@ -95,7 +116,7 @@ Before rolling out to all users:
 
 1. Create a test workspace from the updated template
 2. Check workspace build logs for sync messages
-3. Verify all units reach "completed" status
+3. Verify all units reach "completed" status using `coder exp sync list`
 4. Test workspace functionality
 
 Once you're satisfied, [promote the new template version](../../../reference/cli/templates_versions_promote.md).