Atlassian CLI (atl) - Agent Reference

This document provides guidance for LLM agents using the atl CLI tool.

Overview

atl is a command-line tool for Jira and Confluence. All commands support --json for structured output, making it ideal for programmatic use.

Authentication

atl auth status                         # Check authentication status
atl auth login                          # Authenticate (opens browser)

Context Switching (Multi-Environment)

Switch between Atlassian instances using aliases:

# Create aliases
atl config set-alias prod                                    # alias "prod" → current host
atl config set-alias sandbox mycompany-sandbox.atlassian.net # alias → specific host

# Switch active host
atl config use-context prod       # by alias
atl config use-context mycompany.atlassian.net  # by hostname

# Show current context
atl config current-context        # prints alias + hostname
atl config current-context --json # JSON output

# Remove alias
atl config delete-alias sandbox

# View aliases
atl config list                   # shows Aliases section with (current) marker

Aliases also work with --hostname flags: atl auth status --hostname prod

Jira Issues

View Issues

atl issue view PROJ-1234                  # View issue details (includes custom fields)
atl issue view PROJ-1234 --json           # View as JSON (includes custom_fields section)
atl issue view PROJ-1234 --web            # Open in browser

List Issues

atl issue list --assignee @me           # Your assigned issues
atl issue list --project PROJ             # Issues in project
atl issue list --jql "status = Open"    # Custom JQL query
atl issue list --jql "sprint in openSprints() AND assignee = currentUser()"

Create Issues

atl issue create --project PROJ --type Bug --summary "Title"
atl issue create --project PROJ --type Task --summary "Title" --description "Details"
atl issue create --project PROJ --parent PROJ-123 --summary "Subtask"

Edit Issues

atl issue edit PROJ-1234 --summary "New summary"
atl issue edit PROJ-1234 --description "New description content"
atl issue edit PROJ-1234 --description "Additional notes" --append  # Append to existing
atl issue edit PROJ-1234 --assignee @me
atl issue edit PROJ-1234 --add-label bug --remove-label wontfix
atl issue edit PROJ-1234 --field "Story Points=8"
atl issue edit PROJ-1234 --field "Custom Field=Some **markdown** text"  # Auto-converts to ADF

Notes:

--append preserves existing description content (including embedded media) and adds new content at the end
Textarea custom fields automatically convert Markdown to ADF format

Transitions and Workflow

atl issue transition PROJ-1234 "In Progress"
atl issue transition PROJ-1234 --list     # List available transitions
atl issue transition PROJ-1234 "Done" --field "Resolution=Fixed"  # With required fields

Comments

atl issue comment list PROJ-1234                    # List comments
atl issue comment add PROJ-1234 --body "Comment"    # Add comment
atl issue comment add PROJ-1234 --body-file msg.md  # Add from file (avoids shell escaping)
atl issue comment edit PROJ-1234 --id 123 --body "Updated"
atl issue comment edit PROJ-1234 --id 123 --body-file msg.md
atl issue comment delete PROJ-1234 --id 123

Issue Links

atl issue link PROJ-1234 PROJ-5678                    # Link issues (default: Relates)
atl issue link PROJ-1234 PROJ-5678 --type Blocks      # Link with specific type

Web Links

atl issue weblink PROJ-1234 --url "https://..." --title "Title"

Sprint Management

atl issue sprint PROJ-1234 --sprint-id 123          # Move to sprint
atl issue sprint PROJ-1234 --backlog                # Move to backlog

Attachments

atl issue attachment PROJ-1234 --list               # List attachments
atl issue attachment PROJ-1234 --download <id>      # Download attachment

Metadata Discovery

atl issue types --project PROJ                      # List issue types
atl issue priorities                                # List available priorities
atl issue fields                                    # List all fields
atl issue fields --search "story points"            # Search for field by name
atl issue field-options --project PROJ --type Bug   # Show allowed values for fields
atl issue field-options --project PROJ --type Bug --field "Priority"  # Specific field

Jira Boards

atl board list                                    # List all boards
atl board list --project PROJ                       # List boards for project
atl board rank PROJ-123 --before PROJ-456             # Rank issue before another
atl board rank PROJ-123 --after PROJ-456              # Rank issue after another
atl board rank PROJ-123 --top --board-id 42         # Move to top of backlog

Confluence

Spaces

atl confluence space list               # List spaces
atl confluence space list --json        # List as JSON

Pages

atl confluence page view <id>           # View page by ID
atl confluence page view --space DOCS --title "Title"
atl confluence page list --space DOCS   # List pages in space
atl confluence page list --space DOCS --status draft     # List draft pages
atl confluence page list --space DOCS --status archived  # List archived pages
atl confluence page search "query"      # Search pages
atl confluence page children <id>       # List child pages
atl confluence page create --space DOCS --title "New Page" --body "<p>Content</p>"
atl confluence page create --space DOCS --title "Draft" --draft   # Create as draft
atl confluence page edit <id> --body "<p>New content</p>"
atl confluence page delete <id>         # Delete page (prompts for confirmation)
atl confluence page delete <id> --force # Delete without confirmation
atl confluence page publish <id>        # Publish a draft page
atl confluence page move <id> --target <parent-id>
atl confluence page archive <id>        # Archive page (unarchive not supported via API)

Templates

atl confluence template view <id>       # View template
atl confluence template create --space DOCS --name "Name" --body "<html>"
atl confluence template update <id> --body "<html>"

Attachments

atl confluence page attachment <id> --list               # List attachments
atl confluence page attachment <id> --list --json        # List as JSON
atl confluence page attachment <id> --download --id <attID>  # Download specific
atl confluence page attachment <id> --download-all       # Download all
atl confluence page attachment <id> --download-all -o ./dir  # Download to directory
atl confluence page attachment <id> --upload ./file.pdf  # Upload file
atl confluence page attachment <id> --upload a.pdf --upload b.png  # Upload multiple

Formatting Guidelines

Jira Formatting (Markdown to ADF)

The atl CLI accepts Markdown for descriptions AND comments, converting to Atlassian Document Format (ADF):

Standard Markdown: headings, bold, italic, strikethrough, code, lists, links
Blockquotes: > text
Horizontal rules: --- or *** or ___
GFM tables: | Header | Header | with |---|---| separator
Panels: :::info, :::warning, :::error, :::note, :::success
Expandable sections: +++Title\ncontent\n+++
Media references: !media[attachment-id]
Mentions: @[Display Name] or @[id:accountId]

Tip: Use --body-file for multi-line content to avoid shell escaping issues with backticks and special characters.

Confluence HTML

Confluence page bodies must be HTML with Confluence macros for code blocks:

<h1>Heading</h1>
<p>Paragraph with <strong>bold</strong> and <code>inline code</code>.</p>
<ul>
  <li>Bullet item</li>
</ul>
<table>
  <tr><th>Header</th></tr>
  <tr><td>Cell</td></tr>
</table>

For code blocks, use Confluence macro format:

<ac:structured-macro ac:name="code">
  <ac:plain-text-body><![CDATA[your code here
multi-line code is preserved]]></ac:plain-text-body>
</ac:structured-macro>

Important: The --body flag replaces the ENTIRE page content. View the page first with atl confluence page view <id> to understand its structure.

JSON Output

Use --json flag for structured output suitable for parsing:

# Get issue data as JSON
atl issue view PROJ-1234 --json | jq '.status'

# List issues and extract keys
atl issue list --assignee @me --json | jq '.[].key'

# Get page content
atl confluence page view 12345 --json | jq '.body'

Common Workflows

Find and Update an Issue

# Find the issue
atl issue list --jql "summary ~ 'login bug'" --json

# View details
atl issue view PROJ-1234

# Update it
atl issue edit PROJ-1234 --assignee @me
atl issue transition PROJ-1234 "In Progress"
atl issue comment PROJ-1234 --body "Starting work on this"

Create a Linked Issue

# Create the issue
atl issue create --project PROJ --type Task --summary "Implement feature X"

# Link it to a parent story
atl issue link PROJ-1235 PROJ-1000 --type "is part of"

Update Confluence Documentation

# Find the page
atl confluence page search "API documentation" --json

# View current content
atl confluence page view 12345

# Update it
atl confluence page edit 12345 --body "<h1>Updated API Docs</h1><p>New content...</p>"

Error Handling

The CLI returns non-zero exit codes on failure. Common errors:

401 Unauthorized: Run atl auth login to re-authenticate
403 Forbidden: Check permissions for the resource
404 Not Found: Verify the issue key, page ID, or space key exists

Limitations

No automatic pagination for large result sets
Rate limiting may apply for bulk operations

Development Guide

This section is for agents working on the atl codebase itself.

Build Commands

make build      # Build to ./bin/atl
make install    # Install to $GOPATH/bin
make test       # Run tests
make lint       # Run golangci-lint
make check      # Run all checks (test + lint)
make clean      # Remove build artifacts

Quick build and run:

go build -o bin/atl ./cmd/atl
./bin/atl <command>

Architecture

cmd/atl/main.go          # Entry point
internal/
  api/                   # Atlassian API clients
    client.go            # Base HTTP client with OAuth
    jira.go              # Jira API (issues, search, transitions, comments)
    confluence.go        # Confluence API (spaces, pages)
    resources.go         # Accessible resources discovery
  auth/                  # OAuth 2.0 flow and token management
    oauth.go             # OAuth flow with browser callback
    token.go             # Keyring-based token storage
    browser.go           # Browser launcher
  cmd/                   # Cobra command definitions
    root.go              # Root command, subcommand registration
    auth/                # auth login|logout|status
    issue/               # issue view|list|create|edit|transition|comment|assign
    confluence/          # confluence space|page subcommands
    board/               # board list|rank
    config/              # config get|set|list|use-context|current-context|set-alias|delete-alias
  config/                # Configuration management (~/.config/atlassian/)
  iostreams/             # I/O abstraction for testability
  output/                # Output formatting (JSON, tables, colors)

Adding a New Command

Create file in appropriate internal/cmd/<group>/ directory
Define *Options struct with IO *iostreams.IOStreams and flags
Create NewCmd* function returning *cobra.Command
Define *Output struct for JSON output with proper json tags
Implement run* function that:
- Creates API client via api.NewClientFromConfig()
- Calls API methods
- Outputs via output.JSON() or fmt.Fprintf(opts.IO.Out, ...)
Register in parent command's NewCmd* function

Error Messages for Required Flags

Don't use cmd.MarkFlagRequired() - it produces unhelpful errors. Instead, validate in RunE with helpful messages:

RunE: func(cmd *cobra.Command, args []string) error {
    if opts.Space == "" {
        return fmt.Errorf("--space flag is required\n\nUse 'atl confluence space list' to see available spaces")
    }
    return runList(opts)
},

API Client Usage

client, err := api.NewClientFromConfig()
if err != nil {
    return err
}
ctx := context.Background()
jira := api.NewJiraService(client)
// or
confluence := api.NewConfluenceService(client)

Output Format

All commands must support --json flag:

if opts.JSON {
    return output.JSON(opts.IO.Out, outputStruct)
}
// Plain text output
fmt.Fprintf(opts.IO.Out, "Result: %s\n", value)

OAuth Configuration

OAuth 2.0 credentials can be configured two ways:

Interactive setup: atl auth setup - walks through creating OAuth app
Environment variables: ATLASSIAN_CLIENT_ID and ATLASSIAN_CLIENT_SECRET

Credentials stored in ~/.config/atlassian/config.yaml. Tokens stored in system keyring.

FilesExpand file tree

AGENTS.md

Latest commit

History

AGENTS.md

File metadata and controls

Atlassian CLI (atl) - Agent Reference

Overview

Authentication

Context Switching (Multi-Environment)

Jira Issues

View Issues

List Issues

Create Issues

Edit Issues

Transitions and Workflow

Comments

Issue Links

Web Links

Sprint Management

Attachments

Metadata Discovery

Jira Boards

Confluence

Spaces

Pages

Templates

Attachments

Formatting Guidelines

Jira Formatting (Markdown to ADF)

Confluence HTML

JSON Output

Common Workflows

Find and Update an Issue

Create a Linked Issue

Update Confluence Documentation

Error Handling

Limitations

Development Guide

Build Commands

Architecture

Adding a New Command

Error Messages for Required Flags

API Client Usage

Output Format

OAuth Configuration