sudocode issue update

Syntax

sudocode issue update <issue-id> [options]

Description

The issue update command allows you to modify properties of an existing issue. Common updates include:

Changing status as work progresses
Updating priority
Assigning/reassigning to team members or agents
Modifying title or description
Archiving completed or abandoned work

When you update an issue:

Changes are written to the SQLite database
Changes are exported to JSONL for version control
The updated_at timestamp is automatically set
If status changes to closed, closed_at timestamp is set

Updates are partial - you only need to specify the fields you want to change. Other fields remain unchanged.

Arguments

issue-id

string

required

The ID of the issue to updateExample: ISSUE-001The issue must exist in your project.

Options

-s, --status

string

Update issue statusExample: --status in_progressValid statuses:

open - Ready to be worked on
in_progress - Currently being worked on
blocked - Waiting on dependencies
needs_review - Implementation complete, awaiting review
closed - Work completed

-p, --priority

number

Update priority level (0-4)Example: --priority 0Priority levels:

0 - Critical (highest)
1 - High
2 - Medium
3 - Low
4 - Lowest

-a, --assignee

string

Update assigneeExample: --assignee "alice" or --assignee "agent-backend"Can be a username, agent ID, or any identifier. Use empty string to unassign: --assignee ""

--title

string

Update the issue titleExample: --title "Fix critical OAuth bug"Changes the display title of the issue.

-d, --description

string

Update the issue description/contentExample: --description "Updated implementation details"This replaces the content of the issue.

--archived

boolean

Archive or unarchive the issueExample: --archived true or --archived falseArchived issues are hidden from default listings but retained for reference.

Examples

Claim an Issue

Assign yourself and mark as in progress:

sudocode issue update ISSUE-001 --status in_progress --assignee "alice"

Expected output

✓ Updated issue ISSUE-001
  status: in_progress
  assignee: alice

Change Priority

Elevate to critical:

sudocode issue update ISSUE-001 --priority 0

Expected output

✓ Updated issue ISSUE-001
  priority: 0

Mark as Blocked

Update status when blocked:

sudocode issue update ISSUE-003 --status blocked

Expected output

✓ Updated issue ISSUE-003
  status: blocked

Reassign to Another Team Member

Transfer ownership:

sudocode issue update ISSUE-001 --assignee "bob"

Expected output

✓ Updated issue ISSUE-001
  assignee: bob

Unassign an Issue

Remove assignee:

sudocode issue update ISSUE-001 --assignee ""

Expected output

✓ Updated issue ISSUE-001
  assignee:

Update Multiple Fields

Change status, priority, and assignee together:

sudocode issue update ISSUE-001 \
  --status needs_review \
  --priority 1 \
  --assignee "alice"

Expected output

✓ Updated issue ISSUE-001
  status: needs_review
  priority: 1
  assignee: alice

Update Title

Rename an issue:

sudocode issue update ISSUE-001 --title "Implement OAuth 2.0 with PKCE"

Expected output

✓ Updated issue ISSUE-001
  title: Implement OAuth 2.0 with PKCE

Update Description

Replace content:

sudocode issue update ISSUE-001 \
  --description "Updated implementation plan with new security requirements"

Expected output

✓ Updated issue ISSUE-001
  description: Updated implementation plan with new security requirements

Archive an Issue

Mark as archived (hidden from default views):

sudocode issue update ISSUE-050 --archived true

Expected output

✓ Updated issue ISSUE-050
  archived: true

Unarchive an Issue

Restore an archived issue:

sudocode issue update ISSUE-050 --archived false

Expected output

✓ Updated issue ISSUE-050
  archived: false

Status Transitions

Issues typically flow through statuses in this order:

Common Status Transitions

open → in_progress

When you start working on an issue:

sudocode issue update ISSUE-001 --status in_progress --assignee "your-name"

in_progress → needs_review

When implementation is done but needs review:

sudocode issue update ISSUE-001 --status needs_review

needs_review → closed

After review is complete:

sudocode issue close ISSUE-001
# or
sudocode issue update ISSUE-001 --status closed

open/in_progress → blocked

When dependencies aren’t met:

sudocode issue update ISSUE-003 --status blocked

blocked → in_progress

When blockers are resolved:

sudocode issue update ISSUE-003 --status in_progress

closed → open (reopen)

If work needs to be resumed:

sudocode issue update ISSUE-001 --status open

JSON Output

Use the global --json flag for machine-readable output:

sudocode --json issue update ISSUE-001 --status in_progress --assignee "alice"

JSON output

{
  "id": "ISSUE-001",
  "title": "Implement OAuth 2.0 token endpoint",
  "status": "in_progress",
  "priority": 1,
  "assignee": "alice",
  "content": "...",
  "parent_id": null,
  "created_at": "2025-10-29T10:00:00Z",
  "updated_at": "2025-10-29T18:30:00Z",
  "closed_at": null,
  "archived": false
}

Common Workflows

Agent Claiming Work

Find ready work

sudocode ready

Review details

sudocode issue show ISSUE-001

Claim and start

sudocode issue update ISSUE-001 --status in_progress --assignee "agent-backend"

Implementing a Feature

Start work

sudocode issue update ISSUE-001 --status in_progress --assignee "your-name"

If blocked, mark it

sudocode issue update ISSUE-001 --status blocked

When implementation done

sudocode issue update ISSUE-001 --status needs_review

After review passes

sudocode issue close ISSUE-001

Handling Blocked Work

Mark as blocked

sudocode issue update ISSUE-003 --status blocked

Create blocker relationship

sudocode link ISSUE-001 ISSUE-003 --type blocks

When blocker resolves

sudocode issue update ISSUE-003 --status open

Reassigning Work

Find issues to reassign

sudocode issue list --assignee "alice" --status open

Reassign to new team member

sudocode issue update ISSUE-001 --assignee "bob"
sudocode issue update ISSUE-002 --assignee "bob"

Bulk Updates with Scripting

Update multiple issues programmatically:

# Mark all alice's issues as needs_review
for issue_id in $(sudocode --json issue list --assignee "alice" --status in_progress | jq -r '.[] | .id'); do
  sudocode issue update "$issue_id" --status needs_review
done

# Elevate all blocked issues to high priority
sudocode --json issue list --status blocked | jq -r '.[] | .id' | while read issue_id; do
  sudocode issue update "$issue_id" --priority 1
done

Update Behavior

What Gets Updated

When you run issue update:

Database - SQLite database is updated immediately
JSONL - Changes are exported to issues.jsonl for version control
Timestamps - updated_at is set to current time
Closed timestamp - If status changes to closed, closed_at is set

What Doesn’t Change

Issue ID - Immutable, cannot be changed
Creation timestamp - created_at never changes
Relationships - Use link command to manage relationships
Parent - Use --parent option on create, or update database directly
Tags - Currently no CLI option (edit JSONL or database directly)

Common Questions

Can I update multiple issues at once?

No, issue update works on one issue at a time. For bulk updates, use shell scripting with loops:

for id in ISSUE-001 ISSUE-002 ISSUE-003; do
  sudocode issue update "$id" --priority 1
done

What's the difference between closing and archiving?

Closing (--status closed) marks work as complete, normal workflow state
Archiving (--archived true) hides the issue from default listings, used for abandoned or obsolete work

Closed issues appear in lists by default. Archived issues don’t.

How do I change the parent issue?

The CLI doesn’t currently support updating parent_id. Options:

Edit the JSONL file directly and run sudocode sync
Use the database directly
Create a new issue with the correct parent

Will updating status notify anyone?

No, sudocode doesn’t have built-in notifications. Status changes are tracked via git commits and the updated_at timestamp.

Can I change the issue ID?

No, issue IDs are immutable. They serve as stable references across the system. If you need a different ID, create a new issue and close the old one.

What happens to relationships when I update an issue?

Relationships are unaffected by issue update. They persist regardless of changes to status, priority, assignee, or other properties.

Troubleshooting

Error: Issue not found

Cause: The issue ID doesn’t existSolution: Verify the ID:

sudocode issue list

Error: Invalid status value

Cause: Status must be one of: open, in_progress, blocked, needs_review, closedSolution: Use a valid status:

sudocode issue update ISSUE-001 --status in_progress

Error: Invalid priority value

Cause: Priority must be 0-4Solution: Use a valid priority:

sudocode issue update ISSUE-001 --priority 2

Update succeeded but nothing changed

Cause: You may have set the same value it already hadSolution: Check current values:

sudocode issue show ISSUE-001

issue show

View issue details

issue create

Create new issue

issue list

List all issues

issue close

Close completed issues

issue delete

Delete an issue

ready

Find ready work

Next Steps

View issue details

sudocode issue show ISSUE-001

Update properties

sudocode issue update ISSUE-001 --status in_progress --assignee "you"

Verify changes

sudocode issue show ISSUE-001

Commit to git

git add .sudocode/issues.jsonl
git commit -m "Update issue status"

Issues Concept Guide

Learn more about issues and their lifecycle

CLI Reference

Spec Commands

Issue Commands

Relationship Commands

Feedback Commands

Query & Sync Commands

Documentation Index

​Syntax

​Description

​Arguments

​Options

​Examples

​Claim an Issue

​Change Priority

​Mark as Blocked

​Reassign to Another Team Member

​Unassign an Issue

​Update Multiple Fields

​Update Title

​Update Description

​Archive an Issue

​Unarchive an Issue

​Status Transitions

​Common Status Transitions

​JSON Output

​Common Workflows

​Agent Claiming Work

​Implementing a Feature

​Handling Blocked Work

​Reassigning Work

​Bulk Updates with Scripting

​Update Behavior

​What Gets Updated

​What Doesn’t Change

​Common Questions

​Troubleshooting

​Related Commands

issue show

issue create

issue list

issue close

issue delete

ready

​Next Steps

Issues Concept Guide

Syntax

Description

Arguments

Options

Examples

Claim an Issue

Change Priority

Mark as Blocked

Reassign to Another Team Member

Unassign an Issue

Update Multiple Fields

Update Title

Update Description

Archive an Issue

Unarchive an Issue

Status Transitions

Common Status Transitions

JSON Output

Common Workflows

Agent Claiming Work

Implementing a Feature

Handling Blocked Work

Reassigning Work

Bulk Updates with Scripting

Update Behavior

What Gets Updated

What Doesn’t Change

Common Questions

Troubleshooting

Related Commands

Next Steps