linear-sdk-cli 0.8.3 → 0.9.0

package/CHANGELOG.md

@@ -4,6 +4,13 @@ Release Please generates this file from Conventional Commits. Feature and fix pu
 not edit it directly; their squash-commit titles are the release-note source of truth. This project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.9.0](https://github.com/zhendalf/linear-sdk-cli/compare/v0.8.3...v0.9.0) (2026-10-22)
+
+### Features
+
+- add native release commands and folder project defaults ([#97](https://github.com/zhendalf/linear-sdk-cli/issues/97)) ([e382f52](https://github.com/zhendalf/linear-sdk-cli/commit/e382f52a8146ede0d9268d6c6aa557f9836e9274))
+- **auth:** add resumable workspace API-key profile rename ([#95](https://github.com/zhendalf/linear-sdk-cli/issues/95)) ([9297b16](https://github.com/zhendalf/linear-sdk-cli/commit/9297b16e00928441124bffe291a0567e86c59f09))
+
 ## [0.8.3](https://github.com/zhendalf/linear-sdk-cli/compare/v0.8.2...v0.8.3) (2026-10-19)
 
 ### Bug Fixes

package/COVERAGE.md

@@ -4,18 +4,19 @@ Generated by `bun run audit:coverage`. Total LinearClient members: **481**.
 
 | Status   | Count | Meaning                                         |
 | -------- | ----- | ----------------------------------------------- |
-| curated  | 107   | Has a first-class CLI command                   |
+| curated  | 128   | Has a first-class CLI command                   |
 | raw-only | 146   | Reachable via `linear api` (no bespoke command) |
-| excluded | 228   | Out of scope (admin/integration/SDK plumbing)   |
+| excluded | 207   | Out of scope (admin/integration/SDK plumbing)   |
 
 Every member is classified — CI fails otherwise. `raw-only` members are still
 100% reachable through the raw GraphQL escape hatch; they simply lack a tailored command.
 
 ## Curated field capabilities
 
+- Release projections — `ReleasePipeline.stages`, `Release.issues/links`, and release-note document content are selected through the authenticated SDK GraphQL transport, with stable command JSON shapes and offline schema validation.
 - Issue delegation (Developer Preview) — `Issue.delegate`, `IssueCreateInput.delegateId`, `IssueUpdateInput.delegateId`, and eligible agent-user fields are covered by `issue delegate` and the delegation options on `issue create`/`issue update`.
 
-## Curated (107)
+## Curated (128)
 
 - `agentSession` — issue
 - `agentSessions` — issue
@@ -41,9 +42,14 @@ Every member is classified — CI fails otherwise. `raw-only` members are still
 - `createIssue` — issue
 - `createIssueLabel` — label
 - `createIssueRelation` — issue
+- `createIssueToRelease` — release
 - `createProject` — project
 - `createProjectMilestone` — milestone
 - `createProjectUpdate` — project-update
+- `createRelease` — release
+- `createReleaseNote` — release-note
+- `createReleasePipeline` — release-pipeline
+- `createReleaseStage` — release-stage
 - `createRoadmap` — roadmap
 - `createTeam` — team
 - `createWebhook` — webhook
@@ -63,6 +69,7 @@ Every member is classified — CI fails otherwise. `raw-only` members are still
 - `deleteIssueRelation` — issue
 - `deleteProject` — project
 - `deleteProjectMilestone` — milestone
+- `deleteReleaseNote` — release-note
 - `deleteRoadmap` — roadmap
 - `deleteTeam` — team
 - `deleteWebhook` — webhook
@@ -82,6 +89,7 @@ Every member is classified — CI fails otherwise. `raw-only` members are still
 - `issueRelations` — issue
 - `issueSearch` — issue
 - `issueSubscribe` — issue
+- `issueToReleaseDeleteByIssueAndRelease` — release
 - `issueUnsubscribe` — issue
 - `issues` — issue
 - `notification` — notification
@@ -96,6 +104,16 @@ Every member is classified — CI fails otherwise. `raw-only` members are still
 - `projectStatuses` — project
 - `projectUpdates` — project-update
 - `projects` — project
+- `release` — release
+- `releaseComplete` — release
+- `releaseNote` — release-note
+- `releaseNotes` — release-note
+- `releasePipeline` — release-pipeline
+- `releasePipelines` — release-pipeline
+- `releaseStage` — release-stage
+- `releaseSync` — release
+- `releaseUpdateByPipeline` — release
+- `releases` — release
 - `roadmap` — roadmap
 - `roadmaps` — roadmap
 - `searchIssues` — issue
@@ -114,6 +132,10 @@ Every member is classified — CI fails otherwise. `raw-only` members are still
 - `updateNotification` — notification
 - `updateProject` — project
 - `updateProjectMilestone` — milestone
+- `updateRelease` — release
+- `updateReleaseNote` — release-note
+- `updateReleasePipeline` — release-pipeline
+- `updateReleaseStage` — release-stage
 - `updateRoadmap` — roadmap
 - `updateTeam` — team
 - `updateWebhook` — webhook
@@ -125,7 +147,7 @@ Every member is classified — CI fails otherwise. `raw-only` members are still
 - `workflowState` — state
 - `workflowStates` — state
 
-## Excluded (228)
+## Excluded (207)
 
 - `agentActivities` — specialized/raw api only
 - `agentActivity` — specialized/raw api only
@@ -161,14 +183,9 @@ Every member is classified — CI fails otherwise. `raw-only` members are still
 - `createIntegrationGithubCommit` — integration/import (raw api only)
 - `createIntegrationTemplate` — integration/import (raw api only)
 - `createIntegrationsSettings` — integration/import (raw api only)
-- `createIssueToRelease` — specialized/raw api only
 - `createNotificationSubscription` — specialized/raw api only
 - `createOrganizationInvite` — admin/enterprise (raw api only)
 - `createPushSubscription` — specialized/raw api only
-- `createRelease` — specialized/raw api only
-- `createReleaseNote` — specialized/raw api only
-- `createReleasePipeline` — specialized/raw api only
-- `createReleaseStage` — specialized/raw api only
 - `createTemplate` — specialized/raw api only
 - `createTimeSchedule` — specialized/raw api only
 - `createTriageResponsibility` — specialized/raw api only
@@ -207,7 +224,6 @@ Every member is classified — CI fails otherwise. `raw-only` members are still
 - `deleteOrganizationInvite` — admin/enterprise (raw api only)
 - `deletePushSubscription` — specialized/raw api only
 - `deleteRelease` — specialized/raw api only
-- `deleteReleaseNote` — specialized/raw api only
 - `deleteReleasePipeline` — specialized/raw api only
 - `deleteTemplate` — specialized/raw api only
 - `deleteTimeSchedule` — specialized/raw api only
@@ -276,7 +292,6 @@ Every member is classified — CI fails otherwise. `raw-only` members are still
 - `issueImportProcess` — integration/import (raw api only)
 - `issueTitleSuggestionFromCustomerRequest` — specialized/raw api only
 - `issueToRelease` — specialized/raw api only
-- `issueToReleaseDeleteByIssueAndRelease` — specialized/raw api only
 - `issueToReleases` — specialized/raw api only
 - `latestReleaseByAccessKey` — specialized/raw api only
 - `logout` — auth/session flows (out of scope)
@@ -291,22 +306,12 @@ Every member is classified — CI fails otherwise. `raw-only` members are still
 - `pushSubscriptionTest` — specialized/raw api only
 - `rateLimitStatus` — SDK plumbing
 - `recentReleasesByAccessKey` — specialized/raw api only
-- `release` — specialized/raw api only
-- `releaseComplete` — specialized/raw api only
 - `releaseCompleteByAccessKey` — specialized/raw api only
-- `releaseNote` — specialized/raw api only
-- `releaseNotes` — specialized/raw api only
-- `releasePipeline` — specialized/raw api only
 - `releasePipelineByAccessKey` — specialized/raw api only
-- `releasePipelines` — specialized/raw api only
 - `releaseSearch` — specialized/raw api only
-- `releaseStage` — specialized/raw api only
 - `releaseStages` — specialized/raw api only
-- `releaseSync` — specialized/raw api only
 - `releaseSyncByAccessKey` — specialized/raw api only
-- `releaseUpdateByPipeline` — specialized/raw api only
 - `releaseUpdateByPipelineByAccessKey` — specialized/raw api only
-- `releases` — specialized/raw api only
 - `samlTokenUserAccountAuth` — auth/session flows (out of scope)
 - `semanticSearch` — specialized/raw api only
 - `slaConfigurations` — specialized/raw api only
@@ -341,10 +346,6 @@ Every member is classified — CI fails otherwise. `raw-only` members are still
 - `updateIntegrationsSettings` — integration/import (raw api only)
 - `updateIssueImport` — integration/import (raw api only)
 - `updateNotificationSubscription` — specialized/raw api only
-- `updateRelease` — specialized/raw api only
-- `updateReleaseNote` — specialized/raw api only
-- `updateReleasePipeline` — specialized/raw api only
-- `updateReleaseStage` — specialized/raw api only
 - `updateTemplate` — specialized/raw api only
 - `updateTimeSchedule` — specialized/raw api only
 - `updateTriageResponsibility` — specialized/raw api only

package/README.md

@@ -298,6 +298,45 @@ Successful browser, app, and API-key login also save `workspace = "<authenticate
 
 Global defaults are optional: login, credential adoption, and logout never choose a new one. Use `linear auth default <slug>` to explicitly select a global fallback. Removing that workspace clears its default without promoting another workspace. Existing defaults, including defaults imported from the reference CLI, are preserved on upgrade because older files cannot distinguish a user choice from an automatically assigned default. To opt out of a legacy default, remove the top-level `default_workspace` from the user config and, if present, `default` from the reference CLI's `credentials.toml`; retain the workspace entries.
 
+After a workspace URL slug changes, migrate its stored **API-key profile** with:
+
+```sh
+linear auth rename old-workspace new-workspace --json
+# Or include additional known project configs without editing them:
+linear auth rename old-workspace new-workspace --project-config /path/to/another/.linear.toml
+```
+
+The command validates the exact stored key against Linear's current organization/slug, preserving
+the credential, storage type, profile team, user workspace/default, and the reference CLI's shared
+keyring list/default. It ignores environment credentials and refuses credential flags. API-key
+profiles do not contain a historical organization ID; the unchanged key proves its own organization,
+which is returned in the result. Configured destinations and unlisted keyring entries are collisions,
+even if they contain the same key. Nothing is revoked, exported, or placed on argv.
+Keyring moves use an atomic create-only operation on macOS Keychain, so another client's
+destination created during the rename cannot be replaced. The Linux `secret-tool` backend lacks
+this operation and keyring-backed renames are refused before changes; file-only profiles remain
+supported when no source keyring entry needs moving.
+
+Project files are never edited. JSON reports `checkedProjectConfigs` and `projectConfigUpdates`
+with exact paths and old/new workspace values; human output lists the same required edits. Discovery
+covers the active project config plus explicit `--project-config` paths. Check other repositories
+separately, update their `workspace` selectors, and update `LINEAR_WORKSPACE` overrides. The reference
+CLI's global `linear.toml` selector, if affected, is reported in `globalConfigUpdates` for manual editing.
+
+If storage fails or the process stops partway through, repeat **the same rename command**. A
+non-secret `api_key_profile_rename` marker in the private user config reserves the destination and
+records recovery progress. The source is kept until a verified destination and committed metadata
+exist. Recovery checks for conflicting changes and resumes the remaining steps. Do not log out,
+replace, or migrate either profile while recovery is pending. Fix the reported store/permission
+problem, then retry; do not delete the recovery marker or print credential-store contents.
+
+OAuth user and app profiles (including dormant keyring records) are refused before validation or
+mutation. User sessions have rotating refresh tokens and require coordination with in-flight
+refreshes; app profiles contain organization-bound client credentials, and token exchanges with
+different scopes can revoke existing app tokens. This command does not refresh, exchange, revoke,
+or rename either OAuth lifecycle. It does not require browser authorization. See Linear's
+[OAuth lifecycle documentation](https://linear.app/developers/oauth-2-0-authentication).
+
 If revocation is intentionally unavailable, `auth logout --local-only` removes only local state.
 If browser login temporarily superseded an existing personal API-key profile for that workspace,
 OAuth logout preserves and reactivates the API key instead of deleting it.
@@ -484,6 +523,104 @@ linear cv results 01234567-89ab-cdef-0123-456789abcdef --json
 # [{"type":"issue","id":"…","identifier":"ENG-42","name":"Fix login","url":"…"}]
 ```
 
+### Releases
+
+`release`, `release-pipeline`, `release-stage`, and `release-note` provide native release tracking.
+Linear currently requires a [Business or Enterprise workspace](https://linear.app/docs/releases.md);
+Business supports up to 15 pipelines. Schema visibility or an empty list does not establish
+entitlement to create pipelines, or permission to change them. Linear enforces plan, role, team,
+and credential permissions; the CLI preserves `feature_not_accessible` and `forbidden` errors.
+
+These commands use the CLI's usual OAuth or personal API credentials and `--workspace` selection.
+Pipeline **access keys** are separate credentials for the official
+[`linear-release`](https://github.com/linear/linear-release) CI tool. Do not put a pipeline key in
+`LINEAR_API_KEY` or `LINEAR_ACCESS_TOKEN`. This CLI does not consume `LINEAR_ACCESS_KEY`, create
+pipeline keys, or invoke/install the official tool automatically.
+
+```sh
+linear release-pipeline list --json
+linear release-pipeline view production --json       # UUID or API slug; not display name
+linear release-stage list production --all --json
+linear release list --pipeline production --stage-type started --json
+linear release view RELEASE_ID --json                # release UUID or slug
+linear release issues RELEASE_ID --all --json
+linear release links RELEASE_ID --json
+```
+
+Create a pipeline explicitly as `scheduled` or `continuous`. Creation includes Linear's default
+stages. Add further `started` stages for verification/observation, or rename/reorder the defaults:
+
+```sh
+linear release-pipeline create --name Production --type scheduled --json
+linear release-pipeline update PIPELINE_ID --rollover-issues false --json
+linear release-stage create --pipeline PIPELINE_ID --name Observe --type started \
+  --color '#5e6ad2' --position 3 --frozen true --json
+linear release-stage update STAGE_ID --frozen false --json
+```
+
+Stage types are immutable. Only `started` stages can be frozen, and Linear requires at least one
+unfrozen started stage. Freezing excludes releases in that stage from automated sync; it is not a
+deployment approval or a lock on manual membership edits. Pipeline updates support explicit
+`true|false` for production, automatic notes, and issue rollover. Repeated `--include-path` and
+`--team-id` replace the corresponding collections; `--clear-paths` and `--clear-teams` clear them.
+Team associations use UUIDs, not the global default `--team`.
+
+For a scheduled rollout, create the release with a full commit SHA, explicit version and stage,
+then add the exact issue scope. `release create` otherwise defaults to a started stage on scheduled
+pipelines and a completed stage on continuous pipelines:
+
+```sh
+linear release create --pipeline PIPELINE_ID --name 'Release 1.2.3' \
+  --release-version 1.2.3 --commit-sha "$approved_sha" --stage PLANNED_STAGE_ID \
+  --target-date 2026-10-30 --description-file release-plan.md --json
+linear release add-issue RELEASE_ID ENG-42 --json
+linear release update RELEASE_ID --stage VERIFY_STAGE_ID --json
+linear release-note create --pipeline PIPELINE_ID --release RELEASE_ID \
+  --title 'Verification' --body-file verification.md --json
+```
+
+`release update <id>` edits that exact release, including SHA/version/dates or a stage UUID from
+the same pipeline. `release update-version`, `sync`, and `complete` require **both** `--pipeline`
+and `--release-version`; they never implicitly pick the latest release. `update-version` accepts a
+stage **name**, matched by Linear, and attaches links without changing the version:
+
+```sh
+linear release update-version --pipeline PIPELINE_ID --release-version 1.2.3 \
+  --stage Observe --link "CI=https://ci.example/run/123" --json
+# Only after the external deployment, verification and observation gates pass:
+linear release complete --pipeline PIPELINE_ID --release-version 1.2.3 \
+  --link "GitHub=https://github.com/acme/app/releases/tag/v1.2.3" --json
+```
+
+Completion records Linear lifecycle state; it does not deploy, enforce service ordering, check
+approvals, verify a running revision, or wait for observation. Completing a scheduled release may
+move its open issues into the next release (creating one if needed), depending on pipeline settings.
+When `complete --commit-sha` targets a version, Linear preserves an existing stored SHA. Set and
+verify the intended SHA with `create`/`update` first. Stage transitions through `update` also trigger
+Linear's lifecycle behavior, including rollover on completion.
+
+For explicit, already-attributed data, `release sync --pipeline PIPELINE_ID --release-version 1.2.3
+--commit-sha FULL_SHA --issue ENG-42 --issue ENG-43=OTHER_FULL_SHA` calls Linear's native sync API.
+It does not scan Git. References accumulate; omitted issues are not removed. `--reverted-issue`
+removes reverted attribution, and `release remove-issue RELEASE_ID ENG-42 --yes` removes exact
+membership. Scheduled sync can assign the version to an unversioned started release or create a
+release; continuous sync creates/completes a release immediately. Use sync at the appropriate point
+in your deployment process, and read the returned release ID, version, SHA and stage.
+
+Use the official `linear-release` when you need commit-range scanning, path/subject filters,
+revert detection, branch/PR attribution, and pipeline-key CI authentication. It can work alongside
+this CLI against the same pipeline; pass the same explicit release version. Native commands are
+useful for preparation, exact membership, management, inspection, and subsequent lifecycle steps.
+No Git attribution implementation or additional runtime dependency is duplicated here.
+
+Release notes can cover repeated `--release <id>` values, or an inclusive **createdAt** range using
+both `--from-release` and `--to-release`. These shapes are mutually exclusive and all releases must
+belong to the note's pipeline. `release-note update` changes title, Markdown or scope; delete needs
+confirmation (`--yes` noninteractively). Use `--body-file -` or `--description-file -` for stdin.
+List commands emit bare arrays, views and mutations emit objects, and errors remain JSON on stderr.
+`linear commands release sync --json` exposes options and output fields without credentials.
+Archive/trash operations and other advanced fields remain available through `linear api`.
+
 ## Command overview
 
 Every group has `--help` with full options and (for the busy ones) an Examples section. Aliases
@@ -498,6 +635,10 @@ are shown in parentheses. For a machine-readable tree of _every_ command, run
 | **`project-update`** (`pu`)    | `create` · `list` (project status updates, with `--health`)                                                                                                                                                                                                                                      |
 | **`milestone`** (`m`)          | `list` · `view` · `create` · `update` · `delete`                                                                                                                                                                                                                                                 |
 | **`cycle`** (`c`)              | `list` · `view` · `current` · `create` · `update`                                                                                                                                                                                                                                                |
+| **`release`**                  | `list` · `view` · `create` · `update` · `sync` · `update-version` · `complete` · `issues` · `links` · `add-issue` · `remove-issue`                                                                                                                                                               |
+| **`release-pipeline`**         | `list` · `view` · `create` · `update`                                                                                                                                                                                                                                                            |
+| **`release-stage`**            | `list` · `view` · `create` · `update`                                                                                                                                                                                                                                                            |
+| **`release-note`**             | `list` · `view` · `create` · `update` · `delete`                                                                                                                                                                                                                                                 |
 | **`user`** (`u`)               | `list` · `view` · `me`                                                                                                                                                                                                                                                                           |
 | **`label`** (`lb`)             | `list` · `create` · `update` · `delete`                                                                                                                                                                                                                                                          |
 | **`state`** (`st`)             | `list` · `view` (workflow states)                                                                                                                                                                                                                                                                |
@@ -556,6 +697,11 @@ resolver semantics are designed, rather than acquiring a silent partial implemen
 | `attachment list`                                      | `Issue.attachments`                           | yes            | not exposed                                    | not exposed                   |
 | `comment list`, `issue comment list`, `issue comments` | `Issue.comments`                              | yes            | not exposed                                    | not exposed                   |
 | `cycle list`, `team cycles`                            | `Team.cycles`                                 | yes            | not exposed                                    | not exposed                   |
+| `release list`                                         | `Query.releases`                              | yes            | `--include-archived`                           | `archivedAt`                  |
+| `release-pipeline list`                                | `Query.releasePipelines`                      | yes            | `--include-archived`                           | `archivedAt`                  |
+| `release-stage list`                                   | `ReleasePipeline.stages`                      | yes            | `--include-archived`                           | `archivedAt`                  |
+| `release-note list`                                    | `Query.releaseNotes`                          | yes            | `--include-archived`                           | `archivedAt`                  |
+| `release issues`, `release links`                      | `Release.issues/links`                        | yes            | not exposed                                    | not exposed                   |
 | `custom-view list`                                     | `Query.customViews`                           | yes            | not exposed                                    | `archivedAt`                  |
 | `custom-view results`                                  | `CustomView.issues/projects/initiatives`      | yes            | not exposed                                    | not exposed                   |
 | `document list`                                        | `Query.documents`                             | yes            | not exposed                                    | not exposed                   |
@@ -772,10 +918,10 @@ profile slug where applicable:
    only, so a migrating user's defaults carry over
 7. no default team
 
-`workspace` and `sort` keep their existing flag → environment → project → user → legacy-global
+`workspace`, `project`, and `sort` use flag → environment → project → user → legacy-global
 order. Workspace credential selection is independent and follows the order described above.
 
-Keys: `team` (or `team_id`), `workspace`, and `sort` (or `issue_sort`). You can write these from
+Keys: `team` (or `team_id`), `workspace`, `project`, and `sort` (or `issue_sort`). You can write these from
 the CLI. Project and top-level setting edits preserve comments and layout. Profile updates preserve
 all TOML data and use the same locked, atomic rewrite as credential updates:
 
@@ -783,11 +929,26 @@ all TOML data and use the same locked, atomic rewrite as credential updates:
 linear config init                    # pick a team from a list → <git root>/.linear.toml
 linear config init --team TES         # …or say which (scripts); --sort, --path, --force
 linear config set sort updated        # edit one key in the project config in effect
+linear config set project "My Project" # default Linear project for new issues (name or UUID)
 linear config set team ENG --user     # legacy top-level user fallback (backward compatible)
 linear config set team ENG --user --workspace acme # validated default for the acme profile
 linear config                         # show the result, with each value's source
 ```
 
+To associate a particular folder and its descendants with a Linear project, run
+`linear config set project "My Project" --path .linear.toml` inside that folder. Without `--path`,
+`config set` edits the discovered config, or creates one at the Git root (cwd outside Git).
+Keep `team` and `workspace` in the same file when needed: discovery reads the nearest config
+file, without merging ancestor files.
+
+`issue create` (also `issue new`) uses this project automatically. `--project <name|id>` overrides
+it; sub-issues inherit their parent's project ahead of the configured default. `--no-project`
+creates outside any project, including parent and template defaults. `LINEAR_PROJECT` overrides
+the configured value for an invocation. A configured project is resolved before creation, so
+an unknown or ambiguous name fails without creating an issue; UUIDs avoid name ambiguity.
+This default applies to issue creation; list, search, and update commands keep their explicit
+project selection. Remove the `project` line from the config to clear the association.
+
 `config set` will not write `api_key` or anything else that belongs to the credential store — that
 is what `auth login` is for. A profile team is validated against the selected workspace whenever a
 credential is available. Login, adopt, OAuth refresh/fallback, and credential migration preserve

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "linear-sdk-cli",
-  "version": "0.8.3",
+  "version": "0.9.0",
   "description": "Ergonomic command-line interface for Linear, built on @linear/sdk",
   "type": "module",
   "license": "MIT",

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)           |