Linear

Never edit this file directly. To make additions or modifications, edit the appropriate section in ./vstack.toml. Then run vstack refresh.

Linear CLI

CLI wrapper for Linear's GraphQL API with local cache, bulk operations, and structured output.

.agents/skills/linear/scripts/linear.sh <resource> <action> [options]

Resources

ctx7 CLI

Workflow Patterns

Commands

Compatibility aliases: issues relations maps to issues list-relations, and projects dependencies maps to projects list-dependencies. Prefer the explicit action names in new workflows.

There is no view or show action. Single-issue lookups are issues get <ID> (live) or cache issues get <ID> (cache); multi-issue lookups are issues bulk-get <ID1> <ID2> .... For post-mutation verification, use live issues bulk-get — it returns fresh state for every mutated issue in one command.

Hierarchy

INITIATIVE (Strategic goal — months)
  └── PROJECT (2-6 week deliverable)
        ├── MILESTONE (stage: Alpha, Beta, Release)
        │     └── ISSUE (1-5 day work item)
        └── ISSUE (work item without milestone)
              └── SUB-ISSUE (breakdown for parallel work)

Cache Pattern

Reads go through cache. Writes go through live commands (auto-update cache via write-through). Sync at session start or when cache is stale.

# READS → cache (fast, no API calls)
linear.sh cache issues list --project "Phase 2" --state "Todo,In Progress"
linear.sh cache issues list --all-projects --state "Backlog,Todo" --max --format=compact
linear.sh cache issues get ABC-100 --with-bundle

# WRITES → live (hit API, auto-update cache)
linear.sh issues create --title "New task" --project "Phase 2"
linear.sh issues update ABC-100 --state "Done"

# SYNC → refresh cache
linear.sh sync --reconcile      # Incremental + reconcile archived
linear.sh sync --full           # Full re-sync

cache issues list --all-projects enumerates every project in ONE command — each row carries its project name, and other filters (--state, --max, --format) compose. Use it for cross-project comparison sets instead of looping --project per project; restricted harness approval policies reject loop-shaped commands. Mutually exclusive with --project.

Cache and attachment files live under .cache/linear in the physical git worktree root reported by git rev-parse --show-toplevel, not under the path used to reach the skill script. This keeps sync, cache, and attachment reads consistent across symlinked checkout spellings, worktrees, and canonical source-path invocation. A missing-cache error includes the checked cache_dir and meta_path; inspect those fields before assuming a sync wrote somewhere else.

Output Formats

compact omits description and other large text fields. raw nests fields under GraphQL structure — do not assume top-level jq paths. Use safe (default) when you need issue descriptions or full field access.

Configuration

Put LINEAR_API_KEY in .env.local. Put non-secret defaults in committed vstack.settings.toml under [env]; .env.local still wins for local overrides.

Safe Format Field Mapping

identifier → id         # ABC-XXX issue ID
id → uuid              # GraphQL UUID
state.name → state     # State name
state.type → state_type
sortOrder → sort_order  # Manual sort position

Blocked Label vs Issue Relations

Blocking relations must connect peers of one bundle: same direct parent, or both top-level (and same project). An issue cannot block its own ancestor or descendant — the parent-child hierarchy already encodes that dependency; use --related for traceability. Rejections for cross-subtree pairs prescribe the valid pair at the level where the subtrees separate. Before either acceptance or remediation, the guard proves each parent chain reaches an explicit null root through well-formed edges with unique IDs/identifiers. It also requires an explicit null or well-formed project value; incomplete, cyclic, or malformed hierarchy data is rejected before mutation.

A blocking relation pointing at a Done or Canceled issue is satisfied history, not stale metadata — Linear itself already treats the dependent issue as unblocked. The relation stays for provenance and traceability; never remove or "fix" it, and audits must never classify it as stale. The only legitimate audit output for a completed-blocker relation is a scheduling signal ("gates cleared, ready to schedule"). Cautionary precedent: an audit agent once emitted a "STALE blocked_by METADATA" section listing issues whose blockers were Done, framing valid history as defects and inviting destructive cleanup — the issues were simply ready to schedule.

Common Pitfalls

• State names are case-sensitive and team-specific — verify with linear.sh statuses list
• Available states: Backlog, Todo, In Progress, In Review, Done, Canceled (not "Cancelled")
• agent:* labels are mutually exclusive (only one per issue)
• issues activate ISSUE --agent NAME applies agent:NAME in the same update as the "In Progress" transition, replacing any existing agent:* label; it fails without changing state when the label does not exist
• issues complete ISSUE --summary-file PATH posts the completion summary comment first and only then transitions to "Done"; a failed post leaves the state unchanged
• issues validate-completion is a pre-merge check: session-root targets are expected in "In Progress"/"In Review" (Done fails state_ok — managed roots stay pre-merge until PR merge; this pre-merge rule applies to the session root only). --include-children-of expands the bundle and validates each child as "Done": every completed child IS included and passes, a still-pending child fails, and canceled children are excluded from the expansion (abandoned work is never "Done")
• --labels replaces the full issue-label set on update. Workflow callers must fetch current labels, compute the final set, validate against cache labels list --format=safe, then call update with the full final set.
• cache labels list --format=safe returns issue labels with id, name, team, parent, and is_group so workflows can reject parent/group labels before mutation.
• issues bulk-update is non-atomic. If one item fails after earlier updates succeeded, it emits a JSON summary with partial: true, per-issue results, and exits nonzero.

Troubleshooting

• "labelIds not exclusive child labels" error: Using multiple labels from the same exclusive group. Only one agent:* label and one platform:* label per issue.
• Need raw GraphQL output?: Use --format=raw
• Script help: linear.sh <resource> --help

Dependencies

• Bash 4.0 or newer (macOS system Bash 3.2 is unsupported; install a newer Bash and invoke linear.sh with it)
• curl
• jq