> ## 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 list

> List all issues in your sudocode project with comprehensive filtering by status, assignee, priority, and content search

## Syntax

```bash theme={null}
sudocode issue list [options]
```

## Description

The `issue list` command displays all issues in your project. You can filter by status, assignee, priority, search content, control archive visibility, and limit results.

By default, the command:

* Shows up to 50 issues
* Excludes archived issues
* Displays issues with their ID, status, title, priority, and assignee
* Color-codes status for easy scanning

<Note>
  Use `--status` to filter by workflow state, `--grep` for full-text search, or `--assignee` to see work assigned to specific agents or users.
</Note>

## Options

<ParamField path="-s, --status" type="string">
  Filter by 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="-a, --assignee" type="string">
  Filter by assignee name or agent ID

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

  Shows only issues assigned to the specified user or agent.
</ParamField>

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

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

  Only shows issues with the specified priority:

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

<ParamField path="-g, --grep" type="string">
  Search issues by title or content

  **Example:** `--grep "authentication"`

  Performs a full-text search across issue titles and content. Case-insensitive by default.
</ParamField>

<ParamField path="--archived" type="boolean">
  Filter by archive status

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

  * `false` (default) - Exclude archived issues
  * `true` - Show only archived issues
  * Omit to see all issues regardless of archive status
</ParamField>

<ParamField path="--limit" type="number" default="50">
  Maximum number of results to return

  **Example:** `--limit 100`

  Useful for large projects with many issues. Increase to see more results.
</ParamField>

## Examples

### List All Issues (Default)

Show all non-archived issues (up to 50):

```bash theme={null}
sudocode issue list
```

<Accordion title="Expected output">
  ```
  Found 5 issue(s):

  ISSUE-001 [open] Implement login endpoint
    Priority: 1

  ISSUE-002 [in_progress] Fix token expiration bug @alice
    Priority: 0

  ISSUE-003 [blocked] Add password reset flow
    Priority: 2

  ISSUE-004 [needs_review] Unit tests for auth service @agent-testing
    Priority: 2

  ISSUE-005 [closed] Database schema setup @bob
    Priority: 1
  ```
</Accordion>

Status is color-coded:

* 🟢 Green: `closed`
* 🟡 Yellow: `in_progress`
* 🔴 Red: `blocked`
* ⚪ Gray: `open`, `needs_review`

### Filter by Status

Show only issues currently in progress:

```bash theme={null}
sudocode issue list --status in_progress
```

<Accordion title="Expected output">
  ```
  Found 2 issue(s):

  ISSUE-002 [in_progress] Fix token expiration bug @alice
    Priority: 0

  ISSUE-010 [in_progress] Implement OAuth flow @agent-backend
    Priority: 1
  ```
</Accordion>

### Filter by Assignee

Show all issues assigned to a specific user:

```bash theme={null}
sudocode issue list --assignee "alice"
```

<Accordion title="Expected output">
  ```
  Found 3 issue(s):

  ISSUE-002 [in_progress] Fix token expiration bug @alice
    Priority: 0

  ISSUE-007 [open] Add rate limiting @alice
    Priority: 1

  ISSUE-012 [needs_review] Security audit @alice
    Priority: 1
  ```
</Accordion>

### Filter by Priority

Show only critical (priority 0) issues:

```bash theme={null}
sudocode issue list --priority 0
```

<Accordion title="Expected output">
  ```
  Found 2 issue(s):

  ISSUE-002 [in_progress] Fix token expiration bug @alice
    Priority: 0

  ISSUE-008 [open] Database migration
    Priority: 0
  ```
</Accordion>

### Search with Grep

Search for issues containing "auth":

```bash theme={null}
sudocode issue list --grep "auth"
```

<Accordion title="Expected output">
  ```
  Found 4 issue(s):

  ISSUE-001 [open] Implement login endpoint
    Priority: 1

  ISSUE-004 [needs_review] Unit tests for auth service @agent-testing
    Priority: 2

  ISSUE-010 [in_progress] Implement OAuth flow @agent-backend
    Priority: 1

  ISSUE-015 [open] Add multi-factor authentication
    Priority: 2
  ```
</Accordion>

### Show Open Issues Only

View all open issues ready to be claimed:

```bash theme={null}
sudocode issue list --status open
```

<Accordion title="Expected output">
  ```
  Found 3 issue(s):

  ISSUE-001 [open] Implement login endpoint
    Priority: 1

  ISSUE-008 [open] Database migration
    Priority: 0

  ISSUE-015 [open] Add multi-factor authentication
    Priority: 2
  ```
</Accordion>

### Show Blocked Issues

Identify issues waiting on dependencies:

```bash theme={null}
sudocode issue list --status blocked
```

<Accordion title="Expected output">
  ```
  Found 1 issue(s):

  ISSUE-003 [blocked] Add password reset flow
    Priority: 2
  ```
</Accordion>

Use `sudocode issue show ISSUE-003` to see what's blocking it.

### Combine Filters

Show high-priority open issues:

```bash theme={null}
sudocode issue list --status open --priority 1
```

<Accordion title="Expected output">
  ```
  Found 1 issue(s):

  ISSUE-001 [open] Implement login endpoint
    Priority: 1
  ```
</Accordion>

### Search for Unassigned Work

Find open issues without an assignee:

```bash theme={null}
sudocode issue list --status open
```

Then look for issues without `@assignee` in the output.

### Show Closed Issues

Review completed work:

```bash theme={null}
sudocode issue list --status closed
```

<Accordion title="Expected output">
  ```
  Found 3 issue(s):

  ISSUE-005 [closed] Database schema setup @bob
    Priority: 1

  ISSUE-020 [closed] Initial project setup @alice
    Priority: 0

  ISSUE-025 [closed] Documentation @charlie
    Priority: 3
  ```
</Accordion>

### Increase Result Limit

Show up to 200 issues:

```bash theme={null}
sudocode issue list --limit 200
```

Useful for large projects with many issues.

## JSON Output

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

```bash theme={null}
sudocode --json issue list --status open --priority 1
```

<Accordion title="JSON output">
  ```json theme={null}
  [
    {
      "id": "ISSUE-001",
      "title": "Implement login endpoint",
      "status": "open",
      "priority": 1,
      "assignee": null,
      "content": "Create REST endpoint for user login...",
      "created_at": "2025-10-29T10:00:00Z",
      "updated_at": "2025-10-29T15:30:00Z",
      "closed_at": null,
      "parent_id": null,
      "archived": false
    }
  ]
  ```
</Accordion>

## Common Workflows

### Finding Ready Work

Identify issues ready to be worked on:

<Steps>
  <Step title="List open issues">
    ```bash theme={null}
    sudocode issue list --status open
    ```
  </Step>

  <Step title="Or use ready command">
    ```bash theme={null}
    sudocode ready
    ```

    This shows open issues without blockers, sorted by priority.
  </Step>

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

### Tracking Your Work

See all issues assigned to you:

<Steps>
  <Step title="View your issues">
    ```bash theme={null}
    sudocode issue list --assignee "your-name"
    ```
  </Step>

  <Step title="Filter by status">
    ```bash theme={null}
    sudocode issue list --assignee "your-name" --status in_progress
    ```
  </Step>

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

### Daily Standup

Quick overview of project status:

<Steps>
  <Step title="What's in progress?">
    ```bash theme={null}
    sudocode issue list --status in_progress
    ```
  </Step>

  <Step title="What's blocked?">
    ```bash theme={null}
    sudocode issue list --status blocked
    ```
  </Step>

  <Step title="What's completed today?">
    ```bash theme={null}
    sudocode issue list --status closed
    ```
  </Step>
</Steps>

### Sprint Planning

Organize work by priority:

<Steps>
  <Step title="Critical work">
    ```bash theme={null}
    sudocode issue list --priority 0 --status open
    ```
  </Step>

  <Step title="High priority work">
    ```bash theme={null}
    sudocode issue list --priority 1 --status open
    ```
  </Step>

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

## Filtering Logic

<Info>
  **Important:** When multiple filters are specified, they work as **AND** conditions. All filters must match for an issue to appear in results.
</Info>

Examples:

```bash theme={null}
# Shows issues with status=open AND priority=1
sudocode issue list --status open --priority 1

# Shows issues assigned to alice AND containing "auth"
sudocode issue list --assignee "alice" --grep "auth"

# Shows open issues with priority 0, assigned to bob (up to 100)
sudocode issue list --status open --priority 0 --assignee "bob" --limit 100
```

## Understanding Output

The default output format shows:

```
ISSUE-ID [status] Title @assignee
  Priority: N
```

<CardGroup cols={2}>
  <Card title="Issue ID" icon="fingerprint">
    Unique identifier (e.g., ISSUE-001)
  </Card>

  <Card title="Status" icon="traffic-light">
    Current workflow state (color-coded)
  </Card>

  <Card title="Title" icon="heading">
    Descriptive issue name
  </Card>

  <Card title="Assignee" icon="user">
    Who's working on it (if assigned)
  </Card>

  <Card title="Priority" icon="signal">
    0-4 priority level
  </Card>
</CardGroup>

## Common Questions

<AccordionGroup>
  <Accordion title="Why don't I see all my issues?">
    By default, `issue list`:

    * Limits to 50 results (use `--limit` to increase)
    * Excludes archived issues (use `--archived false` to explicitly exclude, or omit to see all)

    Try:

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

  <Accordion title="How do I find unassigned issues?">
    List issues and look for entries without `@assignee`:

    ```bash theme={null}
    sudocode issue list --status open
    ```

    For programmatic filtering, use JSON output:

    ```bash theme={null}
    sudocode --json issue list | jq '.[] | select(.assignee == null)'
    ```
  </Accordion>

  <Accordion title="What's the difference between grep and searching by status?">
    * `--grep` searches in the title and content (full-text search)
    * `--status` filters by exact workflow state

    Example:

    ```bash theme={null}
    # Find issues mentioning "login" in any state
    sudocode issue list --grep "login"

    # Find open issues (regardless of content)
    sudocode issue list --status open

    # Find open issues mentioning "login"
    sudocode issue list --status open --grep "login"
    ```
  </Accordion>

  <Accordion title="Can I search by tags?">
    Not directly with `issue list`. However, you can use grep to search for tags in content, or use JSON output with `jq`:

    ```bash theme={null}
    sudocode --json issue list | jq '.[] | select(.tags | contains(["auth"]))'
    ```
  </Accordion>

  <Accordion title="How do I see subtasks of an epic?">
    Use `issue show` to see hierarchical relationships:

    ```bash theme={null}
    sudocode issue show ISSUE-001
    ```

    This will display parent and child issues in the relationship section.
  </Accordion>

  <Accordion title="What does 'ready' mean vs 'open'?">
    * **open**: Status of the issue - it's not yet started
    * **ready**: Issue is open AND has no blocking dependencies

    Use `sudocode ready` to find truly ready work (open + unblocked).
  </Accordion>
</AccordionGroup>

## Performance Tips

<Info>
  For large projects with hundreds of issues, consider these optimizations:
</Info>

<Steps>
  <Step title="Use specific filters">
    Narrow results with `--status`, `--priority`, or `--assignee` instead of listing everything
  </Step>

  <Step title="Use grep for targeted searches">
    Search for specific keywords rather than retrieving all issues:

    ```bash theme={null}
    sudocode issue list --grep "auth"
    ```
  </Step>

  <Step title="Use JSON for scripting">
    JSON output is efficient for programmatic processing:

    ```bash theme={null}
    sudocode --json issue list --status open | jq '.[] | .id'
    ```
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Error: sudocode not initialized">
    **Cause:** No `.sudocode/` directory found

    **Solution:**

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

  <Accordion title="No issues found (but I created some)">
    **Possible causes:**

    1. Issues are archived: `sudocode issue list --archived false` (default excludes archived)
    2. Issues don't match filters: Remove filters to see all
    3. Database not synced: Run `sudocode sync`

    **Solution:**

    ```bash theme={null}
    # Try listing with no filters
    sudocode issue list --limit 1000
    ```
  </Accordion>

  <Accordion title="Status filter not working">
    **Cause:** Ensure status value is valid

    **Solution:**
    Valid statuses: `open`, `in_progress`, `blocked`, `needs_review`, `closed`

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

  <Accordion title="Grep not finding expected issues">
    **Cause:** Search term might not match title or content

    **Solution:**

    * Try broader search terms
    * Check issue content with `sudocode issue show ISSUE-ID`
    * Verify spelling
  </Accordion>
</AccordionGroup>

## Related Commands

<CardGroup cols={3}>
  <Card title="issue create" icon="plus" href="/cli/issue-create">
    Create a new issue
  </Card>

  <Card title="issue show" icon="eye" href="/cli/issue-show">
    View issue details
  </Card>

  <Card title="issue update" icon="pen-to-square" href="/cli/issue-update">
    Update existing issue
  </Card>

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

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

  <Card title="blocked" icon="ban" href="/cli/blocked">
    View blocked issues
  </Card>
</CardGroup>

## Next Steps

<Steps>
  <Step title="List your issues">
    ```bash theme={null}
    sudocode issue list
    ```
  </Step>

  <Step title="Filter to find work">
    ```bash theme={null}
    sudocode issue list --status open --priority 1
    ```
  </Step>

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

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

<Card title="Issues Concept Guide" icon="book" href="/concepts/issues">
  Learn more about issues and how they fit into sudocode's workflow
</Card>