Skip to content

getting-started.md

Latest commit

 

History

History
225 lines (148 loc) · 4.59 KB

getting-started.md

File metadata and controls

225 lines (148 loc) · 4.59 KB
title Getting Started
description Install atla and set up your first Atlassian CLI workflow.

Getting Started

atla is a unified command-line interface for Atlassian Jira and Confluence. It lets you search issues, manage boards, read and publish Confluence pages, and more — all from your terminal.

Key features:

  • Profile-based authentication with multiple Atlassian instances
  • Multiple output formats: table, json, csv, keys
  • Shell completions for bash, zsh, fish, and PowerShell
  • Command aliases for common workflows

Installation

Installer script (macOS / Linux)

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/NeoHsu/atla/releases/latest/download/atla-installer.sh | sh

Windows (PowerShell)

powershell -ExecutionPolicy Bypass -c "irm https://github.com/NeoHsu/atla/releases/latest/download/atla-installer.ps1 | iex"

mise

mise use -g github:NeoHsu/atla

From source (requires Rust toolchain)

cargo install --git https://github.com/NeoHsu/atla atla

Direct downloads

Pre-built binaries are available for:

Platform Architecture
macOS Apple Silicon (aarch64)
macOS Intel (x86_64)
Linux ARM64 (aarch64)
Linux x64 (x86_64)
Windows x64 (x86_64)

Download from the latest release.

First-time setup

1. Log in to your Atlassian instance

atla auth login

The interactive prompt will ask for:

  1. Your Atlassian instance URL (e.g. https://example.atlassian.net)
  2. Your email address
  3. An API token (generate one at https://id.atlassian.com/manage-profile/security/api-tokens)

You can also pass flags directly:

atla auth login \
  --instance https://example.atlassian.net \
  --email you@example.com \
  --token YOUR_API_TOKEN

2. Verify your authentication

atla auth status

This confirms your active profile, instance, and credential storage method.

3. Set a default Jira project

atla config set profiles.work.default-project PROJ

4. Set a default Confluence space

atla config set profiles.work.default-space DEV

5. Install the bundled agent skill

If you use an AI coding assistant, install the bundled atla-cli skill so the agent knows current atla commands, flags, pagination behavior, JQL/CQL patterns, and safety rules.

From GitHub:

npx skills add NeoHsu/atla --skill atla-cli

From a local checkout of this repo:

npx skills add . --skill atla-cli

For non-interactive setup across all supported agents:

npx skills add . --skill atla-cli --agent '*' -y

Use --copy if you want a standalone installed copy instead of a symlink back to the repo.

6. Create a useful alias

atla config set aliases.mine "jira search 'assignee = currentUser() order by updated desc'"

Now atla mine expands to your assigned issues.

Shell completions

Set up tab completion for your shell:

Bash

atla completion bash > ~/.local/share/bash-completion/completions/atla

Zsh

atla completion zsh > ~/.zfunc/_atla

Add fpath+=~/.zfunc to your .zshrc before compinit if not already present.

Fish

atla completion fish > ~/.config/fish/completions/atla.fish

PowerShell

atla completion powershell >> $PROFILE

Quick demo

Once authenticated, try these commands:

Search Jira issues assigned to you

atla jira search "assignee = currentUser() ORDER BY updated DESC"

View a specific issue

atla jira issue view PROJ-123

List Confluence spaces

atla confluence space list

View a Confluence page as JSON

atla confluence page view 12345 --output json

Use a different output format

atla jira search "project = PROJ" --output csv

Global flags

These flags work with any command:

Flag Short Description
--output -o Output format: table, json, csv, keys
--profile Use a specific named profile
--verbose Enable verbose/debug output
--dry-run Show what would happen without making changes
--no-input Disable interactive prompts

Next steps

  • Authentication — manage profiles, tokens, and storage strategies
  • Configuration — config keys, aliases, and multi-environment setup
  • Agent Reference — skill installation and automation-focused command reference