Authentication & Profiles

Overview

atlassian-cli supports three authentication paths, all managed by a single auth command group:

• Atlassian Cloud API tokens — for Jira, Confluence, and Jira Service Management. Tokens are scoped per user and created at id.atlassian.com/manage-profile/security/api-tokens.
• Bitbucket bearer tokens (OAuth app passwords, access tokens, or workspace access tokens). Basic-auth is also supported for legacy accounts.
• Environment variables — when a profile isn't configured or you're running in CI.

Each configured account lives in a named profile. You can have any number of profiles (e.g. personal, work, bb-ci) and switch between them with a single flag.

Atlassian Cloud API token

This is the most common setup for Jira, Confluence, and JSM.

1. Create an API token

Go to id.atlassian.com/manage-profile/security/api-tokens, click Create API token, give it a label, and copy the value (you can only view it once).

2. Log in

atlassian-cli auth login \
  --profile work \
  --base-url https://your-domain.atlassian.net \
  --email you@company.com \
  --token $ATLASSIAN_API_TOKEN \
  --default

Flags:

• --profile — a local name. Use anything you like.
• --base-url — your Atlassian Cloud URL, including https://.
• --email — the email of the account that owns the token.
• --token — the API token. Use a shell variable so it doesn't land in your history.
• --default — make this the profile used when --profile is omitted.

3. Verify

atlassian-cli auth test --profile work
atlassian-cli jira search --jql "project = DEV" --limit 1

Bitbucket authentication

Bitbucket Cloud supports two token flows. Both are current — pick the one that matches your account model.

API token (Basic auth) — for your personal account

Create an Atlassian API token scoped to Bitbucket at id.atlassian.com/manage-profile/security/api-tokens (select Bitbucket). Use it with your account email:

atlassian-cli auth login \
  --profile work \
  --bitbucket \
  --email you@company.com \
  --token $BITBUCKET_TOKEN

Access token (Bearer auth) — for CI or tight scoping

Access tokens are scoped to a repository, project, or workspace — great for CI pipelines where you want the minimum permissions:

1. Bitbucket → your workspace / repository / project → Settings → Access tokens
2. Click Create and grant only the scopes you need (e.g. repository:read, pullrequest:write)

atlassian-cli auth login \
  --profile bb-ci \
  --bitbucket --bearer \
  --token $BITBUCKET_TOKEN

Bearer auth does not require --email. The workspace is optional at login — supply --workspace when you want it saved in the profile, or pass --workspace <slug> per-command.

Verify

atlassian-cli auth test --bitbucket --profile bb-ci
atlassian-cli bitbucket whoami --profile bb-ci

Profiles

Profiles isolate credentials per account or environment. Common patterns:

• personal — your own sandbox instance
• work — your company's production instance
• bb-ci — a scoped Bitbucket token for CI pipelines
• staging / prod — separate profiles per environment

List profiles

atlassian-cli auth list

Switch profile per command

atlassian-cli jira search --profile personal --jql "project = PERS"
atlassian-cli jira search --profile work --jql "project = DEV"

Change the default

Re-run auth login with --default for the profile you want to promote:

atlassian-cli auth login --profile work --base-url https://x.atlassian.net --email you@x.com --default

Or edit default_profile: directly in ~/.atlassian-cli/config.yaml.

Remove a profile

atlassian-cli auth logout --profile bb-legacy                    # remove credentials, keep profile entry
atlassian-cli auth logout --profile bb-legacy --remove-profile   # remove profile entirely
atlassian-cli auth logout --profile work --bitbucket             # only remove the Bitbucket token

Environment variables & CI/CD

In CI you usually don't want persisted secrets. atlassian-cli overrides the stored token with these environment variables, checked in this order:

Jira / Confluence / JSM

• ATLASSIAN_CLI_TOKEN_<PROFILE> — per-profile override (profile name uppercased). Example: ATLASSIAN_CLI_TOKEN_WORK.
• ATLASSIAN_API_TOKEN — fallback token used by whichever profile is active.

Bitbucket

• ATLASSIAN_CLI_BITBUCKET_TOKEN_<PROFILE> — per-profile Bitbucket token.
• ATLASSIAN_BITBUCKET_TOKEN — generic Bitbucket fallback.
• BITBUCKET_TOKEN — also recognised (shorter, common in GitHub Actions / Jenkins).

# GitHub Actions example — token via env, profile metadata from config.yaml
- name: Sync Jira
  env:
    ATLASSIAN_API_TOKEN: ${{ secrets.ATLASSIAN_API_TOKEN }}
  run: |
    atlassian-cli auth login \
      --profile ci --base-url https://mycompany.atlassian.net \
      --email bot@mycompany.com --default
    atlassian-cli jira search --jql "project = REL" --format json

See the Jira bulk transition runbook for a full CI example.

Where credentials are stored

On login, atlassian-cli writes credentials to ~/.config/atlassian-cli/credentials (Linux/macOS) or %APPDATA%\atlassian-cli\credentials (Windows). Values are encrypted with AES-256-GCM; the per-machine key lives in ~/.config/atlassian-cli/key.

Profile metadata (names, base URLs, default profile) lives in ~/.atlassian-cli/config.yaml. You can edit it by hand if you prefer — see configs/config.example.yaml in the repo.

Troubleshooting

401 Unauthorized

Most likely the token is wrong, expired, or the email doesn't match the token owner. Regenerate at id.atlassian.com/manage-profile/security/api-tokens.

403 Forbidden

The account is authenticated but lacks permission. For Jira/Confluence, check project/space role. For Bitbucket bearer tokens, verify the scopes on the access token.

"No default profile configured"

Run atlassian-cli auth list. If empty, run auth login. If you have profiles but none is default, re-run auth login --default for the profile you want, or edit default_profile: in ~/.atlassian-cli/config.yaml.

CI can't find the credentials file

In CI you usually want environment variables, not a credentials file. See Environment variables & CI/CD above.

Token works in curl but not atlassian-cli

Check that --base-url includes the scheme (https://) and has no trailing slash. Run with --debug to see the full request.

Next: Command reference →