JSON Output

IssueDB provides comprehensive JSON output support for all commands, making it easy to integrate with scripts, automation tools, and other programs.

Enabling JSON Output

Add the --json flag before the command:

issuedb-cli --json COMMAND [ARGS]

Examples:

issuedb-cli --json list
issuedb-cli --json get 1
issuedb-cli --json summary
issuedb-cli --json create -t "New issue"

Output Formats

Issues

Single issue:

{
  "id": 1,
  "title": "Fix login bug",
  "description": "Users cannot log in with special characters",
  "priority": "high",
  "status": "open",
  "created_at": "2025-01-15T10:30:00.123456",
  "updated_at": "2025-01-15T10:30:00.123456"
}

Issue list:

[
  {
    "id": 1,
    "title": "Fix login bug",
    "priority": "high",
    "status": "open",
    ...
  },
  {
    "id": 2,
    "title": "Add dark mode",
    "priority": "medium",
    "status": "in-progress",
    ...
  }
]

Comments

Single comment:

{
  "id": 1,
  "issue_id": 1,
  "text": "Started working on this",
  "created_at": "2025-01-15T11:00:00.123456"
}

Comment list:

[
  {
    "id": 1,
    "issue_id": 1,
    "text": "Started working on this",
    "created_at": "2025-01-15T11:00:00.123456"
  },
  {
    "id": 2,
    "issue_id": 1,
    "text": "Found the root cause",
    "created_at": "2025-01-15T12:30:00.123456"
  }
]

Summary

{
  "total_issues": 10,
  "by_status": {
    "open": {"count": 5, "percentage": 50.0},
    "in_progress": {"count": 3, "percentage": 30.0},
    "closed": {"count": 2, "percentage": 20.0}
  },
  "by_priority": {
    "critical": {"count": 1, "percentage": 10.0},
    "high": {"count": 3, "percentage": 30.0},
    "medium": {"count": 4, "percentage": 40.0},
    "low": {"count": 2, "percentage": 20.0}
  }
}

Report

{
  "group_by": "status",
  "total_issues": 10,
  "groups": {
    "open": {
      "count": 5,
      "issues": [...]
    },
    "in_progress": {
      "count": 3,
      "issues": [...]
    },
    "closed": {
      "count": 2,
      "issues": [...]
    }
  }
}

Audit Logs

[
  {
    "id": 1,
    "issue_id": 1,
    "action": "CREATE",
    "field_name": null,
    "old_value": null,
    "new_value": "{...}",
    "timestamp": "2025-01-15T10:30:00"
  },
  {
    "id": 2,
    "issue_id": 1,
    "action": "UPDATE",
    "field_name": "status",
    "old_value": "open",
    "new_value": "in-progress",
    "timestamp": "2025-01-15T11:00:00"
  }
]

Bulk Operation Results

{
  "message": "Created 3 issue(s)",
  "count": 3,
  "issues": [
    {"id": 1, "title": "Issue 1", ...},
    {"id": 2, "title": "Issue 2", ...},
    {"id": 3, "title": "Issue 3", ...}
  ]
}

Database Info

{
  "database_path": "/path/to/issuedb.sqlite",
  "total_issues": 25,
  "total_audit_logs": 150,
  "database_size_bytes": 45056
}

Working with JSON

Using jq

jq is a powerful command-line JSON processor:

# Get issue titles
issuedb-cli --json list | jq '.[].title'

# Filter by status
issuedb-cli --json list | jq '[.[] | select(.status == "open")]'

# Get count of high priority issues
issuedb-cli --json list | jq '[.[] | select(.priority == "high")] | length'

# Extract IDs
issuedb-cli --json list -s open | jq '[.[].id]'

Using Python

import json
import subprocess

# Run command
result = subprocess.run(
    ['issuedb-cli', '--json', 'list', '-s', 'open'],
    capture_output=True,
    text=True
)

# Parse JSON
issues = json.loads(result.stdout)

# Process
for issue in issues:
    print(f"#{issue['id']}: {issue['title']}")

Using Node.js

const { execSync } = require('child_process');

// Run command
const output = execSync('issuedb-cli --json list').toString();

// Parse JSON
const issues = JSON.parse(output);

// Process
issues.forEach(issue => {
    console.log(`#${issue.id}: ${issue.title}`);
});

Using Bash

# Read into variable
ISSUES=$(issuedb-cli --json list)

# Use with other tools
echo "$ISSUES" | python -c "import sys, json; print(len(json.load(sys.stdin)))"

# Loop through (requires jq)
issuedb-cli --json list | jq -c '.[]' | while read -r issue; do
    ID=$(echo "$issue" | jq -r '.id')
    TITLE=$(echo "$issue" | jq -r '.title')
    echo "Processing issue #$ID: $TITLE"
done

Error Handling

When an error occurs:

• Exit code is non-zero (1)

• Error message goes to stderr

• stdout is empty or contains partial output

# Check for errors
if OUTPUT=$(issuedb-cli --json get 999 2>&1); then
    echo "Success: $OUTPUT"
else
    echo "Error: $OUTPUT"
fi

Best Practices

1. Always check exit codes: Don’t assume success

2. Redirect stderr: Capture errors separately from JSON output

3. Validate JSON: Handle malformed JSON gracefully

4. Use proper parsing: Don’t use string manipulation for JSON

5. Handle empty results: Lists may be empty arrays []

DateTime Format

All timestamps are in ISO 8601 format:

YYYY-MM-DDTHH:MM:SS.microseconds

Example: 2025-01-15T10:30:00.123456

This format is:

• Sortable as strings

• Parseable by most programming languages

• Unambiguous (always local time)