Managing Jira Tasks and Subtasks from the CLI

atlassian-cli is an independent, community open-source project, not affiliated with, endorsed by, or sponsored by Atlassian, and is not Atlassian's official CLI (acli). Product names are used only to identify compatibility.

Task Ops from the Terminal

Jira task management from the command line means creating, linking, transitioning, and updating individual issues without leaving your terminal. With atlassian-cli, one command creates a Jira task, another attaches a subtask to it, and a third moves it across your workflow. No mouse, no context-switch to the browser, and every step is a line you can paste into a script.

This guide is about the day-to-day operations that make up most of a developer's Jira time: opening a task, splitting it into subtasks, wiring up "blocks" and "relates to" links, pushing status forward, and dropping a comment. These are the small, repetitive actions that add up. Doing them in a terminal keeps you in flow and makes each one repeatable.

Before running any command, authenticate once with atlassian-cli auth login (see the authentication guide). Every example below assumes a project key of DEV; swap in your own.

Create a Task

The core command is jira issue create. At minimum it needs a project, an issue type, and a summary:

# Minimal task
atlassian-cli jira issue create \
  --project DEV \
  --issue-type Task \
  --summary "Add rate-limit retry to the API client"

On success the CLI prints the new issue key (for example, DEV-142). You can fill in more fields in the same call. The --description flag accepts Markdown and converts it to Jira's rich-text ADF format, so headings, lists, bold, inline code, and links all render correctly:

# Fully specified task
atlassian-cli jira issue create \
  --project DEV \
  --issue-type Task \
  --summary "Add rate-limit retry to the API client" \
  --description "Retry on HTTP 429 with exponential backoff. See DEV-98 for the throttling report." \
  --assignee dev@example.com \
  --priority High

Need a field that has no dedicated flag, like a custom "Team" or "Sprint" select? Use the repeatable --field flag with a key=JSON pair. Discover field IDs with atlassian-cli jira fields list:

atlassian-cli jira issue create \
  --project DEV \
  --issue-type Task \
  --summary "Instrument the retry path" \
  --field 'customfield_10010={"value":"Platform"}'

Once the task exists, read it back at any time with jira issue get:

atlassian-cli jira issue get DEV-142

Break a Task into Subtasks

A subtask in Jira is a normal issue with a subtask issue type and a parent. atlassian-cli has no dedicated --parent flag, so you set the parent through the same generic --field mechanism using the parent's key:

# Two subtasks under DEV-142
atlassian-cli jira issue create \
  --project DEV \
  --issue-type Sub-task \
  --summary "Write the backoff helper" \
  --field 'parent={"key":"DEV-142"}'

atlassian-cli jira issue create \
  --project DEV \
  --issue-type Sub-task \
  --summary "Add unit tests for 429 handling" \
  --field 'parent={"key":"DEV-142"}'

Two things matter here. First, --issue-type must name a subtask type that exists in your project; the Jira default is Sub-task, but some instances rename it (for example, Subtask). Second, parent is not a reserved key, so passing it via --field is allowed and maps straight to the Jira REST field.

To see every subtask under a parent, search by JQL. The parent JQL field returns the children directly:

# List all subtasks of DEV-142
atlassian-cli jira issue search --jql "parent = DEV-142"

If you are modelling larger structures like epics and stories rather than a single task and its subtasks, read Jira issue hierarchy: epics, stories, and subtasks from the CLI for the level above this one.

Link Tasks Together

Subtasks capture a parent-child breakdown. Issue links capture relationships between peers: this task blocks that one, this bug duplicates another, this story relates to a spike. Create a link with jira issue links create, giving the source key, the target key, and a link type:

# DEV-142 is blocked by DEV-98
atlassian-cli jira issue links create DEV-142 DEV-98 --link-type "is blocked by"

# DEV-142 relates to a discovery spike
atlassian-cli jira issue links create DEV-142 DEV-150 --link-type "relates to"

The link type name must match one that is configured in your Jira instance. The common defaults are blocks, is blocked by, relates to, duplicates, is duplicated by, clones, and is cloned by. If your admin has renamed or added link types, use those exact names.

To remove a link later, delete it by its link ID:

atlassian-cli jira issue links delete 10432

Transition, Assign, and Comment

Most day-to-day churn is moving a task through its workflow and keeping people informed. Transition a task by naming the target step. The CLI resolves the name against the transitions that are actually available for that issue right now, so the step you name has to be a valid next move from the current status:

# Move the task forward
atlassian-cli jira issue transition DEV-142 --transition "In Progress"

# ...and later, when it ships
atlassian-cli jira issue transition DEV-142 --transition "Done"

Assign and unassign are their own verbs:

atlassian-cli jira issue assign DEV-142 --assignee dev@example.com
atlassian-cli jira issue unassign DEV-142

Comments live under jira issue comments. Add one with --body, and the same Markdown-to-ADF conversion applies, so you can include links and inline code:

atlassian-cli jira issue comments add DEV-142 \
  --body "Blocked until DEV-98 ships the throttle fix. Picking up the tests in the meantime."

# Read the thread back, full bodies
atlassian-cli jira issue comments list DEV-142 --full

Want to follow a task without owning it? Add yourself, or a stakeholder, as a watcher:

atlassian-cli jira issue watchers add DEV-142 lead@example.com

And when scope shifts, jira issue update edits fields in place. Only the flags you pass are changed:

atlassian-cli jira issue update DEV-142 \
  --summary "Add rate-limit retry with jitter to the API client" \
  --priority Highest

A Daily Task Management Workflow

Individually these commands are handy. Chained together they replace a lot of clicking. Here is a small script that stands up a task, splits it into two subtasks, links a blocker, and starts work in one pass:

#!/bin/bash
# Spin up a task with subtasks and a blocker link
set -euo pipefail

PROJECT="DEV"

# 1. Create the parent task and capture its key from JSON output
PARENT=$(atlassian-cli jira issue create \
  --project "$PROJECT" \
  --issue-type Task \
  --summary "Add rate-limit retry to the API client" \
  --assignee dev@example.com \
  --format json | jq -r '.key')

echo "Created $PARENT"

# 2. Add subtasks under it
atlassian-cli jira issue create --project "$PROJECT" --issue-type Sub-task \
  --summary "Write the backoff helper" \
  --field "parent={\"key\":\"$PARENT\"}"

atlassian-cli jira issue create --project "$PROJECT" --issue-type Sub-task \
  --summary "Add unit tests for 429 handling" \
  --field "parent={\"key\":\"$PARENT\"}"

# 3. Record the blocker and start work
atlassian-cli jira issue links create "$PARENT" DEV-98 --link-type "is blocked by"
atlassian-cli jira issue transition "$PARENT" --transition "In Progress"

The trick that makes this scriptable is --format json piped to jq. Every command emits machine-readable output on request, so you can capture a new issue key and feed it into the next step. For a running view of your own plate, search with a JQL query and let the CLI sort it:

# My open tasks, most recently updated first
atlassian-cli jira issue search \
  --jql "assignee = currentUser() AND statusCategory != Done ORDER BY updated DESC" \
  --limit 20

Keep this as a shell alias and you have a one-keystroke standup report. If you need to create dozens of tasks at once from a spreadsheet instead of one at a time, see creating Jira issues from a CSV.

Command Reference Table

The full task-management surface at a glance. These are the exact verbs; see the command reference for every flag.

For the same commands laid out as a printable crib sheet with more search and output examples, see the Jira CLI commands cheat sheet.

FAQ

Related Resources