Skip to main content

​
Basic Listing

List all issues in your tracker: 
tracer list
This shows all issues with their status, priority, and type.

​
Filtering by Status

Filter issues by their current status: 
tracer list --status open

​
Finding Ready Work

The ready command is a special filtered view showing only issues that:
  • Have status open
  • Have no blocking dependencies
  • Are available to start immediately
tracer ready
This is more useful than tracer list --status open because it excludes blocked issues.
Use tracer ready at the start of every session to find what you can work on right now.

​
Filtering by Priority

Find issues by priority level (0 = highest, 4 = lowest): 
# Critical issues only
tracer list --priority 0

# High priority
tracer list --priority 1

# Filter ready work by priority
tracer ready --priority 0

​
Filtering by Issue Type

Filter by the kind of work: 
tracer list --issue-type feature
Combine with status filters: 
# All open bugs
tracer list --status open --issue-type bug

​
Filtering by Assignee

Find work assigned to specific people or agents: 
# Issues assigned to specific agent
tracer list --assignee agent-1

# Ready work for specific assignee
tracer ready --assignee agent-2
Assignees are automatically set when you update an issue to in_progress. You can also set them explicitly:
tracer update bd-1 --assignee "my-agent"

​
Filtering by Labels

Filter issues that have specific labels: 
# Issues with "frontend" label
tracer list --labels frontend

# Multiple labels (AND condition)
tracer list --labels frontend,urgent
Add labels to issues: 
# When creating
tracer create "Update UI" -t feature --labels frontend,ui

# You can also add labels after creation via the API

​
Limiting Results

Limit how many results are returned: 
# Show top 5 ready issues
tracer ready --limit 5

# Show 10 most recent issues
tracer list --limit 10
Combine --limit with priority filters to get the most important work:
tracer ready --priority 0 --limit 3

​
Combining Filters

All filters can be combined for powerful queries: 
# Open bugs with priority 0 or 1
tracer list --status open --issue-type bug --priority 0
tracer list --status open --issue-type bug --priority 1

​
JSON Output

Every query command supports --json for programmatic access: 
# Get ready work as JSON
tracer ready --json

# Filter and parse with jq
tracer list --status open --json | jq '.[].id'

# Get issue count
tracer list --status open --json | jq 'length'

​
Example JSON Response

[
  {
    "id": "bd-1",
    "title": "Implement user authentication",
    "description": "",
    "status": "open",
    "priority": 1,
    "issue_type": "feature",
    "assignee": "",
    "created_at": "2025-10-15T10:00:00Z",
    "updated_at": "2025-10-15T10:00:00Z",
    "closed_at": null
  },
  {
    "id": "bd-2",
    "title": "Fix validation bug",
    "description": "",
    "status": "open",
    "priority": 0,
    "issue_type": "bug",
    "assignee": "agent-1",
    "created_at": "2025-10-15T11:00:00Z",
    "updated_at": "2025-10-15T11:00:00Z",
    "closed_at": null
  }
]

​
Sorting Results

Results are automatically sorted by:
  1. Priority (0 first, 4 last)
  2. Creation date (newest first)
This ensures the most important and recent work appears first.

​
Finding Blocked Issues

See all issues that cannot proceed: 
tracer blocked
This shows each blocked issue along with what’s blocking it: 
⚠ Blocked: 2 issue(s)

bd-12 Implement login endpoint [P1, task]
  Status: open
  ⚠ Blocked by: bd-11

bd-15 Add OAuth support [P2, feature]
  Status: open
  ⚠ Blocked by: bd-12, bd-13
Use tracer blocked --json to get blocked issues programmatically with their blocking dependencies.

​
Viewing Statistics

Get aggregate stats across all issues: 
tracer stats
Shows:
  • Total issue counts by status
  • Number of ready issues
  • Average lead time
# Get stats as JSON for dashboards
tracer stats --json

​
Common Query Patterns

# Critical bugs and high priority features
tracer list --priority 0 --issue-type bug
tracer list --priority 1 --issue-type feature

# All open work
tracer list --status open

# Ready to start this sprint
tracer ready --limit 20

# In progress work
tracer list --status in_progress

# What agent-1 is working on
tracer list --assignee agent-1 --status in_progress

# What's available for agent-2
tracer ready --assignee agent-2

# Any blocked issues?
tracer blocked

# Any dependency cycles?
tracer dep cycles

# Overall statistics
tracer stats

​
Programmatic Parsing Examples

Using Tracer with shell scripting and jq: 
# Find the highest priority ready work
ISSUE_ID=$(tracer ready --limit 1 --json | jq -r '.[0].id')
echo "Working on: $ISSUE_ID"

​
Best Practices

Use tracer ready instead of tracer list --status open - it automatically filters out blocked issues.
Combine --limit with priority filters to focus on the most important work:
tracer ready --priority 0 --limit 5
Use JSON output for automation - parse with jq or other tools for scripting and integration.
Filters are combined with AND logic - all conditions must match. Be specific but not too restrictive.

Build docs developers (and LLMs) love

Get started for freeTalk to us