Skip to content

Instantly share code, notes, and snippets.

@rolandkakonyi

rolandkakonyi/aclix.md

Last active August 6, 2025 22:01
Show Gist options
  • Save rolandkakonyi/41df9c47f5e9ef797990c5a59f510c8d to your computer and use it in GitHub Desktop.
Save rolandkakonyi/41df9c47f5e9ef797990c5a59f510c8d to your computer and use it in GitHub Desktop.
Download ZIP
Raw
aclix.md

🛠️ Atlassian CLI (ACLI) Jira Guide – Up-to-Date (2025)

This guide covers the Jira-related features of ACLIX, a wrapper around the Atlassian CLI (acli) that adds custom commands. Uses the official Atlassian Developer Reference as of mid-2025. Ref: https://developer.atlassian.com/cloud/acli/reference/commands/jira/

Installation

Install ACLI (Required)

brew tap atlassian/homebrew-acli
brew install acli

Install ACLIX Wrapper

Download and install the aclix wrapper script:

# Download the script
curl -o ~/scripts/aclix.sh https://gist.githubusercontent.com/rolandkakonyi/dd822ec2833f40b0f8adbecc90777e30/raw/aclix.sh

# Make it executable
chmod +x ~/scripts/aclix.sh

# Add alias to your shell profile (.zshrc, .bashrc, etc.)
echo 'alias aclix="~/scripts/aclix.sh"' >> ~/.zshrc

# Install completions (for zsh)
~/scripts/aclix.sh completion zsh > ~/.zsh/_aclix
echo 'source ~/.zsh/_aclix' >> ~/.zshrc
echo 'compdef _aclix aclix 2>/dev/null || true' >> ~/.zshrc

# Reload your shell
exec zsh

Assume aclix is already authenticated for you! If it fails due to authentication, provide the user with auth options!

Project ID Selection

Always ask the user for PROJECT ID (like PROJ-123) before invoking aclix if the project ID is needed for a given command, unless explicitly stated by the user on which project to work on. When asking for the project ID, provide the list of available projects as a numbered list to make it easy to select.

🚪 Authenticate to Jira

aclix jira auth login --web

Or use an API token:

aclix jira auth login --site "https://your-site.atlassian.net" \\
  --email "[email protected]" --token <API-token>

✍️ Workitem Commands

Workitem rich text formatting

Use the Atlaskit Document Format (ADF) with JSON when rich text formatting is needed.

Important: ADF formatting is only supported for creating work items, not editing existing ones.

Generate the correct JSON template first:

aclix jira workitem create --generate-json > template.json

Create work item with ADF:

aclix jira workitem create --from-json adf-issue.json

The adf-issue.json must use the correct field names (note projectKey not project):

{
  "projectKey": "AISA",
  "summary": "Add type-safe scene classification",
  "type": "Story",
  "description": {
    "version": 1,
    "type": "doc",
    "content": [
      {
        "type": "paragraph",
        "content": [
          { "type": "text", "text": "Add type-safe scene classification to the data model." }
        ]
      },
      {
        "type": "heading",
        "attrs": { "level": 2 },
        "content": [{ "type": "text", "text": "Technical Implementation:" }]
      },
      {
        "type": "bulletList",
        "content": [
          {
            "type": "listItem",
            "content": [
              {
                "type": "paragraph", 
                "content": [{ "type": "text", "text": "Create SceneType enum with 11 scene types" }]
              }
            ]
          },
          {
            "type": "listItem",
            "content": [
              {
                "type": "paragraph",
                "content": [{ "type": "text", "text": "Add nullable type and typeConfidence fields to Scene" }]
              }
            ]
          }
        ]
      },
      {
        "type": "paragraph",
        "content": [
          {
            "type": "text",
            "marks": [{ "type": "code" }],
            "text": "lib/src/main/kotlin/Scene.kt"
          },
          { "type": "text", "text": " - file to modify" }
        ]
      }
    ]
  }
}

Complete ADF (Atlassian Document Format) Reference

Based on the official Atlassian documentation, ADF is a JSON-based format for representing rich text across Atlassian products.

Document Structure

Every ADF document follows this root structure:

{
  "version": 1,
  "type": "doc",
  "content": [ /* array of block nodes */ ]
}

Block Nodes (Top-level)

Node Type Description Example
paragraph Basic text paragraph {"type": "paragraph", "content": [...]}
heading Headers (levels 1-6) {"type": "heading", "attrs": {"level": 2}, "content": [...]}
bulletList Unordered list {"type": "bulletList", "content": [...]}
orderedList Ordered/numbered list {"type": "orderedList", "content": [...]}
blockquote Quote blocks {"type": "blockquote", "content": [...]}
codeBlock Code blocks with syntax highlighting {"type": "codeBlock", "attrs": {"language": "kotlin"}, "content": [...]}
panel Info/warning/error panels {"type": "panel", "attrs": {"panelType": "info"}, "content": [...]}
table Tables {"type": "table", "content": [...]}
rule Horizontal rule/divider {"type": "rule"}

Child Block Nodes

Node Type Description Parent
listItem List item container bulletList, orderedList
tableRow Table row table
tableCell Table cell tableRow

Inline Nodes

Node Type Description Example
text Plain or formatted text {"type": "text", "text": "Hello", "marks": [...]}
hardBreak Line break {"type": "hardBreak"}
mention User mentions {"type": "mention", "attrs": {"id": "user-id"}}
emoji Emoji {"type": "emoji", "attrs": {"shortName": ":smile:"}}
date Date stamps {"type": "date", "attrs": {"timestamp": "1234567890"}}
status Status lozenges {"type": "status", "attrs": {"text": "TODO", "color": "blue"}}

Text Marks (Formatting)

Mark Type Description Example
strong Bold text "marks": [{"type": "strong"}]
em Italic text "marks": [{"type": "em"}]
code Inline code "marks": [{"type": "code"}]
link Hyperlinks "marks": [{"type": "link", "attrs": {"href": "url"}}]
underline Underlined text "marks": [{"type": "underline"}]
strike Strikethrough text "marks": [{"type": "strike"}]
textColor Colored text "marks": [{"type": "textColor", "attrs": {"color": "#FF0000"}}]
subsup Subscript/superscript "marks": [{"type": "subsup", "attrs": {"type": "sup"}}]

Common Patterns

Basic Text with Formatting:

{
  "type": "paragraph",
  "content": [
    {
      "type": "text",
      "text": "This is ",
      "marks": []
    },
    {
      "type": "text", 
      "text": "bold text",
      "marks": [{"type": "strong"}]
    },
    {
      "type": "text",
      "text": " and this is ",
      "marks": []
    },
    {
      "type": "text",
      "text": "italic",
      "marks": [{"type": "em"}]
    }
  ]
}

Lists with Mixed Content:

{
  "type": "bulletList",
  "content": [
    {
      "type": "listItem",
      "content": [
        {
          "type": "paragraph",
          "content": [
            {
              "type": "text",
              "text": "First item with "
            },
            {
              "type": "text",
              "text": "code",
              "marks": [{"type": "code"}]
            }
          ]
        }
      ]
    },
    {
      "type": "listItem", 
      "content": [
        {
          "type": "paragraph",
          "content": [
            {
              "type": "text",
              "text": "Second item"
            }
          ]
        }
      ]
    }
  ]
}

Info Panel:

{
  "type": "panel",
  "attrs": {
    "panelType": "info"
  },
  "content": [
    {
      "type": "paragraph",
      "content": [
        {
          "type": "text",
          "text": "This is an info panel with important information"
        }
      ]
    }
  ]
}

Code Block with Syntax Highlighting:

{
  "type": "codeBlock",
  "attrs": {
    "language": "kotlin"
  },
  "content": [
    {
      "type": "text",
      "text": "data class Scene(\n    val id: String,\n    val type: SceneType?\n)"
    }
  ]
}

Table Structure:

{
  "type": "table",
  "content": [
    {
      "type": "tableRow",
      "content": [
        {
          "type": "tableCell",
          "content": [
            {
              "type": "paragraph",
              "content": [
                {
                  "type": "text",
                  "text": "Header 1",
                  "marks": [{"type": "strong"}]
                }
              ]
            }
          ]
        },
        {
          "type": "tableCell", 
          "content": [
            {
              "type": "paragraph",
              "content": [
                {
                  "type": "text",
                  "text": "Header 2",
                  "marks": [{"type": "strong"}]
                }
              ]
            }
          ]
        }
      ]
    },
    {
      "type": "tableRow",
      "content": [
        {
          "type": "tableCell",
          "content": [
            {
              "type": "paragraph",
              "content": [
                {
                  "type": "text",
                  "text": "Cell 1"
                }
              ]
            }
          ]
        },
        {
          "type": "tableCell",
          "content": [
            {
              "type": "paragraph", 
              "content": [
                {
                  "type": "text",
                  "text": "Cell 2"
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

Panel Types

  • info - Blue info panel
  • note - Yellow note panel
  • tip - Green tip panel
  • warning - Orange warning panel
  • error - Red error panel

Validation:

Always validate JSON with jsonschema CLI tool before passing it to aclix and fix if any issues arise. ADF JSON schema can be found at: http://go.atlassian.com/adf-json-schema.

# Download schema for validation
curl -o ~/.jsonschema/jira-adf.json http://go.atlassian.com/adf-json-schema

# Validate your ADF JSON
jsonschema -i your-adf.json ~/.jsonschema/jira-adf.json

Limitations:

  • Creation only: ADF works with create --from-json but NOT with edit
  • Editing existing tickets: Use Wiki Markup or plain text with workitem edit --description
  • Complexity: ADF can become verbose for complex formatting - consider readability vs. functionality

1. Create Work Items

aclix jira workitem create \\
  --summary "New Task" \\
  --project "PROJ-123" \\
  --type "Task"
  • Use --from-file or --from-json to import data.
  • Use --assignee, --description, --label, --parent, --generate-json as needed.

2. Search Work Items

aclix jira workitem search --jql "project = PROJ-123 AND assignee = currentUser()" \\
  --fields "key,summary,status,assignee" --limit 50 --json

3. View Work Items

aclix jira workitem view PROJ-123 --fields summary,comment --json
aclix jira workitem view PROJ-123 --web

# View issue links and relationships
aclix jira workitem view AISA-53 --fields issuelinks --json

4. Edit Work Items

aclix jira workitem edit --key "PROJ-123,PROJ-124" --summary "Updated summary"
aclix jira workitem edit --jql "project = PROJ-123" --assignee "[email protected]"

5. Transition Work Items

aclix jira workitem transition --key "PROJ-123" --status "In Progress"
aclix jira workitem transition --jql "project = PROJ-123 AND status = 'To Do'" --status "Done" --yes

6. Assign Work Items

aclix jira workitem assign --key "PROJ-123" --assignee "@me"
aclix jira workitem assign --jql "project = PROJ-123" --assignee "[email protected]"

7. Add Comments

aclix jira workitem comment --key "PROJ-123" --body "Looks good to me."
aclix jira workitem comment --jql "project = PROJ-123" --body-file comment.txt --edit-last

8. Clone Work Items

aclix jira workitem clone --key "PROJ-123" --to-project "PROJ-123"
aclix jira workitem clone --jql "project = TEMPLATE" --to-project "NEWPROJ" --yes

9. Archive & Unarchive

aclix jira workitem archive --key "PROJ-123"
aclix jira workitem unarchive --key "PROJ-123"

10. Link Work Items

Custom Wrapper Command - Creates links between Jira issues using the REST API (not available in standard acli):

List Available Link Types

First, discover what link types are available in your Jira instance:

aclix jira workitem link-types [OPTIONS]

Parameters:

  • --site URL - Jira site base URL (overrides $JIRA_SITE env var)
  • --json - Output raw JSON response
  • --verbose - Enable verbose logging

Environment Variables Required:

  • JIRA_EMAIL - Atlassian account email (required)
  • JIRA_API_TOKEN - Atlassian API token (required)
  • JIRA_SITE - Base URL like https://your-site.atlassian.net (optional if --site provided)

Examples:

# List all available link types (pretty formatted)
aclix jira workitem link-types

# Get raw JSON output for parsing
aclix jira workitem link-types --json

# Use specific site
aclix jira workitem link-types --site https://example.atlassian.net

# Verbose logging
aclix jira workitem link-types --verbose

Sample Output:

Name: Blocks
  Outward: blocks
  Inward: is blocked by

Name: Relates
  Outward: relates to
  Inward: relates to

Name: Duplicate
  Outward: duplicates
  Inward: is duplicated by

Create Issue Links

aclix jira workitem link --key ISSUE-1 --to ISSUE-2 --type TYPE [OPTIONS]

Required Parameters:

  • --key KEY - Source issue key (e.g., PROJ-123)
  • --to KEY - Target issue key (e.g., PROJ-456)
  • --type TYPE - Link type name or description

Optional Parameters:

  • --site URL - Jira site base URL (overrides $JIRA_SITE env var)
  • --comment TEXT - Optional comment body to attach to the link
  • --direction outward|inward - Force link direction (default: derived from type)
  • --dry-run - Print the HTTP request body without creating the link
  • --verbose - Enable verbose logging

Environment Variables:

  • JIRA_EMAIL - Atlassian account email (required)
  • JIRA_API_TOKEN - Atlassian API token (required)
  • JIRA_SITE - Base URL like https://your-site.atlassian.net (optional if --site provided)

Common Link Types:

Use the link-types command to see all available types in your instance. Common ones include:

  • "Blocks" / "is blocked by"
  • "Relates" / "relates to"
  • "Duplicates" / "is duplicated by"
  • "Cloners" / "is cloned by"

Examples:

# First, discover available link types
aclix jira workitem link-types

# Create a blocking relationship
aclix jira workitem link --key AIC-101 --to AIC-99 --type "Blocks"

# Create a relation with comment
aclix jira workitem link --key AIC-101 --to AIC-99 --type "relates to" --comment "Related implementation"

# Use specific site
aclix jira workitem link --key AIC-101 --to AIC-99 --type "is blocked by" --site https://example.atlassian.net

# Dry run to see the request
aclix jira workitem link --key AIC-101 --to AIC-99 --type "Duplicates" --dry-run

11. Delete Work Items

aclix jira workitem delete --key "PROJ-123,PROJ-124" --yes

📁 Project & Filter Management

List Projects

aclix jira project list --limit 50

Create Project from Template

aclix jira project create --from-project "TEMPLATE" --key "NEW" \\
  --name "New Project" --description "..." --lead-email "[email protected]"

🧪 Help & Debug

aclix jira --help
aclix jira project --help
aclix jira workitem <command> --help

✅ Summary Table

Function Command Example
Create issue workitem create --summary …
Search issues workitem search --jql … --json
View issue workitem view PROJ-123 --fields summary,comment
View issue links workitem view PROJ-123 --fields issuelinks --json
Edit issue workitem edit --key … --summary …
Transition issue workitem transition --jql … --status …
Assign issue workitem assign --key … --assignee …
Comment on issue workitem comment --key … --body …
Clone issue workitem clone --key … --to-project …
List link types workitem link-types [--json] (via aclix)
Link issues workitem link --key … --to … --type … (via aclix)
Archive/unarchive workitem archive/unarchive --key …
Delete issue workitem delete --filter …
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment