CLI Reference¶
Complete reference for all Gira commands and options.
Table of Contents¶
Epic Management¶
-
gira epic create- Create a new epic. -
gira epic delete- Delete or archive an epic. -
gira epic list- List epics with optional filters. -
gira epic show- Show details of a specific epic. -
gira epic update- Update an existing epic.
Global Options¶
These options can be used with any command:
--help- Show help message and exit--version- Show version number and exit
Commands¶
gira epic create¶
Create a new epic.
Arguments:
title- Epic title (required unless using --stdin) (optional)- Type: string
- Min length: 3
- Max length: 200
Options:
-d, --description- Epic description (use '-' for stdin, 'editor' to open editor)- Default:
-
Max length: 5000
-
--description-file- Read description from a file - Default:
-
Examples: ticket-description.md, docs/feature-spec.md, /tmp/bug-report.txt
-
-o, --owner- Epic owner email (defaults to git user email) - Default:
- Pattern:
^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$ -
Examples: user@example.com, john.doe@company.org
-
-t, --target-date- Target completion date (YYYY-MM-DD) - Default:
- Pattern:
^\d{4}-\d{2}-\d{2}$ -
Examples: 2025-01-20, 2025-12-31
-
--output- Output format: text, json - Choices: text, json, table, csv
- Default: text
-
Examples: json, table
-
-q, --quiet- Only output epic ID -
Type: boolean
-
--stdin- Read JSON array of epics from stdin for bulk creation -
Type: boolean
-
--jsonl- Read JSONL (JSON Lines) format for streaming large datasets - Type: boolean
Examples:
gira epic list¶
List epics with optional filters.
Options:
-q, --query- Query expression (e.g., 'status:active AND owner:me()')- Default:
-
Examples: ..py$, ^test_., (bug|fix):
-
-s, --status- Filter by status (draft, active, completed) - Choices: backlog, todo, in_progress, review, done
- Default:
-
Examples: backlog, todo, in_progress
-
-o, --owner- Filter by owner email - Default:
- Pattern:
^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$ -
Examples: user@example.com, john.doe@company.org
-
--search- Search text in epic fields (default: title and description) -
Default:
-
--search-in- Specify fields to search: title, description, id, status, owner, all (can be used multiple times) - Type: array
-
Default:
-
--exact-match- Perform exact string match instead of fuzzy match -
Type: boolean
-
--regex-search- Treat search pattern as a regular expression - Type: boolean
-
Examples: ..py$, ^test_., (bug|fix):
-
--case-sensitive-search- Make search case-sensitive -
Type: boolean
-
-f, --format- Output format - Type: enum
- Choices: TABLE, JSON, YAML, CSV, TSV, TEXT, IDS
- Default: table
-
Examples: json, table
-
--counts- Show summary counts -
Type: boolean
-
--fields- Comma-separated list of fields to include in JSON output (e.g., 'id,title,status' or use aliases like 'epic_basics') -
Default:
-
--filter-json- JSONPath expression to filter JSON output (e.g., '$[?(@.status=="active")].id') -
Default:
-
--color- Enable syntax highlighting for JSON output (default: no color for AI compatibility) -
Type: boolean
-
--no-color- Explicitly disable syntax highlighting (default is already no color) - Type: boolean
Examples:
gira epic show¶
Show details of a specific epic.
Arguments:
epic_id- Epic ID to show (e.g., EPIC-001) (required)- Type: string
- Pattern:
^EPIC-\d{3}$ - Examples: EPIC-001, EPIC-002
Options:
-f, --format- Output format- Type: enum
- Choices: TABLE, JSON, YAML, CSV, TSV, TEXT, IDS
- Default: text
-
Examples: json, table
-
--json- Output as JSON (shorthand for --format json) -
Type: boolean
-
--tickets/--no-tickets- Show tickets belonging to this epic - Type: boolean
-
Default: True
-
--filter-json- JSONPath expression to filter JSON output (e.g., '$.tickets[*]') -
Default:
-
--color- Enable syntax highlighting for JSON output (default: no color for AI compatibility) -
Type: boolean
-
--no-color- Explicitly disable syntax highlighting (default is already no color) - Type: boolean
Examples:
gira epic update¶
Update an existing epic.
Arguments:
epic_id- Epic ID to update (required unless using --stdin) (optional)- Type: string
- Pattern:
^EPIC-\d{3}$ - Examples: EPIC-001, EPIC-002
Options:
-t, --title- New title- Default:
- Min length: 3
-
Max length: 200
-
-d, --description- New description (use '-' for stdin, 'editor' to open editor) - Default:
-
Max length: 5000
-
--description-file- Read description from a file - Default:
-
Examples: ticket-description.md, docs/feature-spec.md, /tmp/bug-report.txt
-
-s, --status- New status (draft, active, completed) - Choices: backlog, todo, in_progress, review, done
- Default:
-
Examples: backlog, todo, in_progress
-
-o, --owner- New owner email - Default:
- Pattern:
^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$ -
Examples: user@example.com, john.doe@company.org
-
--target-date- New target date (YYYY-MM-DD) - Default:
- Pattern:
^\d{4}-\d{2}-\d{2}$ -
Examples: 2025-01-20, 2025-12-31
-
--add-ticket- Add ticket to epic (can be used multiple times) - Type: array
-
Default:
-
--remove-ticket- Remove ticket from epic (can be used multiple times) - Type: array
-
Default:
-
--output- Output format: text, json - Choices: text, json, table, csv
- Default: text
-
Examples: json, table
-
-q, --quiet- Only output epic ID -
Type: boolean
-
--stdin- Read JSON array of epic updates from stdin -
Type: boolean
-
--jsonl- Read JSONL (JSON Lines) format for streaming large datasets -
Type: boolean
-
--dry-run- Preview changes without saving them - Type: boolean
Examples:
gira epic delete¶
Delete or archive an epic.
Arguments:
epic_id- Epic ID to delete (required)- Type: string
- Pattern:
^EPIC-\d{3}$ - Examples: EPIC-001, EPIC-002
Options:
-f, --force- Skip confirmation prompt-
Type: boolean
-
-p, --permanent- Permanently delete instead of archiving -
Type: boolean
-
-o, --output- Output format (json) - Choices: text, json, table, csv
- Default:
-
Examples: json, table
-
--git/--no-git- Stage the archive/delete using 'git mv' or 'git rm' - Type: boolean
- Default:
Examples: