# Linear CLI Linear resources through the cmdhub CLI. ## Install ```bash cmdhub get linear ``` ## Authentication api_key ## Agent-Readable Catalog - Machine-readable command catalog: `/cli/linear/catalog.json` - Stable command anchors use the `cmd-...` IDs listed under each command. - Inspect this catalog before planning tool use for command paths, examples, flags, mutation markers, and dry-run support. ## Overview ```bash # Inspect auth state and available command schemas linear auth status --json linear schema ``` ## CLI Overview Linear adapter CLI ## Generated Coverage - Command groups: `19` - Total documented command nodes: `65` - Live examples: `3` - Lifecycle surfaces: `auth`, `doctor`, `capabilities`, `schema`, `resolve`, `version` - Machine-readable output: `--json`, `--jsonl` - Human views: `summary`, `full` ## Auth Contract - Auth mode: api_key - Provider permission model: Linear OAuth or API key - Auth scopes: `Linear workspace API access` - Scope note: Used for Linear workspaces, teams, users, states, cycles, labels, projects, issues, and comments. - Standard commands: `auth login`, `auth logout`, `auth refresh`, `auth status`, `auth whoami` - `auth status --json` reports `tool`, `profile`, `provider`, `authenticated`, and `suggested_next_step`. - `auth whoami --json` is the stable way to answer identity questions. ## Agent Safety Notes - Discovery commands such as `list`, `search`, `get`, `resolve`, `schema`, `doctor`, `capabilities`, `status`, and `whoami` are the safest commands to run first. - Treat commands marked as mutating as state-changing local or provider operations. - Mutating command paths: `linear attachment create`, `linear attachment delete`, `linear attachment update`, `linear auth login`, `linear auth logout`, `linear auth refresh`, `linear comment`, `linear comment create`, `linear comment delete`, `linear comment update`, `linear issue archive`, `linear issue create`, `linear issue label`, `linear issue label add`, `linear issue label remove`, `linear issue unarchive`, `linear issue update`, `linear label`, `linear login`, `linear logout`, `linear profile create`, `linear profile delete`, `linear profile use` - Commands with `--dry-run`: `linear attachment delete`, `linear comment delete`, `linear issue archive`, `linear issue unarchive` ## Global Flags - `--json` (bool): Emit JSON machine output - `--jsonl` (bool): Emit JSONL records for piping - `--output` (string): Compatibility output mode: json|jsonl. Prefer --json or --jsonl - `--view` (string): View mode: summary|full Default: `summary`. - `--profile` (string): Config/auth profile Default: `default`. - `--config` (string): Config path override - `--quiet` (bool): Suppress non-essential diagnostics - `--debug` (bool): Enable debug diagnostics - `--limit` (int): Maximum items to emit Default: `50`. - `--page-size` (int): Requested upstream page size Default: `50`. - `--cursor` (string): Continuation cursor - `--no-paginate` (bool): Fetch only one page - `--version` (bool): Print version information ## Command Reference ### `linear attachment` - Anchor: `cmd-linear-attachment` - Mutates state: `no` - Supports dry run: `no` Manage Linear attachment records #### `linear attachment create` - Anchor: `cmd-linear-attachment-create` - Mutates state: `yes` - Supports dry run: `no` Create a Linear external URL attachment Example: ```bash linear attachment create --help linear attachment create --issue i1 --url https://example.com/logs --title "Logs" ``` Flags: - `--issue` (string): Issue ref, identifier, URL, or ID - `--metadata-json` (string): Attachment metadata JSON object - `--subtitle` (string): Attachment subtitle - `--title` (string): Attachment title - `--url` (string): External URL to attach #### `linear attachment delete` - Anchor: `cmd-linear-attachment-delete` - Mutates state: `yes` - Supports dry run: `yes` Delete a Linear external URL attachment Example: ```bash linear attachment delete a1 --yes ``` Flags: - `--dry-run` (bool): Preview without changing Linear state - `--yes` (bool): Confirm attachment deletion #### `linear attachment get` - Anchor: `cmd-linear-attachment-get` - Mutates state: `no` - Supports dry run: `no` Get a Linear attachment Example: ```bash linear attachment get a1 ``` #### `linear attachment list` - Anchor: `cmd-linear-attachment-list` - Mutates state: `no` - Supports dry run: `no` List Linear attachment records Example: ```bash linear attachment list linear attachment list --issue CMD-123 ``` Flags: - `--include-archived` (bool): Include archived Linear records - `--issue` (string): Issue ref, identifier, URL, or ID #### `linear attachment update` - Anchor: `cmd-linear-attachment-update` - Mutates state: `yes` - Supports dry run: `no` Update a Linear external URL attachment Example: ```bash linear attachment update a1 --title "Updated logs" ``` Flags: - `--metadata-json` (string): Attachment metadata JSON object - `--subtitle` (string): Attachment subtitle - `--title` (string): Attachment title ### `linear auth` - Anchor: `cmd-linear-auth` - Mutates state: `no` - Supports dry run: `no` Manage Linear authentication #### `linear auth login` - Anchor: `cmd-linear-auth-login` - Mutates state: `yes` - Supports dry run: `no` Authenticate with Linear Example: ```bash linear auth login linear auth login --api-key linear auth login --help linear auth status ``` Flags: - `--api-key` (bool): authenticate with a Linear personal API key instead of OAuth - `--api-key-stdin` (bool): read the Linear API key from stdin #### `linear auth logout` - Anchor: `cmd-linear-auth-logout` - Mutates state: `yes` - Supports dry run: `no` Remove stored Linear credentials Example: ```bash linear auth login linear auth logout linear auth logout --help ``` #### `linear auth refresh` - Anchor: `cmd-linear-auth-refresh` - Mutates state: `yes` - Supports dry run: `no` Refresh stored Linear credentials Example: ```bash linear auth refresh linear auth refresh --help ``` #### `linear auth status` - Anchor: `cmd-linear-auth-status` - Mutates state: `no` - Supports dry run: `no` Show Linear auth status Example: ```bash linear auth status linear auth status --help linear auth status --json ``` #### `linear auth whoami` - Anchor: `cmd-linear-auth-whoami` - Mutates state: `no` - Supports dry run: `no` Show the current Linear user and workspace Example: ```bash linear auth whoami linear auth whoami --help linear auth whoami --json ``` ### `linear capabilities` - Anchor: `cmd-linear-capabilities` - Mutates state: `no` - Supports dry run: `no` Describe capabilities Example: ```bash linear capabilities --help ``` ### `linear comment` - Anchor: `cmd-linear-comment` - Mutates state: `yes` - Supports dry run: `no` Manage Linear comment records #### `linear comment create` - Anchor: `cmd-linear-comment-create` - Mutates state: `yes` - Supports dry run: `no` Create a Linear issue comment Example: ```bash linear comment create --help linear comment create --issue i1 --body "Reproduced in staging." ``` Flags: - `--body` (string): Comment markdown body - `--body-file` (string): Read comment body from a file - `--issue` (string): Issue ref, identifier, URL, or ID #### `linear comment delete` - Anchor: `cmd-linear-comment-delete` - Mutates state: `yes` - Supports dry run: `yes` Delete a Linear issue comment Example: ```bash linear comment delete cm1 --yes ``` Flags: - `--dry-run` (bool): Preview without changing Linear state - `--yes` (bool): Confirm comment deletion #### `linear comment get` - Anchor: `cmd-linear-comment-get` - Mutates state: `no` - Supports dry run: `no` Get a Linear comment Example: ```bash linear comment get cm1 ``` #### `linear comment list` - Anchor: `cmd-linear-comment-list` - Mutates state: `no` - Supports dry run: `no` List Linear comment records Example: ```bash linear comment list linear comment list --issue CMD-123 ``` Flags: - `--include-archived` (bool): Include archived Linear records - `--issue` (string): Issue ref, identifier, URL, or ID #### `linear comment update` - Anchor: `cmd-linear-comment-update` - Mutates state: `yes` - Supports dry run: `no` Update a Linear issue comment Example: ```bash linear comment update cm1 --body "Updated comment." ``` Flags: - `--body` (string): Comment markdown body - `--body-file` (string): Read comment body from a file ### `linear config` - Anchor: `cmd-linear-config` - Mutates state: `no` - Supports dry run: `no` Inspect local configuration #### `linear config explain` - Anchor: `cmd-linear-config-explain` - Mutates state: `no` - Supports dry run: `no` Explain resolved configuration Example: ```bash linear config explain --help ``` ### `linear cycle` - Anchor: `cmd-linear-cycle` - Mutates state: `no` - Supports dry run: `no` Manage Linear cycle records #### `linear cycle get` - Anchor: `cmd-linear-cycle-get` - Mutates state: `no` - Supports dry run: `no` Get a Linear cycle Example: ```bash linear cycle get cy1 ``` #### `linear cycle list` - Anchor: `cmd-linear-cycle-list` - Mutates state: `no` - Supports dry run: `no` List Linear cycle records Example: ```bash linear cycle list linear cycle list --team CMD ``` Flags: - `--include-archived` (bool): Include archived Linear records - `--team` (string): Team ref, key, name, or ID ### `linear doctor` - Anchor: `cmd-linear-doctor` - Mutates state: `no` - Supports dry run: `no` Run diagnostics Example: ```bash linear doctor --help ``` ### `linear issue` - Anchor: `cmd-linear-issue` - Mutates state: `no` - Supports dry run: `no` Manage Linear issue records #### `linear issue archive` - Anchor: `cmd-linear-issue-archive` - Mutates state: `yes` - Supports dry run: `yes` Archive a Linear issue Example: ```bash linear issue archive i1 --yes ``` Flags: - `--dry-run` (bool): Preview without changing Linear state - `--yes` (bool): Confirm the issue archive operation #### `linear issue create` - Anchor: `cmd-linear-issue-create` - Mutates state: `yes` - Supports dry run: `no` Create a Linear issue Example: ```bash linear issue create --help linear issue create --team CMD --title "Investigate login error" ``` Flags: - `--assignee` (string): Assignee user ref, email, name, ID, or me - `--cycle` (string): Cycle ref, number, name, or ID - `--description` (string): Issue markdown description - `--description-file` (string): Read issue markdown description from a file - `--due-date` (string): Due date in YYYY-MM-DD form - `--label` (stringArray): Issue label ref, name, or ID; repeatable - `--priority` (string): Priority: none, urgent, high, medium, low, or 0-4 - `--project` (string): Project ref, slug, name, or ID - `--state` (string): Workflow state ref, name, or ID - `--team` (string): Team ref, key, name, or ID - `--title` (string): Issue title #### `linear issue get` - Anchor: `cmd-linear-issue-get` - Mutates state: `no` - Supports dry run: `no` Get a Linear issue Example: ```bash linear issue get CMD-123 ``` #### `linear issue label` - Anchor: `cmd-linear-issue-label` - Mutates state: `yes` - Supports dry run: `no` Manage labels on Linear issues ##### `linear issue label add` - Anchor: `cmd-linear-issue-label-add` - Mutates state: `yes` - Supports dry run: `no` Add a label on a Linear issue Example: ```bash linear issue label add i1 --label cmdhub-demo ``` Flags: - `--label` (string): Label ref, name, or ID ##### `linear issue label remove` - Anchor: `cmd-linear-issue-label-remove` - Mutates state: `yes` - Supports dry run: `no` Remove a label on a Linear issue Example: ```bash linear issue label remove i1 --label cmdhub-demo ``` Flags: - `--label` (string): Label ref, name, or ID #### `linear issue list` - Anchor: `cmd-linear-issue-list` - Mutates state: `no` - Supports dry run: `no` List Linear issue records Example: ```bash linear issue list linear issue list --limit 20 ``` Flags: - `--assignee` (string): Assignee user ref, email, name, ID, or me - `--created-after` (string): Only include issues created after this date or RFC3339 timestamp - `--creator` (string): Creator user ref, email, name, ID, or me - `--cycle` (string): Cycle ref, number, name, or ID - `--due-after` (string): Only include issues due on or after this YYYY-MM-DD date - `--due-before` (string): Only include issues due on or before this YYYY-MM-DD date - `--include-archived` (bool): Include archived Linear records - `--label` (string): Issue label ref, name, or ID - `--priority` (string): Priority: none, urgent, high, medium, low, or 0-4 - `--project` (string): Project ref, slug, name, or ID - `--state` (string): Workflow state ref, name, or ID - `--state-type` (string): Workflow state type such as backlog, unstarted, started, completed, or canceled - `--team` (string): Team ref, key, name, or ID - `--updated-after` (string): Only include issues updated after this date or RFC3339 timestamp #### `linear issue search` - Anchor: `cmd-linear-issue-search` - Mutates state: `no` - Supports dry run: `no` Search Linear issue records Example: ```bash linear issue search linear issue search --query login ``` Flags: - `--assignee` (string): Assignee user ref, email, name, ID, or me - `--created-after` (string): Only include issues created after this date or RFC3339 timestamp - `--creator` (string): Creator user ref, email, name, ID, or me - `--cycle` (string): Cycle ref, number, name, or ID - `--due-after` (string): Only include issues due on or after this YYYY-MM-DD date - `--due-before` (string): Only include issues due on or before this YYYY-MM-DD date - `--include-archived` (bool): Include archived Linear records - `--label` (string): Issue label ref, name, or ID - `--priority` (string): Priority: none, urgent, high, medium, low, or 0-4 - `--project` (string): Project ref, slug, name, or ID - `--query` (string): Search text - `--state` (string): Workflow state ref, name, or ID - `--state-type` (string): Workflow state type such as backlog, unstarted, started, completed, or canceled - `--team` (string): Team ref, key, name, or ID - `--updated-after` (string): Only include issues updated after this date or RFC3339 timestamp #### `linear issue unarchive` - Anchor: `cmd-linear-issue-unarchive` - Mutates state: `yes` - Supports dry run: `yes` Unarchive a Linear issue Example: ```bash linear issue unarchive i1 --yes ``` Flags: - `--dry-run` (bool): Preview without changing Linear state - `--yes` (bool): Confirm the issue unarchive operation #### `linear issue update` - Anchor: `cmd-linear-issue-update` - Mutates state: `yes` - Supports dry run: `no` Update a Linear issue Example: ```bash linear issue update i1 --state "In Progress" linear issue update i1 --title "Updated title" ``` Flags: - `--assignee` (string): Assignee user ref, email, name, ID, or me - `--clear-assignee` (bool): Remove issue assignee - `--clear-cycle` (bool): Remove issue cycle - `--clear-due-date` (bool): Remove issue due date - `--clear-project` (bool): Remove issue project - `--cycle` (string): Cycle ref, number, name, or ID - `--description` (string): Issue markdown description - `--description-file` (string): Read issue markdown description from a file - `--due-date` (string): Due date in YYYY-MM-DD form - `--priority` (string): Priority: none, urgent, high, medium, low, or 0-4 - `--project` (string): Project ref, slug, name, or ID - `--state` (string): Workflow state ref, name, or ID - `--title` (string): Issue title ### `linear label` - Anchor: `cmd-linear-label` - Mutates state: `yes` - Supports dry run: `no` Manage Linear label records #### `linear label get` - Anchor: `cmd-linear-label-get` - Mutates state: `no` - Supports dry run: `no` Get a Linear label Example: ```bash linear label get l1 ``` #### `linear label list` - Anchor: `cmd-linear-label-list` - Mutates state: `no` - Supports dry run: `no` List Linear label records Example: ```bash linear label list linear label list --team CMD ``` Flags: - `--include-archived` (bool): Include archived Linear records - `--team` (string): Team ref, key, name, or ID ### `linear login` - Anchor: `cmd-linear-login` - Mutates state: `yes` - Supports dry run: `no` Authenticate with Linear Example: ```bash linear auth status linear login linear login --api-key ``` Flags: - `--api-key` (bool): authenticate with a Linear personal API key instead of OAuth - `--api-key-stdin` (bool): read the Linear API key from stdin ### `linear logout` - Anchor: `cmd-linear-logout` - Mutates state: `yes` - Supports dry run: `no` Remove stored Linear credentials Example: ```bash linear auth login linear logout ``` ### `linear profile` - Anchor: `cmd-linear-profile` - Mutates state: `no` - Supports dry run: `no` Manage provider profiles #### `linear profile create` - Anchor: `cmd-linear-profile-create` - Mutates state: `yes` - Supports dry run: `no` Create an unauthenticated provider profile Example: ```bash linear profile create --help ``` #### `linear profile delete` - Anchor: `cmd-linear-profile-delete` - Mutates state: `yes` - Supports dry run: `no` Delete a local provider profile Example: ```bash linear profile delete --help ``` #### `linear profile list` - Anchor: `cmd-linear-profile-list` - Mutates state: `no` - Supports dry run: `no` List provider profiles Example: ```bash linear profile list --help ``` #### `linear profile rename` - Anchor: `cmd-linear-profile-rename` - Mutates state: `no` - Supports dry run: `no` Rename a local provider profile Example: ```bash linear profile rename --help ``` #### `linear profile use` - Anchor: `cmd-linear-profile-use` - Mutates state: `yes` - Supports dry run: `no` Set the default provider profile Example: ```bash linear profile use --help ``` ### `linear project` - Anchor: `cmd-linear-project` - Mutates state: `no` - Supports dry run: `no` Manage Linear project records #### `linear project get` - Anchor: `cmd-linear-project-get` - Mutates state: `no` - Supports dry run: `no` Get a Linear project Example: ```bash linear project get p1 ``` #### `linear project list` - Anchor: `cmd-linear-project-list` - Mutates state: `no` - Supports dry run: `no` List Linear project records Example: ```bash linear project list linear project list --limit 10 ``` Flags: - `--include-archived` (bool): Include archived Linear records #### `linear project search` - Anchor: `cmd-linear-project-search` - Mutates state: `no` - Supports dry run: `no` Search Linear project records Example: ```bash linear project search linear project search --query onboarding ``` Flags: - `--include-archived` (bool): Include archived Linear records - `--query` (string): Search text ### `linear resolve` - Anchor: `cmd-linear-resolve` - Mutates state: `no` - Supports dry run: `no` Resolve a local ref, short id, or URL alias Example: ```bash linear resolve --help linear resolve ``` ### `linear schema` - Anchor: `cmd-linear-schema` - Mutates state: `no` - Supports dry run: `no` Emit schema hints Example: ```bash linear schema --help ``` Flags: - `--in` (bool): Show input schema - `--input` (bool): Show input schema - `--out` (bool): Show output schema ### `linear state` - Anchor: `cmd-linear-state` - Mutates state: `no` - Supports dry run: `no` Manage Linear state records #### `linear state get` - Anchor: `cmd-linear-state-get` - Mutates state: `no` - Supports dry run: `no` Get a Linear state Example: ```bash linear state get s1 ``` #### `linear state list` - Anchor: `cmd-linear-state-list` - Mutates state: `no` - Supports dry run: `no` List Linear state records Example: ```bash linear state list linear state list --team CMD ``` Flags: - `--include-archived` (bool): Include archived Linear records - `--team` (string): Team ref, key, name, or ID ### `linear team` - Anchor: `cmd-linear-team` - Mutates state: `no` - Supports dry run: `no` Manage Linear team records #### `linear team get` - Anchor: `cmd-linear-team-get` - Mutates state: `no` - Supports dry run: `no` Get a Linear team Example: ```bash linear team get t1 ``` #### `linear team list` - Anchor: `cmd-linear-team-list` - Mutates state: `no` - Supports dry run: `no` List Linear team records Example: ```bash linear team list linear team list --limit 10 ``` Flags: - `--include-archived` (bool): Include archived Linear records #### `linear team search` - Anchor: `cmd-linear-team-search` - Mutates state: `no` - Supports dry run: `no` Search Linear team records Example: ```bash linear team search linear team search --query platform ``` Flags: - `--include-archived` (bool): Include archived Linear records - `--query` (string): Search text ### `linear user` - Anchor: `cmd-linear-user` - Mutates state: `no` - Supports dry run: `no` Manage Linear user records #### `linear user get` - Anchor: `cmd-linear-user-get` - Mutates state: `no` - Supports dry run: `no` Get a Linear user Example: ```bash linear user get u1 ``` #### `linear user list` - Anchor: `cmd-linear-user-list` - Mutates state: `no` - Supports dry run: `no` List Linear user records Example: ```bash linear user list linear user list --limit 10 ``` Flags: - `--include-archived` (bool): Include archived Linear records #### `linear user search` - Anchor: `cmd-linear-user-search` - Mutates state: `no` - Supports dry run: `no` Search Linear user records Example: ```bash linear user search linear user search --query alice ``` Flags: - `--include-archived` (bool): Include archived Linear records - `--query` (string): Search text ### `linear version` - Anchor: `cmd-linear-version` - Mutates state: `no` - Supports dry run: `no` Show version information Example: ```bash linear version --help ``` ## Live Examples ### Auth #### Show auth status Shows the current auth state and next step. _Example metadata: provider state: local._ ```bash linear auth status ``` ```text Authenticated as kestrelphilip@gmail.com Next steps: - Issues: linear issue list --limit 10 - Teams: linear team list --limit 10 - Doctor: linear doctor - Capabilities: linear capabilities ``` ### Lifecycle #### Show capabilities Lists command surfaces and output modes. _Example metadata: provider state: local._ ```bash linear capabilities ``` ```text linear capabilities Resources: attachment, auth, capabilities, comment, config, cycle, doctor, issue, issue_label, label, profile, project, resolve, schema, state, team, user, version Machine output: --json, --jsonl Required scopes: comments:create, issues:create, read, write Next steps: - Scopes: linear capabilities --section scopes - Schema: linear schema - Contract: linear capabilities --json - Help: linear --help ``` ### Schemas #### Show schema overview Lists available schemas. _Example metadata: provider state: local._ ```bash linear schema ``` ```text linear schemas COMMAND DIR user.list output user.search input issue.list output issue.archive output comment.create output issue.archive input issue.unarchive input comment.update input state.get output label.get input comment.get output comment.delete output cycle.get output project.list input project.search output issue_label.remove output attachment.delete output label.list input project.get input attachment.update output comment.create input auth.login output issue.update input attachment.delete input label.list output issue.list input issue.search output issue.create input auth.refresh output resolve.get output user.list input state.list output issue.get input attachment.list output capabilities.describe output issue.create output issue_label.add output comment.list input comment.list output comment.update output attachment.update input auth.status output user.get output issue.update output attachment.list input attachment.get input user.search output cycle.list output project.list output attachment.create output cycle.list input issue.search input auth.logout output team.get input label.get output cycle.get input issue.get output team.list output state.get input project.search input comment.get input issue_label.add input team.list input project.get output issue.unarchive output attachment.create input auth.whoami output team.search input state.list input attachment.get output comment.delete input doctor.run output version.get output team.search output team.get output user.get input issue_label.remove input Next steps: - Issues: linear issue list --limit 10 - Teams: linear team list --limit 10 - Doctor: linear doctor - Capabilities: linear capabilities ```