> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sudocode.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# sudocode issue update

> Update properties of an existing issue without recreating it

## Syntax

```bash theme={null}
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

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

## Arguments

<ParamField path="issue-id" type="string" required>
  The ID of the issue to update

  **Example:** `ISSUE-001`

  The issue must exist in your project.
</ParamField>

## Options

<ParamField path="-s, --status" type="string">
  Update issue status

  **Example:** `--status in_progress`

  Valid 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
</ParamField>

<ParamField path="-p, --priority" type="number">
  Update priority level (0-4)

  **Example:** `--priority 0`

  Priority levels:

  * **0** - Critical (highest)
  * **1** - High
  * **2** - Medium
  * **3** - Low
  * **4** - Lowest
</ParamField>

<ParamField path="-a, --assignee" type="string">
  Update assignee

  **Example:** `--assignee "alice"` or `--assignee "agent-backend"`

  Can be a username, agent ID, or any identifier. Use empty string to unassign: `--assignee ""`
</ParamField>

<ParamField path="--title" type="string">
  Update the issue title

  **Example:** `--title "Fix critical OAuth bug"`

  Changes the display title of the issue.
</ParamField>

<ParamField path="-d, --description" type="string">
  Update the issue description/content

  **Example:** `--description "Updated implementation details"`

  This replaces the content of the issue.
</ParamField>

<ParamField path="--archived" type="boolean">
  Archive or unarchive the issue

  **Example:** `--archived true` or `--archived false`

  Archived issues are hidden from default listings but retained for reference.
</ParamField>

## Examples

### Claim an Issue

Assign yourself and mark as in progress:

```bash theme={null}
sudocode issue update ISSUE-001 --status in_progress --assignee "alice"
```

<Accordion title="Expected output">
  ```
  ✓ Updated issue ISSUE-001
    status: in_progress
    assignee: alice
  ```
</Accordion>

### Change Priority

Elevate to critical:

```bash theme={null}
sudocode issue update ISSUE-001 --priority 0
```

<Accordion title="Expected output">
  ```
  ✓ Updated issue ISSUE-001
    priority: 0
  ```
</Accordion>

### Mark as Blocked

Update status when blocked:

```bash theme={null}
sudocode issue update ISSUE-003 --status blocked
```

<Accordion title="Expected output">
  ```
  ✓ Updated issue ISSUE-003
    status: blocked
  ```
</Accordion>

### Reassign to Another Team Member

Transfer ownership:

```bash theme={null}
sudocode issue update ISSUE-001 --assignee "bob"
```

<Accordion title="Expected output">
  ```
  ✓ Updated issue ISSUE-001
    assignee: bob
  ```
</Accordion>

### Unassign an Issue

Remove assignee:

```bash theme={null}
sudocode issue update ISSUE-001 --assignee ""
```

<Accordion title="Expected output">
  ```
  ✓ Updated issue ISSUE-001
    assignee:
  ```
</Accordion>

### Update Multiple Fields

Change status, priority, and assignee together:

```bash theme={null}
sudocode issue update ISSUE-001 \
  --status needs_review \
  --priority 1 \
  --assignee "alice"
```

<Accordion title="Expected output">
  ```
  ✓ Updated issue ISSUE-001
    status: needs_review
    priority: 1
    assignee: alice
  ```
</Accordion>

### Update Title

Rename an issue:

```bash theme={null}
sudocode issue update ISSUE-001 --title "Implement OAuth 2.0 with PKCE"
```

<Accordion title="Expected output">
  ```
  ✓ Updated issue ISSUE-001
    title: Implement OAuth 2.0 with PKCE
  ```
</Accordion>

### Update Description

Replace content:

```bash theme={null}
sudocode issue update ISSUE-001 \
  --description "Updated implementation plan with new security requirements"
```

<Accordion title="Expected output">
  ```
  ✓ Updated issue ISSUE-001
    description: Updated implementation plan with new security requirements
  ```
</Accordion>

### Archive an Issue

Mark as archived (hidden from default views):

```bash theme={null}
sudocode issue update ISSUE-050 --archived true
```

<Accordion title="Expected output">
  ```
  ✓ Updated issue ISSUE-050
    archived: true
  ```
</Accordion>

### Unarchive an Issue

Restore an archived issue:

```bash theme={null}
sudocode issue update ISSUE-050 --archived false
```

<Accordion title="Expected output">
  ```
  ✓ Updated issue ISSUE-050
    archived: false
  ```
</Accordion>

## Status Transitions

Issues typically flow through statuses in this order:

```mermaid theme={null}
graph LR
    A[open] --> B[in_progress]
    B --> C[needs_review]
    C --> D[closed]
    A --> E[blocked]
    E --> B
    D -.reopen.-> A
```

### Common Status Transitions

<AccordionGroup>
  <Accordion title="open → in_progress">
    When you start working on an issue:

    ```bash theme={null}
    sudocode issue update ISSUE-001 --status in_progress --assignee "your-name"
    ```
  </Accordion>

  <Accordion title="in_progress → needs_review">
    When implementation is done but needs review:

    ```bash theme={null}
    sudocode issue update ISSUE-001 --status needs_review
    ```
  </Accordion>

  <Accordion title="needs_review → closed">
    After review is complete:

    ```bash theme={null}
    sudocode issue close ISSUE-001
    # or
    sudocode issue update ISSUE-001 --status closed
    ```
  </Accordion>

  <Accordion title="open/in_progress → blocked">
    When dependencies aren't met:

    ```bash theme={null}
    sudocode issue update ISSUE-003 --status blocked
    ```
  </Accordion>

  <Accordion title="blocked → in_progress">
    When blockers are resolved:

    ```bash theme={null}
    sudocode issue update ISSUE-003 --status in_progress
    ```
  </Accordion>

  <Accordion title="closed → open (reopen)">
    If work needs to be resumed:

    ```bash theme={null}
    sudocode issue update ISSUE-001 --status open
    ```
  </Accordion>
</AccordionGroup>

## JSON Output

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

```bash theme={null}
sudocode --json issue update ISSUE-001 --status in_progress --assignee "alice"
```

<Accordion title="JSON output">
  ```json theme={null}
  {
    "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
  }
  ```
</Accordion>

## Common Workflows

### Agent Claiming Work

<Steps>
  <Step title="Find ready work">
    ```bash theme={null}
    sudocode ready
    ```
  </Step>

  <Step title="Review details">
    ```bash theme={null}
    sudocode issue show ISSUE-001
    ```
  </Step>

  <Step title="Claim and start">
    ```bash theme={null}
    sudocode issue update ISSUE-001 --status in_progress --assignee "agent-backend"
    ```
  </Step>
</Steps>

### Implementing a Feature

<Steps>
  <Step title="Start work">
    ```bash theme={null}
    sudocode issue update ISSUE-001 --status in_progress --assignee "your-name"
    ```
  </Step>

  <Step title="If blocked, mark it">
    ```bash theme={null}
    sudocode issue update ISSUE-001 --status blocked
    ```
  </Step>

  <Step title="When implementation done">
    ```bash theme={null}
    sudocode issue update ISSUE-001 --status needs_review
    ```
  </Step>

  <Step title="After review passes">
    ```bash theme={null}
    sudocode issue close ISSUE-001
    ```
  </Step>
</Steps>

### Handling Blocked Work

<Steps>
  <Step title="Mark as blocked">
    ```bash theme={null}
    sudocode issue update ISSUE-003 --status blocked
    ```
  </Step>

  <Step title="Create blocker relationship">
    ```bash theme={null}
    sudocode link ISSUE-001 ISSUE-003 --type blocks
    ```
  </Step>

  <Step title="When blocker resolves">
    ```bash theme={null}
    sudocode issue update ISSUE-003 --status open
    ```
  </Step>
</Steps>

### Reassigning Work

<Steps>
  <Step title="Find issues to reassign">
    ```bash theme={null}
    sudocode issue list --assignee "alice" --status open
    ```
  </Step>

  <Step title="Reassign to new team member">
    ```bash theme={null}
    sudocode issue update ISSUE-001 --assignee "bob"
    sudocode issue update ISSUE-002 --assignee "bob"
    ```
  </Step>
</Steps>

### Bulk Updates with Scripting

Update multiple issues programmatically:

```bash theme={null}
# 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
```

```bash theme={null}
# 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`:

1. **Database** - SQLite database is updated immediately
2. **JSONL** - Changes are exported to `issues.jsonl` for version control
3. **Timestamps** - `updated_at` is set to current time
4. **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

<AccordionGroup>
  <Accordion title="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:

    ```bash theme={null}
    for id in ISSUE-001 ISSUE-002 ISSUE-003; do
      sudocode issue update "$id" --priority 1
    done
    ```
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="How do I change the parent issue?">
    The CLI doesn't currently support updating `parent_id`. Options:

    1. Edit the JSONL file directly and run `sudocode sync`
    2. Use the database directly
    3. Create a new issue with the correct parent
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Error: Issue not found">
    **Cause:** The issue ID doesn't exist

    **Solution:**
    Verify the ID:

    ```bash theme={null}
    sudocode issue list
    ```
  </Accordion>

  <Accordion title="Error: Invalid status value">
    **Cause:** Status must be one of: open, in\_progress, blocked, needs\_review, closed

    **Solution:**
    Use a valid status:

    ```bash theme={null}
    sudocode issue update ISSUE-001 --status in_progress
    ```
  </Accordion>

  <Accordion title="Error: Invalid priority value">
    **Cause:** Priority must be 0-4

    **Solution:**
    Use a valid priority:

    ```bash theme={null}
    sudocode issue update ISSUE-001 --priority 2
    ```
  </Accordion>

  <Accordion title="Update succeeded but nothing changed">
    **Cause:** You may have set the same value it already had

    **Solution:**
    Check current values:

    ```bash theme={null}
    sudocode issue show ISSUE-001
    ```
  </Accordion>
</AccordionGroup>

## Related Commands

<CardGroup cols={3}>
  <Card title="issue show" icon="eye" href="/cli/issue-show">
    View issue details
  </Card>

  <Card title="issue create" icon="plus" href="/cli/issue-create">
    Create new issue
  </Card>

  <Card title="issue list" icon="list" href="/cli/issue-list">
    List all issues
  </Card>

  <Card title="issue close" icon="circle-check" href="/cli/issue-close">
    Close completed issues
  </Card>

  <Card title="issue delete" icon="trash" href="/cli/issue-delete">
    Delete an issue
  </Card>

  <Card title="ready" icon="circle-check" href="/cli/ready">
    Find ready work
  </Card>
</CardGroup>

## Next Steps

<Steps>
  <Step title="View issue details">
    ```bash theme={null}
    sudocode issue show ISSUE-001
    ```
  </Step>

  <Step title="Update properties">
    ```bash theme={null}
    sudocode issue update ISSUE-001 --status in_progress --assignee "you"
    ```
  </Step>

  <Step title="Verify changes">
    ```bash theme={null}
    sudocode issue show ISSUE-001
    ```
  </Step>

  <Step title="Commit to git">
    ```bash theme={null}
    git add .sudocode/issues.jsonl
    git commit -m "Update issue status"
    ```
  </Step>
</Steps>

<Card title="Issues Concept Guide" icon="book" href="/concepts/issues">
  Learn more about issues and their lifecycle
</Card>