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
This commit is contained in:
Sas Swart
2026-06-17 15:59:52 +02:00
committed by GitHub
parent e6147d082a
commit 45dcd7edfc
2 changed files with 46 additions and 1 deletions
@@ -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
@@ -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).