Linear

Linear CLI

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

Reads go through cache; writes go through the live commands, which write through to the cache. linear.sh <resource> --help prints per-resource options. --format values: safe (the default, flat and null-safe), compact (a smaller shape for workflow routing), ids (identifiers only), table, raw (the GraphQL nesting, so never assume top-level jq paths). safe renames fields: identifier→id, id→uuid, state.name→state, state.type→state_type, sortOrder→sort_order.

Commands

Aliases: issues relations → list-relations, projects dependencies → list-dependencies. Singular resource names (issue, project, …) route to the plural. There is no view/show: single-issue lookups are issues get <ID> (live) or cache issues get <ID>, and multi-issue lookups are issues bulk-get <ID1> <ID2> ..., which is also the post-mutation verification path.

Schema reference over ctx7: /websites/studio_apollographql_public_linear-api_variant_current (API), /linear/linear (SDK), /websites/linear_app_developers (guides). patterns/workflow-actions.md covers multi-step state changes.

Cache

linear.sh cache issues list --project "Phase 2" --state "Todo,In Progress"
linear.sh cache issues get ABC-100 --with-bundle
linear.sh sync --reconcile

cache issues list --all-projects enumerates every project in one command (each row carries its project name); --no-project returns only unassigned issues. Both are mutually exclusive with --project. Use --all-projects; never loop per project. An unrecognized filter flag is rejected. Repeated --label flags (and --labels a,b) require ALL named labels.

Both issues list and cache issues list return the first 75 rows by default and warn on stderr when that truncated the result; --max fetches everything. --limit N caps a CACHE listing's total; on the live path it is the per-page size (--max --limit N pages at N under a 200-page cap that warns when it truncates). An audit that must see the whole backlog passes --max.

The cache is .cache/linear under the physical worktree root (README.md); a linked worktree whose .cache should be a WORKTREE_SYMLINKS-managed symlink but is a real directory refuses sync and names the repair. A repo whose WORKTREE_SYMLINKS deliberately excludes .cache is exempt.

Team Target

LINEAR_TEAM has no default. With it unset every write refuses before any API call; reads drop the team filter. --team <name> overrides per call only on issues create, projects create, cycles create, and labels create. Run auth-check --strict before the first mutation in a project.

LINEAR_API_KEY belongs in the project's private env file, .env.local unless KENDEX_ENV_FILE names another; non-secret defaults in committed kendex.settings.toml [env]. The kendex app's Customize tab writes both. A key from project files beats one inherited from the environment, and auth-check warns (fingerprints only) when it shadows a differing inherited key.

Shared label maintenance

LINEAR_TEAM requires a target before writes; it does not restrict an API key or check a label's owning team. auth-check verifies authentication and the local target, not the key's permission mask. Inspect key permissions in Linear settings; report fingerprints only.

Before changing a label definition, read its ID, team, parent and group status. An empty team means workspace scope. Read issue use across affected teams and check references in their manifests, scripts, gates and generated instructions. A team-restricted key cannot establish workspace-wide issue use.

The workspace owner coordinates shared label changes with affected repository maintainers. A repository taxonomy names that owner. Keep generic labels shared and project-specific labels team-scoped. Obtain approval for the concrete affected set and the exact proposed change before any shared-label definition change, replacement or deletion. Issue-label assignment authority does not authorize changing a shared label definition.

Prepare dependent repository corrections before the label change. After an authorized change, refresh each affected inventory, render instructions from their source, and run its taxonomy and repository checks. Record the label IDs, issue assignments and repository commits together. If the API cannot change scope, prepare a replacement plan with history and recovery limits before requesting migration approval.

Issue Creation Routing

Never create a tracked issue directly from an orchestration or review session. Route it through the TPM pipeline (project-management skill), which owns labels, project, priority, estimate, and relations.

Where LINEAR_AGENT_LABELS declares a taxonomy, issues create refuses before any API call a create with no agent label from that set (--no-agent-label permits a deliberate bare create). Where LINEAR_REQUIRE_REACH is set, it refuses a description with no Reached by: line and, with --review-born and --priority 2, one with no Symptom: line; a placeholder or null token counts as no line. Each guard is its own setting. What the lines say is the author's to judge; the rule is the project-management skill's SKILL.md § Disposition, Name what reaches it, which is also where a create decides whether it is review-born.

Attachments

issues create, issues update, and comments create take a repeatable --attach <path>. Images embed as markdown in the description/body. On issues update without --description, the embed appends to the existing description rather than replacing it. Other files become Linear attachments on issues, or markdown links on comments (comments have no attachment surface). An unreadable path refuses before any API call; an attachment failure after a successful issue write reports partial: true and exits non-zero.

Resolve a cited artifact

Read a cited repository path when it exists. When it is absent, reconcile the tracker before looking up attachments, even if the workflow's general cache is fresh. If reconciliation fails, stop and report the sync failure; do not treat it as a missing attachment.

linear.sh sync --reconcile
linear.sh cache attachments list [ISSUE_ID]

Match the original cited repository path against repo_path, scoped to that issue or the research/source issue its brief explicitly names. For attachments with no repo_path, accept a filename match only when it is unique within that issue. Use an attachment URL in the brief to select the matching url when references collide. Read the matching local_path under .cache/linear/attachments/; keep the repository path as the tracker reference. Resolve companion files, such as a plan's JSON or research metadata, the same way. Do not write a machine's cache path into an issue or delegation for another checkout.

No match leaves the calling workflow's missing-file behavior unchanged. Multiple matches without a distinguishing reference require clarification. A matched attachment whose local file is unreadable is a download failure; report it instead of treating the research as absent. Consumers without attachments keep reading repository files as before.

Blocked Label vs Issue Relations

A blocker that is itself a Linear issue is a relation (--blocked-by); an external one (vendor, license) is the blocked label plus a comment.

Blocking relations must connect peers of one bundle: same direct parent, or both top-level. The two issues need not share a project. An issue cannot block its own ancestor or descendant; use --related for traceability. The check reads each issue's own direct parent in one query.

A blocking relation pointing at a Done or Canceled issue is satisfied history, not stale metadata. The relation stays for provenance; 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").

Normalized issue lists, gets, bulk gets, bundles, recursive children, relation reads, and session status keep each blocking relation in blocked_by and list only nonterminal blockers in blocked_by_open.

Option Behavior

What each option accepts: issues --help. Refused before any write, on the create and update paths alike: --cycle on a non-UUID, --project/--milestone/--assignee on a reference that matches nothing, and --priority on an out-of-range value. Available states: Backlog, Todo, In Progress, In Review, Done, Canceled (not "Cancelled"). Verify with statuses list.

A name selects one project on issues create / update / bulk-update --project, projects get / cache projects get, projects list-dependencies / cache projects list-dependencies, milestones --project, and initiatives add-project / remove-project. There a canceled project sharing that name loses to the live one, and a name with no live match is refused, naming each match and its state; pass a UUID to reach a canceled project. Name filters never resolve: issues list --project, cache issues list --project and documents list --project match on the name alone, so their results can mix a live project with its canceled twin.

--labels REPLACES the whole issue-label set. Fetch current labels, compute the final set, validate it against cache labels list --format=safe (which reports is_group so parent/group labels can be rejected), then pass the complete set. A name that does not resolve fails the update; --clear-labels is the only way to empty the set.

• agent:* labels are mutually exclusive, one per issue; issues activate applies them with the "In Progress" transition (semantics: issues --help).
• issues bulk-update is non-atomic: on partial failure it emits partial: true with per-issue results and exits non-zero.
• issues block applies the blocked label, creates the blocking relation, and comments. A rejected relation fails the command.

validate-completion

The pre-merge check on state plus summary comment, live only: issues validate-completion, with no cache spelling. The expected-state matrix is in issues --help § Validate-Completion: session root vs bundle children vs --container parents, and the fail-closed flag pairing.

A "labelIds not exclusive child labels" error means two labels from one exclusive group. Requires Bash 4.0+ (macOS system Bash 3.2 is unsupported), curl, and jq.