Linear CLI — Everyday

Bundled Python uv-script. Auth: $LINEAR_API_KEY. Invoke as ${CLAUDE_PLUGIN_ROOT}/skills/linear/bin/linear-cli (or just linear-cli if symlinked into PATH).

Defaults (env vars)

Set in your shell rc so you stop typing --team "<team>" on every command. CLI args still override env.

Quick reference

Create — flags

linear-cli issues create [OPTIONS] <TITLE> (title is positional, not --title).

Update

linear-cli issues update [OPTIONS] <ID> (ID positional). Title flag is -T (capital), not --title.

If --state "Name" fails validation: use --data '{"stateId": "UUID"}' with the workflow state UUID. Project: --project "Name" or --project none to clear. Parent (epic): --parent <prefix>-100 or --parent none to detach.

Epics / sub-issues

Linear has no "epic" type; an epic is a parent issue, children link via parentId. get returns parent {id, identifier, title} on every issue and children [{identifier, title, state}] (first 100). list returns parent only. Verify an attach with i get <child> --fields "identifier,parent.identifier".

History: before 2026-09-20 the CLI accepted --data '{"parentId": ...}' but never queried parent/children, so a successful attach read back as null and could not be verified from the CLI.

Output

Default human table. Override:

--output json       # structured JSON
--output ndjson     # one object per line
--fields "identifier,title,state.name"   # table honours the projection (nested keys ok)
--format '{{identifier}} {{title}}'
--id-only           # just identifiers, scripting-friendly

Common pitfalls

Team name → key

<team>=<prefix>, IT=IT, <team>=<prefix>, <team>=<prefix>, Data=<prefix>, <prefix>=<prefix>, <team>=<prefix>, <team>=<prefix>, <team>=<prefix>, <team>=<prefix>, <org>=<prefix>, <team>=<prefix>, <team>=<prefix>, <team>=<prefix>, <team>=<prefix>.

Use the name with --team. The key is the issue prefix (<prefix>-123).