Skip to main content

​
Synopsis

Update a thread’s status without adding an entry. Always updates last_updated timestamp and rewrites the thread projection.

​
Usage

watercooler set-status <topic> <status> [options]

​
Arguments

​
topic
string
required
Thread topic identifier
​
status
string
required
New status value. Common values: OPEN, IN_REVIEW, CLOSED, BLOCKED, or custom status

​
Options

​
--threads-dir
string
Threads directory path. Defaults to ./watercooler or $WATERCOOLER_DIR.

​
Examples

​
Set status to closed

watercooler set-status feature-auth CLOSED
Output: 
/home/user/project/watercooler/feature-auth.md

​
Set status to blocked

watercooler set-status api-redesign BLOCKED

​
Set status to in review

watercooler set-status feature-auth IN_REVIEW

​
Reopen closed thread

watercooler set-status bug-123 OPEN

​
Custom status

watercooler set-status feature-auth WAITING_FOR_DEPLOYMENT

​
Update status in custom directory

watercooler set-status feature-auth CLOSED --threads-dir ~/projects/myapp/threads

​
Common Status Values

StatusTypical Use
OPENActive work, default for new threads
IN_REVIEWAwaiting review or approval
BLOCKEDCannot proceed due to dependency or issue
CLOSEDCompleted or resolved
ABANDONEDWork discontinued
WAITINGWaiting for external input
You can use any custom status value that fits your workflow.

​
Expected Output

The command prints the path to the updated thread file: 
/home/user/project/watercooler/feature-auth.md

​
Side Effects

​
Metadata Updates

  • Updates status field in YAML frontmatter
  • Updates last_updated timestamp to current time
  • Rewrites thread projection file

​
Git Sync

  • Triggers automatic git commit (if threads directory is a git repository)
  • Commit message: "Update status: feature-auth -> CLOSED"

​
Status vs Entry

Two ways to change status:

​
1. set-status (silent update)

watercooler set-status feature-auth CLOSED
  • No entry added to thread
  • Only updates metadata
  • Quick status change

​
2. say with status update (documented change)

watercooler say feature-auth \
  --title "Work complete" \
  --body "All tasks finished. Closing thread." \
  --status "CLOSED"
  • Adds entry explaining the status change
  • Updates metadata
  • Better for audit trail
Recommendation: Use say with status when you want to document why the status changed.

​
Workflows

​
Close completed thread

# Document completion
watercooler say feature-auth \
  --title "Feature complete" \
  --body "PR #42 merged. Closing thread." \
  --type "Closure"

# Update status
watercooler set-status feature-auth CLOSED

​
Block thread

# Document blocker
watercooler say api-redesign \
  --title "Blocked" \
  --body "Waiting for upstream API changes."

# Update status
watercooler set-status api-redesign BLOCKED

​
Reopen thread

# Explain reopening
watercooler say bug-123 \
  --title "Regression found" \
  --body "Bug reappeared in production. Reopening."

# Update status
watercooler set-status bug-123 OPEN

​
Batch status update

# Close multiple completed threads
for topic in feature-auth api-redesign bug-123; do
  watercooler set-status "$topic" CLOSED
done

​
Query Status

To see current status of threads: 
# List all threads with status
watercooler list

# Filter by status pattern
watercooler list | grep BLOCKED

# Count by status
watercooler list | cut -f2 | sort | uniq -c

​
Error Handling

​
Thread not found

watercooler set-status nonexistent CLOSED
Error: 
Error: Thread not found: nonexistent
Solution: Verify thread exists with watercooler list.

​
Invalid status format

While any string is technically valid, consider using consistent status values across your project.
  • say - Add entry with optional status update
  • set-ball - Update ball ownership
  • list - List threads with current status
  • set-status - MCP tool equivalent

Build docs developers (and LLMs) love

Get started for freeTalk to us