Skip to content

Getting Started

This guide walks you through installing atlcli, authenticating with Atlassian, and running your first commands.

Installation

Prerequisites

  • Bun v1.0 or later
  • An Atlassian Cloud account

Install from Source

git clone https://github.com/BjoernSchotte/atlcli.git
cd atlcli
bun install
bun run build

The CLI is now available at ./apps/cli/dist/atlcli.

Add to PATH

Add the dist directory to your PATH or create an alias: 

alias atlcli="$(pwd)/apps/cli/dist/atlcli"

Authentication

atlcli uses API tokens for authentication. You can manage multiple profiles for different Atlassian instances.

Create an API Token

  1. Go to Atlassian Account Settings
  2. Click Create API token
  3. Give it a descriptive name (e.g., "atlcli")
  4. Copy the token

Initialize Authentication

atlcli auth init

Follow the prompts to enter:

  • Instance URL: Your Atlassian instance (e.g., https://yourcompany.atlassian.net)
  • Email: Your Atlassian account email
  • API Token: The token you created

Your credentials are stored securely at ~/.atlcli/credentials.json.

Multiple Profiles

Create named profiles for different instances:

atlcli auth init --profile work
atlcli auth init --profile personal

Use --profile with any command:

atlcli jira search --assignee me --profile work

Confluence Quick Start

Initialize a Local Directory

atlcli wiki docs init ./team-docs --space TEAM

This creates a local directory linked to the TEAM space.

Pull Pages

atlcli wiki docs pull ./team-docs

Pages are downloaded as markdown files with YAML frontmatter:

---
id: "12345"
title: "Meeting Notes"
space: "TEAM"
---

# Meeting Notes

Content here...

Edit and Push

Edit files locally with your favorite editor, then push changes:

atlcli wiki docs push ./team-docs

atlcli detects changes and updates only modified pages.

Jira Quick Start

Search Issues

# Your assigned issues
atlcli jira search --assignee me

# Open bugs in a project
atlcli jira search --project PROJ --type Bug --status Open

# Using JQL directly
atlcli jira search --jql "project = PROJ AND sprint in openSprints()"

View an Issue

atlcli jira get PROJ-123

Create an Issue

atlcli jira create --project PROJ --type Task --summary "Fix login bug"

Track Time

# Start a timer
atlcli jira worklog timer start PROJ-123

# Stop and log time
atlcli jira worklog timer stop PROJ-123

# Or log directly
atlcli jira worklog add PROJ-123 --time 2h --comment "Code review"

JSON Output

All commands support --json for scripting:

atlcli jira search --assignee me

PROJ-123  In Progress  Fix login bug
PROJ-124  To Do        Add dark mode


atlcli jira search --assignee me --json

{
  "schemaVersion": "1",
  "issues": [
    {"key": "PROJ-123", "status": "In Progress", "summary": "Fix login bug"},
    {"key": "PROJ-124", "status": "To Do", "summary": "Add dark mode"}
  ]
}

Next Steps