Agents

lin is built to be driven headless by AI agents as a first-class consumer, not an afterthought. Load these invariants into context instead of parsing help text.

Discover the surface

lin describe returns every command, flag, type, default and exit code as JSON. lin describe issue create scopes to one command. Never parse prose help.

Output discipline

• stdout is data (JSON by default); stderr is messaging. Parse stdout, ignore stderr.
• Always pass --fields ... on list/get calls to protect your context window.
• Lists return {"items": [...], "next_cursor": "..."}; follow with --cursor, or --all (prefer --output ndjson when exhausting).

Mutation discipline

• Always run a mutation with --dry-run first and check the printed {operation, variables}. Dry-run resolves references but never executes.
• Prefer the raw payload path when input is structured: --json '{...}' maps 1:1 to Linear's GraphQL input types; unknown fields fail with exit 65.
• Unset fields are never sent (no accidental clears). Clearing a field to null is not supported; say so rather than trying.
• Deletes require --confirm=<exact-id>.

Branch on exit codes

0 ok, 65 validation, 66 not-found, 70 internal, 75 temporary (retry), 77 permission (key problem), 78 config (no key). See the full exit codes reference.

The authoritative, machine-readable version of this contract ships in the repo as AGENTS.md.