Skip to content

JSON Color Output

Gira supports optional syntax highlighting for JSON output across all commands. By default, JSON output is plain text for better compatibility with AI agents and programmatic usage.

Default Behavior

By default, all JSON output is plain text without any ANSI color codes:

gira ticket list --format json
gira describe
gira epic show EPIC-001 --format json

Enabling Color

Users can enable syntax highlighting for JSON output in two ways:

1. Using the --color flag

gira ticket list --format json --color
gira describe --color
gira epic show EPIC-001 --format json --color

2. Using the GIRA_COLOR environment variable

export GIRA_COLOR=1
gira ticket list --format json  # Now with colors

# Or for a single command:
GIRA_COLOR=1 gira describe

Valid values for GIRA_COLOR are: 1, true, yes (case-insensitive)

Disabling Color Explicitly

While color is off by default, you can explicitly disable it:

gira ticket list --format json --no-color

This is useful if you have GIRA_COLOR=1 set but want plain output for a specific command.

AI Agent Compatibility

The default no-color behavior ensures that AI agents and scripts can reliably parse JSON output without dealing with ANSI escape codes. This design choice prioritizes machine readability while still allowing human users to opt into a more visually appealing output.

Implementation for Commands

Commands that support JSON output can add color support by:

  1. Importing the helper functions: 

    from gira.utils.output import add_color_option, add_no_color_option, get_color_kwargs

  2. Adding color options to the command: 

    def list_items(
    # ... other options ...
    color: bool = add_color_option(),
    no_color: bool = add_no_color_option(),
):

  3. Passing color kwargs to print_output: 

    color_kwargs = get_color_kwargs(color, no_color)
print_output(data, OutputFormat.JSON, **color_kwargs)

Examples

Plain JSON (default)

$ gira ticket list --format json --status todo
[
  {
    "id": "GCM-123",
    "title": "Fix login bug",
    "status": "todo"
  }
]

Colored JSON

$ gira ticket list --format json --status todo --color
# Output will include syntax highlighting with colors for keys, strings, etc.