CLI reference

The CLI is the supported interface in this repository. It is a Cobra command tree backed by Linear's GraphQL HTTP endpoint. The CLI's own output contract is not the raw GraphQL response: every normal result is wrapped in a JSON envelope.

Global flags

These flags are available on the root command and its subcommands:

Flag	Default	Effect
--pretty	false	Indent JSON with two spaces.
--api-key <key>	empty	Use this key before LINEAR_API_KEY and the config file. Avoid it in shared command history.

Run linear-cli --help or any command with --help for Cobra's generated usage. The complete command and flag inventory is in Command reference, with detailed groups for issues and comments, resources, and attachments.

JSON success envelope

{
  "success": true,
  "data": {},
  "pagination": {
    "hasNextPage": false,
    "endCursor": "cursor-string"
  }
}

data is an object for a get or mutation command and an array for a list or search command. pagination is omitted when the command does not pass pagination data to the formatter. endCursor is omitted when it is empty.

JSON error envelope

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "issue not found: ENG-999"
  }
}

The stable codes and process exits are documented in AI-agent automation. Do not parse human text to classify a failure when error.code and the exit code are available.