ACLI - Atlassian CLI Docker Wrapper

A lightweight, containerized wrapper for Atlassian CLI (ACLI) that simplifies Jira Cloud operations through Docker.

Use it to download Jira issues and interact with Jira from the command line.

Using this wrapper:

• Provides an alternative to MCP: reducing time and consuming fewer tokens
• Zero-configuration global installation
• Does not require special instructions for LLMs to use since it's just a CLI
• Use it to compose powerful scripts without the need for an MCP integration
• More complete feature set than the Jira MCP

Contents

• Quick Start
• Prerequisites
• Installation
• Configuration
  • Authentication Setup
  • Environment Variables
  • Volume Mounts
• Usage
  • Basic Commands
  • Common Use Cases
  • Shell Aliases
• Image Information
• Development
• Contributing
• License

Quick Start

1. One-Line Install

curl -fsSL https://raw.githubusercontent.com/zero-to-prod/acli/main/install.sh | bash

2. Authenticate:

Get a token from https://id.atlassian.com/manage-profile/security/api-tokens

docker run -it --rm -v ~/.config/acli:/root/.config/acli davidsmith3/acli:latest jira auth login

3. View an issue:

docker run -it --rm -v ~/.config/acli:/root/.config/acli davidsmith3/acli jira workitem view PROJ-123

4. Alias (Recommended) Since this package is a Docker wrapper, an LLM should need no specific instructions to use the underlying CLI.

Adding an alias makes the wrapper transparent, allowing it to be used naturally.

alias acli='docker run -it --rm -v ~/.config/acli:/root/.config/acli -v $(pwd):/workspace -w /workspace davidsmith3/acli'

5. Run Directly (Optional)

Use this to run in non-interactive contexts such as CI/CD pipelines, scripts, or other automation.

docker run --rm -v ~/.config/acli:/root/.config/acli -v $(pwd):/workspace -w /workspace davidsmith3/acli jira workitem view [ISSUE_KEY]

Manual Setup

# Pull the image
docker pull davidsmith3/acli:latest

# Authenticate (one-time setup)
docker run -it --rm -v ~/.config/acli:/root/.config/acli davidsmith3/acli jira auth login

# Run a command (example: view a Jira issue)
docker run -it --rm -v ~/.config/acli:/root/.config/acli davidsmith3/acli jira workitem view PROJ-123

Creating Shell Aliases

For convenience, create an alias in your shell configuration (.bashrc, .zshrc):

alias acli='docker run -it --rm -v ~/.config/acli:/root/.config/acli -v $(pwd):/workspace -w /workspace davidsmith3/acli'

Prerequisites

Before using this Docker image, ensure you have:

• Docker: Version 20.10+ or Docker Desktop (Windows/Mac)
• Docker Compose (optional): Version 1.29+
• Atlassian Account: With API token for authentication

Installation

Option 1: Using Docker Run (Recommended)

Pull the latest image from Docker Hub:

docker pull davidsmith3/acli:latest

Option 2: Using Docker Compose

Create a docker-compose.yml:

services:
  acli:
    image: davidsmith3/acli:latest
    container_name: acli
    volumes:
      - ~/.config/acli:/root/.config/acli
    environment:
      - TZ=UTC

Run with:

docker-compose run --rm acli --help

Available Tags

• latest - Current stable release (recommended)
• {X.Y.Z} - Specific versions (e.g., 1.1.3)
• {X.Y} - Major.minor versions (e.g., 1.1)

Configuration

Authentication Setup (Required)

ACLI requires authentication to connect to your Atlassian instance.

Step 1: Create Local Configuration

Configure ACLI with your credentials:

docker run -it --rm -v ~/.config/acli:/root/.config/acli davidsmith3/acli jira auth login

Follow the interactive prompts to:

• Set your Atlassian instance URL
• Provide your email address
• Enter your API token

Environment Variables

Optional environment variables you can set:

docker run -it --rm \
  -e ACLI_HOME=/root/.config/acli \
  -e TZ=UTC \
  -v ~/.config/acli:/root/.config/acli \
  davidsmith3/acli [COMMAND]

Supported variables:

• ACLI_HOME - Configuration directory (default: /root/.config/acli)
• TZ - Timezone setting (default: UTC)

Volume Mounts

Essential volumes:

Volume	Purpose	Required
~/.config/acli:/root/.config/acli	Credentials & configuration	Yes
$(pwd):/workspace	Current directory access	Optional

Example with workspace mount:

docker run -it --rm \
  -v ~/.config/acli:/root/.config/acli \
  -v $(pwd):/workspace \
  -w /workspace \
  davidsmith3/acli [COMMAND]

Security Considerations

• Credentials are stored in ~/.config/acli on your host machine
• Never commit .config/acli to version control
• Ensure file permissions are restrictive: chmod 700 ~/.config/acli
• Use API tokens instead of passwords for authentication

Usage

Basic Command Structure

docker run -it --rm -v ~/.config/acli:/root/.config/acli davidsmith3/acli [COMMAND] [OPTIONS]

Quick Reference

Display help:

# General help
docker run -it --rm davidsmith3/acli --help

# Command-specific help
docker run -it --rm davidsmith3/acli [COMMAND] --help

Common Use Cases

Jira Operations

View an issue:

docker run -it --rm -v ~/.config/acli:/root/.config/acli davidsmith3/acli jira workitem view PROJ-123

View with all fields:

docker run -it --rm -v ~/.config/acli:/root/.config/acli davidsmith3/acli jira workitem view PROJ-123 --fields '*all'

Search for issues:

docker run -it --rm -v ~/.config/acli:/root/.config/acli davidsmith3/acli jira workitem search --jql "project = MY-PROJECT"

Create an issue:

docker run -it --rm -v ~/.config/acli:/root/.config/acli davidsmith3/acli jira workitem create \
  --project MY-PROJECT \
  --type Bug \
  --summary "Issue summary" \
  --description "Issue description"

Add a comment:

docker run -it --rm -v ~/.config/acli:/root/.config/acli davidsmith3/acli jira workitem comment \
  PROJ-123 \
  --add "This is a comment"

Transition an issue:

docker run -it --rm -v ~/.config/acli:/root/.config/acli davidsmith3/acli jira workitem transition \
  PROJ-123 \
  --name "In Progress"

After adding the alias, restart your shell or run source ~/.bashrc. Then you can use:

acli jira workitem view PROJ-123

Using Docker Compose

# Run a command
docker-compose run --rm acli jira workitem search --jql "project = MY-PROJECT"

# Interactive mode
docker-compose run --rm acli

Export to CSV

Export issues using JQL search with CSV format:

docker run -it --rm \
  -v ~/.config/acli:/root/.config/acli \
  -v $(pwd):/workspace \
  -w /workspace \
  davidsmith3/acli jira workitem search \
  --jql "project = MY-PROJECT" \
  --csv > export.csv

Image Information

Docker Hub

• Repository: davidsmith3/acli
• Pull Command: docker pull davidsmith3/acli

Updating the Image

# Pull the latest version
docker pull davidsmith3/acli:latest

# Verify the update
docker run --rm davidsmith3/acli --version

Development

For development or custom builds, see Image Development.

Project Links

• GitHub Repository: zero-to-prod/acli
• Docker Hub: davidsmith3/acli
• ACLI Official Docs: Atlassian CLI Reference

Contributing

Contributions, issues, and feature requests are welcome! Feel free to check the issues page if you want to contribute.

Please read our:

• Contributing Guide - Contribution guidelines
• Code of Conduct - Community standards
• Security Policy - Vulnerability reporting

How to Contribute

1. Fork the repository
2. Create a new branch (git checkout -b feature-branch)
3. Make your changes
4. Commit changes (git commit -m 'Add some feature')
5. Push to the branch (git push origin feature-branch)
6. Create a Pull Request

License

This project is licensed under the MIT License - see LICENSE.md for details.

---

Maintained by: ZeroToProd Last Updated: 2025-11-16