CLI Reference¶
Complete reference for all Gira commands and options.
Table of Contents¶
Sprint Management¶
-
gira sprint assign- Assign multiple tickets to a sprint. -
gira sprint assign-by-dates- Assign tickets to sprint based on completion dates. -
gira sprint assign-by-epic- Assign all tickets from an epic to a sprint. -
gira sprint assign-wizard- Interactive wizard for assigning unassigned tickets to sprints. -
gira sprint close- Close a sprint (change status to completed). -
gira sprint complete- Complete a sprint (alias for close). -
gira sprint create- Create a new sprint. -
gira sprint delete- Delete or archive a sprint. -
gira sprint generate-historical- Generate historical sprints from completed epics and tickets. -
gira sprint list- List all sprints. -
gira sprint show- Show details of a specific sprint. -
gira sprint start- Start a sprint (change status from planned to active). -
gira sprint unassign- Remove tickets from sprint assignments. -
gira sprint update- Update sprint fields.
Global Options¶
These options can be used with any command:
--help- Show help message and exit--version- Show version number and exit
Commands¶
gira sprint create¶
Create a new sprint.
Arguments:
name- Sprint name (required)- Type: string
Options:
-g, --goal- Sprint goal-
Default:
-
--goal-file- Read goal from a file - Default:
-
Examples: sprint-goals.md, objectives/q1-goals.txt, ./planning/sprint-15.md
-
-s, --start-date- Start date (YYYY-MM-DD, defaults to today) - Default:
- Pattern:
^\d{4}-\d{2}-\d{2}$ -
Examples: 2025-01-20, 2025-12-31
-
-e, --end-date- End date (YYYY-MM-DD, overrides duration) - Default:
- Pattern:
^\d{4}-\d{2}-\d{2}$ -
Examples: 2025-01-20, 2025-12-31
-
-d, --duration- Duration in days (ignored if end-date is provided) - Type: integer
- Default: 14
-
Examples: 7, 14, 30
-
-q, --quiet- Quiet mode - only show sprint ID - Type: boolean
Examples:
gira sprint list¶
List all sprints.
Options:
-q, --query- Query expression (e.g., 'status:active AND name:~"sprint"')- Default:
-
Examples: ..py$, ^test_., (bug|fix):
-
--status- Filter by sprint status (planned, active, completed) - Type: array
- Choices: backlog, todo, in_progress, review, done
- Default:
-
Examples: backlog, todo, in_progress
-
--after- Show sprints that start after this date (YYYY-MM-DD) -
Default:
-
--before- Show sprints that end before this date (YYYY-MM-DD) -
Default:
-
--between- Show sprints within date range (YYYY-MM-DD,YYYY-MM-DD) -
Default:
-
--min-tickets- Show sprints with at least this many tickets - Type: integer
-
Default:
-
--active- Show only active sprints (deprecated: use --status active) -
Type: boolean
-
--completed- Show only completed sprints (deprecated: use --status completed) -
Type: boolean
-
--search- Search text in sprint fields (default: name and goal) -
Default:
-
--search-in- Specify fields to search: name, goal, id, status, 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
-
--json- Output in JSON format (shorthand for --format json) -
Type: boolean
-
--fields- Comma-separated list of fields to include in JSON output (e.g., 'id,name,status' or use aliases like 'sprint_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 sprint show¶
Show details of a specific sprint.
Arguments:
sprint_id- Sprint ID to show (e.g., SPRINT-001) (required)- Type: string
- Pattern:
^SPRINT-\d{3}$ - Examples: SPRINT-001, SPRINT-002
Options:
-f, --format- Output format- Type: enum
- Choices: TABLE, JSON, YAML, CSV, TSV, TEXT, IDS
- Default: text
-
Examples: json, table
-
--json- Output in JSON format (shorthand for --format json) -
Type: boolean
-
--tickets/--no-tickets- Show tickets belonging to this sprint - 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 sprint update¶
Update sprint fields.
Arguments:
sprint_id- Sprint ID to update (e.g., SPRINT-2025-01-15) (required)- Type: string
- Pattern:
^SPRINT-\d{3}$ - Examples: SPRINT-001, SPRINT-002
Options:
-n, --name- Update sprint name-
Default:
-
-g, --goal- Update sprint goal -
Default:
-
--goal-file- Read goal from a file - Default:
-
Examples: sprint-goals.md, objectives/q1-goals.txt, ./planning/sprint-15.md
-
--start-date- Update start date (YYYY-MM-DD) - Default:
- Pattern:
^\d{4}-\d{2}-\d{2}$ -
Examples: 2025-01-20, 2025-12-31
-
--end-date- Update end date (YYYY-MM-DD) - Default:
- Pattern:
^\d{4}-\d{2}-\d{2}$ -
Examples: 2025-01-20, 2025-12-31
-
-a, --add-ticket- Add ticket(s) to sprint - Type: array
-
Default:
-
-r, --remove-ticket- Remove ticket(s) from sprint - Type: array
-
Default:
-
-s, --status- Update sprint status (planned/active/completed) - Choices: backlog, todo, in_progress, review, done
- Default:
-
Examples: backlog, todo, in_progress
-
--dry-run- Preview changes without saving them - Type: boolean
Examples:
gira sprint start¶
Start a sprint (change status from planned to active).
Arguments:
sprint_id- Sprint ID to start (required)- Type: string
- Pattern:
^SPRINT-\d{3}$ - Examples: SPRINT-001, SPRINT-002
Examples:
gira sprint close¶
Close a sprint (change status to completed).
Arguments:
sprint_id- Sprint ID to close (required)- Type: string
- Pattern:
^SPRINT-\d{3}$ - Examples: SPRINT-001, SPRINT-002
Options:
--retrospective/--no-retrospective- Include retrospective- Type: boolean
-
Default: True
-
--git/--no-git- Stage the sprint move using 'git mv' - Type: boolean
- Default:
Examples:
gira sprint complete¶
Complete a sprint (alias for close).
Arguments:
sprint_id- Sprint ID to complete (required)- Type: string
- Pattern:
^SPRINT-\d{3}$ - Examples: SPRINT-001, SPRINT-002
Options:
--retrospective/--no-retrospective- Include retrospective- Type: boolean
-
Default: True
-
--git/--no-git- Stage the sprint move using 'git mv' - Type: boolean
- Default:
Examples:
gira sprint delete¶
Delete or archive a sprint.
Arguments:
sprint_id- Sprint ID to delete (required)- Type: string
- Pattern:
^SPRINT-\d{3}$ - Examples: SPRINT-001, SPRINT-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:
gira sprint assign¶
Assign multiple tickets to a sprint.
Arguments:
sprint_id- Sprint ID to assign tickets to (required)- Type: string
- Pattern:
^SPRINT-\d{3}$ -
Examples: SPRINT-001, SPRINT-002
-
ticket_ids- Ticket ID(s) to assign (supports patterns like 'GCM-1*', ranges like 'GCM-1..10', or '-' for stdin) (optional) - Type: array
- Pattern:
^[A-Z]{2,4}-\d+$ - Examples: GIRA-123, GCM-456, PROJ-1
Options:
--from-file- Read ticket IDs from file- Default:
-
Examples: .gira/config.json, /path/to/file.txt, ./relative/path.md
-
--query- Assign tickets matching query - Default:
-
Examples: ..py$, ^test_., (bug|fix):
-
--from-context- Assign tickets from current context -
Type: boolean
-
-f, --force- Legacy option (confirmation removed for AI-friendliness) -
Type: boolean
-
--dry-run- Preview changes without applying them -
Type: boolean
-
-q, --quiet- Suppress output -
Type: boolean
-
-o, --output- Output format (table, json) - Choices: text, json, table, csv
- Default: table
- Examples: json, table
Examples:
gira sprint unassign¶
Remove tickets from sprint assignments.
Arguments:
ticket_ids- Ticket ID(s) to unassign (supports patterns like 'GCM-1*', ranges like 'GCM-1..10', or '-' for stdin) (optional)- Type: array
- Pattern:
^[A-Z]{2,4}-\d+$ - Examples: GIRA-123, GCM-456, PROJ-1
Options:
--all- Unassign all tickets from specified sprint-
Type: boolean
-
--from- Unassign only from this specific sprint -
Default:
-
-f, --force- Legacy option (confirmation removed for AI-friendliness) -
Type: boolean
-
--dry-run- Preview changes without applying them -
Type: boolean
-
-q, --quiet- Suppress output -
Type: boolean
-
-o, --output- Output format (table, json) - Choices: text, json, table, csv
- Default: table
- Examples: json, table
Examples:
gira sprint assign-by-dates¶
Assign tickets to sprint based on completion dates.
Arguments:
sprint_id- Sprint ID to assign tickets to (required)- Type: string
- Pattern:
^SPRINT-\d{3}$ - Examples: SPRINT-001, SPRINT-002
Options:
--start- Start date for ticket search (YYYY-MM-DD)- Default:
- Pattern:
^\d{4}-\d{2}-\d{2}$ -
Examples: 2025-01-20, 2025-12-31
-
--end- End date for ticket search (YYYY-MM-DD) - Default:
- Pattern:
^\d{4}-\d{2}-\d{2}$ -
Examples: 2025-01-20, 2025-12-31
-
--include-assigned- Include tickets already assigned to other sprints -
Type: boolean
-
--dry-run- Preview changes without applying them - Type: boolean
Examples:
gira sprint assign-by-epic¶
Assign all tickets from an epic to a sprint.
Arguments:
sprint_id- Sprint ID to assign tickets to (required)- Type: string
- Pattern:
^SPRINT-\d{3}$ -
Examples: SPRINT-001, SPRINT-002
-
epic_id- Epic ID to assign tickets from (required) - Type: string
- Pattern:
^EPIC-\d{3}$ - Examples: EPIC-001, EPIC-002
Options:
--status- Only assign tickets with this status (e.g., 'done')- Choices: backlog, todo, in_progress, review, done
- Default:
-
Examples: backlog, todo, in_progress
-
--dry-run- Preview changes without applying them - Type: boolean
Examples:
gira sprint assign-wizard¶
Interactive wizard for assigning unassigned tickets to sprints.
Examples:
gira sprint generate-historical¶
Generate historical sprints from completed epics and tickets.
Options:
--epic- Generate sprint only for specific epic-
Default:
-
--start- Start date filter (YYYY-MM-DD) - Default:
- Pattern:
^\d{4}-\d{2}-\d{2}$ -
Examples: 2025-01-20, 2025-12-31
-
--end- End date filter (YYYY-MM-DD) - Default:
- Pattern:
^\d{4}-\d{2}-\d{2}$ -
Examples: 2025-01-20, 2025-12-31
-
--duration- Sprint duration in days - Type: integer
- Default: 14
-
Examples: 7, 14, 30
-
--include-orphaned/--no-orphaned- Include tickets without epic assignments - Type: boolean
-
Default: True
-
--dry-run- Preview sprints without creating them - Type: boolean
Examples: