JSON Output Format

Complete reference for JSON output formats from all Tracer commands

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

Response Formats

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": []
  }
]

Get Ready Work

tracer ready --json

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": []
}

Create Issue

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": []
}

Update Status

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

Show Issue

tracer show bd-1 --json

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

List Issues

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

Get Blocked

tracer blocked --json

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
}

Get Stats

tracer stats --json

Parsing Examples

Using jq

jq is the recommended tool for parsing JSON output:

Extract Fields

# 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 for Ready Work

# 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 and Link Issues

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

Batch Processing

# 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

Status Monitoring

# 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