CLI Reference¶

Complete reference for all Gira commands and options.

Table of Contents¶

Archive Management¶

gira archive done - Archive all done tickets with optional filtering.
gira archive list - List archived tickets with optional filtering.
gira archive old - Archive tickets older than specified number of days.
gira archive restore - Restore an archived ticket back to the board.
gira archive suggest - Suggest tickets to archive based on various criteria.
gira archive ticket - Archive a single ticket.

Comments¶

gira comment add - Add a comment to a ticket or epic.
gira comment attach - Attach files to an existing comment.
gira comment delete - Delete a comment from a ticket or epic.
gira comment detach -
gira comment download -
gira comment list - List all comments on a ticket or epic.

Configuration¶

gira config get -
gira config rename-prefix - Rename the ticket ID prefix for the entire project.
gira config reset - Reset configuration to default values.
gira config set - Set a configuration value.

Core Commands¶

gira board - Display the kanban board.
gira describe -
gira graph -
gira init - Initialize a new Gira project in the current directory.
gira query - Execute queries and manage saved queries.
gira sync - Detect and resolve ticket ID conflicts from merge operations.
gira sync - Detect and resolve ticket ID conflicts from merge operations.

Documentation¶

gira docs generate - Generate documentation for Gira including CLI reference, AI agent guides, and workflow documentation.

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.

Migration¶

gira migrate hybrid - Migrate the project to use hybrid directory structure for backlog tickets.

Other Commands¶

gira ai ai-help - Show AI-optimized command examples and patterns.
gira ai examples - Alias for ai-help command.
gira ai setup - Set up AI documentation for the project.
gira ai status - Show AI documentation files and integration status.
gira ai-help - Show AI-optimized command examples and patterns.
gira attachment add - Add attachment(s) to a ticket or epic.
gira attachment cat -
gira attachment download - Download attachment(s) to specified location without opening.
gira attachment list - List all attachments for a ticket or epic.
gira attachment open -
gira attachment remove -
gira backlog - Show tickets in the backlog with enhanced filtering and display options.
gira backup -
gira cache clear - Clear cached data.
gira cache status - Show cache statistics.
gira context epic - Show ticket in the context of its epic.
gira context references - Show where this ticket is referenced (comments, commits).
gira context related - Find tickets related by various criteria.
gira context show - Display comprehensive context for a ticket (explicit show subcommand).
gira context timeline - Show activity timeline for a ticket.
gira context tree - Show visual dependency tree for a ticket.
gira export csv - Export tickets to CSV format
gira export json - Export tickets to JSON format
gira export md - Export tickets to Markdown format
gira ext disable - Disable hook execution.
gira ext enable - Enable hook execution.
gira ext init - Initialize the hooks directory with example templates.
gira ext install - Install a specific hook template.
gira ext list - List all available hooks and their status.
gira ext show - Display the contents of a hook file.
gira ext test - Test a hook with sample data.
gira hooks install - Install Git hooks for Gira integration.
gira hooks status - Show the status of Git hooks for Gira integration.
gira hooks uninstall - Uninstall Git hooks for Gira integration.
gira metrics duration - Analyze time tickets spend in each status to identify bottlenecks.
gira metrics overview - Display comprehensive metrics overview for the project.
gira metrics trends - Display ticket creation, completion, and backlog trends over time.
gira metrics velocity - Display team velocity trends across sprints.
gira operation cancel - Cancel a running operation.
gira operation cleanup - Clean up old operation snapshots.
gira operation list - List async operations.
gira operation resume - Resume operations from persistence.
gira operation status - Check the status of an async operation.
gira operation wait - Wait for an operation to complete.
gira query-list - List all saved queries (DEPRECATED).
gira query-run - Run a saved query by name (DEPRECATED).
gira query-save - Save a query expression for later reuse (DEPRECATED).
gira restore -
gira storage configure - Configure storage backend for attachments.
gira storage status - Check storage configuration and credential status.
gira storage validate - Validate storage credentials and show detailed information.
gira webhook add - Add a new webhook endpoint.
gira webhook disable - Disable webhooks globally or a specific webhook endpoint.
gira webhook enable - Enable webhooks globally or a specific webhook endpoint.
gira webhook health - Check webhook endpoint health and connectivity.
gira webhook list - List configured webhook endpoints.
gira webhook remove - Remove a webhook endpoint.
gira webhook stats - Show webhook delivery statistics.
gira webhook test - Test a webhook endpoint with a sample payload.
gira webhook webhook filter help - Show help for webhook filter expressions.
gira webhook webhook filter validate - Validate a webhook filter expression.
gira workflow analyze - Analyze workflow patterns and suggest improvements.
gira workflow apply - Apply a predefined workflow template.
gira workflow config - Display current workflow configuration.
gira workflow diagram - Display visual workflow diagram.
gira workflow enforce - Set workflow enforcement level.
gira workflow migrate - Migrate tickets from one workflow to another.
gira workflow rule - Manage custom workflow rules.
gira workflow show - Display available workflow transitions for a ticket.
gira workflow stats - Show workflow statistics and metrics.
gira workflow strict - Enable or disable strict workflow enforcement.
gira workflow templates - List available workflow templates.
gira workflow transitions - Manage allowed status transitions.
gira workflow validate - Validate all tickets against workflow rules.

Shell Completion¶

gira completion install - Install shell completion for Gira.
gira completion show - Show completion script for manual installation.

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.

Team Management¶

gira team add - Add a new team member.
gira team discover - Discover team members from Git commit history.
gira team list - List all team members.
gira team remove - Remove a team member.

Ticket Management¶

gira ticket add-dep - Add a dependency relationship between tickets.
gira ticket blame - Discover tickets associated with specific file lines.
gira ticket bulk-add-deps - Add dependencies to multiple tickets at once.
gira ticket bulk-remove-deps - Remove dependencies from multiple tickets at once.
gira ticket bulk-update - Update multiple tickets with the same changes.
gira ticket clear-deps - Clear all dependencies from one or more tickets.
gira ticket commits - List all commits associated with a ticket.
gira ticket create - Create a new ticket.
gira ticket delete - Delete or archive ticket(s).
gira ticket deps - Show dependency relationships for a ticket.
gira ticket edit - Edit a ticket (alias for update).
gira ticket list - List tickets with optional filters.
gira ticket ls - List tickets (alias for list).
gira ticket move - Move ticket(s) to a different status/swimlane.
gira ticket mv - Move ticket(s) to a different status (alias for move).
gira ticket order - Set the order of a ticket within its status column.
gira ticket remove-dep - Remove a dependency relationship between tickets.
gira ticket rm - Remove ticket(s) (alias for delete).
gira ticket show - Show details of a specific ticket.
gira ticket ticket estimate batch - Interactive batch estimation of multiple tickets.
gira ticket ticket estimate compare - Compare two tickets side-by-side for relative estimation.
gira ticket ticket estimate relative - Show base ticket details while estimating other tickets.
gira ticket ticket estimate set - Set story points for one or more tickets.
gira ticket tree - Display parent ticket and all subtasks in a hierarchical tree view.
gira ticket update - Update one or more tickets.

Global Options¶

These options can be used with any command:

--help - Show help message and exit
--version - Show version number and exit

Commands¶

`gira init`¶

Initialize a new Gira project in the current directory.

gira init [name] [options]

Arguments:

name - Project name (optional)
Type: string

Options:

-d, --description - Project description
Max length: 5000
-p, --prefix - Ticket ID prefix (2-4 uppercase letters)
Default:
-f, --force - Overwrite existing project
Type: boolean
--strict-workflow - Use traditional linear workflow instead of flexible transitions
Type: boolean
-w, --workflow - Workflow template: scrum, kanban, support-desk, bug-tracking, minimal, custom
Default:
--non-interactive - Run without prompts (all required options must be provided)
Type: boolean

Examples:

gira init

gira init --force

`gira board`¶

Display the kanban board.

gira board [options]

Options:

-a, --assignee - Filter by assignee
Default:
Pattern: ^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$
Examples: user@example.com, john.doe@company.org
-p, --priority - Filter by priority
Choices: low, medium, high, critical
Default:
Examples: medium, high
-t, --type - Filter by ticket type
Default:
-l, --label - Filter by label
Default:
--story-points-eq - Filter by exact story point value
Type: integer
Default:
--story-points-gt - Filter by story points greater than value
Type: integer
Default:
--story-points-lt - Filter by story points less than value
Type: integer
Default:
--created-after - Filter tickets created after date (YYYY-MM-DD)
Default:
Pattern: ^\d{4}-\d{2}-\d{2}$
Examples: 2025-01-20, 2025-12-31
--created-before - Filter tickets created before date (YYYY-MM-DD)
Default:
Pattern: ^\d{4}-\d{2}-\d{2}$
Examples: 2025-01-20, 2025-12-31
--updated-after - Filter tickets updated after date (YYYY-MM-DD)
Default:
Pattern: ^\d{4}-\d{2}-\d{2}$
Examples: 2025-01-20, 2025-12-31
--updated-before - Filter tickets updated before date (YYYY-MM-DD)
Default:
Pattern: ^\d{4}-\d{2}-\d{2}$
Examples: 2025-01-20, 2025-12-31
--due-after - Filter tickets due after date (YYYY-MM-DD)
Default:
--due-before - Filter tickets due before date (YYYY-MM-DD)
Default:
--due-on - Filter tickets due on specific date (YYYY-MM-DD)
Default:
--overdue - Show only tickets past their due date
Type: boolean
--has-comments - Show only tickets that have comments
Type: boolean
--no-comments - Show only tickets without comments
Type: boolean
--has-parent - Show only subtasks that have a parent ticket
Type: boolean
--no-parent - Show only tickets that are not subtasks
Type: boolean
--in-sprint - Filter tickets in a specific sprint
Default:
--not-in-sprint - Filter tickets not in a specific sprint
Default:
--not-in-epic - Filter tickets not linked to a specific epic
Default:
-c, --compact - Show compact view
Type: boolean
--fast - Use optimized display for large projects
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
--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 board

gira board --assignee user@example.com --priority medium

gira board --overdue

`gira backlog`¶

Show tickets in the backlog with enhanced filtering and display options.

gira backlog [options]

Options:

-a, --assignee - Filter by assignee
Default:
Pattern: ^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$
Examples: user@example.com, john.doe@company.org
-p, --priority - Filter by priority (critical, high, medium, low)
Choices: low, medium, high, critical
Default:
Examples: medium, high
-t, --type - Filter by type (bug, feature, task, etc.)
Default:
-l, --label - Filter by label
Default:
--epic - Filter by epic ID (comma-separated for multiple)
Default:
--no-epic - Show only tickets without epic assignment
Type: boolean
--search - Search text in ticket title and description
Default:
--sort - Sort by: priority (default), created, updated, title, id
Default: priority
--limit - Limit number of results shown
Type: integer
Default:
-f, --format - Output format
Type: enum
Choices: TABLE, JSON, YAML, CSV, TSV, TEXT, IDS
Default: table
Examples: json, table
--fields - Comma-separated list of fields to include in JSON output
Default:
--counts - Show summary counts by priority
Type: boolean
--ready - Show only ready tickets (no blockers, assigned)
Type: boolean
--unassigned - Show only unassigned tickets
Type: boolean
--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 backlog

gira backlog --assignee user@example.com --priority medium

gira backlog --no-epic

`gira query`¶

Execute queries and manage saved queries.

gira query [options]

Options:

-e, --entity - Type of entity to search
Default: ticket
-f, --format - Output format
Choices: text, json, table, csv
Default: table
Examples: json, table
-l, --limit - Maximum number of results to return
Type: integer
Default:
-o, --offset - Number of results to skip
Type: integer
Default: 0
-s, --sort - Sort results by field
Default:
--filter-json - JSONPath expression to filter JSON output
Default:
--no-header - Don't show table header
Type: boolean
-v, --verbose - Show detailed error messages
Type: boolean
--save - Save query with given name
Default:
-d, --description - Description for saved query
Default:
Max length: 5000
--force - Overwrite existing saved query
Type: boolean
--color/--no-color - Enable/disable colored output
Type: boolean
Default: True

Examples:

gira query

gira query --format json

gira query --no-header

`gira query-save`¶

Save a query expression for later reuse (DEPRECATED).

gira query-save <name><query_string> [options]

Arguments:

name - Name for the saved query (required)
Type: string
query_string - Query expression to save (required)
Type: string
Examples: ..py$, ^test_., (bug|fix):

Options:

-d, --description - Description of what the query returns
Default:
Max length: 5000
-e, --entity - Entity type the query targets
Default: ticket
-f, --force - Overwrite existing query with the same name
Type: boolean

Examples:

gira query-save <name> .*\.py$

gira query-save <name> .*\.py$ --force

`gira query-list`¶

List all saved queries (DEPRECATED).

gira query-list [options]

Options:

-e, --entity - Filter by entity type
Default:
-v, --verbose - Show detailed information
Type: boolean
-f, --format - Output format
Type: enum
Choices: TABLE, JSON, YAML, CSV, TSV, TEXT, IDS
Default: table
Examples: json, table

Examples:

gira query-list

gira query-list --format json

gira query-list --verbose

`gira query-run`¶

Run a saved query by name (DEPRECATED).

gira query-run <name> [options]

Arguments:

name - Name of the saved query to run (required)
Type: string

Options:

-f, --format - Output format
Type: enum
Choices: TABLE, JSON, YAML, CSV, TSV, TEXT, IDS
Default: table
Examples: json, table
-l, --limit - Maximum number of results
Type: integer
Default:
-o, --offset - Number of results to skip
Type: integer
Default: 0
-s, --sort - Sort results by field
Default:
--filter-json - JSONPath expression
Default:
--no-header - Don't show table header
Type: boolean
-v, --verbose - Show detailed error messages
Type: boolean

Examples:

gira query-run <name>

gira query-run <name> --format json

gira query-run <name> --no-header

`gira graph`¶

gira graph [entity_args] [options]

Arguments:

entity_args - Ticket ID (e.g., GCM-123) or epic command (e.g., epic EPIC-001) (optional)
Type: array

Options:

-d, --depth - Maximum depth to traverse relationships
Type: integer
Default: 2
--blockers/--no-blockers - Show tickets that block this ticket
Type: boolean
Default: True
--blocks/--no-blocks - Show tickets blocked by this ticket
Type: boolean
Default: True
--parent/--no-parent - Show parent ticket relationship
Type: boolean
Default: True
--children/--no-children - Show child tickets
Type: boolean
Default: True
--epic/--no-epic - Show epic relationship
Type: boolean
Default: True
-f, --format - Output format: tree, json
Choices: text, json, table, csv
Default: tree
Examples: json, table
--epics - Show all epics overview
Type: boolean
--epic-deps - Show dependencies between epics
Type: boolean
--mixed - Show mixed view of epics and tickets
Type: boolean
-s, --status - Filter epics by status (for --epics mode)
Choices: backlog, todo, in_progress, review, done
Default:
Examples: backlog, todo, in_progress
-o, --owner - Filter epics by owner (for --epics mode)
Default:
Pattern: ^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$
Examples: user@example.com, john.doe@company.org
--min-progress - Filter epics by minimum progress percentage
Type: integer
Default:
--all-tickets - Show all tickets in epic view (default shows first 5 per status)
Type: boolean
--compact - Use compact mode for large graphs
Type: boolean
--stats - Show graph statistics panel
Type: boolean
--legend - Show legend for icons and colors
Type: boolean
Pattern: ^\d{4}-\d{2}-\d{2}$
Examples: 2025-01-20, 2025-12-31
--enhanced - Use enhanced visual display with panels
Type: boolean
--export - Export graph to file (format determined by extension: .svg, .png, .html, .mermaid, .dot)
Default:

Examples:

gira graph

gira graph --format json --status backlog

gira graph --blockers/--no-blockers

`gira describe`¶

gira describe [command] [options]

Arguments:

command - Command path to describe (e.g., 'ticket create') (optional)
Type: array

Options:

-f, --format - Output format: json or markdown
Choices: text, json, table, csv
Default: json
Examples: json, table
--no-color - Explicitly disable syntax highlighting (default is already no color)
Type: boolean
--color - Enable syntax highlighting (colors the JSON output)
Type: boolean
--theme - Syntax highlighting theme (requires --color)
Default: monokai
--indent - JSON indentation spaces
Type: integer
Default: 2
--compact - Compact JSON output
Type: boolean
--render - Render markdown with Rich formatting
Type: boolean
Pattern: ^\d{4}-\d{2}-\d{2}$
Examples: 2025-01-20, 2025-12-31
--examples/--no-examples - Include command examples in markdown
Type: boolean
Default: True
--full - Generate full documentation with all commands
Type: boolean

Examples:

gira describe

gira describe --format json

gira describe --no-color

`gira backup`¶

gira backup [options]

Options:

-o, --output - Output file path. If not specified, creates backup in current directory
Choices: text, json, table, csv
Default:
Examples: json, table
--exclude-archived - Exclude archived tickets from the backup
Type: boolean

Examples:

gira backup

gira backup --exclude-archived

`gira restore`¶

gira restore <backup_file> [options]

Arguments:

backup_file - Path to the backup file to restore (required)
Type: string
Examples: .gira/config.json, /path/to/file.txt, ./relative/path.md

Options:

-t, --target - Target directory for restoration. Defaults to current directory
Default:
Pattern: ^\d{4}-\d{2}-\d{2}$
Examples: 2025-01-20, 2025-12-31
-f, --force - Skip confirmation prompt
Type: boolean

Examples:

gira restore .gira/config.json

gira restore .gira/config.json --force

`gira sync`¶

Detect and resolve ticket ID conflicts from merge operations.

gira sync [options]

Options:

-n, --dry-run - Show what would be changed without making changes
Type: boolean

Examples:

gira sync

gira sync --dry-run

`gira ai-help`¶

Show AI-optimized command examples and patterns.

gira ai-help [agent]

Arguments:

agent - Specific AI agent (claude, gemini, etc.) (optional)
Type: string

Examples:

gira ai-help

`gira sync`¶

Detect and resolve ticket ID conflicts from merge operations.

gira sync [options]

Options:

-n, --dry-run - Show what would be changed without making changes
Type: boolean

Examples:

gira sync

gira sync --dry-run

`gira ticket create`¶

Create a new ticket.

gira ticket create [title] [options]

Arguments:

title - Ticket title (required unless using --stdin) (optional)
Type: string
Min length: 3
Max length: 200

Options:

-d, --description - Ticket description (use '-' for stdin, 'editor' to open editor)
Max length: 5000
--description-file - Read description from a file
Default:
Examples: ticket-description.md, docs/feature-spec.md, /tmp/bug-report.txt
-p, --priority - Priority level
Choices: low, medium, high, critical
Default: medium
Examples: medium, high
-a, --assignee - Assignee
Default:
Pattern: ^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$
Examples: user@example.com, john.doe@company.org
-t, --type - Ticket type
Default: task
-l, --labels - Comma-separated labels
Default:
-e, --epic - Epic ID
Default:
--parent - Parent ticket ID for subtasks
Default:
-sp, --story-points - Story points estimate
Type: integer
Default:
-s, --status - Initial status (e.g., backlog, todo, in_progress)
Choices: backlog, todo, in_progress, review, done
Default:
Examples: backlog, todo, in_progress
-o, --output - Output format: text, json
Choices: text, json, table, csv
Default: text
Examples: json, table
-q, --quiet - Only output ticket ID
Type: boolean
--strict - Enforce strict assignee validation (no external assignees)
Type: boolean
--stdin - Read JSON array of tickets from stdin for bulk creation
Type: boolean
--jsonl - Read JSONL (JSON Lines) format for streaming large datasets
Type: boolean
--csv - Read CSV format from stdin for bulk creation
Type: boolean
--csv-delimiter - CSV delimiter character (default: comma)
Default: ,
--skip-invalid - Skip invalid rows and continue processing
Type: boolean
--fail-on-error/--no-fail-on-error - Exit with error if any row fails (default: true)
Type: boolean
Default: True
--cf - Custom field value in format 'name=value' (can be used multiple times)
Type: array
Default:

Examples:

gira ticket create "Fix login bug" --priority high --type bug

gira ticket create "Add user authentication" --description "Implement OAuth2" --epic EPIC-001

gira ticket create "Update documentation" --assignee john@example.com --labels "docs,urgent"

`gira ticket list`¶

List tickets with optional filters.

gira ticket list [options]

Options:

-q, --query - Query expression (e.g., 'status:todo AND priority:high')
Default:
Examples: ..py$, ^test_., (bug|fix):
-s, --status - Filter by status
Choices: backlog, todo, in_progress, review, done
Default:
Examples: backlog, todo, in_progress
-a, --assignee - Filter by assignee
Default:
Pattern: ^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$
Examples: user@example.com, john.doe@company.org
-t, --type - Filter by type
Default:
-p, --priority - Filter by priority
Choices: low, medium, high, critical
Default:
Examples: medium, high
-l, --label - Filter by label
Default:
--parent - Filter by parent ticket ID (show subtasks)
Default:
--blocked - Show only tickets blocked by unresolved dependencies
Type: boolean
--story-points-eq - Filter by exact story point value
Type: integer
Default:
--story-points-gt - Filter by story points greater than value
Type: integer
Default:
--story-points-lt - Filter by story points less than value
Type: integer
Default:
--created-after - Filter tickets created after date (YYYY-MM-DD)
Default:
Pattern: ^\d{4}-\d{2}-\d{2}$
Examples: 2025-01-20, 2025-12-31
--created-before - Filter tickets created before date (YYYY-MM-DD)
Default:
Pattern: ^\d{4}-\d{2}-\d{2}$
Examples: 2025-01-20, 2025-12-31
--updated-after - Filter tickets updated after date (YYYY-MM-DD)
Default:
Pattern: ^\d{4}-\d{2}-\d{2}$
Examples: 2025-01-20, 2025-12-31
--updated-before - Filter tickets updated before date (YYYY-MM-DD)
Default:
Pattern: ^\d{4}-\d{2}-\d{2}$
Examples: 2025-01-20, 2025-12-31
--due-after - Filter tickets due after date (YYYY-MM-DD)
Default:
--due-before - Filter tickets due before date (YYYY-MM-DD)
Default:
--due-on - Filter tickets due on specific date (YYYY-MM-DD)
Default:
--overdue - Show only tickets past their due date
Type: boolean
--has-comments - Show only tickets that have comments
Type: boolean
--no-comments - Show only tickets without comments
Type: boolean
--has-parent - Show only subtasks that have a parent ticket
Type: boolean
--no-parent - Show only tickets that are not subtasks
Type: boolean
--in-sprint - Filter tickets in a specific sprint
Default:
--not-in-sprint - Filter tickets not in a specific sprint
Default:
--not-in-epic - Filter tickets not linked to a specific epic
Default:
--epic - Filter tickets by epic ID (comma-separated for multiple epics)
Default:
--no-epic - Show only tickets without epic assignment (alias for --not-in-epic without value)
Type: boolean
--search - Search text in ticket fields (default: title and description)
Default:
--search-in - Specify fields to search: title, description, id, status, type, priority, assignee, reporter, labels, 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
--sort - Sort by: id, priority, created, updated, title, order
Default: id
-f, --format - Output format
Type: enum
Choices: TABLE, JSON, YAML, CSV, TSV, TEXT, IDS
Default: table
Examples: json, table
--ids-only - Show only ticket IDs
Type: boolean
--counts - Show summary counts
Type: boolean
--include-archived - Include archived tickets in results
Type: boolean
--fields - Comma-separated list of fields to include in JSON output (e.g., 'id,title,status' or use aliases like 'basics')
Default:
--filter-json - JSONPath expression to filter JSON output (e.g., '$[?(@.priority=="high")].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 ticket list --status in_progress

gira ticket list --assignee john@example.com --priority high

gira ticket list --query "login" --format json

`gira ticket show`¶

Show details of a specific ticket.

gira ticket show <ticket_id> [options]

Arguments:

ticket_id - Ticket ID to show (required)
Type: string
Pattern: ^[A-Z]{2,4}-\d+$
Examples: GIRA-123, GCM-456, PROJ-1

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
--filter-json - JSONPath expression to filter JSON output (e.g., '$.title')
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 ticket show GIRA-123

gira ticket show GIRA-123 --format json

gira ticket show GIRA-123 --json

`gira ticket update`¶

Update one or more tickets.

gira ticket update [ticket_ids] [options]

Arguments:

ticket_ids - Ticket ID(s) to update (supports patterns like 'GCM-1*', ranges like 'GCM-1..10', use '-' to read IDs from stdin, or omit for --stdin JSON) (optional)
Type: array
Pattern: ^[A-Z]{2,4}-\d+$
Examples: GIRA-123, GCM-456, PROJ-1

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
Choices: backlog, todo, in_progress, review, done
Default:
Examples: backlog, todo, in_progress
-p, --priority - New priority
Choices: low, medium, high, critical
Default:
Examples: medium, high
--type - New ticket type
Default:
-a, --assignee - New assignee (use 'none' to clear)
Default:
Pattern: ^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$
Examples: user@example.com, john.doe@company.org
--add-labels - Labels to add (comma-separated)
Default:
--remove-labels - Labels to remove (comma-separated)
Default:
-e, --epic - New epic ID (use 'none' to clear)
Default:
--parent - New parent ID (use 'none' to clear)
Default:
--sprint - Sprint ID to assign ticket to (use 'current' for active sprint, 'none' to clear)
Default:
-sp, --story-points - New story points estimate (use 0 to clear)
Type: integer
Default:
-o, --output - Output format: text, json
Choices: text, json, table, csv
Default: text
Examples: json, table
-q, --quiet - Only output ticket ID
Type: boolean
--strict - Enforce strict assignee validation (no external assignees)
Type: boolean
--stdin - Read JSON array of ticket 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
-f, --force - Legacy option (confirmation removed for AI-friendliness)
Type: boolean
--cf - Update custom field value in format 'name=value' (can be used multiple times)
Type: array
Default:
--remove-cf - Remove custom field by name (can be used multiple times)
Type: array
Default:

Examples:

gira ticket update GCM-123 --status in_progress

gira ticket update PROJ-456 --assignee jane@example.com --priority high

gira ticket update GCM-789 --add-label "backend" --story-points 5

`gira ticket move`¶

Move ticket(s) to a different status/swimlane.

gira ticket move [ticket_ids]<target_status> [options]

Arguments:

ticket_ids - Ticket ID(s) to move (use '-' to read from stdin) (optional)
Type: array
Pattern: ^[A-Z]{2,4}-\d+$
Examples: GIRA-123, GCM-456, PROJ-1
target_status - Target status to move ticket to (required)
Type: string
Pattern: ^\d{4}-\d{2}-\d{2}$
Examples: 2025-01-20, 2025-12-31

Options:

-p, --position - Position in new column (1-based)
Type: integer
Default:
-o, --output - Output format: text, json
Choices: text, json, table, csv
Default: text
Examples: json, table
-q, --quiet - Only output ticket ID
Type: boolean
--dry-run - Preview the move without performing it
Type: boolean
--git/--no-git - Stage the move using 'git mv'
Type: boolean
Default:
-f, --force - Skip confirmation prompt
Type: boolean
--force-transition - Skip workflow validation and force the transition
Type: boolean
--confirm - Force confirmation prompt even if configured to skip
Type: boolean
-a, --assignee - Filter by assignee (use 'me' for current user)
Default:
Pattern: ^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$
Examples: user@example.com, john.doe@company.org
--from - Only move tickets from this status
Choices: backlog, todo, in_progress, review, done
Default:
Examples: backlog, todo, in_progress
-e, --epic - Filter tickets by epic ID
Default:
Pattern: ^EPIC-\d{3}$
Examples: EPIC-001, EPIC-002
-s, --sprint - Filter tickets by sprint ID (use 'current' for active sprint)
Default:
Pattern: ^SPRINT-\d{3}$
Examples: SPRINT-001, SPRINT-002
-c, --comment - Add comment to moved tickets
Default:
--assign - Assign tickets to user while moving
Default:
--add-label - Add label to moved tickets
Default:
--priority - Update priority while moving
Choices: low, medium, high, critical
Default:
Examples: medium, high
--check-dependencies - Check for blocking dependencies
Type: boolean
-b, --batch - Batch ID for undo operations
Default:
--if-no-blockers - Only move if ticket has no unresolved blocking dependencies
Type: boolean
--if-complete - Only move if ticket completion criteria are met
Type: boolean
--if-allowed - Only move if workflow transition is allowed
Type: boolean

Examples:

gira ticket move GCM-123 in_progress

gira ticket move PROJ-456 review

gira ticket move GCM-789 done

`gira ticket tree`¶

Display parent ticket and all subtasks in a hierarchical tree view.

gira ticket tree <ticket_id>

Arguments:

ticket_id - Ticket ID to display tree for (required)
Type: string
Pattern: ^[A-Z]{2,4}-\d+$
Examples: GIRA-123, GCM-456, PROJ-1

Examples:

gira ticket tree GIRA-123

`gira ticket add-dep`¶

Add a dependency relationship between tickets.

gira ticket add-dep <ticket_id><dependency_id> [options]

Arguments:

ticket_id - Ticket ID to add dependency to (required)
Type: string
Pattern: ^[A-Z]{2,4}-\d+$
Examples: GIRA-123, GCM-456, PROJ-1
dependency_id - Ticket ID that this ticket depends on (blocks this ticket) (required)
Type: string
Pattern: ^\d{4}-\d{2}-\d{2}$
Examples: 2025-01-20, 2025-12-31

Options:

--no-reciprocal - Don't add reciprocal relationship
Type: boolean

Examples:

gira ticket add-dep GIRA-123 2025-01-20

gira ticket add-dep GIRA-123 2025-01-20 --no-reciprocal

`gira ticket remove-dep`¶

Remove a dependency relationship between tickets.

gira ticket remove-dep <ticket_id><dependency_id> [options]

Arguments:

ticket_id - Ticket ID to remove dependency from (required)
Type: string
Pattern: ^[A-Z]{2,4}-\d+$
Examples: GIRA-123, GCM-456, PROJ-1
dependency_id - Ticket ID to remove as dependency (required)
Type: string
Pattern: ^\d{4}-\d{2}-\d{2}$
Examples: 2025-01-20, 2025-12-31

Options:

--no-reciprocal - Don't remove reciprocal relationship
Type: boolean

Examples:

gira ticket remove-dep GIRA-123 2025-01-20

gira ticket remove-dep GIRA-123 2025-01-20 --no-reciprocal

`gira ticket deps`¶

Show dependency relationships for a ticket.

gira ticket deps <ticket_id> [options]

Arguments:

ticket_id - Ticket ID to show dependencies for (required)
Type: string
Pattern: ^[A-Z]{2,4}-\d+$
Examples: GIRA-123, GCM-456, PROJ-1

Options:

-f, --format - Output format: table, json
Choices: text, json, table, csv
Default: table
Examples: json, table

Examples:

gira ticket deps GIRA-123

gira ticket deps GIRA-123 --format json

`gira ticket order`¶

Set the order of a ticket within its status column.

gira ticket order <ticket_id>[position] [options]

Arguments:

ticket_id - Ticket ID to reorder (required)
Type: string
Pattern: ^[A-Z]{2,4}-\d+$
Examples: GIRA-123, GCM-456, PROJ-1
position - New position (1-based) (optional)
Type: integer

Options:

--before - Place before this ticket ID
Default:
--after - Place after this ticket ID
Default:

Examples:

gira ticket order GIRA-123

`gira ticket delete`¶

Delete or archive ticket(s).

gira ticket delete [ticket_ids] [options]

Arguments:

ticket_ids - Ticket ID(s) to delete (use '-' to read from stdin) (optional)
Type: array
Pattern: ^[A-Z]{2,4}-\d+$
Examples: GIRA-123, GCM-456, PROJ-1

Options:

-f, --force - Skip confirmation prompt
Type: boolean
--confirm - Force confirmation prompts even when skip is configured
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
-q, --quiet - Only output ticket IDs
Type: boolean
--git/--no-git - Stage the archive/delete using 'git mv' or 'git rm'
Type: boolean
Default:
-s, --status - Filter by status (e.g., done)
Choices: backlog, todo, in_progress, review, done
Default:
Examples: backlog, todo, in_progress
--older-than - Filter tickets older than duration (e.g., '30 days', '2 weeks')
Default:
-e, --epic - Filter tickets by epic ID
Default:
--dry-run - Show what would be archived without doing it
Type: boolean
-b, --batch - Batch ID for undo operations
Default:

Examples:

gira ticket delete

gira ticket delete --status backlog

gira ticket delete --force

`gira ticket bulk-update`¶

Update multiple tickets with the same changes.

gira ticket bulk-update [ticket_ids] [options]

Arguments:

ticket_ids - List of ticket IDs to update (optional if using stdin) (optional)
Type: array
Pattern: ^[A-Z]{2,4}-\d+$
Examples: GIRA-123, GCM-456, PROJ-1

Options:

-t, --title - New title (applied to all tickets)
Default:
Min length: 3
Max length: 200
-d, --description - New description (applied to all tickets)
Default:
Max length: 5000
-s, --status - New status
Choices: backlog, todo, in_progress, review, done
Default:
Examples: backlog, todo, in_progress
-p, --priority - New priority
Choices: low, medium, high, critical
Default:
Examples: medium, high
--type - New ticket type
Default:
-a, --assignee - New assignee (use 'none' to clear)
Default:
Pattern: ^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$
Examples: user@example.com, john.doe@company.org
--add-labels - Labels to add (comma-separated)
Default:
--remove-labels - Labels to remove (comma-separated)
Default:
-e, --epic - New epic ID (use 'none' to clear)
Default:
--parent - New parent ID (use 'none' to clear)
Default:
-sp, --story-points - New story points estimate (use 0 to clear)
Type: integer
Default:
-o, --output - Output format: text, json
Choices: text, json, table, csv
Default: text
Examples: json, table
-q, --quiet - Only output ticket IDs
Type: boolean
--strict - Enforce strict assignee validation (no external assignees)
Type: boolean
--all-or-nothing - Fail entire operation if any ticket update fails
Type: boolean
--dry-run - Preview changes without saving them
Type: boolean
--stdin - Read CSV format from stdin (first column must be ticket ID)
Type: boolean
--csv-delimiter - CSV delimiter character (default: comma)
Default: ,
--skip-invalid - Skip invalid rows and continue processing
Type: boolean
--fail-on-error/--no-fail-on-error - Exit with error if any update fails (default: true)
Type: boolean
Default: True
--transaction - Execute all updates atomically with rollback on failure
Type: boolean

Examples:

gira ticket bulk-update

gira ticket bulk-update --status backlog --priority medium

gira ticket bulk-update --quiet

`gira ticket bulk-add-deps`¶

Add dependencies to multiple tickets at once.

gira ticket bulk-add-deps [ticket_ids] [options]

Arguments:

ticket_ids - Ticket IDs to add dependencies to (optional if using file input) (optional)
Type: array
Pattern: ^[A-Z]{2,4}-\d+$
Examples: GIRA-123, GCM-456, PROJ-1

Options:

-d, --deps - Comma-separated list of dependency IDs
Default:
--from-csv - CSV file with dependency mappings
Default:
--from-json - JSON file with dependency mappings
Default:
--no-reciprocal - Don't add reciprocal relationships
Type: boolean
--dry-run - Preview changes without applying them
Type: boolean
--validate-only - Only validate dependencies, don't apply
Type: boolean
Pattern: ^\d{4}-\d{2}-\d{2}$
Examples: 2025-01-20, 2025-12-31
-o, --output - Output format: text, json
Choices: text, json, table, csv
Default: text
Examples: json, table
-q, --quiet - Suppress progress output
Type: boolean
--transaction - Execute all operations atomically with rollback on failure
Type: boolean

Examples:

gira ticket bulk-add-deps

gira ticket bulk-add-deps --no-reciprocal

`gira ticket bulk-remove-deps`¶

Remove dependencies from multiple tickets at once.

gira ticket bulk-remove-deps [ticket_ids] [options]

Arguments:

ticket_ids - Ticket IDs to remove dependencies from (optional if using file input) (optional)
Type: array
Pattern: ^[A-Z]{2,4}-\d+$
Examples: GIRA-123, GCM-456, PROJ-1

Options:

-d, --deps - Comma-separated list of dependency IDs to remove
Default:
--from-csv - CSV file with dependency mappings to remove
Default:
--from-json - JSON file with dependency mappings to remove
Default:
--all - Remove all dependencies from specified tickets
Type: boolean
--no-reciprocal - Don't remove reciprocal relationships
Type: boolean
--dry-run - Preview changes without applying them
Type: boolean
-o, --output - Output format: text, json
Choices: text, json, table, csv
Default: text
Examples: json, table
-q, --quiet - Suppress progress output
Type: boolean
--transaction - Execute all operations atomically with rollback on failure
Type: boolean

Examples:

gira ticket bulk-remove-deps

gira ticket bulk-remove-deps --all

`gira ticket clear-deps`¶

Clear all dependencies from one or more tickets.

gira ticket clear-deps <ticket_ids> [options]

Arguments:

ticket_ids - Ticket IDs to clear all dependencies from (required)
Type: array
Pattern: ^[A-Z]{2,4}-\d+$
Examples: GIRA-123, GCM-456, PROJ-1

Options:

--no-reciprocal - Don't remove reciprocal relationships
Type: boolean
-f, --force - Skip confirmation prompt
Type: boolean
--dry-run - Preview changes without applying them
Type: boolean
-o, --output - Output format: text, json
Choices: text, json, table, csv
Default: text
Examples: json, table
-q, --quiet - Suppress progress output
Type: boolean
--transaction - Execute all operations atomically with rollback on failure
Type: boolean

Examples:

gira ticket clear-deps GIRA-123

gira ticket clear-deps GIRA-123 --no-reciprocal

`gira ticket commits`¶

List all commits associated with a ticket.

gira ticket commits <ticket_id> [options]

Arguments:

ticket_id - Ticket ID to show commits for (required)
Type: string
Pattern: ^[A-Z]{2,4}-\d+$
Examples: GIRA-123, GCM-456, PROJ-1

Options:

-n, --limit - Maximum number of commits to show
Type: integer
Default:
-f, --format - Output format: text, json
Choices: text, json, table, csv
Default: text
Examples: json, table
--json - Output as JSON (shorthand for --format json)
Type: boolean
--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 ticket commits GIRA-123

gira ticket commits GIRA-123 --format json

gira ticket commits GIRA-123 --json

`gira ticket blame`¶

Discover tickets associated with specific file lines.

gira ticket blame <files> [options]

Arguments:

files - File(s) to analyze for ticket references (required)
Type: array
Examples: .gira/config.json, /path/to/file.txt, ./relative/path.md

Options:

-L, --lines - Line range (e.g., '10,20' or '10,+5')
Default:
-f, --format - Output format: table, json, simple
Choices: text, json, table, csv
Default: table
Examples: json, table
--ids-only - Show only ticket IDs (implies simple format)
Type: boolean
--json - Output as JSON (shorthand for --format json)
Type: boolean
-C, --context - Show N lines of context around blamed lines
Type: integer
Default:
--history - Show full history of tickets that touched specific lines (requires -L)
Type: boolean
--no-cache - Bypass cache and force fresh blame analysis
Type: boolean
--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 ticket blame .gira/config.json

gira ticket blame .gira/config.json --format json

gira ticket blame .gira/config.json --ids-only

`gira ticket edit`¶

Edit a ticket (alias for update).

gira ticket edit [ticket_ids] [options]

Arguments:

ticket_ids - Ticket ID(s) to edit (supports patterns like 'GCM-1*', ranges like 'GCM-1..10', use '-' to read IDs from stdin, or omit for --stdin JSON) (optional)
Type: array
Pattern: ^[A-Z]{2,4}-\d+$
Examples: GIRA-123, GCM-456, PROJ-1

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
Choices: backlog, todo, in_progress, review, done
Default:
Examples: backlog, todo, in_progress
-p, --priority - New priority
Choices: low, medium, high, critical
Default:
Examples: medium, high
--type - New ticket type
Default:
-a, --assignee - New assignee (use 'none' to clear)
Default:
Pattern: ^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$
Examples: user@example.com, john.doe@company.org
--add-labels - Labels to add (comma-separated)
Default:
--remove-labels - Labels to remove (comma-separated)
Default:
-e, --epic - New epic ID (use 'none' to clear)
Default:
--parent - New parent ID (use 'none' to clear)
Default:
--sprint - Sprint ID to assign ticket to (use 'current' for active sprint, 'none' to clear)
Default:
-sp, --story-points - New story points estimate (use 0 to clear)
Type: integer
Default:
-o, --output - Output format: text, json
Choices: text, json, table, csv
Default: text
Examples: json, table
-q, --quiet - Only output ticket ID
Type: boolean
--strict - Enforce strict assignee validation (no external assignees)
Type: boolean
--stdin - Read JSON array of ticket 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
-f, --force - Legacy option (confirmation removed for AI-friendliness)
Type: boolean
--cf - Update custom field value in format 'name=value' (can be used multiple times)
Type: array
Default:
--remove-cf - Remove custom field by name (can be used multiple times)
Type: array
Default:

Examples:

gira ticket edit

gira ticket edit --status backlog --priority medium

gira ticket edit --quiet

`gira ticket mv`¶

Move ticket(s) to a different status (alias for move).

gira ticket mv [ticket_ids]<target_status> [options]

Arguments:

ticket_ids - Ticket ID(s) to move (use '-' to read from stdin) (optional)
Type: array
Pattern: ^[A-Z]{2,4}-\d+$
Examples: GIRA-123, GCM-456, PROJ-1
target_status - Target status to move ticket to (required)
Type: string
Pattern: ^\d{4}-\d{2}-\d{2}$
Examples: 2025-01-20, 2025-12-31

Options:

-p, --position - Position in new column (1-based)
Type: integer
Default:
-o, --output - Output format: text, json
Choices: text, json, table, csv
Default: text
Examples: json, table
-q, --quiet - Only output ticket ID
Type: boolean
--dry-run - Preview the move without performing it
Type: boolean
--git/--no-git - Stage the move using 'git mv'
Type: boolean
Default:
-f, --force - Skip confirmation prompt
Type: boolean
--force-transition - Skip workflow validation and force the transition
Type: boolean
-a, --assignee - Filter by assignee (use 'me' for current user)
Default:
Pattern: ^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$
Examples: user@example.com, john.doe@company.org
--from - Only move tickets from this status
Choices: backlog, todo, in_progress, review, done
Default:
Examples: backlog, todo, in_progress
-e, --epic - Filter tickets by epic ID
Default:
Pattern: ^EPIC-\d{3}$
Examples: EPIC-001, EPIC-002
-s, --sprint - Filter tickets by sprint ID (use 'current' for active sprint)
Default:
Pattern: ^SPRINT-\d{3}$
Examples: SPRINT-001, SPRINT-002
-c, --comment - Add comment to moved tickets
Default:
--assign - Assign tickets to user while moving
Default:
--add-label - Add label to moved tickets
Default:
--priority - Update priority while moving
Choices: low, medium, high, critical
Default:
Examples: medium, high
--check-dependencies - Check for blocking dependencies
Type: boolean
-b, --batch - Batch ID for undo operations
Default:

Examples:

gira ticket mv 2025-01-20

gira ticket mv 2025-01-20 --assignee user@example.com --priority medium

gira ticket mv 2025-01-20 --quiet

`gira ticket ls`¶

List tickets (alias for list).

gira ticket ls [options]

Options:

-q, --query - Query expression (e.g., 'status:todo AND priority:high')
Default:
Examples: ..py$, ^test_., (bug|fix):
-s, --status - Filter by status
Choices: backlog, todo, in_progress, review, done
Default:
Examples: backlog, todo, in_progress
-a, --assignee - Filter by assignee
Default:
Pattern: ^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$
Examples: user@example.com, john.doe@company.org
-t, --type - Filter by type
Default:
-p, --priority - Filter by priority
Choices: low, medium, high, critical
Default:
Examples: medium, high
-l, --label - Filter by label
Default:
--parent - Filter by parent ticket ID (show subtasks)
Default:
--blocked - Show only tickets blocked by unresolved dependencies
Type: boolean
--story-points-eq - Filter by exact story point value
Type: integer
Default:
--story-points-gt - Filter by story points greater than value
Type: integer
Default:
--story-points-lt - Filter by story points less than value
Type: integer
Default:
--created-after - Filter tickets created after date (YYYY-MM-DD)
Default:
Pattern: ^\d{4}-\d{2}-\d{2}$
Examples: 2025-01-20, 2025-12-31
--created-before - Filter tickets created before date (YYYY-MM-DD)
Default:
Pattern: ^\d{4}-\d{2}-\d{2}$
Examples: 2025-01-20, 2025-12-31
--updated-after - Filter tickets updated after date (YYYY-MM-DD)
Default:
Pattern: ^\d{4}-\d{2}-\d{2}$
Examples: 2025-01-20, 2025-12-31
--updated-before - Filter tickets updated before date (YYYY-MM-DD)
Default:
Pattern: ^\d{4}-\d{2}-\d{2}$
Examples: 2025-01-20, 2025-12-31
--due-after - Filter tickets due after date (YYYY-MM-DD)
Default:
--due-before - Filter tickets due before date (YYYY-MM-DD)
Default:
--due-on - Filter tickets due on specific date (YYYY-MM-DD)
Default:
--overdue - Show only tickets past their due date
Type: boolean
--has-comments - Show only tickets that have comments
Type: boolean
--no-comments - Show only tickets without comments
Type: boolean
--has-parent - Show only subtasks that have a parent ticket
Type: boolean
--no-parent - Show only tickets that are not subtasks
Type: boolean
--in-sprint - Filter tickets in a specific sprint
Default:
--not-in-sprint - Filter tickets not in a specific sprint
Default:
--not-in-epic - Filter tickets not linked to a specific epic
Default:
--epic - Filter tickets by epic ID (comma-separated for multiple epics)
Default:
--no-epic - Show only tickets without epic assignment (alias for --not-in-epic without value)
Type: boolean
--search - Search text in ticket fields (default: title and description)
Default:
--search-in - Specify fields to search: title, description, id, status, type, priority, assignee, reporter, labels, 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
--sort - Sort by: id, priority, created, updated, title, order
Default: id
-f, --format - Output format
Type: enum
Choices: TABLE, JSON, YAML, CSV, TSV, TEXT, IDS
Default: table
Examples: json, table
--ids-only - Show only ticket IDs
Type: boolean
--counts - Show summary counts
Type: boolean
--include-archived - Include archived tickets in results
Type: boolean
--fields - Comma-separated list of fields to include in JSON output (e.g., 'id,title,status' or use aliases like 'basics')
Default:
--filter-json - JSONPath expression to filter JSON output (e.g., '$[?(@.priority=="high")].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 ticket ls

gira ticket ls --status backlog --assignee user@example.com

gira ticket ls --blocked

`gira ticket rm`¶

Remove ticket(s) (alias for delete).

gira ticket rm [ticket_ids] [options]

Arguments:

ticket_ids - Ticket ID(s) to remove (use '-' to read from stdin) (optional)
Type: array
Pattern: ^[A-Z]{2,4}-\d+$
Examples: GIRA-123, GCM-456, PROJ-1

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
-q, --quiet - Only output ticket IDs
Type: boolean
--git/--no-git - Stage the archive/delete using 'git mv' or 'git rm'
Type: boolean
Default:
-s, --status - Filter by status (e.g., done)
Choices: backlog, todo, in_progress, review, done
Default:
Examples: backlog, todo, in_progress
--older-than - Filter tickets older than duration (e.g., '30 days', '2 weeks')
Default:
-e, --epic - Filter tickets by epic ID
Default:
--dry-run - Show what would be archived without doing it
Type: boolean
-b, --batch - Batch ID for undo operations
Default:

Examples:

gira ticket rm

gira ticket rm --status backlog

gira ticket rm --force

`gira ticket ticket estimate set`¶

Set story points for one or more tickets.

gira ticket ticket estimate set <story_points><ticket_ids> [options]

Arguments:

story_points - Story points to assign (0-100) (required)
Type: integer
ticket_ids - Ticket ID(s) to estimate (supports patterns) (required)
Type: array
Pattern: ^[A-Z]{2,4}-\d+$
Examples: GIRA-123, GCM-456, PROJ-1

Options:

-o, --output - Output format: text, json
Choices: text, json, table, csv
Default: text
Examples: json, table
-q, --quiet - Only output ticket IDs
Type: boolean
--dry-run - Preview changes without saving
Type: boolean

Examples:

gira ticket estimate set <story_points> GIRA-123

gira ticket estimate set <story_points> GIRA-123 --quiet

`gira ticket ticket estimate compare`¶

Compare two tickets side-by-side for relative estimation.

gira ticket ticket estimate compare <ticket_id_1><ticket_id_2> [options]

Arguments:

ticket_id_1 - First ticket ID (required)
Type: string
Pattern: ^[A-Z]{2,4}-\d+$
Examples: GIRA-123, GCM-456, PROJ-1
ticket_id_2 - Second ticket ID (required)
Type: string
Pattern: ^[A-Z]{2,4}-\d+$
Examples: GIRA-123, GCM-456, PROJ-1

Options:

-o, --output - Output format: text, json
Choices: text, json, table, csv
Default: text
Examples: json, table

Examples:

gira ticket estimate compare GIRA-123 GIRA-123

`gira ticket ticket estimate relative`¶

Show base ticket details while estimating other tickets.

gira ticket ticket estimate relative <base_ticket_id><ticket_ids> [options]

Arguments:

base_ticket_id - Base ticket ID for comparison (required)
Type: string
Pattern: ^[A-Z]{2,4}-\d+$
Examples: GIRA-123, GCM-456, PROJ-1
ticket_ids - Ticket ID(s) to estimate relative to base (required)
Type: array
Pattern: ^[A-Z]{2,4}-\d+$
Examples: GIRA-123, GCM-456, PROJ-1

Options:

-o, --output - Output format: text, json
Choices: text, json, table, csv
Default: text
Examples: json, table

Examples:

gira ticket estimate relative GIRA-123 GIRA-123

`gira ticket ticket estimate batch`¶

Interactive batch estimation of multiple tickets.

gira ticket ticket estimate batch <ticket_ids> [options]

Arguments:

ticket_ids - Ticket ID(s) to estimate interactively (required)
Type: array
Pattern: ^[A-Z]{2,4}-\d+$
Examples: GIRA-123, GCM-456, PROJ-1

Options:

-o, --output - Output format: text, json
Choices: text, json, table, csv
Default: text
Examples: json, table
--skip-estimated - Skip tickets that already have story points
Type: boolean

Examples:

gira ticket estimate batch GIRA-123

gira ticket estimate batch GIRA-123 --skip-estimated

`gira epic create`¶

Create a new epic.

gira epic create [title] [options]

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 create "User Authentication System" --description "Implement full auth flow"

gira epic create "Performance Optimization" --owner tech-lead@company.com --target-date 2025-03-01

`gira epic list`¶

List epics with optional filters.

gira epic list [options]

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 list

gira epic list --status backlog --format json

gira epic list --exact-match

`gira epic show`¶

Show details of a specific epic.

gira epic show <epic_id> [options]

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 show EPIC-001

gira epic show EPIC-001 --format json

gira epic show EPIC-001 --json

`gira epic update`¶

Update an existing epic.

gira epic update [epic_id] [options]

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 update EPIC-001 --status active

gira epic update EPIC-002 --add-ticket GCM-123 --add-ticket GCM-124

`gira epic delete`¶

Delete or archive an epic.

gira epic delete <epic_id> [options]

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:

gira epic delete EPIC-001

gira epic delete EPIC-001 --force

`gira sprint create`¶

Create a new sprint.

gira sprint create <name> [options]

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 create "Sprint 23" --goal "Complete authentication features" --duration 14

gira sprint create "Q1 Sprint 1" --start-date 2025-01-15 --duration 21

`gira sprint list`¶

List all sprints.

gira sprint list [options]

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 list

gira sprint list --status backlog --format json

gira sprint list --active

`gira sprint show`¶

Show details of a specific sprint.

gira sprint show <sprint_id> [options]

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 show SPRINT-001

gira sprint show SPRINT-001 --format json

gira sprint show SPRINT-001 --json

`gira sprint update`¶

Update sprint fields.

gira sprint update <sprint_id> [options]

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 update SPRINT-001

gira sprint update SPRINT-001 --status backlog

gira sprint update SPRINT-001 --dry-run

`gira sprint start`¶

Start a sprint (change status from planned to active).

gira sprint start <sprint_id>

Arguments:

sprint_id - Sprint ID to start (required)
Type: string
Pattern: ^SPRINT-\d{3}$
Examples: SPRINT-001, SPRINT-002

Examples:

gira sprint start SPRINT-001

`gira sprint close`¶

Close a sprint (change status to completed).

gira sprint close <sprint_id> [options]

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 close SPRINT-001

gira sprint close SPRINT-001 --retrospective/--no-retrospective

`gira sprint complete`¶

Complete a sprint (alias for close).

gira sprint complete <sprint_id> [options]

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 complete SPRINT-001

gira sprint complete SPRINT-001 --retrospective/--no-retrospective

`gira sprint delete`¶

Delete or archive a sprint.

gira sprint delete <sprint_id> [options]

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 delete SPRINT-001

gira sprint delete SPRINT-001 --force

`gira sprint assign`¶

Assign multiple tickets to a sprint.

gira sprint assign <sprint_id>[ticket_ids] [options]

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 assign SPRINT-001

gira sprint assign SPRINT-001 --from-context

`gira sprint unassign`¶

Remove tickets from sprint assignments.

gira sprint unassign [ticket_ids] [options]

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 unassign

gira sprint unassign --all

`gira sprint assign-by-dates`¶

Assign tickets to sprint based on completion dates.

gira sprint assign-by-dates <sprint_id> [options]

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-dates SPRINT-001

gira sprint assign-by-dates SPRINT-001 --include-assigned

`gira sprint assign-by-epic`¶

Assign all tickets from an epic to a sprint.

gira sprint assign-by-epic <sprint_id><epic_id> [options]

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-by-epic SPRINT-001 EPIC-001

gira sprint assign-by-epic SPRINT-001 EPIC-001 --status backlog

gira sprint assign-by-epic SPRINT-001 EPIC-001 --dry-run

`gira sprint assign-wizard`¶

Interactive wizard for assigning unassigned tickets to sprints.

gira sprint assign-wizard

Examples:

gira sprint assign-wizard

`gira sprint generate-historical`¶

Generate historical sprints from completed epics and tickets.

gira sprint generate-historical [options]

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:

gira sprint generate-historical

gira sprint generate-historical --include-orphaned/--no-orphaned

`gira comment add`¶

Add a comment to a ticket or epic.

gira comment add <entity_id> [options]

Arguments:

entity_id - Ticket or Epic ID to add comment to (e.g., GCM-123 or EPIC-001) (required)
Type: string

Options:

-c, --content - Comment content
Default:
--content-file - Read comment content from a file
Default:
Examples: comment.md, update-notes.txt, ./feedback/review-comments.md
-e, --editor - Open editor for comment
Type: boolean
-a, --attach - Attach file(s) to the comment (can be used multiple times)
Type: array
Default:

Examples:

gira comment add GCM-123

gira comment add PROJ-456 --message "Fixed the issue with login timeout"

`gira comment list`¶

List all comments on a ticket or epic.

gira comment list <entity_id> [options]

Arguments:

entity_id - Ticket or Epic ID to show comments for (e.g., GCM-123 or EPIC-001) (required)
Type: string

Options:

-l, --limit - Limit number of comments shown
Type: integer
Default:
-r, --reverse - Show oldest comments first
Type: boolean
-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
--fields - Comma-separated list of fields to include in JSON output (e.g., 'id,author,content' or use aliases like 'comment_basics')
Default:
--filter-json - JSONPath expression to filter JSON output (e.g., '$[?(@.author=="john@example.com")].content')
Default:
-v, --verbose - Show detailed information including attachment details
Type: boolean
--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 comment list <entity_id>

gira comment list <entity_id> --format json

gira comment list <entity_id> --reverse

`gira comment delete`¶

Delete a comment from a ticket or epic.

gira comment delete <entity_id><comment_id> [options]

Arguments:

entity_id - Ticket or Epic ID (e.g., GCM-123 or EPIC-001) (required)
Type: string
comment_id - Comment ID to delete (required)
Type: string

Options:

-f, --force - Skip confirmation prompt
Type: boolean

Examples:

gira comment delete <entity_id> <comment_id>

gira comment delete <entity_id> <comment_id> --force

`gira comment attach`¶

Attach files to an existing comment.

gira comment attach [entity_id][comment_id][file_paths] [options]

Arguments:

entity_id - Ticket or Epic ID (e.g., GCM-123, 123, or EPIC-001) (optional)
Type: string
comment_id - Comment ID to attach files to (optional)
Type: string
file_paths - Path(s) to file(s) to attach (optional)
Type: array
Examples: .gira/config.json, /path/to/file.txt, ./relative/path.md

Options:

-i, --interactive - Run in interactive mode
Type: boolean
-n, --note - Optional note for the attachments
Default:
-u, --user - User adding the attachment (defaults to git user)
Default:

Examples:

gira comment attach

gira comment attach --interactive

`gira comment detach`¶

gira comment detach <entity_id><comment_id>[filenames] [options]

Arguments:

entity_id - Ticket or Epic ID (e.g., GCM-123 or EPIC-001) (required)
Type: string
comment_id - Comment ID to remove attachments from (required)
Type: string
filenames - Filename(s) to remove (if not specified, use --all) (optional)
Type: array
Examples: .gira/config.json, /path/to/file.txt, ./relative/path.md

Options:

-a, --all - Remove all attachments from the comment
Type: boolean
-f, --force - Skip confirmation prompt
Type: boolean

Examples:

gira comment detach <entity_id> <comment_id>

gira comment detach <entity_id> <comment_id> --all

`gira comment download`¶

gira comment download <entity_id><comment_id>[filenames] [options]

Arguments:

entity_id - Ticket or Epic ID (e.g., GCM-123 or EPIC-001) (required)
Type: string
comment_id - Comment ID to download attachments from (required)
Type: string
filenames - Specific filename(s) to download (downloads all if not specified) (optional)
Type: array
Examples: .gira/config.json, /path/to/file.txt, ./relative/path.md

Options:

-o, --output - Output directory (defaults to current directory)
Choices: text, json, table, csv
Default:
Examples: json, table
-a, --all - Download all attachments (default if no filenames specified)
Type: boolean
-f, --overwrite - Overwrite existing files
Type: boolean

Examples:

gira comment download <entity_id> <comment_id>

gira comment download <entity_id> <comment_id> --all

`gira config set`¶

Set a configuration value.

gira config set <key><value> [options]

Arguments:

key - Configuration key (e.g., user.name) (required)
Type: string
value - Configuration value (required)
Type: string

Options:

-g, --global - Set in global config (not implemented)
Type: boolean
Examples: .py, **/.json, src/**/*.ts

Examples:

gira config set <key> <value>

gira config set <key> <value> --global

`gira config get`¶

gira config get [key] [options]

Arguments:

key - Configuration key to get (show all if not specified) (optional)
Type: string

Options:

-l, --list - List all configuration keys
Type: boolean
-f, --format - Output format: table, json
Choices: text, json, table, csv
Default: table
Examples: json, table
--json - Output as JSON (shorthand for --format json)
Type: boolean
--fields - Comma-separated list of fields to include in JSON output (for filtering config keys)
Default:

Examples:

gira config get

gira config get --format json

gira config get --list

`gira config reset`¶

Reset configuration to default values.

gira config reset [key] [options]

Arguments:

key - Configuration key to reset (reset all if not specified) (optional)
Type: string

Options:

-f, --force - Skip confirmation prompt
Type: boolean

Examples:

gira config reset

gira config reset --force

`gira config rename-prefix`¶

Rename the ticket ID prefix for the entire project.

gira config rename-prefix <new_prefix> [options]

Arguments:

new_prefix - New ticket ID prefix (2-5 uppercase letters) (required)
Type: string

Options:

-f, --force - Skip confirmation prompts
Type: boolean

Examples:

gira config rename-prefix <new_prefix>

gira config rename-prefix <new_prefix> --force

`gira metrics overview`¶

Display comprehensive metrics overview for the project.

gira metrics overview [options]

Options:

-f, --format - Output format: human, json
Choices: text, json, table, csv
Default: human
Examples: json, table
-d, --days - Number of days to analyze for trends
Type: integer
Default: 30
Examples: 7, 14, 30
--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 metrics overview

gira metrics overview --format json

gira metrics overview --color

`gira metrics velocity`¶

Display team velocity trends across sprints.

gira metrics velocity [options]

Options:

-n, --limit - Number of sprints to display
Type: integer
Default: 5
-f, --format - Output format: human, json, csv
Choices: text, json, table, csv
Default: human
Examples: json, table
--all - Show all sprints including active ones
Type: boolean
--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 metrics velocity

gira metrics velocity --format json

gira metrics velocity --all

`gira metrics trends`¶

Display ticket creation, completion, and backlog trends over time.

gira metrics trends [options]

Options:

-d, --days - Number of days to analyze
Type: integer
Default: 30
Examples: 7, 14, 30
-f, --format - Output format: human, json, csv
Choices: text, json, table, csv
Default: human
Examples: json, table
--type - Filter by ticket type
Default:
--priority - Filter by priority
Choices: low, medium, high, critical
Default:
Examples: medium, high
--assignee - Filter by assignee
Default:
Pattern: ^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$
Examples: user@example.com, john.doe@company.org
--epic - Filter by epic 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 metrics trends

gira metrics trends --format json --priority medium

gira metrics trends --color

`gira metrics duration`¶

Analyze time tickets spend in each status to identify bottlenecks.

gira metrics duration [options]

Options:

-d, --days - Analyze tickets from last N days
Type: integer
Default:
Examples: 7, 14, 30
-f, --format - Output format: human, json, csv
Choices: text, json, table, csv
Default: human
Examples: json, table
--type - Filter by ticket type
Default:
--priority - Filter by priority
Choices: low, medium, high, critical
Default:
Examples: medium, high
--no-cache - Bypass cache and force fresh analysis
Type: boolean
--no-progress - Disable progress indicator
Type: boolean
--force-batch - Force batch git operations (for testing)
Type: boolean
--working-hours - Calculate durations using business hours only
Type: boolean
Examples: 7, 14, 30
--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 metrics duration

gira metrics duration --format json --priority medium

gira metrics duration --no-cache

`gira completion install`¶

Install shell completion for Gira.

gira completion install <shell> [options]

Arguments:

shell - Shell type: bash, zsh, fish (required)
Type: string

Options:

--path - Custom installation path
Default:
Examples: .gira/config.json, /path/to/file.txt, ./relative/path.md
-v, --verbose - Show detailed path selection process
Type: boolean

Examples:

gira completion install <shell>

gira completion install <shell> --verbose

`gira completion show`¶

Show completion script for manual installation.

gira completion show <shell>

Arguments:

shell - Shell type: bash, zsh, fish (required)
Type: string

Examples:

gira completion show <shell>

`gira archive ticket`¶

Archive a single ticket.

gira archive ticket <ticket_id> [options]

Arguments:

ticket_id - ID of the ticket to archive (required)
Type: string
Pattern: ^[A-Z]{2,4}-\d+$
Examples: GIRA-123, GCM-456, PROJ-1

Options:

-f, --force - Skip confirmation prompt
Type: boolean
--dry-run - Preview the archive operation without performing it
Type: boolean
--git/--no-git - Use git operations for archiving (auto-detected if not specified)
Type: boolean
Default:

Examples:

gira archive ticket GIRA-123

gira archive ticket GIRA-123 --force

`gira archive done`¶

Archive all done tickets with optional filtering.

gira archive done [options]

Options:

--dry-run - Preview what would be archived
Type: boolean
--before - Archive tickets completed before this date (YYYY-MM-DD)
Default:
--older-than - Archive tickets older than N days
Type: integer
Default:
--sprint - Archive tickets from specific sprint
Default:
-f, --force - Skip confirmation prompt
Type: boolean

Examples:

gira archive done

gira archive done --dry-run

`gira archive old`¶

Archive tickets older than specified number of days.

gira archive old [options]

Options:

-d, --days - Archive tickets older than N days
Type: integer
Default: 30
Examples: 7, 14, 30
-s, --status - Only archive tickets with this status
Choices: backlog, todo, in_progress, review, done
Default: done
Examples: backlog, todo, in_progress
--dry-run - Preview what would be archived
Type: boolean
-f, --force - Skip confirmation prompt
Type: boolean

Examples:

gira archive old

gira archive old --status backlog

gira archive old --dry-run

`gira archive list`¶

List archived tickets with optional filtering.

gira archive list [options]

Options:

-m, --month - Show tickets from specific month (YYYY-MM)
Default:
-s, --search - Search in ticket title and description
Default:
-l, --limit - Maximum number of tickets to show
Type: integer
Default:
-f, --format - Output format
Type: enum
Choices: TABLE, JSON, YAML, CSV, TSV, TEXT, IDS
Default: table
Examples: json, table
--stats - Show archive statistics
Type: boolean
--filter-json - JSONPath expression to filter JSON output (e.g., '$[?(@.priority=="high")].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 archive list

gira archive list --format json

gira archive list --stats

`gira archive restore`¶

Restore an archived ticket back to the board.

gira archive restore <ticket_id> [options]

Arguments:

ticket_id - ID of the ticket to restore (required)
Type: string
Pattern: ^[A-Z]{2,4}-\d+$
Examples: GIRA-123, GCM-456, PROJ-1

Options:

-s, --status - Status to restore ticket to
Choices: backlog, todo, in_progress, review, done
Default: done
Examples: backlog, todo, in_progress
-f, --force - Skip confirmation prompt
Type: boolean
--git/--no-git - Use git operations for restoration (auto-detected if not specified)
Type: boolean
Default:

Examples:

gira archive restore GIRA-123

gira archive restore GIRA-123 --status backlog

gira archive restore GIRA-123 --force

`gira archive suggest`¶

Suggest tickets to archive based on various criteria.

gira archive suggest [options]

Options:

-e, --execute - Execute the suggestions (archive the tickets)
Type: boolean
-c, --category - Filter by category: old_done, completed_epics, completed_sprints, stale_backlog
Default:
-l, --limit - Maximum number of suggestions per category
Type: integer
Default: 50

Examples:

gira archive suggest

gira archive suggest --execute

`gira migrate hybrid`¶

Migrate the project to use hybrid directory structure for backlog tickets.

gira migrate hybrid [options]

Options:

--dry-run - Preview migration without making changes
Type: boolean
--verify - Verify current migration status without changes
Type: boolean
-f, --force - Skip confirmation prompts
Type: boolean

Examples:

gira migrate hybrid

gira migrate hybrid --dry-run

`gira team list`¶

List all team members.

gira team list [options]

Options:

-r, --role - Filter by role
Default:
--active-only - Show only active members
Type: boolean
-f, --format - Output format
Type: enum
Choices: TABLE, JSON, YAML, CSV, TSV, TEXT, IDS
Default: table
Examples: json, table
--json - Output as JSON (shorthand for --format json)
Type: boolean
--filter-json - JSONPath expression to filter JSON output (e.g., '$[?(@.active==true)].email')
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 team list

gira team list --format json

gira team list --active-only

`gira team add`¶

Add a new team member.

gira team add <email> [options]

Arguments:

email - Email address of the team member (required)
Type: string
Pattern: ^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$
Examples: user@example.com, john.doe@company.org

Options:

-n, --name - Display name
Default:
-u, --username - Username for @mentions
Default:
-r, --role - Role in the project
Default: developer
-a, --alias - Alias for quick assignment (can be used multiple times)
Type: array
Default:
-i, --interactive - Interactive mode
Type: boolean

Examples:

gira team add user@example.com

gira team add user@example.com --interactive

`gira team remove`¶

Remove a team member.

gira team remove <identifier> [options]

Arguments:

identifier - Email, username, or alias of the team member to remove (required)
Type: string

Options:

-f, --force - Skip confirmation prompt
Type: boolean

Examples:

gira team remove <identifier>

gira team remove <identifier> --force

`gira team discover`¶

Discover team members from Git commit history.

gira team discover [options]

Options:

-l, --limit - Maximum number of commits to analyze
Type: integer
Default: 50
--add-all - Add all discovered members without prompting
Type: boolean
--dry-run - Show what would be added without making changes
Type: boolean

Examples:

gira team discover

gira team discover --add-all

`gira docs generate`¶

Generate documentation for Gira including CLI reference, AI agent guides, and workflow documentation.

gira docs generate

Examples:

gira docs generate

`gira export json`¶

Export tickets to JSON format

gira export json [options]

Options:

-o, --output - Output file path. If not specified, outputs to stdout
Choices: text, json, table, csv
Default:
Examples: json, table
--include-archived - Include archived tickets in the export
Type: boolean
--pretty - Pretty-print JSON output with indentation
Type: boolean
--fields - Comma-separated list of fields to include (default: all fields)
Default:

Examples:

gira export json

gira export json --include-archived

`gira export csv`¶

Export tickets to CSV format

gira export csv [options]

Options:

-o, --output - Output file path. If not specified, outputs to stdout
Choices: text, json, table, csv
Default:
Examples: json, table
--include-archived - Include archived tickets in the export
Type: boolean
--fields - Comma-separated list of fields to include (default: common fields)
Default:
--delimiter - Field delimiter character (default: comma)
Default: ,
--quote-all - Quote all fields, not just those containing special characters
Type: boolean

Examples:

gira export csv

gira export csv --include-archived

`gira export md`¶

Export tickets to Markdown format

gira export md [options]

Options:

-o, --output - Output file path. If not specified, outputs to stdout
Choices: text, json, table, csv
Default:
Examples: json, table
--include-archived - Include archived tickets in the export
Type: boolean
--fields - Comma-separated list of fields to include (default: common fields)
Default:

Examples:

gira export md

gira export md --include-archived

`gira hooks install`¶

Install Git hooks for Gira integration.

gira hooks install [options]

Options:

-h, --hook - Specific hooks to install (can be used multiple times). If not specified, installs all available hooks.
Type: array
Default:
-f, --force - Overwrite existing hooks without prompting
Type: boolean
--dry-run - Show what would be installed without actually installing
Type: boolean

Examples:

gira hooks install

gira hooks install --force

`gira hooks uninstall`¶

Uninstall Git hooks for Gira integration.

gira hooks uninstall [options]

Options:

-h, --hook - Specific hooks to uninstall (can be used multiple times). If not specified, uninstalls all Gira hooks.
Type: array
Default:
-f, --force - Remove hooks without prompting
Type: boolean

Examples:

gira hooks uninstall

gira hooks uninstall --force

`gira hooks status`¶

Show the status of Git hooks for Gira integration.

gira hooks status

Examples:

gira hooks status

`gira ext list`¶

List all available hooks and their status.

gira ext list [options]

Options:

-v, --verbose - Show detailed information about each hook
Type: boolean

Examples:

gira ext list

gira ext list --verbose

`gira ext init`¶

Initialize the hooks directory with example templates.

gira ext init [options]

Options:

-f, --force - Overwrite existing hooks directory
Type: boolean

Examples:

gira ext init

gira ext init --force

`gira ext install`¶

Install a specific hook template.

gira ext install <hook_name> [options]

Arguments:

hook_name - Name of the hook template to install (required)
Type: string

Options:

-f, --force - Overwrite existing hook
Type: boolean

Examples:

gira ext install <hook_name>

gira ext install <hook_name> --force

`gira ext test`¶

Test a hook with sample data.

gira ext test <hook_name> [options]

Arguments:

hook_name - Name of the hook to test (required)
Type: string

Options:

--data - JSON string with test event data
Default:

Examples:

gira ext test <hook_name>

`gira ext enable`¶

Enable hook execution.

gira ext enable

Examples:

gira ext enable

`gira ext disable`¶

Disable hook execution.

gira ext disable

Examples:

gira ext disable

`gira ext show`¶

Display the contents of a hook file.

gira ext show <hook_name>

Arguments:

hook_name - Name of the hook to display (required)
Type: string

Examples:

gira ext show <hook_name>

`gira webhook add`¶

Add a new webhook endpoint.

gira webhook add <name><url> [options]

Arguments:

name - Name for the webhook endpoint (required)
Type: string
url - Webhook URL to send events to (required)
Type: string

Options:

-e, --events - Comma-separated list of events to send (or '*' for all)
Default: ticket_created,ticket_updated,ticket_moved
-t, --template - Template to apply for formatting (slack, discord, etc.)
Default:
-f, --filter - Filter events using Gira query language
Default:
Examples: ..py$, ^test_., (bug|fix):
--auth-type - Authentication type (bearer, api_key, basic)
Default:
--auth-token - Authentication token (use ${ENV_VAR} for environment variables)
Default:
--auth-key - Authentication header key (for api_key auth)
Default:
--auth-username - Username for basic auth (use ${ENV_VAR} for environment variables)
Default:
--auth-password - Password for basic auth (use ${ENV_VAR} for environment variables)
Default:
--timeout - Request timeout in seconds (default: global setting)
Type: integer
Default:
--retry-attempts - Number of retry attempts (default: global setting)
Type: integer
Default:
--headers - Additional headers as JSON string
Default:
--enabled/--disabled - Whether the webhook is enabled
Type: boolean
Default: True

Examples:

gira webhook add <name> <url>

gira webhook add <name> <url> --enabled/--disabled

`gira webhook remove`¶

Remove a webhook endpoint.

gira webhook remove <name> [options]

Arguments:

name - Name of the webhook endpoint to remove (required)
Type: string

Options:

-f, --force - Skip confirmation prompt
Type: boolean

Examples:

gira webhook remove <name>

gira webhook remove <name> --force

`gira webhook list`¶

List configured webhook endpoints.

gira webhook list [options]

Options:

-v, --verbose - Show detailed information about each webhook
Type: boolean

Examples:

gira webhook list

gira webhook list --verbose

`gira webhook test`¶

Test a webhook endpoint with a sample payload.

gira webhook test <name> [options]

Arguments:

name - Name of the webhook endpoint to test (required)
Type: string

Options:

-e, --event - Event type for the test payload (default: test)
Default: test

Examples:

gira webhook test <name>

`gira webhook enable`¶

Enable webhooks globally or a specific webhook endpoint.

gira webhook enable [name]

Arguments:

name - Name of specific webhook to enable (omit to enable globally) (optional)
Type: string

Examples:

gira webhook enable

`gira webhook disable`¶

Disable webhooks globally or a specific webhook endpoint.

gira webhook disable [name] [options]

Arguments:

name - Name of specific webhook to disable (omit to disable globally) (optional)
Type: string

Options:

-f, --force - Skip confirmation prompt for global disable
Type: boolean

Examples:

gira webhook disable

gira webhook disable --force

`gira webhook health`¶

Check webhook endpoint health and connectivity.

gira webhook health [name] [options]

Arguments:

name - Name of webhook to check (omit to check all) (optional)
Type: string

Options:

-v, --verbose - Show detailed health information
Type: boolean

Examples:

gira webhook health

gira webhook health --verbose

`gira webhook stats`¶

Show webhook delivery statistics.

gira webhook stats [name]

Arguments:

name - Name of webhook to show stats for (omit to show all) (optional)
Type: string

Examples:

gira webhook stats

`gira webhook webhook filter help`¶

Show help for webhook filter expressions.

gira webhook webhook filter help

Examples:

gira webhook filter help

`gira webhook webhook filter validate`¶

Validate a webhook filter expression.

gira webhook webhook filter validate <expression>

Arguments:

expression - Filter expression to validate (required)
Type: string

Examples:

gira webhook filter validate <expression>

`gira cache clear`¶

Clear cached data.

gira cache clear [options]

Options:

--all - Clear all caches including git and blame caches
Type: boolean
--git - Clear only git-related cache
Type: boolean
--blame - Clear only blame-related cache
Type: boolean
--tickets - Clear only ticket-related cache
Type: boolean
--metrics - Clear only metrics cache
Type: boolean
--ticket-id - Clear cache for a specific ticket
Default:
Pattern: ^[A-Z]{2,4}-\d+$
Examples: GIRA-123, GCM-456, PROJ-1

Examples:

gira cache clear

gira cache clear --all

`gira cache status`¶

Show cache statistics.

gira cache status

Examples:

gira cache status

`gira storage configure`¶

Configure storage backend for attachments.

gira storage configure [options]

Options:

-p, --provider - Storage provider (s3, r2, b2, gcs, azure)
Default:
-b, --bucket - Storage bucket name
Default:
--test/--no-test - Test connection after configuration
Type: boolean
Default: True
--update-project/--no-update-project - Update project configuration
Type: boolean
Default: True
Pattern: ^\d{4}-\d{2}-\d{2}$
Examples: 2025-01-20, 2025-12-31
--encrypt/--no-encrypt - Encrypt stored credentials
Type: boolean

Examples:

gira storage configure

gira storage configure --test/--no-test

`gira storage status`¶

Check storage configuration and credential status.

gira storage status

Examples:

gira storage status

`gira storage validate`¶

Validate storage credentials and show detailed information.

gira storage validate [options]

Options:

-p, --provider - Storage provider to validate (s3, r2, b2, gcs, azure)
Default:
--help-credentials - Show credential help for providers
Type: boolean

Examples:

gira storage validate

gira storage validate --help-credentials

`gira attachment add`¶

Add attachment(s) to a ticket or epic.

gira attachment add <entity_id><file_paths> [options]

Arguments:

entity_id - Ticket or epic ID to attach file to (e.g., PROJ-123, 123, or EPIC-001) (required)
Type: string
file_paths - Path(s) to file(s) or directory to attach (required)
Type: array
Examples: .gira/config.json, /path/to/file.txt, ./relative/path.md

Options:

-n, --note - Optional description or note for the attachments
Default:
-t, --type - Entity type: ticket or epic (auto-detected if not specified)
Default:
--commit/--no-commit - Automatically commit the attachment pointers
Type: boolean
Default: True
-u, --user - User adding the attachment (defaults to git user)
Default:
-i, --include - Include only files matching pattern (e.g., '*.pdf')
Default:
-e, --exclude - Exclude files matching pattern (e.g., '*.tmp')
Default:

Examples:

gira attachment add <entity_id> .gira/config.json

gira attachment add <entity_id> .gira/config.json --commit/--no-commit

`gira attachment cat`¶

gira attachment cat <entity_id><filename> [options]

Arguments:

entity_id - Entity ID (e.g., GCM-123 or EPIC-001) (required)
Type: string
filename - Attachment filename to stream (required)
Type: string
Examples: .gira/config.json, /path/to/file.txt, ./relative/path.md

Options:

-t, --type - Entity type (ticket or epic)
Default:

Examples:

gira attachment cat <entity_id> .gira/config.json

`gira attachment download`¶

Download attachment(s) to specified location without opening.

gira attachment download <entity_id><patterns> [options]

Arguments:

entity_id - Entity ID (e.g., GCM-123 or EPIC-001) (required)
Type: string
patterns - Attachment filename(s) or pattern(s) to download (required)
Type: array

Options:

-t, --type - Entity type (ticket or epic)
Default:
-o, --output - Output directory (defaults to current directory)
Choices: text, json, table, csv
Default:
Examples: json, table
-q, --quiet - Suppress progress output
Type: boolean
-f, --force - Overwrite existing files without prompting
Type: boolean
-a, --all - Download all attachments for the entity
Type: boolean
Examples: .gira/config.json, /path/to/file.txt, ./relative/path.md

Examples:

gira attachment download <entity_id> <patterns>

gira attachment download <entity_id> <patterns> --quiet

`gira attachment list`¶

List all attachments for a ticket or epic.

gira attachment list <entity_id> [options]

Arguments:

entity_id - Ticket or epic ID to list attachments for (e.g., PROJ-123 or EPIC-001) (required)
Type: string

Options:

-t, --type - Entity type: ticket or epic (auto-detected if not specified)
Default:
-f, --format - Output format: table, json, or simple
Choices: text, json, table, csv
Default: table
Examples: json, table
--file-type - Filter by file type/extension (e.g., pdf, png, xlsx)
Default:
Examples: .gira/config.json, /path/to/file.txt, ./relative/path.md
--after - Show attachments uploaded after date (YYYY-MM-DD)
Default:
--before - Show attachments uploaded before date (YYYY-MM-DD)
Default:
-p, --show-provider - Show storage provider details
Type: boolean

Examples:

gira attachment list <entity_id>

gira attachment list <entity_id> --format json

gira attachment list <entity_id> --show-provider

`gira attachment open`¶

gira attachment open <entity_id><attachment_ids> [options]

Arguments:

entity_id - Entity ID (e.g., GCM-123 or EPIC-001) (required)
Type: string
attachment_ids - Attachment ID(s) to open (required)
Type: array

Options:

-t, --type - Entity type (ticket or epic)
Default:
-d, --download-only - Download without opening
Type: boolean
-o, --output - Output directory for downloads
Choices: text, json, table, csv
Default:
Examples: json, table
--no-cache - Skip cache and download fresh copy
Type: boolean
-f, --force - Overwrite existing files
Type: boolean

Examples:

gira attachment open <entity_id> <attachment_ids>

gira attachment open <entity_id> <attachment_ids> --download-only

`gira attachment remove`¶

gira attachment remove <entity_id><attachment_ids> [options]

Arguments:

entity_id - Entity ID (e.g., GCM-123 or EPIC-001) (required)
Type: string
attachment_ids - Attachment filename(s) or ID(s) to remove (required)
Type: array

Options:

-t, --type - Entity type (ticket or epic)
Default:
-r, --delete-remote - Also delete files from remote storage
Type: boolean
-n, --dry-run - Preview changes without executing
Type: boolean
-f, --force - Skip confirmation prompts
Type: boolean
--no-commit - Don't auto-commit changes to Git
Type: boolean

Examples:

gira attachment remove <entity_id> <attachment_ids>

gira attachment remove <entity_id> <attachment_ids> --delete-remote

`gira operation status`¶

Check the status of an async operation.

gira operation status <operation_id> [options]

Arguments:

operation_id - Operation ID to check (required)
Type: string

Options:

-o, --output - Output format: text, json
Choices: text, json, table, csv
Default: text
Examples: json, table

Examples:

gira operation status <operation_id>

`gira operation list`¶

List async operations.

gira operation list [options]

Options:

--active - Show only active operations
Type: boolean
-n, --limit - Maximum operations to show
Type: integer
Default: 10
-o, --output - Output format: text, json
Choices: text, json, table, csv
Default: text
Examples: json, table

Examples:

gira operation list

gira operation list --active

`gira operation cancel`¶

Cancel a running operation.

gira operation cancel <operation_id> [options]

Arguments:

operation_id - Operation ID to cancel (required)
Type: string

Options:

-f, --force - Skip confirmation
Type: boolean

Examples:

gira operation cancel <operation_id>

gira operation cancel <operation_id> --force

`gira operation wait`¶

Wait for an operation to complete.

gira operation wait <operation_id> [options]

Arguments:

operation_id - Operation ID to wait for (required)
Type: string

Options:

-t, --timeout - Timeout in seconds
Type: integer
Default: 300
-q, --quiet - Suppress progress output
Type: boolean

Examples:

gira operation wait <operation_id>

gira operation wait <operation_id> --quiet

`gira operation resume`¶

Resume operations from persistence.

gira operation resume [operation_id] [options]

Arguments:

operation_id - Specific operation to resume (optional)
Type: string

Options:

--all - Resume all incomplete operations
Type: boolean

Examples:

gira operation resume

gira operation resume --all

`gira operation cleanup`¶

Clean up old operation snapshots.

gira operation cleanup [options]

Options:

-d, --days - Delete operations older than N days
Type: integer
Default: 7
Examples: 7, 14, 30
--dry-run - Show what would be deleted
Type: boolean

Examples:

gira operation cleanup

gira operation cleanup --dry-run

`gira ai status`¶

Show AI documentation files and integration status.

gira ai status

Examples:

gira ai status

`gira ai setup`¶

Set up AI documentation for the project.

gira ai setup [options]

Options:

-f, --force - Force setup even if files exist
Type: boolean
--non-interactive - Run without prompts
Type: boolean

Examples:

gira ai setup

gira ai setup --force

`gira ai ai-help`¶

Show AI-optimized command examples and patterns.

gira ai ai-help [agent]

Arguments:

agent - Specific AI agent (claude, gemini, etc.) (optional)
Type: string

Examples:

gira ai ai-help

`gira ai examples`¶

Alias for ai-help command.

gira ai examples [agent]

Arguments:

agent - Specific AI agent (claude, gemini, etc.) (optional)
Type: string

Examples:

gira ai examples

`gira context show`¶

Display comprehensive context for a ticket (explicit show subcommand).

gira context show <ticket_id> [options]

Arguments:

ticket_id - Ticket ID to show context for (required)
Type: string
Pattern: ^[A-Z]{2,4}-\d+$
Examples: GIRA-123, GCM-456, PROJ-1

Options:

-o, --output - Output format: text, json
Choices: text, json, table, csv
Default: text
Examples: json, table
-f, --fields - Comma-separated list of fields to include
Default:
--include-archived - Include archived tickets in related items
Type: boolean

Examples:

gira context show GIRA-123

gira context show GIRA-123 --include-archived

`gira context tree`¶

Show visual dependency tree for a ticket.

gira context tree <ticket_id> [options]

Arguments:

ticket_id - Ticket ID to show dependency tree for (required)
Type: string
Pattern: ^[A-Z]{2,4}-\d+$
Examples: GIRA-123, GCM-456, PROJ-1

Options:

-d, --max-depth - Maximum tree depth
Type: integer
Default: 3
--include-archived - Include archived tickets
Type: boolean

Examples:

gira context tree GIRA-123

gira context tree GIRA-123 --include-archived

`gira context epic`¶

Show ticket in the context of its epic.

gira context epic <ticket_id> [options]

Arguments:

ticket_id - Ticket ID to show in epic context (required)
Type: string
Pattern: ^[A-Z]{2,4}-\d+$
Examples: GIRA-123, GCM-456, PROJ-1

Options:

-a, --all - Show all epic tickets, not just related
Type: boolean

Examples:

gira context epic GIRA-123

gira context epic GIRA-123 --all

`gira context timeline`¶

Show activity timeline for a ticket.

gira context timeline <ticket_id> [options]

Arguments:

ticket_id - Ticket ID to show timeline for (required)
Type: string
Pattern: ^[A-Z]{2,4}-\d+$
Examples: GIRA-123, GCM-456, PROJ-1

Options:

-d, --days - Number of days to show
Type: integer
Default: 30
Examples: 7, 14, 30

Examples:

gira context timeline GIRA-123

`gira context related`¶

Find tickets related by various criteria.

gira context related <ticket_id> [options]

Arguments:

ticket_id - Ticket ID to find related tickets for (required)
Type: string
Pattern: ^[A-Z]{2,4}-\d+$
Examples: GIRA-123, GCM-456, PROJ-1

Options:

-m, --max - Maximum results per category
Type: integer
Default: 10

Examples:

gira context related GIRA-123

`gira context references`¶

Show where this ticket is referenced (comments, commits).

gira context references <ticket_id>

Arguments:

ticket_id - Ticket ID to find references for (required)
Type: string
Pattern: ^[A-Z]{2,4}-\d+$
Examples: GIRA-123, GCM-456, PROJ-1

Examples:

gira context references GIRA-123

`gira workflow show`¶

Display available workflow transitions for a ticket.

gira workflow show <ticket_id> [options]

Arguments:

ticket_id - Ticket ID to show workflow for (required)
Type: string
Pattern: ^[A-Z]{2,4}-\d+$
Examples: GIRA-123, GCM-456, PROJ-1

Options:

-c, --check - Check if a specific transition is valid
Default:
-o, --output - Output format: text, json
Choices: text, json, table, csv
Default: text
Examples: json, table
-v, --visual - Show visual workflow position
Type: boolean

Examples:

gira workflow show GIRA-123

gira workflow show GIRA-123 --visual

`gira workflow validate`¶

Validate all tickets against workflow rules.

gira workflow validate [options]

Options:

-s, --status - Only validate tickets in this status
Choices: backlog, todo, in_progress, review, done
Default:
Examples: backlog, todo, in_progress
-t, --type - Only validate tickets of this type
Choices: story, task, bug, epic, feature, subtask
Default:
Examples: task, bug, feature
-e, --epic - Only validate tickets in this epic
Default:
-o, --output - Output format: text, json
Choices: text, json, table, csv
Default: text
Examples: json, table
-f, --fix - Attempt to auto-fix violations where possible
Type: boolean

Examples:

gira workflow validate

gira workflow validate --status backlog

gira workflow validate --fix

`gira workflow apply`¶

Apply a predefined workflow template.

gira workflow apply <template> [options]

Arguments:

template - Template name (scrum, kanban, support-desk, bug-tracking) (required)
Type: string

Options:

-f, --force - Force apply even if board config exists
Type: boolean

Examples:

gira workflow apply <template>

gira workflow apply <template> --force

`gira workflow templates`¶

List available workflow templates.

gira workflow templates

Examples:

gira workflow templates

`gira workflow rule`¶

Manage custom workflow rules.

gira workflow rule <action>[name] [options]

Arguments:

action - Action: add, remove, list (required)
Type: string
name - Rule name (for add/remove) (optional)
Type: string

Options:

-s, --status - Status condition
Choices: backlog, todo, in_progress, review, done
Default:
Examples: backlog, todo, in_progress
-r, --requires - Requirements (field:value)
Default:
-m, --message - Violation message
Default:

Examples:

gira workflow rule <action>

gira workflow rule <action> --status backlog

`gira workflow transitions`¶

Manage allowed status transitions.

gira workflow transitions [action][from_status][to_status]

Arguments:

action - Action: add, remove, or leave empty to show (optional)
Type: string
from_status - From status (optional)
Type: string
Examples: backlog, todo, in_progress
to_status - To status (comma-separated for multiple) (optional)
Type: string
Examples: backlog, todo, in_progress

Examples:

gira workflow transitions

`gira workflow strict`¶

Enable or disable strict workflow enforcement.

gira workflow strict <action>

Arguments:

action - Action: enable, disable, or status (required)
Type: string

Examples:

gira workflow strict <action>

`gira workflow enforce`¶

Set workflow enforcement level.

gira workflow enforce <level>

Arguments:

level - Enforcement level: strict, warn, or off (required)
Type: string

Examples:

gira workflow enforce <level>

`gira workflow diagram`¶

Display visual workflow diagram.

gira workflow diagram [options]

Options:

-c, --counts - Show ticket counts for each status
Type: boolean
-o, --output - Output format: text, json
Choices: text, json, table, csv
Default: text
Examples: json, table

Examples:

gira workflow diagram

gira workflow diagram --counts

`gira workflow stats`¶

Show workflow statistics and metrics.

gira workflow stats [options]

Options:

-d, --days - Number of days to analyze
Type: integer
Default: 30
Examples: 7, 14, 30
-o, --output - Output format: text, json
Choices: text, json, table, csv
Default: text
Examples: json, table

Examples:

gira workflow stats

`gira workflow config`¶

Display current workflow configuration.

gira workflow config

Examples:

gira workflow config

`gira workflow analyze`¶

Analyze workflow patterns and suggest improvements.

gira workflow analyze [options]

Options:

-d, --days - Number of days to analyze
Type: integer
Default: 30
Examples: 7, 14, 30
-o, --output - Output format: text, json
Choices: text, json, table, csv
Default: text
Examples: json, table

Examples:

gira workflow analyze

`gira workflow migrate`¶

Migrate tickets from one workflow to another.

gira workflow migrate <from_workflow><to_workflow> [options]

Arguments:

from_workflow - Source workflow (current state) (required)
Type: string
to_workflow - Target workflow to migrate to (required)
Type: string

Options:

--dry-run/--apply - Preview changes without applying
Type: boolean
Default: True
--backup/--no-backup - Create backup before migration
Type: boolean
Default: True
-f, --force - Force migration even with conflicts
Type: boolean

Examples:

gira workflow migrate <from_workflow> <to_workflow>

gira workflow migrate <from_workflow> <to_workflow> --dry-run/--apply

CLI Reference¶

Table of Contents¶

Archive Management¶

Comments¶

Configuration¶

Core Commands¶

Documentation¶

Epic Management¶

Migration¶

Other Commands¶

Shell Completion¶

Sprint Management¶

Team Management¶

Ticket Management¶

Global Options¶

Commands¶

gira init¶

gira board¶

gira backlog¶

gira query¶

gira query-save¶

gira query-list¶

gira query-run¶

gira graph¶

gira describe¶

gira backup¶

gira restore¶

gira sync¶

gira ai-help¶

gira sync¶

gira ticket create¶

gira ticket list¶

gira ticket show¶

gira ticket update¶

gira ticket move¶

gira ticket tree¶

gira ticket add-dep¶

gira ticket remove-dep¶

gira ticket deps¶

gira ticket order¶

gira ticket delete¶

gira ticket bulk-update¶

gira ticket bulk-add-deps¶

gira ticket bulk-remove-deps¶

gira ticket clear-deps¶

gira ticket commits¶

gira ticket blame¶

gira ticket edit¶

gira ticket mv¶

gira ticket ls¶

gira ticket rm¶

gira ticket ticket estimate set¶

gira ticket ticket estimate compare¶

gira ticket ticket estimate relative¶

gira ticket ticket estimate batch¶

gira epic create¶

gira epic list¶

gira epic show¶

gira epic update¶

gira epic delete¶

gira sprint create¶

gira sprint list¶

gira sprint show¶

gira sprint update¶

gira sprint start¶

gira sprint close¶

gira sprint complete¶

gira sprint delete¶

gira sprint assign¶

gira sprint unassign¶

gira sprint assign-by-dates¶

gira sprint assign-by-epic¶

gira sprint assign-wizard¶

gira sprint generate-historical¶

gira comment add¶

gira comment list¶

gira comment delete¶

gira comment attach¶

gira comment detach¶

gira comment download¶

`gira init`¶

`gira board`¶

`gira backlog`¶

`gira query`¶

`gira query-save`¶

`gira query-list`¶

`gira query-run`¶

`gira graph`¶

`gira describe`¶

`gira backup`¶

`gira restore`¶

`gira sync`¶

`gira ai-help`¶

`gira sync`¶

`gira ticket create`¶

`gira ticket list`¶

`gira ticket show`¶

`gira ticket update`¶

`gira ticket move`¶

`gira ticket tree`¶

`gira ticket add-dep`¶

`gira ticket remove-dep`¶

`gira ticket deps`¶

`gira ticket order`¶

`gira ticket delete`¶

`gira ticket bulk-update`¶

`gira ticket bulk-add-deps`¶

`gira ticket bulk-remove-deps`¶

`gira ticket clear-deps`¶

`gira ticket commits`¶

`gira ticket blame`¶

`gira ticket edit`¶

`gira ticket mv`¶

`gira ticket ls`¶

`gira ticket rm`¶

`gira ticket ticket estimate set`¶

`gira ticket ticket estimate compare`¶

`gira ticket ticket estimate relative`¶

`gira ticket ticket estimate batch`¶

`gira epic create`¶

`gira epic list`¶

`gira epic show`¶

`gira epic update`¶

`gira epic delete`¶

`gira sprint create`¶

`gira sprint list`¶

`gira sprint show`¶

`gira sprint update`¶

`gira sprint start`¶

`gira sprint close`¶

`gira sprint complete`¶

`gira sprint delete`¶

`gira sprint assign`¶

`gira sprint unassign`¶

`gira sprint assign-by-dates`¶

`gira sprint assign-by-epic`¶

`gira sprint assign-wizard`¶

`gira sprint generate-historical`¶

`gira comment add`¶

`gira comment list`¶

`gira comment delete`¶

`gira comment attach`¶

`gira comment detach`¶

`gira comment download`¶

`gira config set`¶

`gira config get`¶

`gira config reset`¶

`gira config rename-prefix`¶

`gira metrics overview`¶

`gira metrics velocity`¶

`gira metrics trends`¶

`gira metrics duration`¶

`gira completion install`¶

`gira completion show`¶

`gira archive ticket`¶

`gira archive done`¶

`gira archive old`¶

`gira archive list`¶

`gira archive restore`¶

`gira archive suggest`¶