Authentication¶

atlcli uses Atlassian API tokens for authentication, supporting multiple profiles for different instances.

Quick Start¶

# Initialize credentials (interactive)
atlcli auth init

# Check current status
atlcli auth status

# List all profiles
atlcli auth list

API Tokens¶

Creating a Token¶

1. Visit Atlassian Account Settings
2. Click Create API token
3. Enter a label (e.g., "atlcli")
4. Copy the generated token immediately (it won't be shown again)

Token Permissions¶

API tokens inherit your account permissions. For atlcli to work fully, your account needs:

• Confluence: Space admin or contributor permissions
• Jira: Project access for issues you want to manage

Auth Commands¶

Initialize (Interactive)¶

Interactive setup that prompts for all credentials:

atlcli auth init
atlcli auth init --profile work

Login (Non-Interactive)¶

Login with credentials provided via flags or environment:

atlcli auth login --site https://company.atlassian.net --email you@company.com --token YOUR_TOKEN
atlcli auth login --profile work --site https://work.atlassian.net

Options:

Status¶

Check current authentication status:

atlcli auth status

Output:

Profile: work (active)
Site:    https://company.atlassian.net
Email:   you@company.com
Status:  Authenticated ✓

List Profiles¶

atlcli auth list

Output:

PROFILE     SITE                              EMAIL              ACTIVE
default     https://company.atlassian.net     you@company.com
work        https://work.atlassian.net        work@company.com   ✓
personal    https://personal.atlassian.net    me@gmail.com

Switch Profile¶

Change the active profile:

atlcli auth switch work
atlcli auth switch personal

Rename Profile¶

atlcli auth rename old-name new-name

Logout¶

Clear credentials but keep the profile (for easy re-login):

atlcli auth logout
atlcli auth logout work

Delete Profile¶

Remove a profile entirely:

atlcli auth delete old-profile
atlcli auth delete --profile staging --confirm

Profiles¶

Default Profile¶

Initialize the default profile:

atlcli auth init

Enter your instance URL, email, and API token when prompted.

Named Profiles¶

Create profiles for multiple instances:

atlcli auth init --profile work
atlcli auth init --profile personal
atlcli auth init --profile client-acme

Use a profile with any command:

atlcli jira search --assignee me --profile work
atlcli wiki docs pull ./docs --profile client-acme

Per-Command Override¶

# Use specific profile for one command
atlcli wiki page list --space TEAM --profile work

Credential Storage¶

Credentials are stored at ~/.atlcli/credentials.json:

{
  "currentProfile": "work",
  "profiles": {
    "default": {
      "name": "default",
      "baseUrl": "https://company.atlassian.net",
      "email": "you@company.com",
      "apiToken": "ATATT3x..."
    },
    "work": {
      "name": "work",
      "baseUrl": "https://work.atlassian.net",
      "email": "work@company.com",
      "apiToken": "ATATT3x..."
    }
  }
}

chmod 600 ~/.atlcli/credentials.json

Environment Variables¶

Override credentials with environment variables:

Environment variables take precedence over config files:

export ATLCLI_SITE="https://ci.atlassian.net"
export ATLCLI_EMAIL="ci@company.com"
export ATLCLI_API_TOKEN="$CI_ATLASSIAN_TOKEN"
atlcli jira search --jql "project = PROJ"

Precedence¶

Credentials are resolved in this order (later wins):

1. Default profile in config
2. ATLCLI_PROFILE environment variable
3. ATLCLI_SITE / ATLCLI_EMAIL / ATLCLI_API_TOKEN env vars
4. --profile command flag

CI/CD Usage¶

For CI/CD pipelines, use environment variables or secrets:

GitHub Actions¶

- name: Search Jira
  env:
    ATLCLI_SITE: ${{ secrets.ATLASSIAN_URL }}
    ATLCLI_EMAIL: ${{ secrets.ATLASSIAN_EMAIL }}
    ATLCLI_API_TOKEN: ${{ secrets.ATLASSIAN_TOKEN }}
  run: atlcli jira search --jql "fixVersion = ${{ github.ref_name }}"

GitLab CI¶

jira-update:
  script:
    - atlcli jira transition $ISSUE_KEY --status Done
  variables:
    ATLCLI_SITE: $ATLASSIAN_URL
    ATLCLI_EMAIL: $ATLASSIAN_EMAIL
    ATLCLI_API_TOKEN: $ATLASSIAN_TOKEN

Jenkins¶

environment {
    ATLCLI_SITE = credentials('atlassian-url')
    ATLCLI_EMAIL = credentials('atlassian-email')
    ATLCLI_API_TOKEN = credentials('atlassian-token')
}

Docker¶

docker run -e ATLCLI_SITE -e ATLCLI_EMAIL -e ATLCLI_API_TOKEN atlcli jira search

Troubleshooting¶

Invalid Credentials¶

Error: Authentication failed (401)

• Verify your API token hasn't expired
• Check the instance URL includes https://
• Confirm email matches your Atlassian account
• Re-initialize: atlcli auth init

Permission Denied¶

Error: You don't have permission (403)

• Check your account has access to the project/space
• For Jira, verify project permissions
• For Confluence, verify space permissions

Wrong Profile¶

# Check which profile is active
atlcli auth status

# Switch if needed
atlcli auth switch correct-profile

Token Expired¶

Atlassian API tokens can expire. Regenerate and update:

# Generate new token at https://id.atlassian.com/manage-profile/security/api-tokens
# Then update
atlcli auth init --profile work