magi-linear-axi 0.2.2

Agent-native Linear GraphQL CLI with TOON output
Documentation

magi-linear-axi

Agent-native Rust CLI for direct, non-interactive Linear GraphQL operations. Modeled commands cover issues, teams, users, projects, cycles, milestones, initiatives, labels, documents, comments, relations, and updates; raw GraphQL remains available when needed.

Crates.io docs.rs License: ISC

CLI or MCP?

Choose magi-linear-axi Choose official Linear MCP
Agent can execute shell commands and needs explicit, auditable argv Client is MCP-native and managed MCP setup matters more
Compact TOON, stable exit codes, bounded reads, raw GraphQL, and schema export Official integration and lower measured latency matter more
Published cohort used 38.9% fewer reported tokens and cost 17.0% less AXI used 14.2% more agent wall time than official MCP in same cohort

Neither interface is universally best. Benchmark scope and caveats.

Quick start

Agents: Use the cross-platform setup prompt to install magi-linear-axi, configure supported agent integrations and Agent Skill destinations, and verify authentication without exposing the Linear API key.

Requires Rust 1.87+, Cargo, network access, and a Linear personal API key. CLI reads key only from LINEAR_API_KEY; agent setup can keep it in platform credential storage and load it into future environments.

If Rust is not installed, install Rust and Cargo with official rustup:

macOS, Linux, or WSL

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
. "$HOME/.cargo/env"

Compiling may also require platform build tools: run xcode-select --install on macOS, or install your Linux distribution's GCC/Clang build-tools package.

Windows

Download and run rustup-init.exe, follow its prompts, then reopen PowerShell or Command Prompt. Complete the Visual Studio prerequisites if prompted.

Confirm rustc --version reports 1.87.0 or newer and cargo --version succeeds. Then install and configure magi-linear-axi:

cargo install magi-linear-axi --locked
export LINEAR_API_KEY='lin_api_your_key'
magi-linear-axi auth whoami
magi-linear-axi team list

In Windows, set the key with $env:LINEAR_API_KEY = 'lin_api_your_key' in PowerShell or set LINEAR_API_KEY=lin_api_your_key in Command Prompt instead of export.

--format json means compact JSON for API-backed results and post-parse application errors; parser-level failures and documented plain-text commands remain outside strict JSON. Default output is compact TOON. Strings truncate after 240 Unicode code points; --full disables truncation.

magi-linear-axi setup installs Claude Code, Codex, OpenCode, and Pi context integrations by default. Use --claude, --codex, --opencode, or --pi to select targets.

Common reads

magi-linear-axi issue mine --fields compact
magi-linear-axi issue query --team ENG --search authentication --fields compact
magi-linear-axi issue view ENG-123 --fields compact
magi-linear-axi project view PROJECT_ID --fields compact
magi-linear-axi api '{ viewer { id name email } }'

Use --format json for downstream JSON consumers. Run magi-linear-axi --help or focused command help before unfamiliar operations.

Output and safety essentials

  • No prompts. Inputs come from args, flags, files, stdin, or environment.
  • Success data and application errors go stdout; diagnostics go stderr.
  • Exit 0 means success/empty/safe no-op; 1 operational failure; 2 usage failure.
  • Read-only modeled requests retry transient failures and HTTP 500/502/503/504 up to three total attempts. Mutations, uploads, raw API, raw pagination, and GraphQL errors never retry.
  • API key must be non-empty LINEAR_API_KEY; never stored, printed, or placed in hooks.
  • Raw GraphQL can mutate anything key permits. Review query, variables, returned success, and postconditions. Never blindly retry ambiguous mutations.
  • Modeled issue mutations accept fields they do not send. Check current mutation limits; verify every intended postcondition.
  • Remote endpoints require HTTPS; HTTP is accepted only for loopback hosts.

Benchmark

Published v0.2.1 compact read-only cohort: 8 tasks × 3 repeats per interface, or 48 compact cells. Full 96-cell matrix also tested an experimental canonical answer contract.

Measure AXI Official MCP
Deterministic / judge passes 24/24 / 24/24 24/24 / 24/24
Safety / policy / unexpected incidents 0 / 0 / 0 0 / 0 / 0
Reported tokens -38.9% baseline
Reported cost -17.0% baseline
Agent wall time (MCP mean = 100) 114.2 100

Wall time is a relative index, not an absolute duration: for every 100 units of mean MCP time, AXI took 114.2, a difference of 14.2 units. For example, that ratio would mean 114.2 ms versus 100 ms (14.2 ms more), or 11.42 s versus 10 s (1.42 s more). These are illustrations, not measured durations. The published aggregate does not include the absolute mean wall times, so it cannot establish whether the practical delay was milliseconds or seconds; treat the 14.2% difference as directional only.

Aggregate-only directional evidence; raw cohort artifacts are not published, so no universal-superiority or mutation-proof claim. See results, method, and caveats, harness methodology, and showcase.

Documentation