sudocode spec update

Syntax

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

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

Arguments

spec-id

string

required

The ID of the spec to updateExample: SPEC-001The spec must exist in your project.

Options

--title

string

Update the spec titleExample: --title "Updated Authentication System"Changes the display title of the spec.

-p, --priority

number

Update priority level (0-4)Example: --priority 0Priority levels:

0 - Critical (highest)
1 - High
2 - Medium
3 - Low
4 - Lowest

-d, --description

string

Update the spec description/contentExample: --description "Updated spec content"This replaces the markdown content of the spec.

--parent

string

Update parent spec ID for hierarchical organizationExample: --parent SPEC-005Use empty string to remove parent: --parent ""

--tags

string

Replace all tags with new comma-separated listExample: --tags "auth,security,critical"Note: This replaces all existing tags. To add/remove individual tags, edit the markdown file directly.

--archived

boolean

Archive or unarchive the specExample: --archived true or --archived falseArchived specs are hidden from default listings but retained for reference.

Examples

Update Priority

Elevate a spec to critical priority:

sudocode spec update SPEC-001 --priority 0

Expected output

✓ Updated spec SPEC-001
  priority: 0

Update Title

Rename a spec:

sudocode spec update SPEC-001 --title "OAuth 2.0 and JWT Authentication"

Expected output

✓ Updated spec SPEC-001
  Title: OAuth 2.0 and JWT Authentication

Update Description

Replace spec content:

sudocode spec update SPEC-001 \
  --description "This spec defines OAuth 2.0 authentication with JWT token management"

Expected output

✓ Updated spec SPEC-001
  description: This spec defines OAuth 2.0 authentication with JWT token management

Update Multiple Fields

Change priority and title together:

sudocode spec update SPEC-001 \
  --priority 0 \
  --title "Critical: Authentication System" \
  --tags "auth,security,critical"

Expected output

✓ Updated spec SPEC-001
  priority: 0
  title: Critical: Authentication System
  tags: auth,security,critical

Set Parent Spec

Add to hierarchy:

sudocode spec update SPEC-003 --parent SPEC-001

Expected output

✓ Updated spec SPEC-003
  parent: SPEC-001

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

Remove Parent Spec

Remove from hierarchy:

sudocode spec update SPEC-003 --parent ""

Expected output

✓ Updated spec SPEC-003
  parent:

Archive a Spec

Mark spec as archived (deprecated):

sudocode spec update SPEC-050 --archived true

Expected output

✓ Updated spec SPEC-050
  archived: true

Archived specs won’t appear in spec list by default.

Unarchive a Spec

Restore an archived spec:

sudocode spec update SPEC-050 --archived false

Expected output

✓ Updated spec SPEC-050
  archived: false

Update Tags

Replace all tags:

sudocode spec update SPEC-001 --tags "backend,api,security,oauth"

Expected output

✓ Updated spec SPEC-001
  tags: backend,api,security,oauth

The --tags option replaces ALL existing tags. To add or remove individual tags, edit the markdown file directly.

JSON Output

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

sudocode --json spec update SPEC-001 --priority 0

JSON output

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

Common Workflows

Promoting Spec Priority

List specs by priority

sudocode spec list --priority 2

Promote to high priority

sudocode spec update SPEC-001 --priority 1

Verify change

sudocode spec show SPEC-001

Reorganizing Spec Hierarchy

View current structure

sudocode spec show SPEC-001

Move child specs

sudocode spec update SPEC-003 --parent SPEC-001
sudocode spec update SPEC-004 --parent SPEC-001

Verify hierarchy

sudocode spec show SPEC-001

Deprecating Old Specs

Archive the spec

sudocode spec update SPEC-050 --archived true

Lower priority

sudocode spec update SPEC-050 --priority 4

Update title to indicate deprecation

sudocode spec update SPEC-050 --title "[DEPRECATED] Old Auth System"

Bulk Updates with Scripting

Update multiple specs programmatically:

# 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

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

Database - SQLite database is updated immediately
Markdown file - Frontmatter is updated with new values
JSONL - Changes are exported to specs.jsonl for version control
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:

---
id: SPEC-001
title: Old Title
---

Old content here

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

---
id: SPEC-001
title: Old Title
updated_at: 2025-10-29T18:30:00Z
---

New content

For complex content updates, edit the markdown file directly rather than using --description.

Common Questions

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:

for id in SPEC-001 SPEC-002 SPEC-003; do
  sudocode spec update "$id" --priority 1
done

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.

How do I add tags without replacing existing ones?

The --tags option replaces all tags. To add tags while keeping existing ones:

View current tags: sudocode spec show SPEC-001
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.

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.

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.

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.

Troubleshooting

Error: Spec not found

Cause: The spec ID doesn’t existSolution: Verify the ID:

sudocode spec list

Error: Invalid priority value

Cause: Priority must be 0-4Solution: Use a valid priority:

sudocode spec update SPEC-001 --priority 2

Error: Parent spec not found

Cause: The parent spec ID doesn’t existSolution: Verify the parent exists:

sudocode spec show SPEC-005

Update succeeded but markdown file unchanged

Cause: Only database-level fields were updated, or sync issueSolution: Run sync to ensure consistency:

sudocode sync

spec show

View spec details

spec create

Create new spec

spec list

List all specs

spec delete

Delete a spec

link

Manage relationships

sync

Synchronize data

Next Steps

View spec details

sudocode spec show SPEC-001

Update properties

sudocode spec update SPEC-001 --priority 0 --title "New Title"

Verify changes

sudocode spec show SPEC-001

Commit to git

git add .sudocode/specs.jsonl
git commit -m "Update spec priority and title"

Specs Concept Guide

Learn more about specs and their lifecycle

​Syntax

​Description

​Arguments

​Options

​Examples

​Update Priority

​Update Title

​Update Description

​Update Multiple Fields

​Set Parent Spec

​Remove Parent Spec

​Archive a Spec

​Unarchive a Spec

​Update Tags

​JSON Output

​Common Workflows

​Promoting Spec Priority

​Reorganizing Spec Hierarchy

​Deprecating Old Specs

​Bulk Updates with Scripting

​Update Behavior

​What Gets Updated

​What Doesn’t Change

​Content Updates

​Common Questions

​Troubleshooting

​Related Commands

spec show

spec create

spec list

spec delete

link

sync

​Next Steps

Specs Concept Guide

Syntax

Description

Arguments

Options

Examples

Update Priority

Update Title

Update Description

Update Multiple Fields

Set Parent Spec

Remove Parent Spec

Archive a Spec

Unarchive a Spec

Update Tags

JSON Output

Common Workflows

Promoting Spec Priority

Reorganizing Spec Hierarchy

Deprecating Old Specs

Bulk Updates with Scripting

Update Behavior

What Gets Updated

What Doesn’t Change

Content Updates

Common Questions

Troubleshooting

Related Commands

Next Steps