Skip to main content

​
Overview

The sd issues command provides dependency-aware issue tracking. This reference covers all available commands and options.

​
Initialization

​
sd issues init

Initialize issue tracking in a project directory. 
sd issues init                    # Auto-detect prefix from directory name
sd issues init --prefix api       # Custom prefix (issues: api-1, api-2, ...)
sd issues init --db ./custom.db   # Custom database location
Options:
OptionDescription
--prefixIssue ID prefix (default: directory name)
--dbDatabase file location
--forceOverwrite existing initialization

​
Creating Issues

​
sd issues create

Create a new issue. 
# Basic creation
sd issues create "Fix login bug"

# With options
sd issues create "Add authentication" \
  -p 0 \                      # Priority (0=critical, 4=lowest)
  -t feature \                # Type: bug, feature, task, chore
  -d "Implement JWT auth" \   # Description
  --assignee alice            # Assign to user

# Bulk create from file
sd issues create from-file tasks.md
Options:
OptionShortDescription
--priority-pPriority level (0-4)
--type-tIssue type
--description-dDetailed description
--assigneeUser to assign
--labels-lComma-separated labels
--dueDue date (YYYY-MM-DD)
--jsonOutput JSON

​
Viewing Issues

​
sd issues list

List issues with filtering. 
# List all issues
sd issues list

# Filter by status
sd issues list --status open
sd issues list --status in_progress
sd issues list --status closed

# Filter by priority
sd issues list --priority 0        # Critical only
sd issues list --priority 0,1      # Critical and high

# Filter by assignee
sd issues list --assignee alice
sd issues list --assignee ""       # Unassigned

# Combine filters
sd issues list --status open --priority 0,1 --assignee alice

# JSON output
sd issues list --json

​
sd issues show

Show detailed issue information. 
sd issues show sd-42

# Output:
# ┌─────────────────────────────────────────────────────┐
# │ sd-42: Add rate limiting middleware                  │
# ├─────────────────────────────────────────────────────┤
# │ Status:      in_progress                            │
# │ Priority:    1 (high)                               │
# │ Type:        feature                                │
# │ Assignee:    claude-agent                           │
# │ Created:     2025-01-15 10:30:00                    │
# │ Updated:     2025-01-15 14:30:00                    │
# ├─────────────────────────────────────────────────────┤
# │ Description:                                        │
# │ Create rate_limit.py in api/middleware/             │
# │ Limit to 100 req/min per API key.                   │
# ├─────────────────────────────────────────────────────┤
# │ Dependencies:                                       │
# │ └─ Blocked by: (none)                              │
# │ └─ Blocks: sd-45, sd-46                            │
# └─────────────────────────────────────────────────────┘
Search issues by text. 
sd issues search "auth"
sd issues search "bug" --status open
sd issues search "api" --type feature

​
sd issues ready

Show issues ready to work on (open + no blockers). 
sd issues ready

# With filters
sd issues ready --priority 0,1     # Only high priority ready work
sd issues ready --assignee alice   # Ready work for alice

# JSON output for agents
sd issues ready --json

​
sd issues blocked

Show blocked issues. 
sd issues blocked

# Output shows what's blocking each issue
sd issues blocked --verbose

​
sd issues stale

Show stale issues (no recent updates). 
sd issues stale                    # Default: 7 days
sd issues stale --days 14         # Custom threshold

​
Managing Dependencies

​
sd issues dep add

Add a dependency between issues. 
# sd-2 is blocked by sd-1
sd issues dep add sd-2 sd-1

# Multiple blockers
sd issues dep add sd-3 sd-1 sd-2

​
sd issues dep remove

Remove a dependency. 
sd issues dep remove sd-2 sd-1

​
sd issues dep tree

Visualize dependency tree. 
sd issues dep tree sd-42

# Output:
# sd-42: Add rate limiting
# ├─ sd-43: Create middleware base class
# │  └─ sd-44: Setup Redis connection
# └─ sd-45: Add rate limit tests
Options:
OptionDescription
--depthMaximum tree depth
--formatOutput format: tree, json, mermaid

​
Updating Issues

​
sd issues update

Update issue fields. 
# Update status
sd issues update sd-42 --status in_progress

# Update priority
sd issues update sd-42 --priority 0

# Update assignee
sd issues update sd-42 --assignee bob

# Multiple updates
sd issues update sd-42 --status in_progress --priority 0 --assignee bob

# JSON output
sd issues update sd-42 --status closed --json
Options:
OptionDescription
--statusStatus: open, in_progress, blocked, closed
--priorityPriority: 0-4
--assigneeAssignee username
--titleNew title
--descriptionNew description
--dueDue date

​
sd issues label

Manage issue labels. 
# Add labels
sd issues label add sd-42 bug urgent

# Remove labels
sd issues label remove sd-42 urgent

# List labels on issue
sd issues label list sd-42

​
sd issues comment

Add comments to issues. 
sd issues comment sd-42 "Started implementation"
sd issues comment sd-42 "Blocked waiting for API design"

# View comments
sd issues show sd-42 --comments

​
Closing Issues

​
sd issues close

Close one or more issues. 
sd issues close sd-42
sd issues close sd-42 --reason "Implemented in PR #38"
sd issues close sd-42 sd-43 sd-44  # Multiple issues

​
sd issues reopen

Reopen a closed issue. 
sd issues reopen sd-42
sd issues reopen sd-42 --reason "Found additional edge case"

​
Synchronization

​
sd issues sync

Synchronize database with Git. 
sd issues sync                    # Full sync cycle
sd issues sync --status           # Show sync status
sd issues sync --flush-only       # Export to JSONL only
sd issues sync --import-only      # Import from JSONL only
sd issues sync --merge            # Merge sync branch to main

​
sd issues daemon

Manage the sync daemon. 
sd issues daemon --status         # Check daemon status
sd issues daemon --health         # Detailed health check
sd issues daemon --start          # Start daemon
sd issues daemon --stop           # Stop daemon

# Start with auto-sync
sd issues daemon --start --auto-commit --auto-push

​
Database Management

​
sd issues doctor

Check installation health. 
sd issues doctor

# Output:
# ✓ Database: Connected
# ✓ Schema: Current (v3)
# ✓ Git: Repository detected
# ✓ Sync branch: issues-sync exists
# ✓ Daemon: Running

​
sd issues validate

Run comprehensive database checks. 
sd issues validate

# Checks:
# - Schema integrity
# - Foreign key constraints
# - Orphaned records
# - Circular dependencies

​
sd issues migrate

Migrate database to current schema version. 
sd issues migrate
sd issues migrate --dry-run       # Preview changes

​
sd issues cleanup

Clean up old data. 
sd issues cleanup                 # Default: closed > 30 days
sd issues cleanup --days 14       # Custom threshold
sd issues cleanup --dry-run       # Preview what would be deleted

​
sd issues compact

Compact database (remove tombstones). 
sd issues compact

​
Import/Export

​
sd issues export

Export issues to file. 
sd issues export -o issues.jsonl
sd issues export -o issues.json --format json
sd issues export -o issues.csv --format csv

​
sd issues import

Import issues from file. 
sd issues import -i issues.jsonl
sd issues import -i legacy.csv --format csv

​
Configuration

​
sd issues config

Manage configuration. 
# Set value
sd issues config set jira.url "https://company.atlassian.net"

# Get value
sd issues config get jira.url

# List all config
sd issues config list

# Remove value
sd issues config unset jira.url
Common settings:
KeyDescription
sync-branchGit branch for issue data
jira.urlJira instance URL
jira.projectJira project key
status.customCustom status values

​
Advanced

​
sd issues prime

Get AI-optimized workflow context. 
sd issues prime

# Output includes:
# - Current task state
# - Ready work
# - Blocked items
# - Recent activity

​
sd issues view

Access the issue viewer for advanced analytics. 
# Get priority recommendations
sd issues view --robot-priority

# Get graph insights (PageRank, betweenness, critical path)
sd issues view --robot-insights

# Get parallel execution plan
sd issues view --robot-plan

# Track drift from baseline
sd issues view --save-baseline "Sprint start"
sd issues view --check-drift

​
sd issues hooks

Manage Git hooks. 
sd issues hooks install           # Install recommended hooks
sd issues hooks uninstall         # Remove hooks
sd issues hooks list              # List installed hooks

​
Global Options

Available on all commands:
OptionDescription
--db PATHDatabase file path
--jsonJSON output format
--quietSuppress non-essential output
--verboseDetailed output
--helpShow help

​
Environment Variables

VariableDescription
STARDUST_ISSUES_DBDefault database path
STARDUST_ISSUES_PREFIXDefault issue prefix
STARDUST_ISSUES_SYNC_BRANCHSync branch name

​
Examples

​
Daily Workflow

# Start of day: see what's ready
sd issues ready

# Claim a task
sd issues update sd-42 --status in_progress

# Work on it...

# Add progress note
sd issues comment sd-42 "Completed initial implementation"

# Done
sd issues close sd-42 --reason "Implemented and tested"

# What's next?
sd issues ready

​
Sprint Planning

# Create sprint tasks
sd issues create "User story: Login flow" -t feature -p 1
sd issues create "User story: Dashboard" -t feature -p 1
sd issues create "Bug: Session timeout" -t bug -p 0

# Set dependencies
sd issues dep add sd-45 sd-44  # Dashboard depends on login

# Check plan
sd issues dep tree sd-45

​
Agent Integration

# Get ready work as JSON
sd issues ready --json | jq '.tasks[0]'

# Claim task
sd issues update sd-42 --status in_progress --json

# Complete
sd issues close sd-42 --reason "Completed" --json

​
Learn More

CLI Overview

Other CLI commands

CLI Commands

Complete command reference