linear
Load for any Linear read or write: issues, projects, cycles, milestones, initiatives, labels.
vanillagreencom · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add vanillagreencom/kendex --skill linear技能说明
name: linear description: "Load for any Linear read or write: issues, projects, cycles, milestones, initiatives, labels." summary: "Bash CLI over Linear's GraphQL API with a local cache: read, search, create, or update issues, projects, cycles, milestones, initiatives, and labels." license: MIT user-invocable: true metadata: author: vanillagreen source: kendex repository: "https://github.com/vanillagreencom/kendex" bugs: "https://github.com/vanillagreencom/kendex/issues" version: "1.1.0" tags: [integration]
Linear CLI
Problem with this skill? Run
kendex report— it files to the owning repo automatically. Do not hand-file.
.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.
Commands
| Resource | Actions |
|---|---|
issues | list, get, bulk-get, create, update, bulk-update, archive, trash/delete, children, list-relations, add-relation, remove-relation, activate, block, unblock, complete, validate-completion |
comments | list, create, update, delete |
projects | list, get, create, update, delete, list-dependencies, add-dependency, remove-dependency, post-update, list-updates, reorder, set-sort-order |
initiatives | list, get, create, update, delete, add-project, remove-project |
milestones | list, get, create, update, delete |
labels / project-labels | list, create, update, delete |
teams / users / statuses / documents | list, get (users also has me) |
cycles | list, create, update |
sync | Refresh the local cache (--full, --reconcile, --if-stale N, --stats) |
cache | Cache-only reads: issues, projects, comments, labels, initiatives, cycles, attachments, status |
auth-check | Report the resolved key/team and writes_enabled (--strict exits non-zero when writes would refuse) |
session-status | Aggregated status for the /start workflow |
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>; 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 lives at .cache/linear under the physical worktree root from git rev-parse --show-toplevel. A missing-cache error names the cache_dir and meta_path it checked. A cache file that exists but does not parse is reported as corrupt, never as an empty result.
In a linked worktree whose .cache should be a WORKTREE_SYMLINKS-managed symlink but is a real directory, sync refuses before touching the API and names the repair (worktree fix-links <PATH> from the main checkout). Repos whose WORKTREE_SYMLINKS deliberately excludes .cache are 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.
| Variable | Purpose | Default |
|---|---|---|
LINEAR_API_KEY | Required for live commands and sync; not for cache reads | — |
LINEAR_API_KEY_OVERRIDE | Inline/test key that beats project files | — |
LINEAR_TEAM | Team every write targets | — (unset refuses writes) |
LINEAR_FORMAT | Default output format | safe |
LINEAR_TEAM_PREFIX | Issue identifier prefix | PROJ |
LINEAR_AGENT_LABELS | Declared agent:* taxonomy; non-empty makes issues create refuse unrouted creates | — (unset = off) |
LINEAR_API_KEY belongs in .env.local; non-secret defaults in committed kendex.settings.toml [env]. A key from project files beats one inherited from the environment, and auth-check warns (fingerprints only) when it shadows a differing inherited key.
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 carrying no agent label from that set, including a typoed agent:* name. --no-agent-label permits a deliberate bare create.
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