| name | setup |
| description | Install and configure atl authentication, backends, and mirror defaults. USE WHEN the user explicitly requests install, authentication, setup repair, or {{atl.setup_cmd}}. DO NOT USE WHEN handling normal Jira, Confluence, search, reporting, or mirror work; explicit-only. |
| disable-model-invocation | true |
| allowed-tools | Bash(command -v atl) Bash(atl version) Bash(brew install *) Bash(brew upgrade *) Bash(curl -fsSL https://github.com/isukharev/atl/releases/latest/download/install.sh | sh) Bash(go install *) Bash(go env *) Bash(echo *) Bash(atl config show) Bash(atl config set *) Bash(atl auth status) Bash(atl auth login *) Bash(atl conf search *) Bash(atl jira fields) |
Set up the atl CLI
Get the user from zero to ready: install the atl binary, point it at their Confluence/Jira,
authenticate, and agree on where the local mirror lives. Work through the steps in order; skip a
step only if its check shows it is already done.
If the user wants an investigation-only agent/CI profile, finish all required
URL/auth setup first, then offer atl config set safety.read_only true as the
last step. Explain that persistent mode intentionally blocks later config set
until a human edits/removes read_only in the owner-only global config file.
When setup commands fail, use JSON kind and remediation rather than parsing
the backend message. configuration_error means complete local setup;
authentication_failed means replace/re-enter the rejected credential.
If config.json itself is malformed, atl version, help/completion, and
offline profile/auth diagnostics still work; use their evidence, then have the
human repair the owner-only file. Do not attempt online reads or mutations.
{{atl.setup_invocation_note}}
1. Detect an existing install
command -v atl && atl version
If atl is found, report version, the full commit, and build_state, then
skip to step 3. clean identifies a supported build from an unchanged source
checkout; dirty means local source changes were present; unknown is valid
for an unstamped build whose Go VCS metadata is unavailable. These are
diagnostics, not signature or update-trust evidence. Otherwise continue.
2. Install the binary
Pick the method that fits the platform:
macOS (or Linuxbrew) with Homebrew — preferred there (handles PATH for you):
brew install isukharev/tap/atl
The Homebrew launcher sets ATL_NO_UPDATE=1: Homebrew is the only owner of
that installation, so later upgrades use brew upgrade atl. Direct
installer/release binaries retain signed self-update unless their environment
sets ATL_NO_UPDATE.
Linux, or macOS without Homebrew — prebuilt, SHA-256 verified, installs to ~/.local/bin/atl:
curl -fsSL https://github.com/isukharev/atl/releases/latest/download/install.sh | sh
Both the brew and curl | sh paths are network installs that {{atl.agent_name}} will ask the user to
approve. That prompt is expected; do not try to bypass it.
Fallback, if the above fail and Go is installed (the main package lives in cmd/atl, so the
module path must end in /cmd/atl):
go install github.com/isukharev/atl/cmd/atl@latest
After installing, confirm atl resolves in this shell (the curl/go install paths do not add
it to PATH automatically — brew does):
command -v atl && atl version || echo 'atl is not on PATH — add ~/.local/bin (or $(go env GOBIN)) to PATH'
If it is not on PATH, give the user the exact line to add to their shell profile (e.g.
export PATH="$HOME/.local/bin:$PATH"); do not edit their profile silently. Do not continue to
step 3 until atl version prints a version in the current session — otherwise every later step
fails with "command not found".
3. Configure backend URLs
Ask the user for their Confluence and Jira base URLs (they must be https://). Set whichever they
use — both is typical:
atl config set --confluence-url https://confluence.example.com --jira-url https://jira.example.com
atl config show
config show prints confluence_url, jira_url, update_base_url, a mirror hint block
with the recommended ~/.atl/<workspace>/ root plus active ATL_MIRROR_ROOT when set, and the
effective render block with render_provenance (see below). Its shared
render.display_time_zone is an IANA presentation zone (deterministic UTC by default); it
changes human Markdown dates only, never JQL/CQL or exact JSON/native timestamps. A non-https URL for a non-loopback
host is rejected at set time.
Render config layer (presentation-only). config set also takes a positional dotted render key
that tunes the derived .md view — render.{jira,confluence}.{profile,include,exclude} (profile is
minimal|default|full) plus Jira-only custom_fields (comma-separated), typed
field_views (JSON descriptor array), and epic_field; Confluence has a
closed read-only page_fields JSON descriptor array:
atl config set render.display_time_zone Europe/Berlin
atl config set render.jira.profile full
atl config set --local render.confluence.profile minimal
atl config set --local render.confluence.page_fields '[{"id":"title"},{"id":"updated","format":"date"}]'
atl config set render.confluence.jira_macros off
atl config set --local render.jira.field_views '[{"id":"customfield_10003","label":"Risk Notes","placement":"section","format":"jira_wiki","editable":true}]'
--local writes a per-mirror .atl/config.json (nearest .atl walking up from cwd, or --into ROOT).
It is a security boundary: a local file may carry render keys only — backend/update URLs are
global/env-only so a shared or checked-out mirror can never redirect where the PAT is sent. config set --local refuses a URL flag (exit 2); at read time any forbidden/unknown key in a local file is
warned about on stderr and ignored. Precedence is local > global > default. Pull/render consume the
effective settings and record the resolved view in .atl/state.json for apply affinity.
4. Authenticate
atl uses a per-service Personal Access Token (PAT). Never put a PAT on the command line —
auth login reads it from a no-echo prompt, piped stdin, or a file. Recommend a least-privilege,
task-scoped token.
Interactive (the agent runs this; the user types the token at the hidden prompt):
atl auth login --service confluence
atl auth login --service jira
Or from a file: atl auth login --service jira --from-file ./token.txt (then delete the file).
Or via environment for CI/agent sessions: ATL_CONFLUENCE_PAT / ATL_JIRA_PAT.
For rare direct REST fallback calls that atl does not cover yet, keep the PAT out of argv/logs:
use env vars, turn off shell tracing, and feed curl config/headers through stdin instead of
curl -H "Authorization: Bearer $TOKEN".
Verify (this never prints the token, only where it resolves from):
atl auth status
5. Agree on the mirror directory
atl mirrors pages/issues to disk. Keep the mirror out of the user's code repository so it is
fully greppable by the agent and never committed into their project's git history.
- Recommended convention:
~/.atl/<workspace>/, where <workspace> is a
meaningful name (the code repo's basename or the Confluence space key).
Example: ~/.atl/payments-service/. This is not the CLI's implicit default:
without ATL_MIRROR_ROOT or --into, Confluence uses mirror and Jira uses
mirror-jira.
- Fix it once with
ATL_MIRROR_ROOT so conf pull / conf status / jira pull default to the
same place without re-passing --into every time. Record it where later sessions will pick it up —
either export it in the shell profile, or add a line to the project's {{atl.guidance_file}}:
atl mirror lives at ~/.atl/<workspace>/ (export ATL_MIRROR_ROOT=~/.atl/<workspace>/).
- An explicit
--into <dir> still overrides ATL_MIRROR_ROOT. conf push does not read the env
var — it finds the mirror root by walking up from the target file to the nearest .atl, so as long
as you push files from inside that same root it lines up automatically.
(See the atl orientation skill's workflow reference for the full rationale and the in-repo /
scratch alternatives.)
6. Smoke test
Confirm auth + connectivity with a cheap read:
atl conf search --cql 'type = page' --limit 1
atl jira fields
atl prints JSON by default. A clean result means setup is complete — tell the user they can now
ask {{atl.agent_short}} to work with Confluence pages or Jira issues (the confluence and jira skills engage
automatically). Offer the separate explicit onboarding skill if they want atl to learn their
recurring workflow, approved field/schema facts, render defaults, and common selectors. Do not run
that interview or inspect sample content unless they opt in; technical setup remains complete
without it.
The installed Claude Code/Codex plugin also bundles atl mcp serve, a typed
read-only evidence surface. Remote tools use the same configured host-scoped
credentials, while the two offline mirror snapshot tools use only an explicit
ATL_MIRROR_ROOT; neither configuration is copied into plugin files. The
surface becomes available after starting a new agent session with atl on
PATH. Its absence does not make CLI setup incomplete; use the CLI fallback and
report a plugin/binary version skew instead of inventing raw REST calls.
Version skew
Plugin and binary release under one version number. If a command documented by the skills is
rejected as unknown (exit 2), compare atl version with the plugin version and update the lagging
side: a direct-install binary self-updates on its next run, a Homebrew binary
uses brew upgrade atl, and the plugin uses {{atl.plugin_update_cmd}}.
Exit codes (so you can react)
2 usage · 3 auth (the server rejected the token → re-run step 4 with a valid PAT) ·
4 not-found · 5 version-conflict · 6 forbidden (token lacks permission) ·
7 not configured (backend URL or PAT not set yet → finish step 3/4). Anything else is 1.
