sudocode issue delete

Syntax

sudocode issue delete <issue-id> [<issue-id>...] [options]

Description

The issue delete command removes issues from your project. By default, it performs a soft delete (closes the issue). Use --hard for permanent deletion.

Soft Delete (Default)

Sets issue status to closed
Records closed_at timestamp
Issue remains in database and JSONL
Can be reopened if needed

Hard Delete (with —hard flag)

Permanently removes from database
Updates JSONL to remove the issue
Cannot be undone (except via git restore)

Hard deletion is permanent and cannot be undone (except by restoring from git history). Consider closing or archiving issues instead if you might need to reference them later.

Arguments

issue-id

string

required

One or more issue IDs to deleteExample: ISSUE-001 or ISSUE-001 ISSUE-002 ISSUE-003You can delete multiple issues in a single command by providing multiple IDs.

Options

--hard

boolean

Permanently delete from database (vs soft delete)Example: --hardWithout this flag, the command performs a soft delete (closes the issue).

Examples

Soft Delete (Default)

Close the issue (default behavior):

sudocode issue delete ISSUE-050

Expected output

✓ Closed issue ISSUE-050

This sets the status to closed but keeps the issue in the database.

Hard Delete

Permanently remove an issue:

sudocode issue delete ISSUE-050 --hard

Expected output

✓ Permanently deleted issue ISSUE-050

Delete Multiple Issues

Soft delete several issues:

sudocode issue delete ISSUE-050 ISSUE-051 ISSUE-052

Expected output

✓ Closed issue ISSUE-050
✓ Closed issue ISSUE-051
✓ Closed issue ISSUE-052

Hard Delete Multiple Issues

Permanently remove several issues:

sudocode issue delete ISSUE-050 ISSUE-051 ISSUE-052 --hard

Expected output

✓ Permanently deleted issue ISSUE-050
✓ Permanently deleted issue ISSUE-051
✓ Permanently deleted issue ISSUE-052

Delete Non-Existent Issue

Attempt to delete an issue that doesn’t exist:

sudocode issue delete ISSUE-999

Expected output

✗ Issue not found: ISSUE-999

JSON Output

Get machine-readable output:

sudocode --json issue delete ISSUE-050 --hard

JSON output

[
  {
    "id": "ISSUE-050",
    "success": true,
    "action": "hard_delete"
  }
]

For soft delete:

[
  {
    "id": "ISSUE-050",
    "success": true,
    "action": "soft_delete",
    "status": "closed"
  }
]

Soft Delete vs Hard Delete

Soft Delete (Default)

Closes the issue

Status set to closed
Remains in database
Can be reopened
Preserves relationships
Safer option

Hard Delete (--hard)

Permanent removal

Removed from database
Removed from JSONL
Cannot be undone
Orphans relationships
Use with caution

When to use each:

Soft delete: Most cases - completed work, decided not to do, obsolete
Hard delete: Duplicates, test issues, genuinely wrong content

What Gets Deleted (Hard Delete)

When you hard delete an issue:

Database record removed

The issue is deleted from the SQLite issues table

JSONL updated

The deletion is recorded in issues.jsonl

Tags cleaned up

Tags associated with the issue are removed

What Doesn’t Get Deleted (Hard Delete)

The following are NOT automatically deleted with hard delete:

Relationships

Relationships to/from the deleted issue remain in the database as orphaned entries.Impact: Specs or other issues that reference the deleted issue will show broken relationships.Solution: Manually remove relationships before deleting.

Feedback provided by this issue

Feedback this issue provided to specs is not automatically deleted.Impact: Feedback entries remain but point to a non-existent issue.Solution: Review and dismiss feedback before deleting:

sudocode issue show ISSUE-050  # Check for feedback

Child issues

If the deleted issue is a parent, child issues are not deleted. They become orphaned with invalid parent_id references.Impact: Child issues lose their parent relationship.Solution: Update or delete child issues first:

sudocode issue show ISSUE-050  # Check for children

Blocking relationships

Issues blocked by the deleted issue remain blocked with invalid blocker reference.Impact: Blocked issues stay blocked but blocker doesn’t exist.Solution: Remove blocking relationships first.

Safe Deletion Workflow

Follow these steps to safely hard delete an issue:

Review issue details

sudocode issue show ISSUE-050

Check for:

Outgoing relationships (what it implements/blocks)
Incoming relationships (what blocks it)
Parent/child relationships
Feedback provided

Remove relationships

Manually clean up if needed (no unlink command currently exists)

Update dependent issues

If this issue blocks others, unblock them:

sudocode issue show ISSUE-051  # Check what was blocked

Hard delete

sudocode issue delete ISSUE-050 --hard

Verify deletion

sudocode issue list
sudocode issue show ISSUE-050  # Should error

Alternative: Close or Archive

Consider these alternatives to deletion:

Close (Soft Delete)

sudocode issue close ISSUE-050
# or
sudocode issue delete ISSUE-050  # Without --hard

Benefits:

Issue preserved for reference
Can be reopened if needed
Relationships stay intact
Shows in closed issues list

Comparison

Action	Visible	Reopenable	Relationships	Best For
Close	Yes (when filtered)	Yes	Intact	Completed work
Archive	No (hidden)	Yes	Intact	Abandoned work
Hard Delete	No (gone)	No (must restore from git)	Orphaned	Duplicates, mistakes

Common Workflows

Cleaning Up Duplicates

Find duplicates

sudocode issue list --grep "duplicate"

Review each issue

sudocode issue show ISSUE-050

Hard delete duplicates

sudocode issue delete ISSUE-050 ISSUE-051 --hard

Bulk Delete with Scripting

Delete all closed issues older than 90 days:

# Soft delete (close) old issues
sudocode --json issue list --status closed | \
  jq -r '.[] | select(.closed_at < (now - 90*24*60*60 | strftime("%Y-%m-%dT%H:%M:%SZ"))) | .id' | \
  xargs sudocode issue delete --hard

Be very careful with bulk deletions. Always review issues before deleting.

Recovering from Accidental Deletion

If you accidentally hard delete an issue:

Check git history

git log .sudocode/issues.jsonl

Restore from git

git checkout HEAD~1 .sudocode/issues.jsonl
sudocode sync  # Re-import from JSONL

Or restore from backup

If you have backups of .sudocode/, restore the database and JSONL files

This is why sudocode uses git-tracked JSONL files as the source of truth. You can always recover from git history.

Common Questions

What's the difference between delete and close?

Without --hard, issue delete is identical to issue close - it soft deletes by closing the issue.

sudocode issue delete ISSUE-001 = sudocode issue close ISSUE-001
sudocode issue delete ISSUE-001 --hard = permanent deletion

Use issue close for clarity when you intend to close (not delete).

Is there a confirmation prompt?

No, the command executes immediately without confirmation, even for hard deletes.For safety, create a shell alias with confirmation:

alias issue-delete='read -p "Delete issue? (y/n) " -n 1 -r && echo && [[ $REPLY =~ ^[Yy]$ ]] && sudocode issue delete'

Can I undo a deletion?

Soft delete: Yes, reopen the issue: sudocode issue update ISSUE-001 --status open
Hard delete: Not directly, but recover from git: git checkout HEAD~1 .sudocode/issues.jsonl

What happens to issues that depend on a deleted issue?

They become orphaned with broken relationships:

Issues implementing a deleted spec show broken implements link
Issues blocked by a deleted issue show broken blocks link

Best practice: Clean up relationships before hard deleting.

Should I delete or archive completed work?

Close completed work (or soft delete):

sudocode issue close ISSUE-001

Archive abandoned work:

sudocode issue update ISSUE-001 --archived true

Hard delete only:

Duplicate issues
Test issues
Genuinely incorrect content

Can I delete multiple issues by pattern?

Yes, using scripting:

# Delete all issues matching "test" in title (soft delete)
sudocode --json issue list --grep "test" | jq -r '.[] | .id' | xargs sudocode issue delete

# Hard delete (be very careful!)
sudocode --json issue list --grep "test" | jq -r '.[] | .id' | xargs sudocode issue delete --hard

Always review the list first!

Troubleshooting

Error: Issue not found

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

sudocode issue list

Error: Failed to delete issue

Cause: Database or file system errorSolution:

Check database isn’t locked by another process
Verify permissions on .sudocode/ directory
Try syncing first: sudocode sync

Issue deleted but still appears in list

Cause: Cache or sync issueSolution: Run sync to ensure consistency:

sudocode sync

Hard delete failed but database updated

Cause: JSONL export failedSolution: Run export manually:

sudocode sync

issue list

List all issues

issue show

View issue details

issue close

Close issues (soft delete)

issue update

Update issue (archive)

sync

Synchronize data

Next Steps

Review the issue

sudocode issue show ISSUE-050

Consider alternatives

Close: sudocode issue close ISSUE-050Archive: sudocode issue update ISSUE-050 --archived true

If hard deleting, clean up

Remove relationships and update dependencies

Delete

sudocode issue delete ISSUE-050 --hard

Commit changes

git add .sudocode/issues.jsonl
git commit -m "Delete obsolete issue"

Issues Concept Guide

Learn more about issues and their lifecycle

CLI Reference

Spec Commands

Issue Commands

Relationship Commands

Feedback Commands

Query & Sync Commands

​Syntax

​Description

​Soft Delete (Default)

​Hard Delete (with —hard flag)

​Arguments

​Options

​Examples

​Soft Delete (Default)

​Hard Delete

​Delete Multiple Issues

​Hard Delete Multiple Issues

​Delete Non-Existent Issue

​JSON Output

​Soft Delete vs Hard Delete

Soft Delete (Default)

Hard Delete (--hard)

​What Gets Deleted (Hard Delete)

​What Doesn’t Get Deleted (Hard Delete)

​Safe Deletion Workflow

​Alternative: Close or Archive

​Close (Soft Delete)

​Archive

​Comparison

​Common Workflows

​Cleaning Up Duplicates

​Bulk Delete with Scripting

​Recovering from Accidental Deletion

​Common Questions

​Troubleshooting

​Related Commands

issue list

issue show

issue close

issue update

sync

​Next Steps

Issues Concept Guide

Syntax

Description

Soft Delete (Default)

Hard Delete (with —hard flag)

Arguments

Options

Examples

Soft Delete (Default)

Hard Delete

Delete Multiple Issues

Hard Delete Multiple Issues

Delete Non-Existent Issue

JSON Output

Soft Delete vs Hard Delete

What Gets Deleted (Hard Delete)

What Doesn’t Get Deleted (Hard Delete)

Safe Deletion Workflow

Alternative: Close or Archive

Close (Soft Delete)

Archive

Comparison

Common Workflows

Cleaning Up Duplicates

Bulk Delete with Scripting

Recovering from Accidental Deletion

Common Questions

Troubleshooting

Related Commands

Next Steps