# summary

Update a setup-agents task (metadata or status).

# description

Patches an existing task record in `.setup-agents/state/tasks.jsonl`. Use `--status` to transition the task to any valid state (open, claimed, done, cancelled, blocked, archived). Without `--status`, only metadata fields are patched.

# flags.task.summary

Task id.

# flags.task.description

Id of the task to update. Alias: --id.

# flags.status.summary

Transition the task to this status.

# flags.status.description

Set the task status to open, claimed, done, cancelled, blocked, or archived. Use --reason to provide context for cancelled or blocked transitions.

# flags.reason.summary

Reason for the status transition.

# flags.reason.description

Free-text explanation for why the task was cancelled or blocked. Recorded in the JSONL event.

# flags.summary.summary

New summary text.

# flags.summary.description

Replace the task summary with this text.

# flags.role.summary

New owner role.

# flags.role.description

Alias for a setup-agents profile owner.

# flags.profile.summary

New owner profile.

# flags.profile.description

Replace the task owner with this setup-agents profile.

# flags.evidence.summary

Related evidence ids.

# flags.evidence.description

Comma-separated evidence ids to attach to the task.

# examples

- Update a task summary:

  <%= config.bin %> <%= command.id %> --task SA-97 --summary "Revised scope"

- Cancel a task that failed:

  <%= config.bin %> <%= command.id %> --task SA-97 --status cancelled --reason "Agent crashed with resource_exhausted"

- Block a task pending external input:

  <%= config.bin %> <%= command.id %> --task SA-97 --status blocked --reason "Waiting on PO acceptance criteria"

- Reassign a task:

  <%= config.bin %> <%= command.id %> --task SA-97 --profile developer

- Transition using --id alias:

  <%= config.bin %> <%= command.id %> --id SA-97 --status done

# info.updated

Task %s → %s

# errors.notFound

Task not found: %s

# errors.noId

Either --task or --id is required.