atli

atli is a command-line interface for Jira, Confluence, and Bitbucket. It exposes every operation of mcp-atlassian as an ordinary shell command — no MCP client, server process, or daemon. Tools are discovered at startup from the mcp-atlassian server itself, so new tools appear automatically with pinned versions. The server comes from an install extra: [atlassian] (Jira + Confluence) or [bitbucket] (mcp-atlassian-with-bitbucket — Jira, Confluence, and Bitbucket).

atli tools                              # list what your credentials unlock
atli jira get-issue --issue-key PROJ-1  # markdown, verbatim from the tool
atli confluence search --query "deploy"
atli bitbucket list-repositories        # with the [bitbucket] extra
atli --profile work jira search --jql "assignee = currentUser()"

Install

Jira + Confluence (upstream mcp-atlassian):

$ pipx install "mcp-atlassian-cli[atlassian]"

Bitbucket support (via the fork — Jira, Confluence, and Bitbucket):

$ pipx install "mcp-atlassian-cli[bitbucket]"

A bare pipx install mcp-atlassian-cli (no extra) installs the CLI without a server: the first tool command fails with a message naming both extras. The two providers are mutually exclusive — both ship the same mcp_atlassian package with conflicting fastmcp pins, so they cannot coexist in one environment and pip will refuse the combination. To switch providers, start fresh: pipx uninstall mcp-atlassian-cli && pipx install "mcp-atlassian-cli[bitbucket]".

Or from a checkout:

$ git clone <this-repo> && cd mcp-atlassian-cli
$ python -m venv .venv
$ .venv/bin/pip install -e ".[atlassian]"
$ .venv/bin/atli tools

Requires Python 3.11+. The package pins cyclopts>=4.22,<5; the mcp-atlassian provider ships only via an extra — mcp-atlassian>=0.23,<0.24 with [atlassian] (fastmcp 3.4.x), or mcp-atlassian-with-bitbucket>=1.0.5,<1.1 with [bitbucket] (fastmcp 2.13–2.14). A base dependency cannot be suppressed by an extra marker, so the provider cannot also be a default.

Authentication

atli authenticates with the same environment variables as mcp-atlassian. Tools appear only for services you have configured — with the [atlassian] provider, 63 Jira commands with JIRA_* set, 35 Confluence commands with CONFLUENCE_* set, 98 with both, none with neither. With the [bitbucket] extra, configuring BITBUCKET_* adds the bitbucket service group (and the fork's jira/confluence surface matches upstream's).

Notes:

• On Cloud, username is the Atlassian account email; the API token comes from https://id.atlassian.com/manage-profile/security/api-tokens.
• On Bitbucket Cloud, the app password is created under Personal settings → App passwords; BITBUCKET_API_TOKEN is an accepted alias. The URL decides Cloud vs Server: bitbucket.org (or any host serving api.bitbucket.org) means Cloud, everything else means Server/Data Center.
• On Data Center/Server, the personal token is created under Profile → Personal Access Tokens.
• mTLS with an encrypted private key is not supported (the underlying library rejects it). Decrypt the key first: openssl rsa -in key.enc -out key.
• Data Center/Server also accepts username + API token via the same *_USERNAME/*_API_TOKEN variables if basic auth is enabled.
• *URL may include /wiki for Confluence. The URL decides Cloud vs Data Center: hosts ending in .atlassian.net (also .jira.com, .jira-dev.com, .atlassian.com, and exact-match api.atlassian.com, plus the US-Gov domains) mean Cloud; everything else, including localhost and private IPs, means Data Center/Server.

$ export JIRA_URL="https://your-company.atlassian.net"
$ export JIRA_USERNAME="you@your-company.com"
$ export JIRA_API_TOKEN="..."
$ atli tools | head -3

Profiles (multiple instances)

Storing credentials in a TOML file lets you switch instances with --profile NAME and keep several side by side. Config lookup order:

1. $ATLI_CONFIG — if set, must point at an existing file (an error otherwise)
2. ./.atli.toml in the current directory
3. ~/.config/atli/config.toml

The first existing file wins. Any key you set in a profile (including options such as TOOLSETS = "all", which is unprefixed) replaces the ambient environment for that service prefix; prefixes the profile doesn't mention are left untouched. TOOLSETS only takes effect in a profile that also sets at least one service-prefixed key (JIRA_*/CONFLUENCE_*/MCP_ATLASSIAN_*/ BITBUCKET_*) — a TOOLSETS-only profile changes nothing.

# ~/.config/atli/config.toml
default_profile = "work"

[profiles.work]
JIRA_URL = "https://your-company.atlassian.net"
JIRA_USERNAME = "you@your-company.com"
JIRA_API_TOKEN = "..."
CONFLUENCE_URL = "https://your-company.atlassian.net/wiki"
CONFLUENCE_USERNAME = "you@your-company.com"
CONFLUENCE_API_TOKEN = "..."

[profiles.dc]
JIRA_URL = "https://jira.internal.example.com"
JIRA_PERSONAL_TOKEN = "..."

Warning: profiles are plaintext credentials. After creating the file, run:

$ chmod 600 ~/.config/atli/config.toml

Profile selection order: --profile NAME flag > $ATLI_PROFILE > the default_profile key. The flag must appear before the subcommand; atli --profile=work tools and atli --profile work tools both work.

$ atli profiles            # lists profiles and URLs — never tokens
* work (default)
    jira: https://your-company.atlassian.net
    confluence: https://your-company.atlassian.net/wiki
  dc
    jira: https://jira.internal.example.com
$ atli --profile dc jira get-issue --issue-key OPS-42

Priming AI agents (atli prime)

atli prime prints a compact primer of the local setup — configured services, active profile, usage patterns, quirks — as AI-optimized markdown. It is designed for SessionStart hooks, so agents re-learn atli after context compaction. It never imports mcp-atlassian and costs milliseconds.

The one-command onboarding installs the hook for you — idempotent, never clobbering existing settings:

$ atli prime --install               # detect harnesses, user scope
$ atli prime --install --scope project  # .claude/settings.json in the repo

• Claude Code is supported (user or project scope).
• Gemini CLI and Codex are detected but not auto-installed: Gemini runs SessionStart hooks without injecting their context (gemini-cli issue #15413); Codex hooks are experimental. atli prime --hook-json output remains compatible with both if you wire them manually.

Manual Claude Code hook, if you prefer (same envelope as the installer writes; the --hook-json envelope is what Gemini CLI and Codex would need too, wired by hand until their hook support lands):

{
  "hooks": {
    "SessionStart": [
      { "hooks": [{ "type": "command", "command": "atli prime --hook-json" }] }
    ]
  }
}

$ atli prime [--hook-json] [--export]

Claude Code hook (same envelope serves Gemini CLI and Codex):

{
  "hooks": {
    "SessionStart": [
      { "hooks": [{ "type": "command", "command": "atli prime --hook-json" }] }
    ]
  }
}

• --hook-json wraps the output in the SessionStart hook envelope.
• --export prints the default content (ignores overrides, works even when nothing is configured) — the starting point for customization.
• With nothing configured and no override file, prime prints nothing and exits 0 — zero token cost on machines where atli cannot act anyway.
• The Configured line reads exported variables and profiles only; .env files (consumed inside mcp-atlassian) are invisible to prime.

Override — a PRIME.md file replaces the default content entirely (no dynamic header, prints even when unconfigured). Lookup order, first existing file wins:

1. $ATLI_PRIME — must point at an existing file (an error otherwise)
2. ./.atli/PRIME.md — current directory; check it into the repo for project-specific conventions
3. ~/.config/atli/PRIME.md — personal default

Exit codes

Notes for agents and scripts

• atli tools --search TEXT shortlists tools by keyword across names and full descriptions.
• atli <service> <tool> --help shows every parameter with its type and default, straight from the tool's schema.
• Parameter descriptions in a tool's --help come verbatim from the tool's schema — accepted formats and semantics, straight from the source.
• Popular tools show real invocations under Example invocations: in --help — identifiers like --page-id, JQL and relative-date formats, @file for long content.
• Repeatable list flags repeat: --read-users alice --read-users bob (on confluence set-page-restrictions) gives ["alice", "bob"]; --read-users alice,bob gives one element "alice,bob".
• String values expand: --body @comment.md reads the file, - reads stdin (when piped), @@text passes a literal @text. A missing file is a usage error (exit 2) whose message shows the escape.
• Startup takes ~1 s warm, a few seconds cold (the mcp-atlassian import dominates). For bulk work, prefer one search over many single-item calls.