Atlassian Jira Cli Reference

---
name: atlassian-jira-cli-reference
description: "Reference guide for the Atlassian CLI (acli) - a command-line tool for interacting with Jira Cloud and Atlassian organization administration. Use this skill when the user wants to perform Jira operations (create/edit/search/transition work items, manage projects, boards, sprints…"
category: "Productivity"
author: community
version: "1.1.0"
icon: check-square
---

# Atlassian CLI (acli) Reference

## Prerequisites

This skill requires `acli` to be installed and authenticated. The binary is NOT bundled with this skill.

If acli is not installed, guide the user to: https://developer.atlassian.com/cloud/acli/guides/install-acli/

Verify availability:
```bash
acli --help
```

## Authentication

Check auth status before running commands:
```bash
acli jira auth status
acli admin auth status
```

If not authenticated, there are three methods:

**OAuth (interactive, recommended for users):**
```bash
acli jira auth login --web
```

**API Token (non-interactive, recommended for CI/automation):**
```bash
echo "$API_TOKEN" | acli jira auth login --site "mysite.atlassian.net" --email "user@atlassian.com" --token
```

**Admin API Key (for admin commands only):**
```bash
echo "$API_KEY" | acli admin auth login --email "admin@atlassian.com" --token
```

Switch between accounts:
```bash
acli jira auth switch --site mysite.atlassian.net --email user@atlassian.com
acli admin auth switch --org myorgname
```

## Security

### Secret Handling
- **Never hardcode tokens or API keys in commands.** Always use environment variables (`$API_TOKEN`, `$API_KEY`) or file-based input (`< token.txt`).
- **Never log, echo, or display tokens** in output. Avoid piping secrets through intermediate files that persist on disk.
- **Prefer OAuth (`--web`) for interactive use.** Only use token-based auth for CI/automation where OAuth is not feasible.
- **Do not store tokens in shell history.** If using `echo "$API_TOKEN" | acli ...`, ensure the variable is set in the environment rather than inlined as a literal value.

### Destructive Operations
The following commands are **destructive or irreversible** — always confirm with the user before executing:
- `acli jira workitem delete` — permanently deletes work items
- `acli jira project delete` — permanently deletes a project and all its work items
- `acli admin user delete` — deletes managed user accounts
- `acli admin user deactivate` — deactivates user accounts
- `acli jira field delete` — moves custom fields to trash

These commands are **impactful but reversible**:
- `acli jira workitem archive` / `unarchive`
- `acli jira project archive` / `restore`
- `acli admin user cancel-delete` — cancels pending deletion
- `acli jira field cancel-delete` — restores field from trash

**Agent safety rules:**
1. Never run destructive commands without explicit user confirmation, even if `--yes` is available.
2. When bulk-targeting via `--jql` or `--filter`, first run a search with the same query to show the user what will be affected.
3. Prefer `--json` output to verify targets before applying destructive changes.
4. Do not combine `--yes` with destructive bulk operations unless the user explicitly requests unattended execution.

### Organization Admin Commands

Commands under `acli admin` (including `admin user activate`, `deactivate`, `delete`, `cancel-delete`) affect the entire Atlassian organization — the blast radius is org-wide, not scoped to a single project or site. Treat them as a separate tier from other destructive operations:

1. **Require fresh user confirmation in the current turn.** Prior approval from earlier in the session does not carry over to the next admin command. Always re-confirm, even if the user authorized a similar admin command moments ago.
2. **Enumerate resolved targets before executing.** For any `admin user` command, first resolve `--email`, `--id`, or `--from-file` inputs to a concrete list (count plus each email/account ID) and show it to the user. This catches typos in comma-separated lists, stale entries in files, and ambiguous partial matches.
3. **Never use `--ignore-errors` with `admin user delete` or `admin user deactivate`.** A partial failure in a bulk admin operation is a signal to stop and investigate, not to continue silently — half-applied deactivations are harder to audit than a clean halt.

## Command Structure

```
acli <command> [<subcommand> ...] {MANDATORY FLAGS} [OPTIONAL FLAGS]
```

Four top-level command groups:
- `acli jira` - Jira Cloud operations (workitems, projects, boards, sprints, filters, dashboards, fields)
- `acli admin` - Organization administration (user management, auth)
- `acli rovodev` - Rovo Dev AI coding agent (Beta)
- `acli feedback` - Submit feedback/bug reports

## Common Patterns

### Output Formats
Most list/search commands support: `--json`, `--csv`, and default table output.

### Bulk Operations
Target multiple items via:
- `--key "KEY-1,KEY-2,KEY-3"` - comma-separated keys
- `--jql "project = TEAM AND status = 'To Do'"` - JQL query
- `--filter 10001` - saved filter ID
- `--from-file "items.txt"` - file with keys/IDs (comma/whitespace/newline separated)

Use `--ignore-errors` to continue past failures in bulk operations.
Use `--yes` / `-y` to skip confirmation prompts (useful for automation).

### Pagination
- `--limit N` - max items to return (defaults vary: 30-50)
- `--paginate` - fetch all pages automatically (overrides --limit)

### JSON Templates
Many create/edit commands support `--generate-json` to produce a template, and `--from-json` to consume it:
```bash
acli jira workitem create --generate-json > template.json
# edit template.json
acli jira workitem create --from-json template.json
```

## Quick Reference: Most Common Operations

### Work Items
```bash
# Create
acli jira workitem create --summary "Fix login bug" --project "TEAM" --type "Bug"
acli jira workitem create --summary "New feature" --project "TEAM" --type "Story" --assignee "@me" --label "frontend,p1"

# Search
acli jira workitem search --jql "project = TEAM AND assignee = currentUser()" --json
acli jira workitem search --jql "project = TEAM AND status = 'In Progress'" --fields "key,summary,assignee" --csv

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

# Edit
acli jira workitem edit --key "KEY-123" --summary "Updated title" --assignee "user@atlassian.com"

# Transition
acli jira workitem transition --key "KEY-123" --status "Done"
acli jira workitem transition --jql "project = TEAM AND sprint in openSprints()" --status "In Progress"

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

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

# Bulk create
acli jira workitem create-bulk --from-csv issues.csv
```

### Projects
```bash
acli jira project list --paginate --json
acli jira project view --key "TEAM" --json
acli jira project create --from-project "TEAM" --key "NEW" --name "New Project"
```

### Boards & Sprints
```bash
acli jira board search --project "TEAM"
acli jira board list-sprints --id 123 --state active
acli jira sprint list-workitems --sprint 1 --board 6
```

## Detailed Command Reference

For complete flag details, parameters, and examples for every command:

- **Jira work item commands** (create, edit, search, assign, transition, comment, clone, link, archive, attachment, watcher): See [references/jira-workitem-commands.md](references/jira-workitem-commands.md)
- **All other commands** (jira project/board/sprint/filter/dashboard/field, admin, rovodev, feedback): See [references/other-commands.md](references/other-commands.md)