Atlassian CLI (acli) - Jira Reference

The Atlassian CLI (acli) provides command-line access to Jira. Authentication is automatic via devcontainer environment variables.

Command Structure

code

acli jira <resource> <action> [flags]

Resources: workitem, project, sprint, board, filter

Work Item Operations

Create Ticket

bash

acli jira workitem create \
  --project "CLDS" \
  --type "Task" \
  --summary "Ticket summary here" \
  --description "Detailed description (supports markdown)"

# With additional options
acli jira workitem create \
  --project "CLDS" \
  --type "Bug" \
  --summary "Fix login issue" \
  --description "Users cannot login after password reset" \
  --assignee "user@wiliot.com" \
  --label "bug,urgent"

# Self-assign
acli jira workitem create \
  --project "CLDS" \
  --type "Task" \
  --summary "My task" \
  --assignee "@me"

Flags:

Flag	Description
`--project`, `-p`	Project key (e.g., "CLDS", "INF") - required
`--type`, `-t`	Work item type: Task, Bug, Story, Epic - required
`--summary`, `-s`	Ticket title - required
`--description`, `-d`	Detailed description (markdown supported)
`--assignee`, `-a`	Email, account ID, `@me`, or `default`
`--label`, `-l`	Comma-separated labels
`--parent`	Parent work item ID (for subtasks)
`--json`	Output in JSON format

Output: Returns the ticket key and URL (e.g., CLDS-16825)

View Ticket

bash

# Basic view
acli jira workitem view CLDS-12345

# JSON output for parsing
acli jira workitem view CLDS-12345 --json

# Specific fields only
acli jira workitem view CLDS-12345 --fields "summary,status,assignee"

# Open in browser
acli jira workitem view CLDS-12345 --web

Flags:

Flag	Description
`--fields`, `-f`	Comma-separated field list (default: key,issuetype,summary,status,assignee,description)
`--json`	JSON output
`--web`, `-w`	Open in web browser

Special field values:

•*all - All fields
•*navigable - All navigable fields
•-description - Exclude description

Search Tickets (JQL)

bash

# Search by project
acli jira workitem search --jql "project = CLDS" --limit 20

# Search by status
acli jira workitem search --jql "project = CLDS AND status = 'In Progress'"

# Search by assignee
acli jira workitem search --jql "assignee = currentUser()"

# Search recent tickets
acli jira workitem search --jql "project = CLDS ORDER BY created DESC" --limit 10

# Get count only
acli jira workitem search --jql "project = CLDS AND status = Open" --count

# CSV output
acli jira workitem search --jql "project = CLDS" --csv --fields "key,summary,status"

# Paginate all results
acli jira workitem search --jql "project = CLDS" --paginate

Flags:

Flag	Description
`--jql`, `-j`	JQL query string - required
`--limit`, `-l`	Max results (default: none)
`--count`	Return count only
`--json`	JSON output
`--csv`	CSV output
`--fields`, `-f`	Fields to display
`--paginate`	Fetch all pages
`--filter`	Use saved filter ID instead of JQL

Common JQL patterns:

code

project = CLDS                           # By project
status = "In Progress"                   # By status
assignee = currentUser()                 # My tickets
created >= -7d                           # Last 7 days
labels in (urgent, bug)                  # By labels
summary ~ "login"                        # Text search
ORDER BY priority DESC, created DESC     # Ordering

Edit Ticket

bash

# Update summary
acli jira workitem edit --key "CLDS-12345" --summary "New summary"

# Update description
acli jira workitem edit --key "CLDS-12345" --description "Updated description"

# Change assignee
acli jira workitem edit --key "CLDS-12345" --assignee "user@wiliot.com"

# Remove assignee
acli jira workitem edit --key "CLDS-12345" --remove-assignee

# Add labels
acli jira workitem edit --key "CLDS-12345" --labels "new-label"

# Remove labels
acli jira workitem edit --key "CLDS-12345" --remove-labels "old-label"

# Multiple tickets via JQL
acli jira workitem edit --jql "project = CLDS AND labels = temp" --remove-labels "temp" --yes

Flags:

Flag	Description
`--key`, `-k`	Ticket key(s), comma-separated
`--jql`	JQL query to select tickets
`--summary`, `-s`	New summary
`--description`, `-d`	New description
`--assignee`, `-a`	New assignee
`--remove-assignee`	Remove assignee
`--labels`, `-l`	Add labels
`--remove-labels`	Remove labels
`--type`, `-t`	Change work item type
`--yes`, `-y`	Skip confirmation

Transition Status

bash

# Move to Done
acli jira workitem transition --key "CLDS-12345" --status "Done" --yes

# Move to In Progress
acli jira workitem transition --key "CLDS-12345" --status "In Progress" --yes

# Bulk transition via JQL
acli jira workitem transition --jql "project = CLDS AND status = 'To Do'" --status "In Progress" --yes

Flags:

Flag	Description
`--key`, `-k`	Ticket key(s)
`--jql`	JQL query
`--status`, `-s`	Target status - required
`--yes`, `-y`	Skip confirmation

Common statuses: To Do, In Progress, In Review, Done, Closed

Comments

bash

# Add comment
acli jira workitem comment create --key "CLDS-12345" --body "Comment text here"

# Add comment from file
acli jira workitem comment create --key "CLDS-12345" --body-file "comment.txt"

# List comments
acli jira workitem comment list --key "CLDS-12345"

# Edit last comment
acli jira workitem comment create --key "CLDS-12345" --body "Updated comment" --edit-last

Subcommands: create, list, update, delete

Project Operations

List Projects

bash

# Recent projects
acli jira project list --recent

# All projects (paginated)
acli jira project list --paginate

# Limited list
acli jira project list --limit 50

# JSON output
acli jira project list --limit 50 --json

# Find specific project
acli jira project list --limit 100 | grep -i "cloud"

Flags:

Flag	Description
`--recent`	Up to 20 recently viewed
`--limit`, `-l`	Max projects (default: 30)
`--paginate`	Fetch all pages
`--json`	JSON output

View Project

bash

acli jira project view CLDS

Sprint Operations

bash

# List work items in sprint
acli jira sprint list-workitems --board-id 123 --sprint-id 456

Common Patterns

Create Ticket for Feature Branch

bash

# Create ticket and capture key
TICKET=$(acli jira workitem create \
  --project "CLDS" \
  --type "Task" \
  --summary "Implement feature X" \
  --json | jq -r '.key')

# Create branch
git checkout -b "feature/${TICKET}-implement-feature-x"

Find My Open Tickets

bash

acli jira workitem search \
  --jql "assignee = currentUser() AND status != Done" \
  --fields "key,summary,status,priority"

Bulk Update Labels

bash

acli jira workitem edit \
  --jql "project = CLDS AND created >= -30d AND labels is EMPTY" \
  --labels "needs-triage" \
  --yes

Create Sub-Tasks for Feature

Used by /feature:tasks to create sub-tasks under a parent ticket:

bash

# Extract project from parent ticket
PARENT_TICKET="CLDS-1234"
PROJECT=$(echo "$PARENT_TICKET" | grep -oE '^[A-Z]+')

# Create sub-task
SUBTASK_KEY=$(acli jira workitem create \
  --project "$PROJECT" \
  --type "Sub-task" \
  --parent "$PARENT_TICKET" \
  --summary "T001: Create project structure" \
  --json | jq -r '.key')

echo "Created sub-task: $SUBTASK_KEY"

Bulk Create Sub-Tasks from tasks.md

bash

#!/bin/bash
PARENT_TICKET="CLDS-1234"
PROJECT=$(echo "$PARENT_TICKET" | grep -oE '^[A-Z]+')

# Parse tasks.md and create sub-tasks
grep -E '^\- \[ \] T[0-9]+' tasks.md | while read -r line; do
  # Extract task ID and description
  TASK_ID=$(echo "$line" | grep -oE 'T[0-9]+')
  SUMMARY=$(echo "$line" | sed 's/.*\] //' | sed 's/\[.*\] //')

  # Create sub-task
  KEY=$(acli jira workitem create \
    --project "$PROJECT" \
    --type "Sub-task" \
    --parent "$PARENT_TICKET" \
    --summary "$TASK_ID: $SUMMARY" \
    --json | jq -r '.key')

  echo "$TASK_ID -> $KEY"
done

Status Lifecycle Transitions

Used by /feature workflow for automated status updates:

bash

# When starting implementation
acli jira workitem transition --key "CLDS-1234" --status "In Progress" --yes

# When creating PR
acli jira workitem transition --key "CLDS-1234" --status "In Review" --yes

# When PR is merged
acli jira workitem transition --key "CLDS-1234" --status "Done" --yes

Output Formats

Flag	Format	Use Case
(none)	Table	Human-readable display
`--json`	JSON	Parsing with `jq`, automation
`--csv`	CSV	Spreadsheets, data export

JSON parsing examples:

bash

# Get ticket key
acli jira workitem create ... --json | jq -r '.key'

# Get assignee email
acli jira workitem view CLDS-123 --json | jq -r '.fields.assignee.emailAddress'

Error Handling

Error	Cause	Solution
"at least one flag required"	Missing required flag	Check required flags (--project, --type, --summary for create)
"project not found"	Invalid project key	Use `acli jira project list` to find valid keys
"transition not valid"	Invalid status transition	Check available transitions for current status
"not authenticated"	Auth expired/missing	Rerun `acli jira auth login` or restart devcontainer

Notes

•Always use acli jira workitem, not the old acli issue syntax
•Project keys are uppercase (CLDS, INF, not "Cloud Services")
•Use --yes / -y to skip confirmation prompts in scripts
•Multi-line descriptions work directly in the --description string
•Authentication is automatic in devcontainer via ATLASSIAN_* env vars