Overview
All Tracer commands support --json output for programmatic parsing. This makes it easy to integrate Tracer into agent workflows and scripts.
Always use --json when parsing Tracer output in scripts to ensure consistent, machine-readable responses.
Enable JSON Output
Add --json to any command:
tracer ready --json
tracer create "Task" --json
tracer stats --json
Ready Work
Returns an array of issues that are unblocked and ready to work on:
[
{
"id": "bd-1",
"title": "Implement feature X",
"description": "Detailed description",
"design": "",
"acceptance_criteria": "",
"notes": "",
"status": "open",
"priority": 1,
"issue_type": "feature",
"assignee": "",
"estimated_minutes": null,
"created_at": "2025-10-15T10:00:00Z",
"updated_at": "2025-10-15T10:00:00Z",
"closed_at": null,
"external_ref": null,
"dependencies": []
}
]
Issue Creation
Returns the newly created issue:
{
"id": "bd-42",
"title": "New issue",
"description": "",
"design": "",
"acceptance_criteria": "",
"notes": "",
"status": "open",
"priority": 2,
"issue_type": "task",
"assignee": "",
"estimated_minutes": null,
"created_at": "2025-10-15T10:30:00Z",
"updated_at": "2025-10-15T10:30:00Z",
"closed_at": null,
"external_ref": null,
"dependencies": []
}
tracer create "Fix bug" -t bug -p 0 --json
Issue Update
Returns the updated issue:
{
"id": "bd-1",
"title": "Updated title",
"description": "Updated description",
"design": "",
"acceptance_criteria": "",
"notes": "",
"status": "in_progress",
"priority": 1,
"issue_type": "feature",
"assignee": "agent-1",
"estimated_minutes": null,
"created_at": "2025-10-15T10:00:00Z",
"updated_at": "2025-10-15T11:00:00Z",
"closed_at": null,
"external_ref": null,
"dependencies": []
}
tracer update bd-1 --status in_progress --json
Issue Details
Returns a single issue with all details:
{
"id": "bd-1",
"title": "Implement feature X",
"description": "Full description here",
"design": "Design notes",
"acceptance_criteria": "Criteria here",
"notes": "Additional notes",
"status": "in_progress",
"priority": 1,
"issue_type": "feature",
"assignee": "agent-1",
"estimated_minutes": 120,
"created_at": "2025-10-15T10:00:00Z",
"updated_at": "2025-10-15T11:00:00Z",
"closed_at": null,
"external_ref": "JIRA-123",
"dependencies": [
{
"issue_id": "bd-2",
"depends_on_id": "bd-1",
"dep_type": "blocks",
"created_at": "2025-10-15T10:05:00Z",
"created_by": "agent-1"
}
]
}
Issue List
Returns an array of issues matching the filter:
[
{
"id": "bd-1",
"title": "First issue",
"status": "open",
"priority": 1,
"issue_type": "feature",
"created_at": "2025-10-15T10:00:00Z",
"updated_at": "2025-10-15T10:00:00Z"
},
{
"id": "bd-2",
"title": "Second issue",
"status": "in_progress",
"priority": 0,
"issue_type": "bug",
"created_at": "2025-10-15T11:00:00Z",
"updated_at": "2025-10-15T11:30:00Z"
}
]
tracer list --status open --json
Blocked Issues
Returns blocked issues with the IDs of blocking issues:
[
{
"issue": {
"id": "bd-2",
"title": "Blocked task",
"status": "open",
"priority": 1,
"issue_type": "task",
"created_at": "2025-10-15T10:00:00Z",
"updated_at": "2025-10-15T10:00:00Z"
},
"blocked_by": ["bd-1", "bd-3"]
}
]
Statistics
Returns aggregate statistics about all issues:
{
"total_issues": 12,
"open_issues": 8,
"in_progress_issues": 1,
"blocked_issues": 0,
"closed_issues": 3,
"ready_issues": 7,
"average_lead_time_hours": 2.3
}
Parsing Examples
Using jq
jq is the recommended tool for parsing JSON output:
# Get issue ID
tracer ready --json | jq -r '.[0].id'
# Get issue title
tracer show bd-1 --json | jq -r '.title'
# Get priority
tracer show bd-1 --json | jq -r '.priority'
Common Patterns
# Check if there's any ready work
WORK=$(tracer ready --json)
if [ "$(echo $WORK | jq length)" -gt 0 ]; then
echo "Found ready work"
else
echo "No ready work"
fi
# Create issue and link it
NEW_ID=$(tracer create "Fix bug" -t bug --json | jq -r '.id')
tracer dep add $NEW_ID bd-5 --type discovered-from
echo "Created and linked: $NEW_ID"
# Process all ready work
tracer ready --json | jq -r '.[].id' | while read ISSUE_ID; do
echo "Processing: $ISSUE_ID"
tracer update $ISSUE_ID --status in_progress
# Do work...
tracer close $ISSUE_ID --reason "Completed"
done
# Monitor progress
while true; do
STATS=$(tracer stats --json)
READY=$(echo $STATS | jq -r '.ready_issues')
IN_PROGRESS=$(echo $STATS | jq -r '.in_progress_issues')
echo "Ready: $READY, In Progress: $IN_PROGRESS"
sleep 60
done
Field Reference
Issue Fields
| Field | Type | Description |
|---|
id | string | Unique issue identifier (e.g., “bd-1”) |
title | string | Issue title |
description | string | Detailed description |
design | string | Design notes |
acceptance_criteria | string | Acceptance criteria |
notes | string | Additional notes |
status | string | One of: open, in_progress, blocked, closed |
priority | number | 0 (highest) to 4 (lowest) |
issue_type | string | One of: task, bug, feature, epic, spike |
assignee | string | Assigned person or agent |
estimated_minutes | number | null | Estimated time in minutes |
created_at | string | ISO 8601 timestamp |
updated_at | string | ISO 8601 timestamp |
closed_at | string | null | ISO 8601 timestamp |
external_ref | string | null | External system reference |
dependencies | array | Array of dependency objects |
Dependency Fields
| Field | Type | Description |
|---|
issue_id | string | The dependent issue ID |
depends_on_id | string | The issue it depends on |
dep_type | string | One of: blocks, parent-child, discovered-from, related |
created_at | string | ISO 8601 timestamp |
created_by | string | Who created this dependency |
Next Steps
Best Practices
Learn proven patterns for agent integration
CLI Reference
Complete command reference
