linear-sdk-cli 0.8.2 → 0.9.0

package/skills/linear-sdk-cli/SKILL.md

@@ -122,6 +122,23 @@ The CLI supports distinct human, hosted-app, and personal-key lifecycles:
 
 Login associates the authenticated workspace with the discovered project config, or creates `.linear.toml` at the Git root (cwd outside Git). Use `--no-project` for credential-only login; JSON reports `projectConfigPath` or null. Credentials stay global. Workspace selection is `--workspace` → `LINEAR_WORKSPACE` → project config → optional global default. A sole stored workspace is automatic; multiple unselected workspaces prompt only interactively and fail in JSON/noninteractive mode. Login/adoption/logout never assign a new default. Existing legacy defaults remain valid because their original intent is unknown; `auth default` is an explicit convenience.
 
+When a workspace URL slug changes, use `linear auth rename <old-slug> <new-slug> --json`
+for an existing API-key profile. It validates the exact stored key's current organization/slug,
+ignores environment credentials, preserves storage/team/default metadata, and refuses destination
+collisions (including unlisted keyring records). Keyring moves require atomic create-only support
+(macOS Keychain). Linux Secret Service keyring entries are refused before changes; file-only profiles
+remain supported. API-key profiles have no historical organization ID; the unchanged stored key proves
+its organization, returned in `organization`. Never export the key or
+combine login/logout to rename it. If interrupted, repeat the same command to resume its non-secret
+recovery marker; do not log out, replace, or migrate either profile while recovery is pending.
+Project files stay unchanged: inspect `checkedProjectConfigs`, `projectConfigUpdates`, and
+`globalConfigUpdates`, then update the authorized selectors separately. Supply
+`--project-config /absolute/path/.linear.toml` to inspect additional known configs. Other repositories
+and `LINEAR_WORKSPACE` overrides require a separate check; discovery is not machine-wide.
+OAuth user/app profiles and dormant OAuth records are explicitly unsupported and left untouched:
+user refresh-token rotation needs coordination, and app token exchange has scope/revocation effects.
+The command performs no OAuth refresh, exchange, browser authorization, or revocation.
+
 An explicit credential flag overrides environment credentials. If both credential kinds occur at
 the same precedence level, the CLI fails rather than silently choosing an actor. Inspect resolution
 with `linear auth status`. `linear auth token` exports stored API keys only and never OAuth tokens.
@@ -135,6 +152,16 @@ forbidden errors include stable `error.details` with the required scope and reme
 
 ## Agent best practices
 
+Folder defaults: `linear config set project "My Project" --path .linear.toml` associates the
+current folder and descendants with a Linear project (name or UUID). Include `team` and
+`workspace` in that file when needed; discovery reads the nearest config without merging
+ancestor files. Omit `--path` to edit the discovered config, or create one at the Git root
+(cwd outside Git). `linear config show --json` reports `project` and `origins.project`.
+`issue create` / `issue new` uses the default; `--project` overrides it, a parent's project
+takes precedence over it, and `--no-project` suppresses config, parent, and template defaults.
+`LINEAR_PROJECT` overrides file defaults. List/search/update commands do not inherit this
+project selection. Remove the config's `project` line to clear the association.
+
 This CLI is built for non-interactive use. Follow these and it will never hang and
 always emit parseable output.
 
@@ -318,6 +345,40 @@ Lead with these two machine-readable commands:
   grep -n 'type Issue ' "${TMPDIR:-/tmp}/linear.graphql"
   ```
 
+### Releases and CI
+
+Use `release-pipeline list`, `release-stage list <pipeline>`, and `release list --pipeline <id|slug>`
+to inspect releases. Pipeline/release lookups accept UUIDs or API slugs, not display names.
+Releases require Business/Enterprise; successful schema introspection or an empty list does not
+prove mutation permission or plan eligibility. Preserve `feature_not_accessible`/`forbidden` errors.
+
+Native commands use ordinary CLI OAuth/API credentials. Pipeline access keys and
+`LINEAR_ACCESS_KEY` belong to the official [linear-release](https://github.com/linear/linear-release)
+CI tool; this CLI does not consume them or install/invoke that tool. Use the official tool for Git
+scanning, path filtering, revert handling and PR attribution. Native `release sync` takes explicit
+`--issue KEY-123[=FULL_SHA]` references and never scans the checkout.
+
+For scheduled releases, prepare with `release create --pipeline <id> --name <name>
+--release-version <version> --commit-sha <full-sha> --stage <planned-stage-id>`. Set exact membership
+with `release add-issue <release-id> <issue>`. `release update <id> --stage <stage-id>` edits an exact
+release; `release update-version --pipeline <id> --release-version <version> --stage <name>` can
+also attach repeated `--link Label=URL`. Freeze a started stage with `release-stage update <id>
+--frozen true` to exclude its releases from automated sync, while keeping one started stage unfrozen.
+
+`sync`, `update-version` and `complete` require a pipeline AND version; no latest fallback is used.
+Scheduled sync can label an unversioned started release or create a release; continuous sync creates
+a completed release immediately. Synced references accumulate; omission does not remove issues.
+Use `--reverted-issue` or `release remove-issue <id> <issue> --yes` for explicit removal.
+Complete only after separately authorized deployment/verification/observation gates pass. Completion
+and transitions to a completed stage may move open issues into another release according to the
+pipeline's rollover setting. `complete --commit-sha` preserves an existing SHA when targeting a
+version: set/verify it using create/update first. No command deploys code or proves verification.
+
+`release-note create --pipeline <id> --release <id> --body-file <path>` supports repeated release
+IDs or a paired `--from-release`/`--to-release` inclusive createdAt range, all in the same pipeline.
+Use file/stdin body input, inspect `release-note view`, and keep release-note deletion confirmation
+and exact membership removal explicit. Archive/trash and advanced operations remain under `api`.
+
 ## Available commands
 
 Generated from `linear commands --json` (run `bun run skill:docs` to refresh):
@@ -339,6 +400,7 @@ linear auth list
 linear auth login
 linear auth logout
 linear auth migrate
+linear auth rename
 linear auth status
 linear auth token
 linear auth whoami
@@ -498,6 +560,38 @@ linear project-update
 linear project-update create
 linear project-update list
 
+linear release
+linear release add-issue
+linear release complete
+linear release create
+linear release issues
+linear release links
+linear release list
+linear release remove-issue
+linear release sync
+linear release update
+linear release update-version
+linear release view
+
+linear release-note
+linear release-note create
+linear release-note delete
+linear release-note list
+linear release-note update
+linear release-note view
+
+linear release-pipeline
+linear release-pipeline create
+linear release-pipeline list
+linear release-pipeline update
+linear release-pipeline view
+
+linear release-stage
+linear release-stage create
+linear release-stage list
+linear release-stage update
+linear release-stage view
+
 linear roadmap
 linear roadmap create
 linear roadmap delete
@@ -570,6 +664,10 @@ prints the same). These are supplementary — `--help` on any command is authori
 - [project-label](references/project-label.md) — Manage project labels (distinct from issue labels)
 - [project-status](references/project-status.md) — Manage workspace project-status definitions
 - [project-update](references/project-update.md) — Post and list project status updates
+- [release](references/release.md) — Track releases, lifecycle and issue membership
+- [release-pipeline](references/release-pipeline.md) — Manage release pipelines
+- [release-stage](references/release-stage.md) — Manage release stages and freezing
+- [release-note](references/release-note.md) — Manage Markdown release notes
 - [roadmap](references/roadmap.md) — Work with roadmaps
 - [schema](references/schema.md) — Print the Linear GraphQL schema as SDL
 - [state](references/state.md) — Inspect workflow states

package/skills/linear-sdk-cli/references/auth.md

@@ -144,6 +144,37 @@ migrated: string[]
 path: string
 ```
 
+### `linear auth rename`
+
+Rename a stored API-key profile after its Linear workspace URL slug changes
+
+```
+linear auth rename [options] <old-slug> <new-slug>
+```
+
+| Option                        | Description                                                                |
+| ----------------------------- | -------------------------------------------------------------------------- |
+| `--project-config <paths...>` | also inspect these project configs for old workspace selectors (read-only) |
+
+**Output (`--json`)**: a receipt object
+
+```text
+success: boolean
+from: string
+workspace: string
+credentialType: string
+organization: {id: string, name: string, urlKey: string}
+path: string
+storage: string
+team: string | null
+defaultWorkspace: string | null
+referenceCredentialsPath: string | null
+checkedProjectConfigs: string[]
+projectConfigUpdates: Array<{path: string, key: string, from: string, to: string}>
+globalConfigUpdates: Array<{path: string, key: string, from: string, to: string}>
+otherProjects: string
+```
+
 ### `linear auth status`
 
 Show where the active credential is resolved from (value redacted)

package/skills/linear-sdk-cli/references/config.md

@@ -25,8 +25,9 @@ credentialWorkspace: string | null
 workspaceProfile: string | null
 team: string | null
 workspace: string | null
+project: string | null
 sort: string
-origins: {team: {source: string, path?: string, key?: string, workspace?: string}, workspace: {source: string, path?: string, key?: string, workspace?: string}, sort: {source: string, path?: string, key?: string, workspace?: string}}
+origins: {team: {source: string, path?: string, key?: string, workspace?: string}, workspace: {source: string, path?: string, key?: string, workspace?: string}, project: {source: string, path?: string, key?: string, workspace?: string}, sort: {source: string, path?: string, key?: string, workspace?: string}}
 userConfigPath: string
 projectConfigPath: string | null
 globalConfigPath: string | null
@@ -40,12 +41,13 @@ Write a project .linear.toml (at the git root, or here outside a repository)
 linear config init [options]
 ```
 
-| Option           | Description                                                        |
-| ---------------- | ------------------------------------------------------------------ |
-| `--team <key>`   | default team key (otherwise chosen from a list)                    |
-| `--sort <order>` | default issue-list sort (priority \| manual \| updated \| created) |
-| `--path <file>`  | write this file instead of <git root>/.linear.toml                 |
-| `--force`        | overwrite an existing file                                         |
+| Option                 | Description                                                        |
+| ---------------------- | ------------------------------------------------------------------ |
+| `--team <key>`         | default team key (otherwise chosen from a list)                    |
+| `--project <name\|id>` | default Linear project for new issues                              |
+| `--sort <order>`       | default issue-list sort (priority \| manual \| updated \| created) |
+| `--path <file>`        | write this file instead of <git root>/.linear.toml                 |
+| `--force`              | overwrite an existing file                                         |
 
 **Output (`--json`)**: a receipt object
 
@@ -54,11 +56,12 @@ success: boolean
 path: string
 team: string
 sort?: string
+project?: string
 ```
 
 ### `linear config set`
 
-Set one project or user setting (team, workspace, sort)
+Set one project or user setting (team, workspace, sort, project)
 
 ```
 linear config set [options] <key> <value>
@@ -98,8 +101,9 @@ credentialWorkspace: string | null
 workspaceProfile: string | null
 team: string | null
 workspace: string | null
+project: string | null
 sort: string
-origins: {team: {source: string, path?: string, key?: string, workspace?: string}, workspace: {source: string, path?: string, key?: string, workspace?: string}, sort: {source: string, path?: string, key?: string, workspace?: string}}
+origins: {team: {source: string, path?: string, key?: string, workspace?: string}, workspace: {source: string, path?: string, key?: string, workspace?: string}, project: {source: string, path?: string, key?: string, workspace?: string}, sort: {source: string, path?: string, key?: string, workspace?: string}}
 userConfigPath: string
 projectConfigPath: string | null
 globalConfigPath: string | null

package/skills/linear-sdk-cli/references/issue.md

@@ -378,8 +378,9 @@ linear issue create [options]
 | `-s, --state <name>`        | workflow state name or type                                                                          |
 | `-P, --priority <0-4>`      | priority                                                                                             |
 | `-l, --label <name>`        | label (repeatable / comma-separated)                                                                 |
-| `-p, --project <name>`      | project name or id                                                                                   |
-| `--milestone <name>`        | project milestone (requires --project)                                                               |
+| `-p, --project <name>`      | project name or id (overrides the configured default)                                                |
+| `--no-project`              | create outside any project, ignoring configured and parent defaults                                  |
+| `--milestone <name>`        | project milestone (requires an explicit, configured, or parent project)                              |
 | `--cycle <n>`               | cycle number, name, id, or 'current'                                                                 |
 | `--estimate <n>`            | estimate points                                                                                      |
 | `--parent <id>`             | parent issue id (the sub-issue joins the parent's project unless --project says otherwise)           |

package/skills/linear-sdk-cli/references/release-note.md

@@ -0,0 +1,148 @@
+# linear release-note
+
+> Manage Markdown notes covering one or more releases
+
+_Generated from `linear commands --json`. `linear release-note --help` (or `<subcommand> --help`) is authoritative._
+
+Every command also accepts the global flags `-j/--json`, `--no-input`, `-y/--yes`, `-q/--quiet`, `--workspace <slug>`, `--api-key <key>`, `--access-token <token>`, `-t/--team <key>`, `-n/--limit <n>`, `--all`, `-f/--fields <a,b,c>`, `--no-ansi` (alias `--no-color`), and `--debug`. Only command-specific options are listed below.
+
+### `linear release-note`
+
+Manage Markdown notes covering one or more releases
+
+```
+linear release-note [options]
+```
+
+### `linear release-note create`
+
+Create a note for explicit releases or an inclusive createdAt range
+
+```
+linear release-note create [options]
+```
+
+| Option                  | Description                                    |
+| ----------------------- | ---------------------------------------------- |
+| `--title <title>`       | release note title                             |
+| `--body <text>`         | release note body (Markdown)                   |
+| `--body-file <path>`    | read Markdown from file ('-' for stdin)        |
+| `--release <id>`        | covered release UUID or slug (repeatable)      |
+| `--from-release <id>`   | oldest release in an inclusive createdAt range |
+| `--to-release <id>`     | newest release in the inclusive range          |
+| `--pipeline <id\|slug>` | pipeline UUID or slug                          |
+
+**Output (`--json`)**: a receipt object
+
+```text
+id: string
+title: string | null
+url: string
+pipeline: {id: string, name: string}
+releaseCount: number
+firstRelease: {id: string, name: string} | null
+lastRelease: {id: string, name: string} | null
+generationStatus: string | null
+archivedAt: string | null
+content: string | null
+```
+
+### `linear release-note delete`
+
+Delete a release note by UUID or slug
+
+```
+linear release-note delete [options] <id>
+```
+
+**Output (`--json`)**: a receipt object
+
+```text
+id: string
+deleted: boolean
+```
+
+### `linear release-note list`
+
+List release notes with optional pipeline/release filters
+
+Aliases: `ls`
+
+```
+linear release-note list [options]
+```
+
+| Option                  | Description                            |
+| ----------------------- | -------------------------------------- |
+| `--pipeline <id\|slug>` | filter by pipeline UUID or slug        |
+| `--release <id>`        | filter by covered release UUID or slug |
+| `--include-archived`    | include archived notes                 |
+
+**Output (`--json`)**: a bare array of objects
+
+```text
+id: string
+title: string | null
+url: string
+pipeline: {id: string, name: string}
+releaseCount: number
+firstRelease: {id: string, name: string} | null
+lastRelease: {id: string, name: string} | null
+generationStatus: string | null
+archivedAt: string | null
+```
+
+### `linear release-note update`
+
+Update a note's title, Markdown, or covered releases
+
+```
+linear release-note update [options] <id>
+```
+
+| Option                | Description                                    |
+| --------------------- | ---------------------------------------------- |
+| `--title <title>`     | release note title                             |
+| `--body <text>`       | release note body (Markdown)                   |
+| `--body-file <path>`  | read Markdown from file ('-' for stdin)        |
+| `--release <id>`      | covered release UUID or slug (repeatable)      |
+| `--from-release <id>` | oldest release in an inclusive createdAt range |
+| `--to-release <id>`   | newest release in the inclusive range          |
+
+**Output (`--json`)**: a receipt object
+
+```text
+id: string
+title: string | null
+url: string
+pipeline: {id: string, name: string}
+releaseCount: number
+firstRelease: {id: string, name: string} | null
+lastRelease: {id: string, name: string} | null
+generationStatus: string | null
+archivedAt: string | null
+content: string | null
+```
+
+### `linear release-note view`
+
+Show a release note and its Markdown body by UUID or slug
+
+```
+linear release-note view [options] <id>
+```
+
+**Output (`--json`)**: a bare object
+
+```text
+id: string
+title: string | null
+url: string
+pipeline: {id: string, name: string}
+releaseCount: number
+firstRelease: {id: string, name: string} | null
+lastRelease: {id: string, name: string} | null
+generationStatus: string | null
+archivedAt: string | null
+content: string | null
+```

package/skills/linear-sdk-cli/references/release-pipeline.md

@@ -0,0 +1,137 @@
+# linear release-pipeline
+
+> Manage release pipelines (Business/Enterprise)
+
+_Generated from `linear commands --json`. `linear release-pipeline --help` (or `<subcommand> --help`) is authoritative._
+
+Every command also accepts the global flags `-j/--json`, `--no-input`, `-y/--yes`, `-q/--quiet`, `--workspace <slug>`, `--api-key <key>`, `--access-token <token>`, `-t/--team <key>`, `-n/--limit <n>`, `--all`, `-f/--fields <a,b,c>`, `--no-ansi` (alias `--no-color`), and `--debug`. Only command-specific options are listed below.
+
+### `linear release-pipeline`
+
+Manage release pipelines (Business/Enterprise)
+
+```
+linear release-pipeline [options]
+```
+
+### `linear release-pipeline create`
+
+Create a pipeline with default stages
+
+```
+linear release-pipeline create [options]
+```
+
+| Option                           | Description                                                                |
+| -------------------------------- | -------------------------------------------------------------------------- |
+| `--name <name>`                  | pipeline name                                                              |
+| `--type <type>`                  | pipeline type                                                              |
+| `--production <boolean>`         | whether pipeline targets production (true\|false)                          |
+| `--auto-release-notes <boolean>` | automatically generate notes on completion (true\|false)                   |
+| `--rollover-issues <boolean>`    | move open issues to the next scheduled release on completion (true\|false) |
+| `--include-path <glob>`          | replace path patterns with these globs (repeatable)                        |
+| `--clear-paths`                  | clear all path filters                                                     |
+| `--team-id <uuid>`               | replace associated teams with these UUIDs (repeatable)                     |
+| `--clear-teams`                  | clear team associations                                                    |
+
+**Output (`--json`)**: a receipt object
+
+```text
+id: string
+name: string
+slugId: string
+type: string
+url: string
+isProduction: boolean
+autoGenerateReleaseNotesOnCompletion: boolean
+rolloverIssuesOnCompletion: boolean
+includePathPatterns: string[]
+archivedAt: string | null
+```
+
+### `linear release-pipeline list`
+
+List workspace release pipelines
+
+Aliases: `ls`
+
+```
+linear release-pipeline list [options]
+```
+
+| Option               | Description                |
+| -------------------- | -------------------------- |
+| `--include-archived` | include archived pipelines |
+
+**Output (`--json`)**: a bare array of objects
+
+```text
+id: string
+name: string
+slugId: string
+type: string
+url: string
+isProduction: boolean
+autoGenerateReleaseNotesOnCompletion: boolean
+rolloverIssuesOnCompletion: boolean
+includePathPatterns: string[]
+archivedAt: string | null
+```
+
+### `linear release-pipeline update`
+
+Update pipeline settings by UUID or slug
+
+```
+linear release-pipeline update [options] <id>
+```
+
+| Option                           | Description                                                                |
+| -------------------------------- | -------------------------------------------------------------------------- |
+| `--name <name>`                  | pipeline name                                                              |
+| `--type <type>`                  | pipeline type                                                              |
+| `--production <boolean>`         | whether pipeline targets production (true\|false)                          |
+| `--auto-release-notes <boolean>` | automatically generate notes on completion (true\|false)                   |
+| `--rollover-issues <boolean>`    | move open issues to the next scheduled release on completion (true\|false) |
+| `--include-path <glob>`          | replace path patterns with these globs (repeatable)                        |
+| `--clear-paths`                  | clear all path filters                                                     |
+| `--team-id <uuid>`               | replace associated teams with these UUIDs (repeatable)                     |
+| `--clear-teams`                  | clear team associations                                                    |
+
+**Output (`--json`)**: a receipt object
+
+```text
+id: string
+name: string
+slugId: string
+type: string
+url: string
+isProduction: boolean
+autoGenerateReleaseNotesOnCompletion: boolean
+rolloverIssuesOnCompletion: boolean
+includePathPatterns: string[]
+archivedAt: string | null
+```
+
+### `linear release-pipeline view`
+
+Show pipeline settings by UUID or slug
+
+```
+linear release-pipeline view [options] <id>
+```
+
+**Output (`--json`)**: a bare object
+
+```text
+id: string
+name: string
+slugId: string
+type: string
+url: string
+isProduction: boolean
+autoGenerateReleaseNotesOnCompletion: boolean
+rolloverIssuesOnCompletion: boolean
+includePathPatterns: string[]
+archivedAt: string | null
+```

package/skills/linear-sdk-cli/references/release-stage.md

@@ -0,0 +1,121 @@
+# linear release-stage
+
+> Manage release stages and freeze scheduled release scope
+
+_Generated from `linear commands --json`. `linear release-stage --help` (or `<subcommand> --help`) is authoritative._
+
+Every command also accepts the global flags `-j/--json`, `--no-input`, `-y/--yes`, `-q/--quiet`, `--workspace <slug>`, `--api-key <key>`, `--access-token <token>`, `-t/--team <key>`, `-n/--limit <n>`, `--all`, `-f/--fields <a,b,c>`, `--no-ansi` (alias `--no-color`), and `--debug`. Only command-specific options are listed below.
+
+### `linear release-stage`
+
+Manage release stages and freeze scheduled release scope
+
+```
+linear release-stage [options]
+```
+
+### `linear release-stage create`
+
+Create a stage in a release pipeline
+
+```
+linear release-stage create [options]
+```
+
+| Option                  | Description                                                  |
+| ----------------------- | ------------------------------------------------------------ |
+| `--name <name>`         | stage name                                                   |
+| `--color <hex>`         | six-digit HEX color                                          |
+| `--position <number>`   | stage ordering position                                      |
+| `--frozen <boolean>`    | exclude this started stage from automated sync (true\|false) |
+| `--pipeline <id\|slug>` | pipeline UUID or slug                                        |
+| `--type <type>`         | lifecycle stage type                                         |
+
+**Output (`--json`)**: a receipt object
+
+```text
+id: string
+name: string
+type: string
+color: string
+position: number
+frozen: boolean
+pipeline: {id: string, name: string}
+archivedAt: string | null
+```
+
+### `linear release-stage list`
+
+List stages for a pipeline UUID or slug
+
+Aliases: `ls`
+
+```
+linear release-stage list [options] <pipeline>
+```
+
+| Option               | Description             |
+| -------------------- | ----------------------- |
+| `--include-archived` | include archived stages |
+
+**Output (`--json`)**: a bare array of objects
+
+```text
+id: string
+name: string
+type: string
+color: string
+position: number
+frozen: boolean
+pipeline: {id: string, name: string}
+archivedAt: string | null
+```
+
+### `linear release-stage update`
+
+Update name, color, order, or frozen state by stage UUID
+
+```
+linear release-stage update [options] <id>
+```
+
+| Option                | Description                                                  |
+| --------------------- | ------------------------------------------------------------ |
+| `--name <name>`       | stage name                                                   |
+| `--color <hex>`       | six-digit HEX color                                          |
+| `--position <number>` | stage ordering position                                      |
+| `--frozen <boolean>`  | exclude this started stage from automated sync (true\|false) |
+
+**Output (`--json`)**: a receipt object
+
+```text
+id: string
+name: string
+type: string
+color: string
+position: number
+frozen: boolean
+pipeline: {id: string, name: string}
+archivedAt: string | null
+```
+
+### `linear release-stage view`
+
+Show a release stage by UUID
+
+```
+linear release-stage view [options] <id>
+```
+
+**Output (`--json`)**: a bare object
+
+```text
+id: string
+name: string
+type: string
+color: string
+position: number
+frozen: boolean
+pipeline: {id: string, name: string}
+archivedAt: string | null
+```