Authentication

Authentication

atlcli supports authentication for both Atlassian Cloud and Server/Data Center installations, with 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

Cloud vs Server/Data Center

atlcli supports both Atlassian deployment types with different authentication methods:

Deployment	Auth Method	Token Type
Cloud (*.atlassian.net)	Basic Auth	API Token
Server / Data Center	Bearer Auth	Personal Access Token (PAT)

Cloud instances use your email address and an API token for authentication. This is the default mode.

Server/Data Center instances use Bearer authentication with a Personal Access Token (PAT). Use the --bearer flag when logging in.

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.

Cloud (Default)

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

Server/Data Center

Use the --bearer flag for PAT authentication:

# With token provided directly
atlcli auth login --bearer --site https://jira.company.com --token YOUR_PAT

# With keychain lookup (macOS)
atlcli auth login --bearer --site https://jira.company.com --username myuser

# With a custom CA certificate (self-signed or internal CA)
atlcli auth login --bearer --site https://jira.company.internal \
  --token YOUR_PAT --ca-file /etc/ssl/certs/company-ca.pem

Options:

Flag	Description
--site	Atlassian instance URL
--email	Account email (Cloud)
--token	API token (Cloud) or PAT (Server/DC)
--bearer	Use Bearer auth with PAT (for Server/DC)
--username	Username for keychain lookup (Server/DC)
--profile	Profile name to create/update
--ca-file	Path to a custom CA certificate (PEM) for self-signed or internal CAs
--insecure	Skip TLS certificate verification (not recommended for production)

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 old-profile --delete-keychain   # macOS only

When deleting a profile with a keychain-backed token, use --delete-keychain to remove the stored credentials. Without it, keychain credentials (if any) are left intact.

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

TLS and Self-Signed Certificates

On-premises Jira and Confluence Data Center deployments often use certificates issued by an internal Certificate Authority or self-signed certificates. atlcli supports both scenarios via per-profile TLS settings.

Custom CA certificate (recommended)

If your instance uses an internal CA, point atlcli at the CA certificate bundle with --ca-file:

atlcli auth login --bearer \
  --site https://jira.company.internal \
  --token YOUR_PAT \
  --ca-file /etc/ssl/certs/company-ca.pem

The path to the CA file is stored per-profile as tlsCaFile and applied to every subsequent Jira and Confluence request for that profile. The file is read on each request, so rotating the CA bundle is as simple as replacing the file on disk — no re-login needed.

Accepted format: PEM-encoded certificates. You can concatenate multiple CAs into a single file.

# Windows path example
atlcli auth login --bearer --site https://jira.company.internal \
  --token YOUR_PAT --ca-file C:\certs\company-ca.pem

Skip TLS verification (testing only)

As a last resort — for example, when debugging on a disposable test instance — you can skip TLS verification entirely with --insecure:

atlcli auth login --bearer --site https://jira.test.local --token YOUR_PAT --insecure

This stores tlsSkipVerify: true on the profile.

Do not use in production

--insecure disables TLS certificate validation. Any attacker with network access between you and the Atlassian instance can intercept your PAT and issue traffic. Always prefer --ca-file unless you are knowingly working against an ephemeral test system.

Inspecting TLS settings

Profile TLS settings are visible in ~/.atlcli/credentials.json under the profile entry:

{
  "name": "onprem",
  "baseUrl": "https://jira.company.internal",
  "authType": "bearer",
  "tlsCaFile": "/etc/ssl/certs/company-ca.pem"
}

To remove TLS settings from a profile, delete and re-create it without the TLS flags.

Token Storage

Config File

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..."
    },
    "onprem": {
      "name": "onprem",
      "baseUrl": "https://jira.company.internal",
      "authType": "bearer",
      "username": "myuser",
      "tlsCaFile": "/etc/ssl/certs/company-ca.pem"
    }
  }
}

For Server/Data Center profiles using Bearer auth, the profile includes authType: "bearer" and may include a username for keychain lookup and optional tlsCaFile / tlsSkipVerify fields for TLS configuration.

Security

Protect this file with appropriate permissions:

chmod 600 ~/.atlcli/credentials.json

Mac Keychain (macOS)

On macOS, you can store tokens securely in the system Keychain instead of the config file. When you provide a --username during login, atlcli stores the token in Keychain and looks it up automatically:

# Store token in Keychain during login
atlcli auth login --bearer --site https://jira.company.com --username myuser --token YOUR_PAT

# Token is now stored in Keychain - subsequent logins can use keychain lookup
atlcli auth login --bearer --site https://jira.company.com --username myuser

The token is stored with:

• Service: atlcli
• Account: Your username

Token Resolution Priority

Tokens are resolved in this order (first found wins):

1. ATLCLI_API_TOKEN environment variable
2. Mac Keychain (if username is configured in profile)
3. Config file (~/.atlcli/credentials.json)

Checking Token Source

Use --json to see where your token is coming from:

atlcli auth status --json

The output includes:

• hasEnvToken: Token is set via environment variable
• hasKeychainToken: Token is available from Keychain
• hasPatInConfig: Token is stored in config file

Environment Variables

Override credentials with environment variables:

Variable	Description
ATLCLI_SITE	Atlassian instance URL
ATLCLI_EMAIL	Account email (Cloud)
ATLCLI_API_TOKEN	API token (Cloud) or PAT (Server/DC)
ATLCLI_PROFILE	Default profile name

Tip

ATLCLI_API_TOKEN works for both Cloud API tokens and Server/Data Center Personal Access Tokens. The authentication method is determined by the profile’s authType setting.

For Cloud profiles, ATLCLI_EMAIL (or a saved profile email) is still required to build Basic auth headers, even if the token comes from ATLCLI_API_TOKEN.

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 issue transition --key $ISSUE_KEY --to 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

Server/Data Center Auth Failures

Error: Authentication failed (401)

For Server/Data Center instances:

• Verify you used --bearer flag when logging in
• Check that your PAT hasn’t expired (Server/DC PATs have expiration dates)
• Confirm the PAT has the required permissions in your Atlassian admin settings
• Ensure the instance URL is correct and accessible

To re-authenticate:

atlcli auth login --bearer --site https://jira.company.com --token YOUR_NEW_PAT

Keychain Issues (macOS)

If Keychain lookup fails:

• Verify the token was stored: security find-generic-password -s atlcli -a <username>
• Re-store the token: atlcli auth login --bearer --site <url> --username <user> --token <pat>
• Check Keychain Access app for any access issues

Related Topics

• Getting Started - Initial setup and first commands
• Configuration - Config file options
• Doctor - Diagnose authentication issues