Skip to content

CLI Reference

Complete reference for all Gira commands and options.

Table of Contents

Ticket Management

Global Options

These options can be used with any command:

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

Commands

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