linear-cli

Linear CLI (Zig)

Single-binary Linear client built with Zig 0.15.2. Uses stdlib only, defaults to human-readable tables with a --json override, and stores auth securely at ~/.config/linear/config.json (0600). Use linear help <command> to see command-specific flags and examples.

Build & Test

• Build: zig build -Drelease-safe (debug is default). Binary installs to zig-out/bin/linear.
• Tests: zig build test. Online suite runs with LINEAR_ONLINE_TESTS=1: LINEAR_ONLINE_TESTS=1 LINEAR_TEST_TEAM_ID=<TEAM_ID> zig build online (requires LINEAR_API_KEY; optional LINEAR_TEST_ISSUE_ID, LINEAR_TEST_PROJECT_ID, LINEAR_TEST_MILESTONE_ID; opt-in mutations with LINEAR_TEST_ALLOW_MUTATIONS=1).

Manual QA (Live API)

• Quick start (uses a temp config):

  export LINEAR_API_KEY=<paste key>
  export LINEAR_ONLINE_TESTS=1
  export LINEAR_TEST_TEAM_ID=<team-id>
  # Optional for broader coverage:
  # export LINEAR_TEST_ISSUE_ID=<identifier like ENG-123>
  # export LINEAR_TEST_PROJECT_ID=<project id>
  # export LINEAR_TEST_MILESTONE_ID=<milestone id>
  # export LINEAR_TEST_ALLOW_MUTATIONS=1  # enables create/delete tests
  rm -f /tmp/linear-cli-qa.json
  echo "$LINEAR_API_KEY" | ./zig-out/bin/linear --config /tmp/linear-cli-qa.json auth set
  ./zig-out/bin/linear --config /tmp/linear-cli-qa.json auth test
  zig build test
  LINEAR_ONLINE_TESTS=1 LINEAR_TEST_TEAM_ID=$LINEAR_TEST_TEAM_ID zig build online
  

• Finding IDs quickly:
  • Team: ./zig-out/bin/linear --config /tmp/linear-cli-qa.json teams list --json | jq -r '.nodes[0].id'
  • Issue identifier: ./zig-out/bin/linear --config /tmp/linear-cli-qa.json issues list --limit 1 --quiet
  • Project/milestone: ./zig-out/bin/linear --config /tmp/linear-cli-qa.json issues list --include-projects --fields project,milestone --limit 1 --json
  • If no suitable issue exists and mutations are allowed: LINEAR_TEST_ALLOW_MUTATIONS=1 ./zig-out/bin/linear --config /tmp/linear-cli-qa.json issue create --team <TEAM_KEY_OR_ID> --title "CLI QA seed" --quiet

Config & Auth

• Config path: ~/.config/linear/config.json (override with --config PATH or env LINEAR_CONFIG).
• Precedence: CLI flags > env (LINEAR_API_KEY) > config file. Keys loaded from env are not written back to disk.
• Keys:
  • api_key (or env LINEAR_API_KEY; auth set accepts --api-key, piped stdin, or an interactive prompt with echo disabled)
  • default_team_id (default ``)
  • default_output (table|json, default table)
  • default_state_filter (default ["completed","canceled"])
  • team_cache (auto-populated key->id cache from issue create)
• Manage defaults without editing JSON: linear config show, linear config set default_team_id ENG, linear config set default_output json, linear config unset default_state_filter
• Files are saved with 0600 perms; the CLI warns if permissions drift. auth show [--redacted] surfaces the configured key without leaking the full token. auth test pings viewer to validate the current key.

CLI Overview

Global flags:

• --json — force JSON output (default follows config.default_output)
• --config PATH or env LINEAR_CONFIG — choose config file
• --endpoint URL — override the GraphQL endpoint (useful for QA/mocking)
• --retries N — retry 5xx responses up to N times with a small backoff
• --timeout-ms MS — request timeout flag (plumbed for future enforcement)
• --no-keepalive — disable HTTP keep-alive reuse
• --help/--version — version includes git hash and build mode
• linear help <command> — show command-specific help with examples