AI-agent automation

Treat linear-cli as a stateless shell tool. One invocation performs one operation and emits one JSON response. The CLI does not require a handshake, a daemon, or interactive input.

Secure invocation

Provide the credential through the environment of the agent process:

export LINEAR_API_KEY="$LINEAR_API_KEY"
linear-cli issue list --team ENG --limit 10

Prefer this over --api-key, because command arguments can be exposed by shell history or process inspection. auth login --token persists the key in the local config file and can also expose it to shell history, so use it for deliberate local setup rather than an unattended agent. Never include API keys in prompts, tool results, logs, or issue content.

Branch on the contract

The process exit code is the first classification channel. The JSON body is the second:

Exit	error.code	Action
0	none	Read data.
1	GENERAL_ERROR	Inspect the message and stop unless the operation is safe to retry.
2	USAGE_ERROR	Correct command arguments or input files.
3	AUTH_ERROR	Refresh or configure the API key.
4	NOT_FOUND	Re-resolve the team, issue, or resource ID.
5	RATE_LIMITED	Apply caller-owned backoff and retry policy.
6	NETWORK_ERROR	Retry transient connectivity failures according to caller policy.
7	PERMISSION_DENIED	Stop and request the required Linear access.

Successful output has success: true and data. Failed output has success: false and error.code plus error.message.

Compose workflows

Use read commands to resolve IDs before mutations:

team list -> cycle list --team KEY -> status list --team KEY -> issue create

For a large list, pass pagination.endCursor back through --cursor only for commands that expose that flag. Do not assume that a hasNextPage value means every command can fetch the next page; see pagination limitations.

This shell interface is not an assertion of MCP protocol parity. Agents should use the documented commands and JSON contract rather than assuming unsupported MCP tools or transports exist.