sudocode issue list

Syntax

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

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

Options

-s, --status

string

Filter by 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

-a, --assignee

string

Filter by assignee name or agent IDExample: --assignee "alice" or --assignee "agent-backend-dev"Shows only issues assigned to the specified user or agent.

-p, --priority

number

Filter by priority level (0-4)Example: --priority 0Only shows issues with the specified priority:

0 - Critical
1 - High
2 - Medium
3 - Low
4 - Lowest

-g, --grep

string

Search issues by title or contentExample: --grep "authentication"Performs a full-text search across issue titles and content. Case-insensitive by default.

--archived

boolean

Filter by archive statusExample: --archived true or --archived false

false (default) - Exclude archived issues
true - Show only archived issues
Omit to see all issues regardless of archive status

--limit

number

default:"50"

Maximum number of results to returnExample: --limit 100Useful for large projects with many issues. Increase to see more results.

Examples

List All Issues (Default)

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

sudocode issue list

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

Status is color-coded:

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

Filter by Status

Show only issues currently in progress:

sudocode issue list --status in_progress

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

Filter by Assignee

Show all issues assigned to a specific user:

sudocode issue list --assignee "alice"

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

Filter by Priority

Show only critical (priority 0) issues:

sudocode issue list --priority 0

Expected output

Found 2 issue(s):

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

ISSUE-008 [open] Database migration
  Priority: 0

Search with Grep

Search for issues containing “auth”:

sudocode issue list --grep "auth"

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

Show Open Issues Only

View all open issues ready to be claimed:

sudocode issue list --status open

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

Show Blocked Issues

Identify issues waiting on dependencies:

sudocode issue list --status blocked

Expected output

Found 1 issue(s):

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

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

Combine Filters

Show high-priority open issues:

sudocode issue list --status open --priority 1

Expected output

Found 1 issue(s):

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

Search for Unassigned Work

Find open issues without an assignee:

sudocode issue list --status open

Then look for issues without @assignee in the output.

Show Closed Issues

Review completed work:

sudocode issue list --status closed

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

Increase Result Limit

Show up to 200 issues:

sudocode issue list --limit 200

Useful for large projects with many issues.

JSON Output

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

sudocode --json issue list --status open --priority 1

JSON output

[
  {
    "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
  }
]

Common Workflows

Finding Ready Work

Identify issues ready to be worked on:

List open issues

sudocode issue list --status open

Or use ready command

sudocode ready

This shows open issues without blockers, sorted by priority.

Claim an issue

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

Tracking Your Work

See all issues assigned to you:

View your issues

sudocode issue list --assignee "your-name"

Filter by status

sudocode issue list --assignee "your-name" --status in_progress

Review details

sudocode issue show ISSUE-002

Daily Standup

Quick overview of project status:

What's in progress?

sudocode issue list --status in_progress

What's blocked?

sudocode issue list --status blocked

What's completed today?

sudocode issue list --status closed

Sprint Planning

Organize work by priority:

Critical work

sudocode issue list --priority 0 --status open

High priority work

sudocode issue list --priority 1 --status open

Assign to team

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

Filtering Logic

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

Examples:

# 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

Issue ID

Unique identifier (e.g., ISSUE-001)

Status

Current workflow state (color-coded)

Title

Descriptive issue name

Assignee

Who’s working on it (if assigned)

Priority

0-4 priority level

Common Questions

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:

sudocode issue list --limit 1000

How do I find unassigned issues?

List issues and look for entries without @assignee:

sudocode issue list --status open

For programmatic filtering, use JSON output:

sudocode --json issue list | jq '.[] | select(.assignee == null)'

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:

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

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:

sudocode --json issue list | jq '.[] | select(.tags | contains(["auth"]))'

How do I see subtasks of an epic?

Use issue show to see hierarchical relationships:

sudocode issue show ISSUE-001

This will display parent and child issues in the relationship section.

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).

Performance Tips

For large projects with hundreds of issues, consider these optimizations:

Use specific filters

Narrow results with --status, --priority, or --assignee instead of listing everything

Use grep for targeted searches

Search for specific keywords rather than retrieving all issues:

sudocode issue list --grep "auth"

Use JSON for scripting

JSON output is efficient for programmatic processing:

sudocode --json issue list --status open | jq '.[] | .id'

Troubleshooting

Error: sudocode not initialized

Cause: No .sudocode/ directory foundSolution:

sudocode init

No issues found (but I created some)

Possible causes:

Issues are archived: sudocode issue list --archived false (default excludes archived)
Issues don’t match filters: Remove filters to see all
Database not synced: Run sudocode sync

Solution:

# Try listing with no filters
sudocode issue list --limit 1000

Status filter not working

Cause: Ensure status value is validSolution: Valid statuses: open, in_progress, blocked, needs_review, closed

sudocode issue list --status in_progress

Grep not finding expected issues

Cause: Search term might not match title or contentSolution:

Try broader search terms
Check issue content with sudocode issue show ISSUE-ID
Verify spelling

issue create

Create a new issue

issue show

View issue details

issue update

Update existing issue

issue close

Close completed issues

ready

Find ready work (unblocked)

blocked

View blocked issues

Next Steps

List your issues

sudocode issue list

Filter to find work

sudocode issue list --status open --priority 1

View issue details

sudocode issue show ISSUE-001

Start working

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

Issues Concept Guide

Learn more about issues and how they fit into sudocode’s workflow

CLI Reference

Spec Commands

Issue Commands

Relationship Commands

Feedback Commands

Query & Sync Commands

Documentation Index

​Syntax

​Description

​Options

​Examples

​List All Issues (Default)

​Filter by Status

​Filter by Assignee

​Filter by Priority

​Search with Grep

​Show Open Issues Only

​Show Blocked Issues

​Combine Filters

​Search for Unassigned Work

​Show Closed Issues

​Increase Result Limit

​JSON Output

​Common Workflows

​Finding Ready Work

​Tracking Your Work

​Daily Standup

​Sprint Planning

​Filtering Logic

​Understanding Output

Issue ID

Status

Title

Assignee

Priority

​Common Questions

​Performance Tips

​Troubleshooting

​Related Commands

issue create

issue show

issue update

issue close

ready

blocked

​Next Steps

Issues Concept Guide

Syntax

Description

Options

Examples

List All Issues (Default)

Filter by Status

Filter by Assignee

Filter by Priority

Search with Grep

Show Open Issues Only

Show Blocked Issues

Combine Filters

Search for Unassigned Work

Show Closed Issues

Increase Result Limit

JSON Output

Common Workflows

Finding Ready Work

Tracking Your Work

Daily Standup

Sprint Planning

Filtering Logic

Understanding Output

Common Questions

Performance Tips

Troubleshooting

Related Commands

Next Steps