sudocode spec list

Syntax

sudocode spec list [options]

Description

The spec list command displays all specifications in your project. You can filter by priority, search by content, control archive visibility, and limit results. By default, the command:

Shows up to 50 specs
Excludes archived specs
Displays specs with their ID, title, priority, and file path

Use --grep for full-text search across spec titles and content, or use --priority to filter by priority level.

Options

number

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

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

string

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

boolean

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

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

number

default:"50"

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

Examples

List All Specs (Default)

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

sudocode spec list

Expected output

Found 5 spec(s):

SPEC-001 Authentication System Design
  Priority: 1 | specs/authentication-system.md

SPEC-002 OAuth 2.0 Integration
  Priority: 1 | specs/oauth-20-integration.md

SPEC-003 Session Management
  Priority: 2 | specs/session-management.md

SPEC-004 API Rate Limiting
  Priority: 2 | specs/api-rate-limiting.md

SPEC-005 Database Schema
  Priority: 0 | specs/database-schema.md

Filter by Priority

Show only critical (priority 0) specs:

sudocode spec list --priority 0

Expected output

Found 1 spec(s):

SPEC-005 Database Schema
  Priority: 0 | specs/database-schema.md

Search with Grep

Search for specs containing “auth”:

sudocode spec list --grep "auth"

Expected output

Found 3 spec(s):

SPEC-001 Authentication System Design
  Priority: 1 | specs/authentication-system.md

SPEC-002 OAuth 2.0 Integration
  Priority: 1 | specs/oauth-20-integration.md

SPEC-010 API Authentication Patterns
  Priority: 2 | specs/api-authentication-patterns.md

The grep search looks in both the title and the markdown content of specs.

Show Archived Specs

View only archived (deprecated) specs:

sudocode spec list --archived true

Expected output

Found 2 spec(s):

SPEC-050 Legacy Authentication (deprecated)
  Priority: 4 | specs/legacy-authentication.md

SPEC-051 Old Database Design (deprecated)
  Priority: 4 | specs/old-database-design.md

Combine Filters

Search for high-priority specs about “security”:

sudocode spec list --priority 1 --grep "security"

Expected output

Found 2 spec(s):

SPEC-001 Authentication System Design
  Priority: 1 | specs/authentication-system.md

SPEC-008 Security Audit Framework
  Priority: 1 | specs/security-audit-framework.md

Increase Result Limit

Show up to 100 specs:

sudocode spec list --limit 100

Useful for large projects with many specifications.

No Specs Found

When no specs match your filters:

sudocode spec list --priority 0 --grep "nonexistent"

Expected output

No specs found

JSON Output

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

sudocode --json spec list --priority 1

JSON output

[
  {
    "id": "SPEC-001",
    "title": "Authentication System Design",
    "priority": 1,
    "file_path": "specs/authentication-system.md",
    "content": "This spec defines...",
    "created_at": "2025-10-29T10:00:00Z",
    "updated_at": "2025-10-29T15:30:00Z",
    "parent_id": null,
    "archived": false
  },
  {
    "id": "SPEC-002",
    "title": "OAuth 2.0 Integration",
    "priority": 1,
    "file_path": "specs/oauth-20-integration.md",
    "content": "Implement OAuth 2.0...",
    "created_at": "2025-10-29T11:00:00Z",
    "updated_at": "2025-10-29T16:00:00Z",
    "parent_id": "SPEC-001",
    "archived": false
  }
]

Common Workflows

Finding High-Priority Work

Identify critical and high-priority specs that need attention:

List critical specs

sudocode spec list --priority 0

List high-priority specs

sudocode spec list --priority 1

Review each spec

sudocode spec show SPEC-001

Find all specs related to a topic:

Search by keyword

sudocode spec list --grep "authentication"

Refine by priority

sudocode spec list --grep "authentication" --priority 1

Review details

sudocode spec show SPEC-001

Auditing Archived Specs

Review deprecated specifications:

List archived specs

sudocode spec list --archived true

Review for removal

Decide if any can be permanently deleted

Clean up if needed

sudocode spec delete SPEC-050

Filtering Logic

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

Examples:

# Shows specs with priority 1 AND containing "auth"
sudocode spec list --priority 1 --grep "auth"

# Shows non-archived specs with priority 0 (first 100)
sudocode spec list --priority 0 --archived false --limit 100

Understanding Output

The default output format shows:

SPEC-ID Title
  Priority: N | file/path.md

Spec ID

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

Title

Human-readable spec name

Priority

0-4 priority level

File Path

Location in .sudocode/specs/

Common Questions

Why don't I see all my specs?

By default, spec list:

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

Try:

sudocode spec list --limit 1000

How does grep search work?

The --grep option searches both:

Spec titles
Markdown content

It’s case-insensitive and looks for partial matches. For example:

sudocode spec list --grep "Auth"

Will match “Authentication”, “OAuth”, “auth-system”, etc.

Can I search by tags?

Not directly with spec list. However, you can use grep to search for tags in content:

sudocode spec list --grep "security"

For more advanced filtering, use the JSON output and pipe to jq:

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

What's the difference between archived and deleted?

Archived specs (archived: true) are retained but hidden by default. They can be listed with --archived true.
Deleted specs are permanently removed from the database.

Archive specs when you want to keep them for reference but hide them from normal workflows.

How do I see child specs?

Use spec show to see hierarchical relationships:

sudocode spec show SPEC-001

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

Performance Tips

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

Use specific filters

Narrow results with --priority or --grep instead of listing everything

Increase limit if needed

Default limit of 50 is usually sufficient, but increase if necessary:

sudocode spec list --limit 200

Use JSON for scripting

JSON output is efficient for programmatic processing:

sudocode --json spec list | jq '.[] | .id'

Troubleshooting

Error: sudocode not initialized

Cause: No .sudocode/ directory foundSolution:

sudocode init

No specs found (but I created some)

Possible causes:

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

Solution:

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

# Check if specs exist in database
ls .sudocode/specs/

Grep not finding expected specs

Cause: Search term might not match title or contentSolution:

Try broader search terms
Check spec content with sudocode spec show SPEC-ID
Verify spelling

spec create

Create a new spec

spec show

View spec details

spec update

Update existing spec

spec delete

Delete specs

issue list

List implementation issues

ready

Find ready work

Next Steps

List your specs

sudocode spec list

Filter by priority

sudocode spec list --priority 1

View spec details

sudocode spec show SPEC-001

Create implementation issues

sudocode issue create "Implement feature"

Specs Concept Guide

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

CLI Reference

Spec Commands

Issue Commands

Relationship Commands

Feedback Commands

Query & Sync Commands

sudocode spec list

Syntax

Description

Options

Examples

List All Specs (Default)

Filter by Priority

Search with Grep

Show Archived Specs

Combine Filters

Increase Result Limit

No Specs Found

JSON Output

Common Workflows

Finding High-Priority Work

Auditing Archived Specs

Filtering Logic

Understanding Output

Spec ID

Title

Priority

File Path

Common Questions

Performance Tips

Troubleshooting

spec create

spec show

spec update

spec delete

issue list

ready

Next Steps

Specs Concept Guide

​Syntax

​Description

​Options

​Examples

​List All Specs (Default)

​Filter by Priority

​Search with Grep

​Show Archived Specs

​Combine Filters

​Increase Result Limit

​No Specs Found

​JSON Output

​Common Workflows

​Finding High-Priority Work

​Searching for Related Specs

​Auditing Archived Specs

​Filtering Logic

​Understanding Output

Spec ID

Title

Priority

File Path

​Common Questions

​Performance Tips

​Troubleshooting

​Related Commands

spec create

spec show

spec update

spec delete

issue list

ready

​Next Steps

Specs Concept Guide

Syntax

Description

Options

Examples

List All Specs (Default)

Filter by Priority

Search with Grep

Show Archived Specs

Combine Filters

Increase Result Limit

No Specs Found

JSON Output

Common Workflows

Finding High-Priority Work

Searching for Related Specs

Auditing Archived Specs

Filtering Logic

Understanding Output

Common Questions

Performance Tips

Troubleshooting

Related Commands

Next Steps