Skip to content

examples.md

Latest commit

 

History

History
226 lines (171 loc) · 5.97 KB

examples.md

File metadata and controls

226 lines (171 loc) · 5.97 KB

jira-cli Examples

These examples are written for agent workflows, CI jobs, and repeatable shell automation. They avoid hidden prompts and keep stdout machine-readable when the result is intended for another program.

Bootstrap

jira config init \
  --profile prod \
  --site example.atlassian.net \
  --email automation@example.com \
  --default-project ENG

jira auth setup-token --profile prod --token "$JIRA_TOKEN"
jira auth login --profile prod \
  --client-id "$JIRA_OAUTH_CLIENT_ID" \
  --client-secret "$JIRA_OAUTH_CLIENT_SECRET"
jira auth status --profile prod --output json
jira auth doctor --profile prod --output json

Issue Read Workflows

# Fetch normalized issue context.
jira issue view ENG-123 --output json

# Fetch only fields an agent needs.
jira issue view ENG-123 --fields key,summary,status.name,assignee.displayName -o json

# Extract Markdown description for prompt context.
jira issue body ENG-123 --output plain

# Stream open issue keys.
jira issue list --jql 'project = ENG AND @open' --all -o jsonl |
  jq -r '.data.key'

Issue Mutation Workflows

# Preview the Jira payload before sending it.
jira issue create \
  --project ENG \
  --type Task \
  --summary 'Investigate API timeout' \
  --description 'Timeouts increased after deploy' \
  --dry-run \
  --output json

# Create from a Markdown file.
jira issue create \
  --type Bug \
  --summary 'Regression in checkout' \
  --description-file ./bug-report.md \
  --priority High \
  --label regression

# Set a custom field by ID.
jira issue edit ENG-123 --set customfield_10042='{"value":"Customer Escalation"}'

# After `jira cache refresh fields`, set a custom field by display name.
jira issue edit ENG-123 --set 'Customer Tier={"value":"Gold"}'

# Transition by name and add a transition comment.
jira issue transition ENG-123 'In Progress' --comment 'Taking this now'

# Delete safely in automation.
jira issue delete ENG-123 --yes --no-input --output json

Comments

# Add a direct comment.
jira comment add ENG-123 --body 'Build passed on main.'

# Read explicit stdin only.
git log -1 --pretty=%B | jira comment add ENG-123 --body -

# Add a restricted comment.
jira comment add ENG-123 \
  --body-file ./internal-note.md \
  --visibility role:Developers

# Update and delete comments.
jira comment update ENG-123 10001 --body 'Updated after retest.'
jira comment delete ENG-123 10001 --yes --no-input

Worklogs

jira worklog add ENG-123 --time-spent 2h --comment 'Implementation'
jira worklog add ENG-123 --time-spent 45m --started '2026-05-27T09:00:00.000+0000'
jira worklog total ENG-123 --output json
jira worklog delete ENG-123 10001 --yes --no-input

Supported duration units are s, m, h, and d. Examples: 30m, 1h30m, 1d 2h.

Attachments

jira attachment upload ENG-123 ./report.pdf ./screenshot.png
jira attachment list ENG-123 --output json
jira attachment download --url "$ATTACHMENT_URL" --filename report.pdf --to ./downloads
jira attachment delete 10001 --yes --no-input

Attachment downloads reject unsafe filenames that contain path separators or traversal segments.

Metadata Discovery

# Find a project, field, or account ID before mutation.
jira project list --output table
jira field list --output json | jq -r '.data[] | select(.custom == true) | [.id, .name] | @tsv'
jira user search 'Ada Lovelace' --output json

# Use the accountId for assignment.
jira issue assign ENG-123 --account-id 712020:abc123

Cache And Completions

jira cache refresh projects
jira cache refresh fields
jira cache refresh boards --project ENG
jira cache refresh sprints --board 42

jira completions dynamic project EN
jira completions dynamic field Customer
jira completions dynamic sprint Sprint

Dynamic completion candidates are local-only. If the cache is missing, the command exits successfully with no candidates.

Agile Workflows

jira board list --project ENG
jira board backlog 42 --output json
jira sprint current --board 42 --output json

jira sprint create \
  --board 42 \
  --name 'Sprint 87' \
  --goal 'Ship production-ready CLI'

jira sprint add-issues 412 ENG-123 ENG-124
jira epic add-issues ENG-100 ENG-123

jira issue list --jql 'project = ENG AND @current-sprint' --board 42

Bulk Operations

# Preview a JQL-driven operation.
jira bulk comment \
  --jql 'project = ENG AND @open' \
  --body 'Queued for triage.' \
  --dry-run \
  --output json

# Assign explicit keys.
jira bulk assign --keys ENG-123,ENG-124 --account-id 712020:abc123

# Transition from a file of issue keys.
jira bulk transition --file issue-keys.txt --to Done --comment 'Released'

# Use the issue namespace aliases in CI.
jira issue bulk-edit --jsonl issues.jsonl --set 'Customer Tier=Gold'
jira issue bulk-delete --jql 'project = ENG AND labels = stale' --yes --no-input

Agent Triage Loop

jira issue list \
  --jql 'project = ENG AND @open AND priority in (High, Highest)' \
  --all \
  --output jsonl |
while IFS= read -r line; do
  key=$(jq -r '.data.key' <<<"$line")
  summary=$(jq -r '.data.summary' <<<"$line")
  printf 'triaging %s: %s\n' "$key" "$summary" >&2
  jira comment add "$key" --body "Queued for automated triage." --output json >/dev/null
done

CI/CD Release Notes

ISSUES=$(git log --format=%B "$PREVIOUS_TAG..HEAD" |
  rg -o '[A-Z][A-Z0-9]+-[0-9]+' |
  sort -u)

for key in $ISSUES; do
  jira comment add "$key" --body "Included in release $GITHUB_REF_NAME" --no-input
done

Debugging

# Print a redacted curl command to stderr before the request.
jira issue view ENG-123 --debug-curl --output json

# Increase tracing verbosity without polluting stdout JSON.
jira -vv issue list --jql 'project = ENG' --output json >/tmp/issues.json

# JSON formatted logs for structured runners.
jira --log-format json -vv issue view ENG-123 --output json

Manual Pages

jira completions man --dir docs/man
man docs/man/jira.1
man docs/man/jira-comment-add.1
man docs/man/jira-worklog-add.1