jira-cli

Before diving into detailed commands, be aware of these critical points:

1. Time Tracking: MUST use jira issue worklog add ISSUE "1m" --new-estimate "1h" - DO NOT use --custom for time tracking
2. Cannot log 0m: Logging "0m" causes server errors - always log at least "1m"
3. Status Names Vary: "Done" may not exist - use exact status name from error message (e.g., "Resolved", "Closed")
4. --no-input Support: Not all commands support --no-input:

- ✓ Supported: issue edit, issue worklog add

- ✗ Not supported: issue move, view/list commands

1. Environment Setup: Test jira me --plain first - only source ~/.envrc if auth fails

Before running any jira-cli commands, check if the user has already configured their environment.

The user may have already:

• Installed and configured jira-cli
• Set up authentication tokens in environment files (e.g., ~/.envrc, ~/.bashrc, ~/.zshrc)
• Configured the Jira CLI in ~/.config/.jira/.config.yml
• Exported JIRA_API_TOKEN in their current shell session

Test if jira-cli is already working before sourcing environment files:

```bash

# First, try running jira-cli directly

jira me --plain

# If you get authentication errors, THEN check for environment files

```

Only source environment files if authentication fails:

```bash

# If needed, check for and source .envrc conditionally

[ -f ~/.envrc ] && source ~/.envrc 2>/dev/null; jira me --plain

```

Why this approach:

• The JIRA_API_TOKEN environment variable is required for authentication
• Users may have already sourced their environment files in the current shell
• Users may have tokens configured globally in their shell configuration
• Do not assume ~/.envrc needs to be sourced - only do so if authentication fails
• The user may have already completed the full setup, so test first before suggesting changes

Troubleshooting steps if commands fail:

1. First try running jira commands directly (e.g., jira me --plain)
2. If authentication fails, check if JIRA_API_TOKEN is set: echo $JIRA_API_TOKEN
3. If not set, then try sourcing common environment files like ~/.envrc
4. Only suggest installation/configuration if the tool is not found or environment variables cannot be located

ALWAYS use --plain flag (or equivalent non-interactive flags) when running jira-cli commands to prevent the tool from entering interactive mode and blocking execution.

Non-Interactive Flags by Command Type

For listing/viewing commands:

• Use --plain to get plain text output instead of interactive UI
• Alternative non-interactive flags: --raw (JSON output), --csv (CSV output)

For commands that prompt for input (create, edit, worklog):

• Use --no-input to skip interactive prompts
• Commands that support --no-input:

- jira issue edit - skips prompts for fields

- jira issue worklog add - skips comment prompt

- Other create/edit commands

• Commands that DO NOT support --no-input:

- jira issue move - does not have this flag

- Most viewing/listing commands (use --plain instead)

Important:

• If a command doesn't support --no-input, provide all required parameters via flags
• If you get "unknown flag: --no-input" error, remove the flag and provide inputs via other flags
• Always check error messages for available flags

Examples:

```bash

# CORRECT - Non-blocking list commands

jira issue list --plain

jira issue list --raw

jira epic list --plain

# CORRECT - Non-blocking edit/worklog commands

jira issue edit PROJ-123 --custom "field=value" --no-input

jira issue worklog add PROJ-123 "1h" --no-input

# CORRECT - Move command (no --no-input flag)

jira issue move PROJ-123 "In Progress"

# INCORRECT - May block in interactive UI

jira issue list

jira epic list

jira issue worklog add PROJ-123 "1h" # Will prompt for comment

```

macOS (via Homebrew)

```bash

brew install jira-cli

```

Linux

Download the latest release from GitHub:

```bash

# For amd64

wget https://github.com/ankitpokhrel/jira-cli/releases/latest/download/jira_linux_amd64.tar.gz

tar -xzf jira_linux_amd64.tar.gz

sudo mv jira /usr/local/bin/

```

Windows

Download from the [releases page](https://github.com/ankitpokhrel/jira-cli/releases) or use Scoop:

```bash

scoop install jira-cli

```

Docker

```bash

docker run -it --rm ghcr.io/ankitpokhrel/jira-cli:latest

```

Other Package Managers

Jira CLI is also available via Nix and other package managers. See [Repology](https://repology.org/project/jira-cli/versions) for a full list.

Cloud Server Setup

1. Generate a Jira API token at: https://id.atlassian.com/manage-profile/security/api-tokens
2. Export the token as an environment variable:

```bash

export JIRA_API_TOKEN="your-token-here"

```

Note: If environment variables are stored in ~/.envrc, you may need to source them first:

```bash

source ~/.envrc

```

1. Run jira init and select "Cloud" installation type
2. Provide your Jira instance URL (e.g., https://your-company.atlassian.net)

On-Premise Installation

1. Export authentication credentials:

```bash

export JIRA_API_TOKEN="your-token-here"

```

1. For Personal Access Token (PAT) authentication:

```bash

export JIRA_AUTH_TYPE="bearer"

```

1. Run jira init and select "Local" installation type
2. For non-English installations, manually configure epic.name, epic.link, and issue.types.*.handle in the config file

Authentication Methods

Jira CLI supports three authentication types:

• Basic (default): Username and password or API token
• Bearer (PAT): Personal Access Token authentication (requires JIRA_AUTH_TYPE=bearer)
• mTLS: Client certificate authentication for on-premise installations

Multiple Project Support

Use the --config/-c flag or JIRA_CONFIG_FILE environment variable to load specific configurations:

```bash

jira issue list --config ~/.config/jira/project2.yml

# or

export JIRA_CONFIG_FILE=~/.config/jira/project2.yml

jira issue list

```

Configuration File

The configuration is stored in ~/.config/.jira/.config.yml. You can edit this file directly.

List Issues

```bash

# List issues assigned to you

jira issue list

# List issues with filters

jira issue list -a$(jira me) -s"To Do,In Progress"

# List issues in a specific project

jira issue list --project PROJ

# List with JQL query

jira issue list --jql "assignee=currentUser() AND status='In Progress'"

# Filter by time (relative dates supported)

jira issue list --created -7d # Created in last 7 days

jira issue list --created week # Created this week

jira issue list --updated month # Updated this month

# Filter by priority, labels, components

jira issue list --priority High,Highest

jira issue list --label bug,urgent

jira issue list --component backend

```

View Issue Details

```bash

# View issue details

jira issue view PROJ-123

# View with comments

jira issue view PROJ-123 --comments 10

```

Create Issues

```bash

# Interactive mode

jira issue create

# Quick create with flags

jira issue create -tTask -s"Issue summary" -y10 -lbug,urgent

# Create from template

jira issue create --template

# Create with custom fields

jira issue create --custom field1=value1,field2=value2

# Create with parent epic

jira issue create -P PROJ-456

```

Update Issues

```bash

# Assign issue

jira issue assign PROJ-123 $(jira me)

# Assign to default assignee

jira issue assign PROJ-123 default

# Unassign

jira issue assign PROJ-123 x

# Move to different status (transition)

jira issue move PROJ-123 "In Progress"

# IMPORTANT: Status names vary by project/workflow

# If you get "invalid transition state" error, the status name is incorrect

# Common mistake: Using "Done" when the actual state is "Resolved" or "Closed"

# The error message will list available states for that issue

# Edit issue

jira issue edit PROJ-123

# Edit with specific fields

jira issue edit PROJ-123 -s"New summary" --priority High

# Remove labels (use minus prefix)

jira issue edit PROJ-123 --label -p2

```

Clone Issues

```bash

# Clone an issue

jira issue clone PROJ-123

# Clone with modifications

jira issue clone PROJ-123 -s"New summary" --priority High

# Clone with text replacement

jira issue clone PROJ-123 -H old:new

```

Link and Unlink Issues

```bash

# Link issues

jira issue link PROJ-123 PROJ-456 "Blocks"

# Unlink issues

jira issue unlink PROJ-123 PROJ-456

# Add web link

jira issue link PROJ-123 https://example.com "Documentation"

```

Delete Issues

```bash

# Delete an issue

jira issue delete PROJ-123

# Delete with cascade (including subtasks)

jira issue delete PROJ-123 --cascade

```

Comment Management

```bash

# Add comment

jira issue comment add PROJ-123 "Working on this"

# Add internal comment

jira issue comment add PROJ-123 --internal "Internal note"

# Add comment from file

jira issue comment add PROJ-123 --template comment.md

# Add comment from stdin

echo "Comment text" | jira issue comment add PROJ-123

```

Worklog and Time Tracking

IMPORTANT: Time tracking estimates are set using the worklog add command with the --new-estimate flag, NOT through custom fields.

```bash

# Add time tracking entry

jira issue worklog add PROJ-123 "2d 3h 30m"

# Add worklog with comment

jira issue worklog add PROJ-123 "4h" --comment "Fixed the bug"

# Set remaining estimate when logging work

jira issue worklog add PROJ-123 "1h" --new-estimate "3h"

# Set original estimate (log minimal time with full estimate remaining)

jira issue worklog add PROJ-123 "1m" --new-estimate "8h"

# Complete work and set remaining to 0

jira issue worklog add PROJ-123 "30m" --new-estimate "0m"

# Use --no-input to skip interactive comment prompt

jira issue worklog add PROJ-123 "1h" --new-estimate "2h" --no-input

# Add worklog with start time

jira issue worklog add PROJ-123 "1h 30m" --started "2022-01-01T09:30:00.000+0200" --new-estimate "0h"

```

Important notes for worklog:

• Cannot log "0m" of time - This causes a server error. Log at least "1m" if you need to set an estimate without logging significant work
• Use --new-estimate to set the remaining time estimate
• The --no-input flag is supported and prevents interactive prompts for comments
• Time formats: "1h", "30m", "1h 30m", "2d 3h 30m"
• Time tracking cannot be set through --custom fields - you must use worklog add with --new-estimate

Search Issues

```bash

# Search with JQL

jira issue list --jql "project=PROJ AND status='In Progress' ORDER BY priority DESC"

# Common JQL examples

jira issue list --jql "assignee=currentUser() AND status!=Done"

jira issue list --jql "created >= -7d AND assignee=currentUser()"

jira issue list --jql "priority in (High, Highest) AND status='To Do'"

```

Epic Management

```bash

# List epics

jira epic list

# List epics in table view

jira epic list --table

# View issues in a specific epic

jira epic list PROJ-123

# Create epic

jira epic create

# Add issues to epic (up to 50 at a time)

jira epic add PROJ-123 PROJ-456 PROJ-789

# Remove issues from epic

jira epic remove PROJ-123 PROJ-456

```

Sprint Management

```bash

# List sprints (shows 25 most recent)

jira sprint list

# List issues in current sprint

jira sprint list --current

# List issues in previous/next sprint

jira sprint list --prev

jira sprint list --next

# Filter by sprint state

jira sprint list --state future,active

# Add issue to sprint (up to 50 at a time)

jira sprint add SPRINT-ID PROJ-123 PROJ-456

```

Project and Board Management

```bash

# List accessible projects

jira project list

# List boards

jira board list

# List releases/versions

jira release list

```

Utility Commands

```bash

# Open project or issue in browser

jira open

jira open PROJ-123

# Get current user information

jira me

# Enable shell completion

jira completion bash > /etc/bash_completion.d/jira

jira completion zsh > "${fpath[1]}/_jira"

```

Jira CLI supports multiple output formats:

```bash

# Default interactive table view

jira issue list

# Plain text (for scripting)

jira issue list --plain

# Raw JSON output

jira issue list --raw

# CSV format

jira issue list --csv

# No headers (with plain output)

jira issue list --plain --no-headers

```

The default list view supports keyboard navigation:

• Arrow keys or j/k/h/l: Navigate up/down/left/right
• g/G: Jump to top/bottom
• CTRL+f/b: Page down/up
• v: View issue details
• m: Transition/move issue to different status
• ENTER: Open issue in browser
• c: Copy issue URL to clipboard
• CTRL+k: Copy issue key to clipboard
• w or TAB: Toggle sidebar focus
• CTRL+r or F5: Refresh list
• ?: Display help

Add these to your shell configuration for quicker access:

```bash

# List your current issues

alias jira-mine='jira issue list -a$(jira me) -s"To Do,In Progress"'

# Quick view

alias jv='jira issue view'

# List current sprint

alias jira-sprint='jira sprint list --current'

# Open issue quickly

alias jo='jira open'

```

Custom Views

Create custom issue views in ~/.config/jira/.config.yml:

```yaml

issue:

fields:

- key

- type

- summary

- status

- assignee

- priority

- created

```

Custom Fields

Configure custom field mapping in ~/.config/jira/.config.yml:

```yaml

custom:

customfield_10001: Team

customfield_10002: Story Points

```

Then use them in commands:

```bash

jira issue create --custom Team=Backend,Story\ Points=5

```

Setting Due Dates

CRITICAL DISTINCTION: Do not confuse due dates with time tracking:

• Due dates (calendar dates): Set via --custom parameter (requires configuration)
• Time tracking (estimates/time spent): Set via jira issue worklog add with --new-estimate flag
• Never try to set time tracking fields (timeoriginalestimate, timetracking, etc.) via --custom - it will not work

IMPORTANT: The duedate field is treated as a custom field and must be explicitly configured to be visible in API responses and usable via the --custom parameter.

#### Configuration Required for Due Dates

Due dates require special configuration because duedate is a standard Jira field that doesn't appear by default in the Jira CLI API responses. To enable setting and viewing due dates:

1. Add the following to your ~/.config/jira/.config.yml:

```yaml

issue:

fields:

custom:

- name: duedate

key: duedate

schema:

datatype: date

```

1. Then you can set due dates when creating or editing issues:

```bash

jira issue create --type Task --summary "Task summary" --custom "duedate=2024-12-31"

jira issue edit PROJ-123 --custom "duedate=2024-12-31"

```

#### Requesting Due Dates in API Responses

Without the above configuration:

• The duedate field will NOT appear in jira issue list --raw output
• Attempts to use --custom "duedate=..." will show a warning that the field is "not configured" and will be ignored
• Due dates cannot be set or retrieved via the CLI

With the configuration:

• Due dates will appear in the fields object of JSON responses from --raw output
• You can set due dates using the --custom parameter
• Due dates can be included in custom views

Note: This is a known limitation of the jira-cli tool. See [jira-cli issue #698](https://github.com/ankitpokhrel/jira-cli/issues/698) for more details.

Scripting with Jira CLI

Use raw JSON output for scripting:

```bash

#!/bin/bash

# Get all high priority issues

jira issue list --jql "priority=High" --raw | jq -r '.issues[].key'

# Count issues by status

jira issue list --plain --no-headers | awk '{print $4}' | sort | uniq -c

```

Templates

Create markdown templates for issues and comments:

```bash

# Issue template (issue-template.md)

What needs to be done?

• [ ] Criterion 1
• [ ] Criterion 2

# Use template

jira issue create --template issue-template.md

```

Authentication Issues

```bash

# Re-initialize configuration

jira init --force

# Check current user

jira me

# Verify API token is set

echo $JIRA_API_TOKEN

```

Connection Issues

```bash

# Test connection

jira issue list --limit 1

# Enable debug mode

JIRA_DEBUG=1 jira issue list

```

Clear Cache

```bash

# Clear cached data

rm -rf ~/.config/jira/.cache

```

Time Tracking Errors

Error: "field not on the appropriate screen"

• This occurs when trying to set time tracking via --custom fields
• Solution: Use jira issue worklog add with --new-estimate instead
• Time tracking fields cannot be set via the edit command

Error: "Internal server error" (500) when logging time

• Usually caused by trying to log "0m" of time
• Solution: Log at least "1m" - you cannot log zero time
• Example: jira issue worklog add PROJ-123 "1m" --new-estimate "8h"

Warning: "field is not configured" for timeoriginalestimate/timetracking

• This appears when using --custom for time tracking fields
• Solution: Ignore the warning - use worklog add command instead
• Do NOT try to configure these as custom fields - they're managed differently

Error: "invalid transition state" when closing issues

• Status names vary by project/workflow
• Common mistake: Using "Done" when the actual state is "Resolved" or "Closed"
• Solution: Check the error message for available states
• Or view the issue in browser: jira open PROJ-123

• [Official Documentation](https://github.com/ankitpokhrel/jira-cli)
• [JQL Guide](https://support.atlassian.com/jira-software-cloud/docs/what-is-advanced-searching-in-jira-cloud/)
• [Issue with installation or usage?](https://github.com/ankitpokhrel/jira-cli/issues)

• The Jira CLI uses the Jira REST API under the hood
• API tokens are more secure than passwords and are the recommended authentication method
• Most commands support --help for detailed usage information
• Supports both Jira Cloud and on-premise installations
• Output is converted from Atlassian Document Format to markdown for better terminal display