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

> List all specs in your sudocode project with powerful filtering and search capabilities.

## Syntax

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

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

## Options

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

  **Example:** `--priority 1`

  Only shows specs with the specified priority:

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

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

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

  Performs a full-text search across spec titles and markdown 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 specs
  * `true` - Show only archived specs
  * Omit to see all specs 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 specs. Increase to see more results.
</ParamField>

## Examples

### List All Specs (Default)

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

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

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

### Filter by Priority

Show only critical (priority 0) specs:

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

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

  SPEC-005 Database Schema
    Priority: 0 | specs/database-schema.md
  ```
</Accordion>

### Search with Grep

Search for specs containing "auth":

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

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

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

### Show Archived Specs

View only archived (deprecated) specs:

```bash theme={null}
sudocode spec list --archived true
```

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

### Combine Filters

Search for high-priority specs about "security":

```bash theme={null}
sudocode spec list --priority 1 --grep "security"
```

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

### Increase Result Limit

Show up to 100 specs:

```bash theme={null}
sudocode spec list --limit 100
```

Useful for large projects with many specifications.

### No Specs Found

When no specs match your filters:

```bash theme={null}
sudocode spec list --priority 0 --grep "nonexistent"
```

<Accordion title="Expected output">
  ```
  No specs found
  ```
</Accordion>

## JSON Output

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

```bash theme={null}
sudocode --json spec list --priority 1
```

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

## Common Workflows

### Finding High-Priority Work

Identify critical and high-priority specs that need attention:

<Steps>
  <Step title="List critical specs">
    ```bash theme={null}
    sudocode spec list --priority 0
    ```
  </Step>

  <Step title="List high-priority specs">
    ```bash theme={null}
    sudocode spec list --priority 1
    ```
  </Step>

  <Step title="Review each spec">
    ```bash theme={null}
    sudocode spec show SPEC-001
    ```
  </Step>
</Steps>

### Searching for Related Specs

Find all specs related to a topic:

<Steps>
  <Step title="Search by keyword">
    ```bash theme={null}
    sudocode spec list --grep "authentication"
    ```
  </Step>

  <Step title="Refine by priority">
    ```bash theme={null}
    sudocode spec list --grep "authentication" --priority 1
    ```
  </Step>

  <Step title="Review details">
    ```bash theme={null}
    sudocode spec show SPEC-001
    ```
  </Step>
</Steps>

### Auditing Archived Specs

Review deprecated specifications:

<Steps>
  <Step title="List archived specs">
    ```bash theme={null}
    sudocode spec list --archived true
    ```
  </Step>

  <Step title="Review for removal">
    Decide if any can be permanently deleted
  </Step>

  <Step title="Clean up if needed">
    ```bash theme={null}
    sudocode spec delete SPEC-050
    ```
  </Step>
</Steps>

## Filtering Logic

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

Examples:

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

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

  <Card title="Title" icon="heading">
    Human-readable spec name
  </Card>

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

  <Card title="File Path" icon="file">
    Location in `.sudocode/specs/`
  </Card>
</CardGroup>

## Common Questions

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

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

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

    ```bash theme={null}
    sudocode spec list --grep "Auth"
    ```

    Will match "Authentication", "OAuth", "auth-system", etc.
  </Accordion>

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

    ```bash theme={null}
    sudocode spec list --grep "security"
    ```

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

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

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

  <Accordion title="How do I see child specs?">
    Use `spec show` to see hierarchical relationships:

    ```bash theme={null}
    sudocode spec show SPEC-001
    ```

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

## Performance Tips

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

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

  <Step title="Increase limit if needed">
    Default limit of 50 is usually sufficient, but increase if necessary:

    ```bash theme={null}
    sudocode spec list --limit 200
    ```
  </Step>

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

    ```bash theme={null}
    sudocode --json spec list | 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 specs found (but I created some)">
    **Possible causes:**

    1. Specs are archived: `sudocode spec list --archived false` (default excludes archived)
    2. Specs 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 spec list --limit 1000

    # Check if specs exist in database
    ls .sudocode/specs/
    ```
  </Accordion>

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

    **Solution:**

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

## Related Commands

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

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

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

  <Card title="spec delete" icon="trash" href="/cli/spec-delete">
    Delete specs
  </Card>

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

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

## Next Steps

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

  <Step title="Filter by priority">
    ```bash theme={null}
    sudocode spec list --priority 1
    ```
  </Step>

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

  <Step title="Create implementation issues">
    ```bash theme={null}
    sudocode issue create "Implement feature"
    ```
  </Step>
</Steps>

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