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

> Update existing specification properties

## Syntax

```bash theme={null}
sudocode spec update <spec-id> [options]
```

## Description

The `spec update` command allows you to modify properties of an existing spec. You can update the title, priority, description, parent relationship, tags, and archive status.

When you update a spec:

* Changes are written to the SQLite database
* The markdown file is updated with new frontmatter
* Changes are exported to JSONL for version control
* The `updated_at` timestamp is automatically set

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

## Arguments

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

  **Example:** `SPEC-001`

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

## Options

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

  **Example:** `--title "Updated Authentication System"`

  Changes the display title of the spec.
</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="-d, --description" type="string">
  Update the spec description/content

  **Example:** `--description "Updated spec content"`

  This replaces the markdown content of the spec.
</ParamField>

<ParamField path="--parent" type="string">
  Update parent spec ID for hierarchical organization

  **Example:** `--parent SPEC-005`

  Use empty string to remove parent: `--parent ""`
</ParamField>

<ParamField path="--tags" type="string">
  Replace all tags with new comma-separated list

  **Example:** `--tags "auth,security,critical"`

  **Note:** This replaces all existing tags. To add/remove individual tags, edit the markdown file directly.
</ParamField>

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

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

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

## Examples

### Update Priority

Elevate a spec to critical priority:

```bash theme={null}
sudocode spec update SPEC-001 --priority 0
```

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

### Update Title

Rename a spec:

```bash theme={null}
sudocode spec update SPEC-001 --title "OAuth 2.0 and JWT Authentication"
```

<Accordion title="Expected output">
  ```
  ✓ Updated spec SPEC-001
    Title: OAuth 2.0 and JWT Authentication
  ```
</Accordion>

### Update Description

Replace spec content:

```bash theme={null}
sudocode spec update SPEC-001 \
  --description "This spec defines OAuth 2.0 authentication with JWT token management"
```

<Accordion title="Expected output">
  ```
  ✓ Updated spec SPEC-001
    description: This spec defines OAuth 2.0 authentication with JWT token management
  ```
</Accordion>

### Update Multiple Fields

Change priority and title together:

```bash theme={null}
sudocode spec update SPEC-001 \
  --priority 0 \
  --title "Critical: Authentication System" \
  --tags "auth,security,critical"
```

<Accordion title="Expected output">
  ```
  ✓ Updated spec SPEC-001
    priority: 0
    title: Critical: Authentication System
    tags: auth,security,critical
  ```
</Accordion>

### Set Parent Spec

Add to hierarchy:

```bash theme={null}
sudocode spec update SPEC-003 --parent SPEC-001
```

<Accordion title="Expected output">
  ```
  ✓ Updated spec SPEC-003
    parent: SPEC-001
  ```
</Accordion>

This makes SPEC-003 a child of SPEC-001.

### Remove Parent Spec

Remove from hierarchy:

```bash theme={null}
sudocode spec update SPEC-003 --parent ""
```

<Accordion title="Expected output">
  ```
  ✓ Updated spec SPEC-003
    parent:
  ```
</Accordion>

### Archive a Spec

Mark spec as archived (deprecated):

```bash theme={null}
sudocode spec update SPEC-050 --archived true
```

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

Archived specs won't appear in `spec list` by default.

### Unarchive a Spec

Restore an archived spec:

```bash theme={null}
sudocode spec update SPEC-050 --archived false
```

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

### Update Tags

Replace all tags:

```bash theme={null}
sudocode spec update SPEC-001 --tags "backend,api,security,oauth"
```

<Accordion title="Expected output">
  ```
  ✓ Updated spec SPEC-001
    tags: backend,api,security,oauth
  ```
</Accordion>

<Warning>
  The `--tags` option replaces ALL existing tags. To add or remove individual tags, edit the markdown file directly.
</Warning>

## JSON Output

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

```bash theme={null}
sudocode --json spec update SPEC-001 --priority 0
```

<Accordion title="JSON output">
  ```json theme={null}
  {
    "id": "SPEC-001",
    "title": "Authentication System Design",
    "priority": 0,
    "file_path": "specs/authentication-system.md",
    "content": "...",
    "parent_id": null,
    "created_at": "2025-10-29T10:00:00Z",
    "updated_at": "2025-10-29T18:30:00Z",
    "archived": false
  }
  ```
</Accordion>

## Common Workflows

### Promoting Spec Priority

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

  <Step title="Promote to high priority">
    ```bash theme={null}
    sudocode spec update SPEC-001 --priority 1
    ```
  </Step>

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

### Reorganizing Spec Hierarchy

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

  <Step title="Move child specs">
    ```bash theme={null}
    sudocode spec update SPEC-003 --parent SPEC-001
    sudocode spec update SPEC-004 --parent SPEC-001
    ```
  </Step>

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

### Deprecating Old Specs

<Steps>
  <Step title="Archive the spec">
    ```bash theme={null}
    sudocode spec update SPEC-050 --archived true
    ```
  </Step>

  <Step title="Lower priority">
    ```bash theme={null}
    sudocode spec update SPEC-050 --priority 4
    ```
  </Step>

  <Step title="Update title to indicate deprecation">
    ```bash theme={null}
    sudocode spec update SPEC-050 --title "[DEPRECATED] Old Auth System"
    ```
  </Step>
</Steps>

### Bulk Updates with Scripting

Update multiple specs programmatically:

```bash theme={null}
# Promote all auth specs to high priority
for spec_id in $(sudocode --json spec list --grep "auth" | jq -r '.[] | .id'); do
  sudocode spec update "$spec_id" --priority 1
done
```

```bash theme={null}
# Archive all low-priority specs
sudocode --json spec list --priority 4 | jq -r '.[] | .id' | while read spec_id; do
  sudocode spec update "$spec_id" --archived true
done
```

## Update Behavior

### What Gets Updated

When you run `spec update`:

1. **Database** - SQLite database is updated immediately
2. **Markdown file** - Frontmatter is updated with new values
3. **JSONL** - Changes are exported to `specs.jsonl` for version control
4. **Timestamp** - `updated_at` is set to current time

### What Doesn't Change

* **Spec ID** - Immutable, cannot be changed
* **Creation timestamp** - `created_at` never changes
* **File path** - Markdown filename stays the same
* **Relationships** - Use `link` command to manage relationships
* **Feedback** - Use `feedback` commands to manage feedback

### Content Updates

The `--description` flag replaces the markdown content below the frontmatter:

**Before:**

```markdown theme={null}
---
id: SPEC-001
title: Old Title
---

Old content here
```

**After** `sudocode spec update SPEC-001 --description "New content"`:

```markdown theme={null}
---
id: SPEC-001
title: Old Title
updated_at: 2025-10-29T18:30:00Z
---

New content
```

<Info>
  For complex content updates, edit the markdown file directly rather than using `--description`.
</Info>

## Common Questions

<AccordionGroup>
  <Accordion title="Can I update multiple specs at once?">
    No, `spec update` works on one spec at a time. For bulk updates, use shell scripting with loops:

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

  <Accordion title="What happens to relationships when I update a spec?">
    Relationships are unaffected by `spec update`. They persist regardless of changes to title, priority, or other properties.
  </Accordion>

  <Accordion title="How do I add tags without replacing existing ones?">
    The `--tags` option replaces all tags. To add tags while keeping existing ones:

    1. View current tags: `sudocode spec show SPEC-001`
    2. Combine old and new: `sudocode spec update SPEC-001 --tags "old,tags,new,tag"`

    Or edit the markdown file directly to add tags to the frontmatter.
  </Accordion>

  <Accordion title="Can I change the spec ID?">
    No, spec IDs are immutable. They serve as stable references across the system. If you need a different ID, create a new spec and archive the old one.
  </Accordion>

  <Accordion title="What's the difference between archiving and deleting?">
    * **Archiving** (`--archived true`) hides the spec from default listings but retains it for reference
    * **Deleting** (`spec delete`) permanently removes the spec from the database

    Use archiving to deprecate specs you might need to reference later.
  </Accordion>

  <Accordion title="Will updating a spec notify anyone?">
    No, sudocode doesn't have built-in notifications. Updates are tracked via git commits and the `updated_at` timestamp. Consider adding a git commit message describing significant updates.
  </Accordion>
</AccordionGroup>

## Troubleshooting

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

    **Solution:**
    Verify the ID:

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

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

    **Solution:**
    Use a valid priority:

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

  <Accordion title="Error: Parent spec not found">
    **Cause:** The parent spec ID doesn't exist

    **Solution:**
    Verify the parent exists:

    ```bash theme={null}
    sudocode spec show SPEC-005
    ```
  </Accordion>

  <Accordion title="Update succeeded but markdown file unchanged">
    **Cause:** Only database-level fields were updated, or sync issue

    **Solution:**
    Run sync to ensure consistency:

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

## Related Commands

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

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

  <Card title="spec list" icon="list" href="/cli/spec-list">
    List all specs
  </Card>

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

  <Card title="link" icon="link" href="/cli/link">
    Manage relationships
  </Card>

  <Card title="sync" icon="arrows-rotate" href="/cli/sync">
    Synchronize data
  </Card>
</CardGroup>

## Next Steps

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

  <Step title="Update properties">
    ```bash theme={null}
    sudocode spec update SPEC-001 --priority 0 --title "New Title"
    ```
  </Step>

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

  <Step title="Commit to git">
    ```bash theme={null}
    git add .sudocode/specs.jsonl
    git commit -m "Update spec priority and title"
    ```
  </Step>
</Steps>

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