vanillagreencom/kendex/linear

Linear CLI

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

Every read and write goes to Linear's API as it runs; no tracker data is stored locally. 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>; only issues get <ID>, without --with-bundle and in the default safe format, carries github_sync, the GitHub issues Linear's GitHub sync links the issue to, each as owner/repo#N lowercased. Safe issues get and issues list rows carry in_pr_bundle, true when the description holds **In-PR bundle**: yes. Multi-issue lookups are issues bulk-get <ID1> <ID2> ..., which is also the post-mutation verification path. Comments for several issues are one comments bulk-list <ID1> <ID2> ... call (--stdin takes one identifier per line), never a loop or parallel comments list readers.

The removed cache and sync verbs refuse with one linear: removed= line (linear.sh --help).

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.

Reads

Read the time an issue entered a state from its history: the matching toState row's createdAt. Read every history page needed to identify the latest transition into that state. updated_at records the issue's latest update, which can be a different change. Use Linear's API or activity history; issues get exposes no history field. If the transition is unavailable, report its time as unread.

linear.sh issues list --project "Phase 2" --state "Todo,In Progress" --max
linear.sh issues get ABC-100 --with-bundle
linear.sh labels list --max --format=safe

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.

A list of issues, projects, labels, project labels, teams, users, cycles, documents or initiatives returns its first --limit rows (75 by default, a positive whole number) and prints a linear-list: truncated line on stderr when rows were left unread; --max reads every page. milestones list, statuses list, comments list and attachments list always read every row and take neither. A read follows each nested collection (labels, relations, children, comments) to its end. A read that cannot finish its chain (a failed later page, a missing or repeated cursor, or a chain still open after 400 pages) exits nonzero with no output, never a partial result. An audit that must see the whole backlog passes --max. A text search over issues uses issues list --search TERMS, which Linear filters by title and description server-side, never a --max list piped to a local filter.

A quota refusal exits nonzero with JSON stderr code:"RATELIMITED". Its quota receipt supplies the selected deadline; requests_reset keeps the raw request-header time. Same-binding GraphQL calls share a private hold on this host. Receipt fields, storage failures and held writes: Quota Holds.

The transport retries a rate refusal, a 5xx query/download or an unanswered query/download at most twice. A known hold can stop a GraphQL retry before HTTP. A 5xx or unanswered mutation is sent once with linear-http: write=unconfirmed: read its result before resending. Waits double, or use a longer Retry-After. A Retry-After over 60 seconds or any other HTTP error fails immediately.

Team Target

LINEAR_TEAM has no default. Existing-issue writes, including comments create, route by the issue identifier and need no configured team. Other writes refuse when it is unset; reads drop the team filter. --team <key-or-name> overrides LINEAR_TEAM per call only on issues create, projects create, cycles create, labels create, labels audit, projects audit, cycles list, statuses list and statuses get; the --team filter of issues list, projects list and labels list takes a key or name too. On these reads and statuses list|get, an empty or dash-led --team value refuses before any request rather than reading every team. Run auth-check --strict before the first mutation that needs a configured team in a project.

Every lane writes with one app token, and Linear lets that token write in every team, so linear.sh keeps writes in LINEAR_TEAM itself. Before any write it refuses issues create whose --team is another team, and issues update, bulk-update, activate, block, unblock, complete, archive and trash (or its alias delete) on an issue outside LINEAR_TEAM, judged by reading the issue's current team for each identifier or UUID, once per distinct reference per invocation. A failed team read refuses as refused=cross-team-unread before any write. Reads, comments create, add-relation and remove-relation run in any team. The refusal line is linear: refused=cross-team action=<verb> issue=<ID> team=<KEY> own-team=<KEY> route=peer-mail: give cross-team work to the overseer of that team's repository with lane-mail peer send --repo [REPO]. No setting turns the guard off. With no LINEAR_TEAM, an existing-issue write runs unchecked and prints linear: cross-team-guard=inactive.

Set LINEAR_APP_TOKEN or the client pair in the project's private env file (.env.local unless KENDEX_ENV_FILE names another); op:// references are supported. Use auth-mint on the host with the real pair to publish a token to the fleet. Credential precedence, expiry, caching and attribution: authentication.

LINEAR_API_KEY and KENDEX_USER_EMAIL, the operator's email, also belong in the private env file. Non-secret defaults belong in committed kendex.settings.toml [env]. The kendex app's Customize tab writes the key, team and email. A LINEAR_API_KEY from project files beats an inherited key. When the personal key is selected, auth-check warns with fingerprints if it shadows a different inherited key. Every other key uses process environment precedence over the private env file.

Shared label maintenance

LINEAR_TEAM requires a target before writes that do not address an issue; 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

Orchestration and review sessions file through the TPM pipeline (project-management skill), which owns labels, project, priority, estimate, and relations. An owner-authorized, well-specified single filing is judged in the filing session, with no analysis agent or audit JSON: project-management workflows/audit-issues.md § 4.1.

issues create needs a LINEAR_AGENT_LABELS label before API calls when set; --no-agent-label allows bare creates. Unless LINEAR_REQUIRE_REACH is set empty, create needs Reached by: and, with --review-born --priority 2, Symptom:; placeholders and null tokens are absent. Under that key, authored create/update/bulk-update bodies refuse an invalid Post-merge: trigger or Deadline, or a missing nonempty quoted > **Story:** and > **Why this matters:** opening. A header over 500 characters prints a linear: advisory=issue-header-length line and writes (issues --help). Filing-line and review-born rules: project-management SKILL.md § Disposition, Name what reaches it.

Under a declared label taxonomy (project-management references/labels.md § Project Taxonomy Contract), issues create, issues update --labels, issues bulk-update --labels, issues activate and issues block refuse before any write a label it does not declare, naming the label and the taxonomy file. The taxonomy check does not refuse an undeclared label the issue already carries. issues create refuses declared labels absent from Linear. labels create and labels update --name refuse an undeclared name, and a name a workspace label already uses (on create, only a --team label). labels audit lists the undeclared labels on the team's open issues and the same-name team/workspace pairs. With no taxonomy declared, none of this applies.