youtrack-axi

A YouTrack CLI built for agents rather than people. It follows the AXI standards - the copy of the spec this was built against is committed at .pi/skills/axi/SKILL.md.

• TOON on stdout, roughly 40% cheaper than the equivalent JSON. The REST layer stays on JSON; conversion happens only at the output boundary.
• Content first. No arguments prints your open issues, not a manual.
• Errors are data. They go to stdout, in TOON, with the command that fixes them.
• No prompts, ever. Every operation is completable with flags alone.
• Time tracking, which is the reason this exists: work <ID> --log 1h30m.

Install

npm install -g @tmcayden/youtrack-axi
youtrack-axi --version

Or run it without installing:

npx -y @tmcayden/youtrack-axi

The bare name youtrack-axi is taken on npm by an unrelated author, so this is published under the @tmcayden scope. The binary is youtrack-axi either way.

To work from a checkout instead:

npm install -g /path/to/youtrack-axi

Configuration

Credentials are two values, YOUTRACK_URL and YOUTRACK_TOKEN. A config file is simply a way to set them, so the file and the environment share one set of names. Each value is resolved independently, in this order:

1. YOUTRACK_URL / YOUTRACK_TOKEN in the environment
2. the file named by --config <path>
3. the file named by YOUTRACK_AXI_CONFIG
4. ~/.config/youtrack-axi/.env (honours XDG_CONFIG_HOME)

Environment values sit on top so YOUTRACK_TOKEN reliably overrides a stored one

• useful in CI, and when rotating a token. --config selects which file is consulted rather than supplying a value, so the two never compete.

A config file is an env file:

YOUTRACK_URL="https://example.youtrack.cloud"
YOUTRACK_TOKEN="perm:..."

export prefixes, # comments, and single or double quoting all work, so the same file can be sourced by a shell. Files are written with mode 0600, and setup --verify warns if the one it read is readable by other accounts.

A file whose first character is { is parsed as JSON instead, accepting url / token or youtrack_url / youtrack_token. That is there so a file already holding other tooling's settings can be named with --config without being reshaped; new files should use the env format.

youtrack-axi setup --url "https://example.youtrack.cloud" --token "<permanent-token>"
youtrack-axi setup --config ~/.config/work.env --url "https://..." --token "..."
youtrack-axi setup --verify

setup rewrites only its own two keys, so comments, ordering, and unrelated variables in an existing file survive. The token is never written to stdout, a log, or a commit; setup --verify confirms it works by naming the authenticated login instead.

A path passed to --config or YOUTRACK_AXI_CONFIG must exist - a missing file is an error, never a silent fallthrough to another source. There is deliberately no automatic project-local config file, since a credential file inside a repository is easy to commit by accident.

Commands

youtrack-axi                                  # your open issues
youtrack-axi issues "project: PROJ #Unresolved" --limit 20
youtrack-axi issues --assignee me --fields Priority,Type
youtrack-axi view PROJ-123 [--full]
youtrack-axi create --project PROJ --summary "..." [--description "..."]
youtrack-axi comment PROJ-123 "..."
youtrack-axi cmd PROJ-123 --command "in progress"
youtrack-axi work PROJ-123                     # read logged time
youtrack-axi work PROJ-123 --log 1h30m --date 2026-09-05 --type Development --text "..."
youtrack-axi projects
youtrack-axi fields PROJ [--full]

--help and --config are accepted on every command. Exit codes are 0 for success including no-ops, 1 for errors, 2 for usage errors.

cmd is idempotent: applying a state an issue is already in reports a no-op and exits 0, and any real change is reported as a field-level diff.

work --log needs time tracking enabled on the project and the create-work-item permission. When either is missing the CLI names which one it was, rather than passing along a bare 403.

Agent integration

Two ways to give an agent this tool. You only need one.

• Session hook - ambient, shows live state at every session start:

  youtrack-axi setup --hooks

  Installs a SessionStart hook for Claude Code, Codex, and OpenCode, pointing at the binary on PATH when it resolves to this executable. Repeat runs are silent no-ops and stale paths are repaired.
• Skill - loads on demand, no per-session token cost: skills/youtrack-axi/SKILL.md, generated from the CLI's own command specs. npm run skill:check fails if it has drifted.

  npx skills add tmcayden/youtrack-axi --skill youtrack-axi

Development

npm install
npm test          # build, unit + end-to-end tests, skill freshness

The end-to-end suite runs the real binary against a stub YouTrack over HTTP and asserts on stdout, stderr, and exit codes - the same surface an agent sees.