Authenticate¶

jira-cli signs in to Jira Cloud with your Atlassian account email and an API token. It verifies the token once, stores it in a credential backend (your OS keyring by default, or 1Password), and records only a reference in the config file. The token itself never lands on disk in plain text. See Where the token is stored for the backends and how jira picks one.

Before you start¶

Have these ready:

• An Atlassian Cloud site, such as https://example.atlassian.net.
• The account email for that site.
• An API token for that account. Both scoped and classic tokens work.

A profile name is optional. jira uses default unless you set one, and you can add more profiles later to point at different sites.

Log in¶

auth login creates or updates a profile, checks the token against Jira, and stores it in your chosen backend. It writes only a reference to the credential into the config file, never the token itself. You can run it two ways: an interactive form when you're sat at a terminal, or a fully flag-driven call for headless machines and scripts. Both end with the same stored profile.

jira config init --base-url https://example.atlassian.net --email you@example.com
jira auth login

JIRA_TOKEN="$(your-secret-source)" jira auth login --no-input \
  --profile-name default \
  --base-url https://example.atlassian.net \
  --email you@example.com \
  --backend keyring \
  --credential-env JIRA_TOKEN

your-secret-source | jira auth login --no-input \
  --profile-name default \
  --base-url https://example.atlassian.net \
  --email you@example.com \
  --backend keyring \
  --secret-stdin

export JIRA_TOKEN_DEFAULT="$(your-secret-source)"
jira auth login --no-input \
  --profile-name default \
  --base-url https://example.atlassian.net \
  --email you@example.com \
  --backend env

Verify¶

Confirm the credential works:

jira auth status

auth status probes Jira and reports the resolved identity and the permissions granted for each profile, so you can see at a glance whether a profile is signed in and what it can do.

Where the token is stored¶

Tokens live outside the config file. The TOML records only a backend reference; the secret sits in the backend you chose.

When jira resolves a token it checks JIRA_TOKEN_<PROFILE> first (profile work becomes JIRA_TOKEN_WORK), then the backend recorded on the profile.

WSL and headless Linux¶

Linux keyring support needs a Secret Service on the session D-Bus. Desktop Linux ships one (gnome-keyring, KWallet); WSL and most headless hosts don't by default, so keyring operations fail with keyring_unavailable until you add one. You have two options.

Recommended — add a Secret Service, then use keyring as normal. On a systemd-enabled WSL distro (Ubuntu, Debian) it takes about a minute, and the keyring then behaves exactly as it does on macOS or Windows.

[boot]
systemd=true

echo "$DBUS_SESSION_BUS_ADDRESS"

sudo apt install gnome-keyring libsecret-tools # (1)!

printf '' | gnome-keyring-daemon --unlock --components=secrets --daemonize # (2)!

jira auth login --backend keyring \
  --base-url https://<site>.atlassian.net --email you@example.com # (3)!

1. Install a Secret Service provider — the keyring daemon plus secret-tool, handy for verifying.
2. Create the keyring once. WSL has no graphical login to unlock it, so it is created without a password, which lets it unlock automatically from then on. This only writes the keyring file; the running daemon is started later, on demand.
3. Store the token in the keyring. Omit --base-url / --email to reuse the profile's existing values.

From then on D-Bus starts and unlocks the keyring on demand — including after every WSL restart — so there is no daemon to keep running and nothing to add to your shell profile. Confirm it resolves with nothing in the environment:

jira auth status

The Credential line should read keyring.

# ~/.bashrc or ~/.zshrc
export DBUS_SESSION_BUS_ADDRESS="unix:path=/run/user/$(id -u)/bus"

# ~/.config/fish/config.fish
set -gx DBUS_SESSION_BUS_ADDRESS "unix:path=/run/user/"(id -u)"/bus"

Simpler — skip the keyring, use the env backend. The profile reads JIRA_TOKEN_<PROFILE> on every command and stores nothing:

export JIRA_TOKEN_DEFAULT="$(op read "op://<vault>/<item>/<field>")"
jira auth login --backend env

1Password¶

The 1password backend keeps the token in a 1Password item and reads it through the desktop app on demand. Two things to know before you choose it:

When access fails¶

auth status tells a bad token apart from a missing permission:

• 401 (jira_unauthorized): the token is missing, revoked, mistyped, or for a different site than the profile's base URL. Run jira auth login to store a fresh one.
• 403 (jira_forbidden): the token authenticates fine but lacks permission for that project or field. That one is resolved on the Jira side.

jira auth status --output json     # machine-readable health check
jira auth logout <profile>         # remove a stored credential

Removing a credential is destructive — getting it back means re-entering the token — so a script, agent, or --no-input invocation must pass --force. An interactive terminal proceeds without a prompt: naming the profile is the intent. --dry-run reports which credential a live logout would remove without touching the secret backend:

jira auth logout work --dry-run --output json
jira auth logout work --force --output json

A stored credential outlives its profile: deleting the profile from config does not remove the secret from the keychain, and a plain jira auth logout <profile> refuses a name that is no longer in config. Pass the profile's old site as --base-url — the keychain entry is keyed by site host and profile name, and the pair identifies the orphaned credential without the config entry:

jira auth logout old-work --base-url acme.atlassian.net

See also¶

• Configure for profiles, defaults, and the full config reference.
• Output and scripting for the JSON envelope and exit codes.