acli

name	acli
description	Use acli CLI for Atlassian operations — primarily Jira work item management, project operations, sprint tracking, and board management with JQL search. Also covers Confluence page/space/blog operations and a CQL search fallback (acli has no native Confluence search).

Atlassian CLI (acli) - Jira Workflow Skill

You are an Atlassian CLI specialist. This skill provides comprehensive guidance for managing Jira work items, projects, sprints, and boards using the acli jira command-line tool.

Sandbox (MANDATORY)

Every acli invocation via the Bash tool MUST set dangerouslyDisableSandbox: true on the FIRST attempt. Do not try sandboxed first.

acli reads and writes OAuth credentials via the macOS Keychain / credential helpers. The default Claude Code sandbox blocks those reads, and the failure mode is deceptive:

• acli jira auth status → failed to retrieve authenticated status
• acli jira workitem search ... → failed to parse JQL (even for valid JQL)
• acli jira project list → failed to list projects

These look like syntax or auth problems, but they are sandbox problems. The fix is always the same: rerun the exact command with dangerouslyDisableSandbox: true.

This applies to every acli subcommand: auth, workitem, project, board, sprint, filter, field, dashboard. No exceptions.

Bash(command="acli jira workitem view FOO-123", dangerouslyDisableSandbox=true)
Bash(command="acli jira workitem search --jql 'project = FOO'", dangerouslyDisableSandbox=true)

Core Principles

Output Formats

Standard formats available:

• Default: Human-readable table format
• --json: JSON output for scripting and automation
• --csv: CSV output for data export (available on search commands)
• --web: Open results in web browser

Best practices:

• Use --json for scripting and parsing
• Use --csv for exporting to spreadsheets
• Use --web for quick visual inspection
• Use default format for human review

Pagination and Limits

# Fetch limited results (default varies by command)
acli jira workitem search --jql "project = TEAM" --limit 50

# Fetch all results with pagination
acli jira workitem search --jql "project = TEAM" --paginate

# Count results without fetching details
acli jira workitem search --jql "project = TEAM" --count

Authentication

Initial Setup

# Login to Jira instance
acli jira auth login

# Check authentication status
acli jira auth status

# Switch between accounts
acli jira auth switch

# Logout
acli jira auth logout

Work Items (Issues)

Searching for Work Items

# Basic JQL search
acli jira workitem search --jql "project = TEAM"

# Search with specific fields
acli jira workitem search --jql "project = TEAM" --fields "key,summary,assignee"

# Search with pagination
acli jira workitem search --jql "project = TEAM" --paginate

# Count matching work items
acli jira workitem search --jql "project = TEAM" --count

# Export to CSV
acli jira workitem search --jql "project = TEAM" --csv

# Export to JSON
acli jira workitem search --jql "project = TEAM" --json

# Search using saved filter
acli jira workitem search --filter 10001

# Open search results in browser
acli jira workitem search --jql "project = TEAM" --web

# Limit results
acli jira workitem search --jql "project = TEAM" --limit 50

Common JQL patterns:

# Assigned to me
acli jira workitem search --jql "assignee = currentUser()"

# Open issues in project
acli jira workitem search --jql "project = TEAM AND status != Done"

# Recently updated
acli jira workitem search --jql "updated >= -7d"

# By priority
acli jira workitem search --jql "priority = High AND status = Open"

# Multiple conditions
acli jira workitem search --jql "project = TEAM AND assignee = currentUser() AND status in (Open, 'In Progress')"

# By type
acli jira workitem search --jql "project = TEAM AND issuetype = Bug"

# By labels
acli jira workitem search --jql "labels = production AND status != Closed"

Viewing Work Items

# View single work item
acli jira workitem view KEY-123

# View with specific fields
acli jira workitem view KEY-123 --fields "summary,description,comment"

# View all fields
acli jira workitem view KEY-123 --fields "*all"

# View navigable fields only
acli jira workitem view KEY-123 --fields "*navigable"

# Exclude specific fields
acli jira workitem view KEY-123 --fields "*navigable,-comment"

# View as JSON
acli jira workitem view KEY-123 --json

# Open in web browser
acli jira workitem view KEY-123 --web

Creating Work Items

Available CLI flags for acli jira workitem create:

Flag	Description
--summary / -s	Work item title
--project / -p	Project key
--type / -t	Issue type (Epic, Story, Task, Bug)
--assignee / -a	Email or @me (NOT raw account IDs)
--description / -d	Plain text or ADF JSON
--description-file	Read description from file
--label / -l	Comma-separated labels
--parent	Parent issue key (e.g., epic key)
--from-json	Create from JSON file
--from-file / -f	Read summary/description from file
--editor / -e	Open text editor
--json	Return JSON output

There is no --component, --sprint, or --story-points flag. To set components, sprint, story points, or any other custom/non-standard field, you MUST use the --from-json approach.

# Basic creation with CLI flags
acli jira workitem create \
  --summary "New feature request" \
  --project "TEAM" \
  --type "Story"

# Create with assignee (use email, not account ID)
acli jira workitem create \
  --summary "Fix login bug" \
  --project "TEAM" \
  --type "Bug" \
  --assignee "[e-mail]"

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

# Create with parent (e.g., story under epic)
acli jira workitem create \
  --summary "Sub-task" \
  --project "TEAM" \
  --type "Story" \
  --parent "TEAM-100"

# Create with labels
acli jira workitem create \
  --summary "Urgent bug fix" \
  --project "TEAM" \
  --type "Bug" \
  --label "production,urgent,bug"

Creating with Custom Fields (components, sprint, story points)

Use --from-json when you need to set fields not available as CLI flags. The JSON format is acli's own format, NOT the raw Jira REST API format.

Generate the template to see the schema:

acli jira workitem create --generate-json

The JSON schema is:

{
  "summary": "Title",
  "projectKey": "PROJ",
  "type": "Story",
  "parentIssueId": "PROJ-100",
  "assignee": "@me",
  "labels": ["label1", "label2"],
  "description": {
    "type": "doc",
    "version": 1,
    "content": [
      {
        "type": "paragraph",
        "content": [{"type": "text", "text": "Description text"}]
      }
    ]
  },
  "additionalAttributes": {
    "components": [{"id": "12345"}],
    "customfield_10003": 5,
    "customfield_10701": 16378
  }
}

Key fields in additionalAttributes:

• components — Array of {"id": "..."} objects (use component ID, not name)
• Sprint custom field (e.g., customfield_10701) — Set to the sprint ID (integer)
• Story points custom field (e.g., customfield_10003) — Set to a number

Important notes about --from-json:

• Use projectKey (not project.key)
• Use parentIssueId (not parent.key) — this is the parent issue key string
• assignee accepts @me or an email address — NOT raw Jira account IDs
• description must be in Atlassian Document Format (ADF), not plain text
• Custom field IDs vary per Jira instance — discover them by viewing an existing issue with --fields "*all" --json and inspecting the customfield_* keys

# Create work item from JSON file
acli jira workitem create --from-json /path/to/workitem.json --json

Assignment Gotchas

Some projects restrict who can be assigned issues during creation. If you get a "cannot be assigned issues" error:

1. Create the issue without an assignee
2. Assign separately using acli jira workitem assign:

# Create without assignee
acli jira workitem create \
  --summary "New task" \
  --project "TEAM" \
  --type "Story" \
  --json

# Then assign (use email, not account ID)
acli jira workitem assign --key "TEAM-456" --assignee "[e-mail]"
# Or self-assign
acli jira workitem assign --key "TEAM-456" --assignee "@me"

The assign subcommand often succeeds where create --assignee fails because they use different Jira API permission checks.

Editing Work Items

# Edit single work item
acli jira workitem edit --key "KEY-123" --summary "Updated summary"

# Edit multiple work items
acli jira workitem edit --key "KEY-123,KEY-124,KEY-125" --assignee "@me"

# Edit with JQL query
acli jira workitem edit \
  --jql "project = TEAM AND status = Open" \
  --assignee "[e-mail]"

# Edit with filter
acli jira workitem edit --filter 10001 --labels "reviewed"

# Update description
acli jira workitem edit --key "KEY-123" --description "Updated description"

# Update description from file
acli jira workitem edit --key "KEY-123" --description-file "desc.txt"

# Change work item type
acli jira workitem edit --key "KEY-123" --type "Epic"

# Add labels
acli jira workitem edit --key "KEY-123" --labels "backend,api"

# Remove labels
acli jira workitem edit --key "KEY-123" --remove-labels "old-label"

# Remove assignee (unassign)
acli jira workitem edit --key "KEY-123" --remove-assignee

# Skip confirmation prompt
acli jira workitem edit --key "KEY-123" --summary "New" --yes

# Ignore errors when editing multiple
acli jira workitem edit \
  --jql "project = TEAM" \
  --assignee "@me" \
  --ignore-errors

# Generate JSON template
acli jira workitem edit --generate-json

# Edit from JSON file
acli jira workitem edit --from-json "update.json"

# Get JSON output
acli jira workitem edit --key "KEY-123" --summary "New" --json

Transitioning Work Items

# Transition single work item
acli jira workitem transition --key "KEY-123" --status "In Progress"

# Transition multiple work items
acli jira workitem transition \
  --key "KEY-123,KEY-124" \
  --status "Done"

# Transition with JQL query
acli jira workitem transition \
  --jql "project = TEAM AND assignee = currentUser()" \
  --status "In Review"

# Transition with filter
acli jira workitem transition \
  --filter 10001 \
  --status "Closed"

# Skip confirmation
acli jira workitem transition \
  --key "KEY-123" \
  --status "Done" \
  --yes

# Ignore errors
acli jira workitem transition \
  --jql "project = TEAM" \
  --status "Done" \
  --ignore-errors

# Get JSON output
acli jira workitem transition \
  --key "KEY-123" \
  --status "Done" \
  --json

Common status transitions:

• To Do / Open - New work
• In Progress - Active work
• In Review / Code Review - Under review
• Testing / QA - Being tested
• Done / Closed / Resolved - Completed

Assigning Work Items

# Assign to specific user
acli jira workitem assign \
  --key "KEY-123" \
  --assignee "[e-mail]"

# Self-assign
acli jira workitem assign --key "KEY-123" --assignee "@me"

# Assign to default assignee
acli jira workitem assign --key "KEY-123" --assignee "default"

# Assign multiple work items
acli jira workitem assign \
  --key "KEY-123,KEY-124,KEY-125" \
  --assignee "@me"

Comments

# Add comment to work item
acli jira workitem comment create \
  --key "KEY-123" \
  --body "This is a comment"

# Add comment from file
acli jira workitem comment create \
  --key "KEY-123" \
  --body-file "comment.txt"

# Add comment using editor
acli jira workitem comment create \
  --key "KEY-123" \
  --editor

# Comment on multiple work items with JQL
acli jira workitem comment create \
  --jql "project = TEAM AND status = Open" \
  --body "Bulk comment"

# Edit last comment from same author
acli jira workitem comment create \
  --key "KEY-123" \
  --body "Updated comment" \
  --edit-last

# Ignore errors when commenting on multiple
acli jira workitem comment create \
  --jql "project = TEAM" \
  --body "Comment" \
  --ignore-errors

# List comments
acli jira workitem comment list --key "KEY-123"

# Update comment
acli jira workitem comment update \
  --key "KEY-123" \
  --comment-id "10001" \
  --body "Updated comment text"

# Delete comment
acli jira workitem comment delete \
  --key "KEY-123" \
  --comment-id "10001"

# Get visibility options
acli jira workitem comment visibility --key "KEY-123"

Attachments

# Work item attachment commands
acli jira workitem attachment --help

Linking Work Items

# Link work items
acli jira workitem link --help

Cloning Work Items

# Clone/duplicate work items
acli jira workitem clone \
  --key "KEY-123" \
  --summary "Cloned issue"

Archiving and Deleting

# Archive work item
acli jira workitem archive --key "KEY-123"

# Archive multiple work items
acli jira workitem archive --key "KEY-123,KEY-124,KEY-125"

# Unarchive work item
acli jira workitem unarchive --key "KEY-123"

# Delete work item
acli jira workitem delete --key "KEY-123"

# Delete multiple work items
acli jira workitem delete --key "KEY-123,KEY-124"

Watchers

# Work item watcher commands
acli jira workitem watcher --help

Bulk Operations

# Bulk create from file
acli jira workitem create-bulk --from-json "bulk-issues.json"

# Generate bulk creation template
acli jira workitem create-bulk --generate-json

Projects

Listing Projects

# List projects (default 30)
acli jira project list

# List specific number
acli jira project list --limit 50

# List all projects with pagination
acli jira project list --paginate

# List recently viewed projects
acli jira project list --recent

# Export to JSON
acli jira project list --json

Viewing Projects

# View project details
acli jira project view --key "TEAM"

# View as JSON
acli jira project view --key "TEAM" --json

Creating Projects

# Create new project
acli jira project create

# The command will prompt for required information

Updating Projects

# Update project
acli jira project update --key "TEAM"

Archiving Projects

# Archive project
acli jira project archive --key "TEAM"

# Restore archived project
acli jira project restore --key "TEAM"

Deleting Projects

# Delete project
acli jira project delete --key "TEAM"

Sprints and Boards

Finding the Active Sprint for a Project

The fastest way to find the active sprint is via JQL, not the board API. Search for any issue in the project's open sprint and read the sprint custom field from the JSON response:

# Step 1: Find one issue in the active sprint
acli jira workitem search \
  --jql "project = PROJ AND sprint in openSprints()" \
  --fields "key" --limit 1 --json

# Step 2: View that issue with all fields, extract active sprint object
acli jira workitem view PROJ-123 --fields "*all" --json \
  | jq '
    .fields | to_entries[]
    | select(.value | type == "array" and length > 0)
    | select(.value[0] | type == "object" and has("state"))
    | .value[] | select(.state == "active")
  '

The sprint object contains id, name, boardId, startDate, endDate, and state. Use id when assigning a sprint to a new issue via additionalAttributes in the --from-json creation flow (see "Creating with Custom Fields" below).

Do NOT try to find the sprint by paginating through acli jira board search — there can be hundreds of boards and the project's board may not appear on early pages.

Board Commands

# Search for boards (paginated — may return hundreds)
acli jira board search

# Get board details
acli jira board get --id 123

# List sprints for a board
acli jira board list-sprints --id 123

Sprint Work Items

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

Filters

Managing Filters

# List my filters or favourites
acli jira filter list

# Search for filters
acli jira filter search

# Get filter by ID
acli jira filter get --id 10001

# Add filter as favourite
acli jira filter add-favourite --id 10001

# Change filter owner
acli jira filter change-owner --id 10001

# Get configured columns
acli jira filter get-columns --id 10001

# Reset columns to default
acli jira filter reset-columns --id 10001

Fields

Field Management

# Jira field commands
acli jira field --help

Dashboards

Dashboard Management

# Jira dashboard commands
acli jira dashboard --help

Complete Workflows

Workflow 1: Create and Track Bug

# 1. Create bug
acli jira workitem create \
  --summary "Fix login validation" \
  --project "TEAM" \
  --type "Bug" \
  --assignee "@me" \
  --label "production,high-priority"

# Output: Created KEY-123

# 2. Transition to In Progress
acli jira workitem transition --key "KEY-123" --status "In Progress"

# 3. Add progress comment
acli jira workitem comment create \
  --key "KEY-123" \
  --body "Found root cause, implementing fix"

# 4. Mark as done
acli jira workitem transition --key "KEY-123" --status "Done"

# 5. Add resolution comment
acli jira workitem comment create \
  --key "KEY-123" \
  --body "Fixed validation logic in LoginController"

Workflow 2: Bulk Update Sprint Items

# 1. Search for sprint items
acli jira workitem search \
  --jql "sprint = 'Sprint 23' AND status = 'To Do'" \
  --fields "key,summary"

# 2. Transition all to In Progress
acli jira workitem transition \
  --jql "sprint = 'Sprint 23' AND status = 'To Do'" \
  --status "In Progress" \
  --yes

# 3. Assign unassigned items to team members
acli jira workitem edit \
  --jql "sprint = 'Sprint 23' AND assignee is EMPTY" \
  --assignee "@me" \
  --yes

Workflow 3: Create Epic with Stories

# 1. Create epic
acli jira workitem create \
  --summary "User Authentication Redesign" \
  --project "TEAM" \
  --type "Epic" \
  --assignee "@me"

# Output: Created TEAM-100

# 2. Create stories under epic
acli jira workitem create \
  --summary "Design new login UI" \
  --project "TEAM" \
  --type "Story" \
  --parent "TEAM-100"

acli jira workitem create \
  --summary "Implement OAuth2 integration" \
  --project "TEAM" \
  --type "Story" \
  --parent "TEAM-100"

acli jira workitem create \
  --summary "Add multi-factor authentication" \
  --project "TEAM" \
  --type "Story" \
  --parent "TEAM-100"

Workflow 4: Daily Standup Report

# Get my current work
acli jira workitem search \
  --jql "assignee = currentUser() AND status in ('In Progress', 'In Review')" \
  --fields "key,summary,status"

# Check what I completed yesterday
acli jira workitem search \
  --jql "assignee = currentUser() AND status changed TO Done AFTER -1d" \
  --fields "key,summary"

Workflow 5: Review and Triage New Bugs

# 1. Find unassigned bugs
acli jira workitem search \
  --jql "project = TEAM AND type = Bug AND assignee is EMPTY" \
  --fields "key,summary,priority,created"

# 2. Assign critical bugs
acli jira workitem edit \
  --jql "project = TEAM AND type = Bug AND priority = Highest AND assignee is EMPTY" \
  --assignee "[e-mail]" \
  --yes

# 3. Add triage label
acli jira workitem edit \
  --jql "project = TEAM AND type = Bug AND created >= -1d" \
  --labels "needs-triage" \
  --yes

Workflow 6: Sprint Cleanup

# 1. Find incomplete items in closed sprint
acli jira workitem search \
  --jql "sprint = 'Sprint 22' AND status != Done" \
  --fields "key,summary,assignee,status"

# 2. Move to next sprint or backlog
acli jira workitem edit \
  --jql "sprint = 'Sprint 22' AND status != Done" \
  --yes
  # (Then manually update sprint in Jira UI or use API)

# 3. Add comment explaining carryover
acli jira workitem comment create \
  --jql "sprint = 'Sprint 22' AND status != Done" \
  --body "Carried over to Sprint 23 due to dependencies"

Workflow 7: Export Issues for Reporting

# Export to CSV for analysis
acli jira workitem search \
  --jql "project = TEAM AND created >= -30d" \
  --fields "key,issuetype,assignee,priority,status,summary,created,resolved" \
  --csv > issues-last-30-days.csv

# Export to JSON for scripting
acli jira workitem search \
  --jql "project = TEAM AND status = Done AND resolved >= -7d" \
  --json > completed-this-week.json

Best Practices

JQL Query Design

1. Be specific: Use precise field matching
2. Use operators: AND, OR, NOT, IN, IS, WAS
3. Date functions: startOfDay(), endOfDay(), startOfWeek()
4. User functions: currentUser(), membersOf()
5. Test first: Use --count to verify query before bulk operations

Bulk Operations Safety

1. Always test JQL: Run search first to verify matching items
2. Use --yes carefully: Only with confirmed queries
3. Use --ignore-errors: For large bulk operations
4. Check limits: Use --paginate for operations on many items
5. Verify results: Check a sample after bulk updates

Field Selection

1. Default fields: Use for quick overview
2. Minimal fields: Use --fields "key,summary" for performance
3. All fields: Use --fields "*all" only when needed
4. Exclude fields: Use --fields "*navigable,-comment" to reduce noise

Output Format Selection

1. Human review: Use default table format
2. Scripting: Use --json for parsing
3. Spreadsheets: Use --csv for export
4. Quick check: Use --web to open in browser
5. Count only: Use --count for metrics

Assignment Best Practices

1. Use @me: For self-assignment
2. Use email: For specific users
3. Use default: For project default assignee
4. Verify users exist: Before bulk assignment
5. Unassign when needed: Use --remove-assignee

Common Patterns

Pattern 1: Find My Open Work

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

Pattern 2: Track Team Velocity

# Completed this sprint
acli jira workitem search \
  --jql "sprint = 'Sprint 23' AND status = Done" \
  --count

# In progress
acli jira workitem search \
  --jql "sprint = 'Sprint 23' AND status = 'In Progress'" \
  --count

Pattern 3: Find Stale Issues

acli jira workitem search \
  --jql "status = 'In Progress' AND updated <= -14d" \
  --fields "key,summary,assignee,updated"

Pattern 4: Label Management

# Add label to matching items
acli jira workitem edit \
  --jql "project = TEAM AND created >= -7d" \
  --labels "new-this-week" \
  --yes

# Remove outdated label
acli jira workitem edit \
  --jql "labels = 'new-this-week' AND created <= -7d" \
  --remove-labels "new-this-week" \
  --yes

Pattern 5: Priority Triage

# Find unprioritzed items
acli jira workitem search \
  --jql "project = TEAM AND priority is EMPTY" \
  --fields "key,summary,created"

# Set default priority
acli jira workitem edit \
  --jql "project = TEAM AND priority is EMPTY" \
  --priority "Medium" \
  --yes

Discovering Custom Field IDs

Jira custom field IDs (customfield_*) vary per instance. To find the correct IDs for sprint, story points, components, etc., inspect an existing issue that already has those fields set:

# Find an issue in the active sprint that has story points set
acli jira workitem search \
  --jql "project = PROJ AND sprint in openSprints()" \
  --fields "key" --limit 1 --json

# View all fields and list non-empty ones with truncated values
acli jira workitem view PROJ-123 --fields "*all" --json \
  | jq -r '
    .fields | to_entries[]
    | select(.value != null and .value != "" and .value != {} and .value != [])
    | "\(.key): \(.value | tostring | .[:200])"
  '

What to look for:

• Sprint: A customfield_* containing a list of objects with boardId, state, startDate, endDate keys
• Story points: A customfield_* containing a plain number (e.g., 5)
• Components: Standard field components (not a custom field) — array of {"id": "...", "name": "..."} objects

You can also list all available fields:

acli jira field --help

Troubleshooting

Issue: JQL Syntax Error

# Problem: Complex JQL failing
# Solution: Build query incrementally

# Start simple
acli jira workitem search --jql "project = TEAM" --count

# Add conditions one at a time
acli jira workitem search --jql "project = TEAM AND status = Open" --count

# Add more specific filters
acli jira workitem search \
  --jql "project = TEAM AND status = Open AND assignee = currentUser()" \
  --count

Issue: No Results from Search

# Verify project key exists
acli jira project list | grep "TEAM"

# Check filter is valid
acli jira filter get --id 10001

# Test broader query
acli jira workitem search --jql "project = TEAM" --count

Issue: Bulk Operation Too Slow

# Problem: Large bulk update timing out
# Solution: Break into smaller batches

# Get count first
acli jira workitem search --jql "project = TEAM" --count

# Process in batches
acli jira workitem edit \
  --jql "project = TEAM AND created >= -7d" \
  --labels "batch1" \
  --yes

acli jira workitem edit \
  --jql "project = TEAM AND created < -7d AND created >= -14d" \
  --labels "batch2" \
  --yes

Issue: Authentication Expired

# Check status
acli jira auth status

# Re-login if needed
acli jira auth login

# Switch to different account
acli jira auth switch

Issue: Permission Denied

# Problem: Cannot edit/delete items
# Solution: Check user permissions in Jira

# Try viewing first
acli jira workitem view KEY-123

# Check project permissions
acli jira project view --key "TEAM"

Advanced Usage

Combining with Other Tools

# Use with jq for JSON processing
acli jira workitem search \
  --jql "project = TEAM" \
  --json | jq '.[] | {key: .key, summary: .fields.summary}'

# Use with xsv for CSV analysis
acli jira workitem search \
  --jql "project = TEAM" \
  --csv | xsv select key,summary,assignee

# Use with grep for filtering
acli jira workitem search \
  --jql "project = TEAM" \
  --fields "key,summary" | grep "authentication"

Scripting Examples

# Create work items from file list
while IFS= read -r summary; do
  acli jira workitem create \
    --summary "$summary" \
    --project "TEAM" \
    --type "Task" \
    --assignee "@me"
done < tasks.txt

# Bulk transition based on external criteria
for key in KEY-{100..110}; do
  acli jira workitem transition \
    --key "$key" \
    --status "Done" \
    --yes 2>/dev/null
done

Quick Reference

# Authentication
acli jira auth login
acli jira auth status

# Search
acli jira workitem search --jql "JQL_QUERY"
acli jira workitem search --jql "JQL_QUERY" --fields "key,summary"
acli jira workitem search --filter FILTER_ID

# View
acli jira workitem view KEY-123
acli jira workitem view KEY-123 --web

# Create
acli jira workitem create --summary "Title" --project "TEAM" --type "Task"

# Edit
acli jira workitem edit --key "KEY-123" --summary "New title"
acli jira workitem edit --jql "JQL_QUERY" --assignee "@me"

# Transition
acli jira workitem transition --key "KEY-123" --status "Done"

# Comment
acli jira workitem comment create --key "KEY-123" --body "Comment"

# Projects
acli jira project list
acli jira project view --key "TEAM"

# Export
acli jira workitem search --jql "JQL_QUERY" --csv > export.csv
acli jira workitem search --jql "JQL_QUERY" --json > export.json

Confluence

acli confluence is thinner than acli jira. It supports:

• acli confluence page view --id <ID> — fetch a page (supports --json, --body-format, --include-labels, etc.)
• acli confluence space list|view|create|update|archive|restore
• acli confluence blog list|view|create
• acli confluence auth login|status|switch|logout

There is no search subcommand. To search Confluence (CQL), use the companion script confluence-search.sh bundled with this skill, then hand the IDs to acli confluence page view --id <ID>.

Search with confluence-search.sh

The script sits alongside this SKILL.md. It reads an Atlassian API token from ~/.netrc and runs CQL against the Confluence REST API. Output is TSV (id\ttitle\turl) by default.

# Text search (wraps into: text ~ "<query>" AND type = "page")
confluence-search.sh "BFF client"

# Scope to a space
confluence-search.sh --space SBP "pagination"

# Raw CQL
confluence-search.sh --cql 'label = "bff" AND type = page ORDER BY lastmodified DESC'

# JSON output (pipe into jq)
confluence-search.sh --json "BFF" | jq '.results'

# Typical flow: search → pick ID → fetch structured
id=$(confluence-search.sh "BFF Client Integration Guide" | head -1 | cut -f1)
acli confluence page view --id "$id" --json

Setup (one-time)

1. Create an Atlassian API token at https://id.atlassian.com/manage-profile/security/api-tokens
2. Add to ~/.netrc:

   machine thescore.atlassian.net
     login [e-mail]
     password <API-TOKEN>
   

3. chmod 600 ~/.netrc

Override the host with CONFLUENCE_HOST=othersite.atlassian.net confluence-search.sh ....

Sandbox note for Claude Code

~/.netrc is in Claude Code's default sandbox deny list, so the script can't read it from a sandboxed Bash call. Set dangerouslyDisableSandbox: true when invoking:

Bash(command="confluence-search.sh 'BFF client'", dangerouslyDisableSandbox=true)

This is the same rule already in force for all acli invocations — different reason (acli hits Keychain; the script hits ~/.netrc), same fix.

Why not reuse acli's stored token?

~/.config/acli/confluence_config.yaml stores the token as !!binary ciphertext, decrypted at runtime via a key stored in the macOS Keychain. Reversing that encryption is fragile and version-dependent. A dedicated API token in ~/.netrc is the clean path.

Summary

Primary directives:

1. Always authenticate first using acli jira auth login
2. Test JQL queries before bulk operations
3. Use --yes flag carefully to avoid unintended changes
4. Select appropriate output format (default, json, csv, web)
5. Use pagination for large result sets
6. Verify permissions before attempting operations
7. Use --ignore-errors for resilient bulk operations

Most common operations:

• acli jira workitem search --jql "..." - Find work items
• acli jira workitem view KEY-123 - View details
• acli jira workitem create - Create new work item
• acli jira workitem edit - Update work items
• acli jira workitem transition - Change status
• acli jira workitem comment create - Add comments
• acli jira project list - List projects

Key features:

• Powerful JQL search capabilities
• Bulk operations with safety controls
• Multiple output formats (table, JSON, CSV, web)
• Pagination for large datasets
• Integration-friendly JSON output