Skip to main content

Core workflow

Every API-backed command follows the same observable sequence.

  1. Resolve configuration. cmd.Execute initializes Viper. The client chooses --api-key, then LINEAR_API_KEY, then ~/.config/linear-cli/config.yaml.
  2. Validate local input. Cobra validates positional arity. Commands validate required flags such as --title, --team, --issue, or --file and return exit code 2 for usage failures.
  3. Resolve human identifiers. Issue mutations and comment/attachment operations turn an identifier such as ENG-123 into a UUID. Team-scoped label and state names are resolved in the same way.
  4. Send GraphQL. The client posts JSON to https://api.linear.app/graphql with Authorization, Content-Type, and a linear-cli/<version> user agent. The request timeout is 30 seconds.
  5. Map the result. HTTP and GraphQL errors become typed CLI errors. Successful data is wrapped by output.PrintSuccess.
  6. Hand off the result. JSON is printed to standard output and main exits with the corresponding code.

Successful list operations may include pagination.hasNextPage and pagination.endCursor. Error responses contain success: false and an error object; they do not contain data.

If a later attachment step fails, the command returns an error and has no cleanup operation for an already-uploaded asset. See limitations.