linear-sdk-cli 0.5.3 → 0.6.0

package/CHANGELOG.md

@@ -4,6 +4,17 @@ 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.6.0](https://github.com/zhendalf/linear-sdk-cli/compare/v0.5.3...v0.6.0) (2026-09-17)
+
+### Features
+
+- add project label resource commands ([#73](https://github.com/zhendalf/linear-sdk-cli/issues/73)) ([198ee7a](https://github.com/zhendalf/linear-sdk-cli/commit/198ee7af00b29b45653d6ca07195d1433c4af844))
+- add project status resource commands ([#71](https://github.com/zhendalf/linear-sdk-cli/issues/71)) ([2120a43](https://github.com/zhendalf/linear-sdk-cli/commit/2120a43496132955932a6af3af3a70364ae8493d))
+
+### Bug Fixes
+
+- expose credential scope capabilities ([#74](https://github.com/zhendalf/linear-sdk-cli/issues/74)) ([9efa3c1](https://github.com/zhendalf/linear-sdk-cli/commit/9efa3c1a2405be6dba79cf808b1c14737b280015)), closes [#70](https://github.com/zhendalf/linear-sdk-cli/issues/70)
+
 ## [0.5.3](https://github.com/zhendalf/linear-sdk-cli/compare/v0.5.2...v0.5.3) (2026-09-14)
 
 ### Bug Fixes

package/README.md

@@ -140,6 +140,13 @@ linear auth status                         # credential kind and source (value r
 linear auth logout --workspace acme        # revoke OAuth (if used) and remove the profile
 ```
 
+`auth status --json` also reports `scopeVisibility`, `scopes`, and `adminScope`. Stored browser
+OAuth grants are inspectable because the CLI records their granted scopes. Personal API keys and
+injected OAuth access tokens are reported as `scopeVisibility: "unknown"` and `adminScope: null`:
+Linear provides no safe read-only scope introspection for them. `whoami --json` keeps the Linear
+member's workspace role in `admin` and reports credential authorization separately under
+`authorization`; an admin member can still hold a credential that lacks the `admin` scope.
+
 Browser login generates a cryptographically random verifier and CSRF state, requires PKCE S256,
 opens Linear, and listens temporarily on the registered `127.0.0.1` callback. It validates the
 viewer and workspace before saving the access token, rotating refresh token, expiry, granted
@@ -542,7 +549,9 @@ value per command:
 - **mutations** (`create`/`update`/`delete`/`archive`/…) emit the affected object — typically a
   small shape like `{ "id", "identifier", "url" }`, or `{ "id", "success": true }` when the API
   returns no body. Destructive commands add a flag such as `{ "deleted": true }` / `{ "archived": true }`.
-- **errors** go to **stderr** as `{"error":{"message":"…","code":"…"}}` and never to stdout. With
+- **errors** go to **stderr** as `{"error":{"message":"…","code":"…"}}` and never to stdout.
+  Scope-related forbidden errors add stable `error.details` such as `requiredScope`,
+  `credentialType`, `scopeVisibility`, and remediation; callers never need to parse prose. With
   `--debug`, the extra detail is carried _inside_ that object as `error.detail` rather than appended
   after it, so `--json --debug` output stays parseable.
 

package/package.json

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

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

@@ -100,6 +100,13 @@ An explicit credential flag overrides environment credentials. If both credentia
 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.
 
+Treat workspace role and credential authorization as separate facts. `whoami.admin` is the Linear
+member role; it does not prove the active credential has the `admin` scope. Check
+`auth status --json`: stored browser OAuth grants report known `scopes` and `adminScope`, while
+personal API keys and injected access tokens honestly report `scopeVisibility: "unknown"` and
+`adminScope: null` because Linear exposes no safe read-only introspection for them. Scope-related
+forbidden errors include stable `error.details` with the required scope and remediation.
+
 ## Agent best practices
 
 This CLI is built for non-interactive use. Follow these and it will never hang and
@@ -441,6 +448,23 @@ linear project milestones
 linear project update
 linear project view
 
+linear project-label
+linear project-label create
+linear project-label delete
+linear project-label list
+linear project-label restore
+linear project-label retire
+linear project-label update
+linear project-label view
+
+linear project-status
+linear project-status archive
+linear project-status create
+linear project-status list
+linear project-status unarchive
+linear project-status update
+linear project-status view
+
 linear project-update
 linear project-update create
 linear project-update list
@@ -513,6 +537,8 @@ prints the same). These are supplementary — `--help` on any command is authori
 - [open](references/open.md) — Open the workspace, an issue, team, project, or URL
 - [organization](references/organization.md) — Inspect the current workspace
 - [project](references/project.md) — Work with projects
+- [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
 - [roadmap](references/roadmap.md) — Work with roadmaps
 - [schema](references/schema.md) — Print the Linear GraphQL schema as SDL

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

@@ -159,6 +159,9 @@ key: string
 keyring: string | null
 scopes: string[] | null
 expiresAt: string | null
+scopeVisibility: string
+adminScope: boolean | null
+scopeNote: string
 ```
 
 ### `linear auth token`
@@ -192,5 +195,6 @@ name: string
 displayName: string
 email: string
 admin: boolean
+authorization: {credentialType: string | null, scopeVisibility: string, scopes: string[] | null, adminScope: boolean | null, note: string}
 organization: {id: string, name: string, urlKey: string}
 ```

package/skills/linear-sdk-cli/references/project-label.md

@@ -0,0 +1,170 @@
+# linear project-label
+
+> Manage project labels (distinct from issue labels)
+
+Group alias: `pl`
+
+_Generated from `linear commands --json`. `linear project-label --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 project-label`
+
+Manage project labels (distinct from issue labels)
+
+Aliases: `pl`
+
+```
+linear project-label [options]
+```
+
+### `linear project-label create`
+
+Create a project label or label group
+
+Aliases: `new`
+
+```
+linear project-label create [options]
+```
+
+| Option                     | Description                               |
+| -------------------------- | ----------------------------------------- |
+| `--name <name>`            | project label name                        |
+| `--color <hex>`            | label color (six-digit hex, e.g. #5E6AD2) |
+| `-d, --description <text>` | label description                         |
+| `--group`                  | create a non-assignable label group       |
+| `--parent <name-or-id>`    | put the label in this group               |
+
+**Output (`--json`)**: a receipt object
+
+```text
+id: string
+name: string
+color: string
+```
+
+### `linear project-label delete`
+
+Permanently delete a project label
+
+Aliases: `rm`
+
+```
+linear project-label delete [options] <name-or-id>
+```
+
+**Output (`--json`)**: a receipt object
+
+```text
+id: string
+name: string
+deleted: boolean
+```
+
+### `linear project-label list`
+
+List project labels
+
+Aliases: `ls`
+
+```
+linear project-label list [options]
+```
+
+| Option              | Description                                        |
+| ------------------- | -------------------------------------------------- |
+| `--include-retired` | include labels retired from new project assignment |
+
+**Output (`--json`)**: a bare array of objects
+
+```text
+id: string
+name: string
+color: string
+description: string | null
+isGroup: boolean
+parent: {id: string, name: string} | null
+retiredAt: string | null
+```
+
+### `linear project-label restore`
+
+Restore a retired project label
+
+Aliases: `unretire`
+
+```
+linear project-label restore [options] <name-or-id>
+```
+
+**Output (`--json`)**: a receipt object
+
+```text
+id: string
+name: string
+restored: boolean
+```
+
+### `linear project-label retire`
+
+Retire a label so it cannot be assigned to new projects
+
+```
+linear project-label retire [options] <name-or-id>
+```
+
+**Output (`--json`)**: a receipt object
+
+```text
+id: string
+name: string
+retired: boolean
+```
+
+### `linear project-label update`
+
+Update a project label by exact name or id
+
+Aliases: `edit`
+
+```
+linear project-label update [options] <name-or-id>
+```
+
+| Option                     | Description                             |
+| -------------------------- | --------------------------------------- |
+| `--name <name>`            | new name                                |
+| `--color <hex>`            | new color (six-digit hex, e.g. #5E6AD2) |
+| `-d, --description <text>` | new description                         |
+| `--parent <name-or-id>`    | move the label into this group          |
+| `--clear-parent`           | remove the label from its group         |
+
+**Output (`--json`)**: a receipt object
+
+```text
+id: string
+name: string
+color: string
+```
+
+### `linear project-label view`
+
+View a project label or label group by exact name or id
+
+```
+linear project-label view [options] <name-or-id>
+```
+
+**Output (`--json`)**: a bare object
+
+```text
+id: string
+name: string
+color: string
+description: string | null
+isGroup: boolean
+parent: {id: string, name: string} | null
+retiredAt: string | null
+children: Array<{id: string, name: string, color: string, retiredAt: string | null}>
+```

package/skills/linear-sdk-cli/references/project-status.md

@@ -0,0 +1,158 @@
+# linear project-status
+
+> Manage workspace project-status definitions
+
+Group alias: `project-statuses`
+
+_Generated from `linear commands --json`. `linear project-status --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 project-status`
+
+Manage workspace project-status definitions
+
+Aliases: `project-statuses`
+
+```
+linear project-status [options]
+```
+
+### `linear project-status archive`
+
+Archive a project status (requires no active projects and another status of its type)
+
+```
+linear project-status archive [options] <name-or-id>
+```
+
+**Output (`--json`)**: a receipt object
+
+```text
+id: string
+name: string
+archived: boolean
+```
+
+### `linear project-status create`
+
+Create a workspace project status (explicit because duplicate names are valid)
+
+Aliases: `new`
+
+```
+linear project-status create [options]
+```
+
+| Option                      | Description                                                          |
+| --------------------------- | -------------------------------------------------------------------- |
+| `--name <name>`             | status name                                                          |
+| `-d, --description <text>`  | status description                                                   |
+| `--description-file <path>` | read description from a file ('-' = stdin)                           |
+| `--color <hex>`             | six-digit hex color (e.g. #5E6AD2)                                   |
+| `--position <number>`       | position within the status type                                      |
+| `--type <type>`             | status type (backlog\|planned\|started\|paused\|completed\|canceled) |
+| `--indefinite`              | allow projects to remain in this status indefinitely                 |
+
+**Output (`--json`)**: a receipt object
+
+```text
+id: string
+name: string
+type: string
+```
+
+### `linear project-status list`
+
+List workspace project statuses
+
+Aliases: `ls`
+
+```
+linear project-status list [options]
+```
+
+| Option               | Description                       |
+| -------------------- | --------------------------------- |
+| `--include-archived` | include archived project statuses |
+
+**Output (`--json`)**: a bare array of objects
+
+```text
+id: string
+name: string
+description: string | null
+color: string
+position: number
+type: string
+indefinite: boolean
+archivedAt: string | null
+```
+
+### `linear project-status unarchive`
+
+Unarchive a project status by exact name or id
+
+```
+linear project-status unarchive [options] <name-or-id>
+```
+
+**Output (`--json`)**: a receipt object
+
+```text
+id: string
+name: string
+archived: boolean
+```
+
+### `linear project-status update`
+
+Update a project status by exact name or id
+
+Aliases: `edit`
+
+```
+linear project-status update [options] <name-or-id>
+```
+
+| Option                      | Description                                                          |
+| --------------------------- | -------------------------------------------------------------------- |
+| `--name <name>`             | new status name                                                      |
+| `-d, --description <text>`  | new status description                                               |
+| `--description-file <path>` | read description from a file ('-' = stdin)                           |
+| `--color <hex>`             | six-digit hex color (e.g. #5E6AD2)                                   |
+| `--position <number>`       | position within the status type                                      |
+| `--type <type>`             | status type (backlog\|planned\|started\|paused\|completed\|canceled) |
+| `--indefinite`              | allow projects to remain in this status indefinitely                 |
+| `--no-indefinite`           | do not allow projects to remain indefinitely                         |
+
+**Output (`--json`)**: a receipt object
+
+```text
+id: string
+name: string
+type: string
+```
+
+### `linear project-status view`
+
+Show a project status by exact name or id
+
+```
+linear project-status view [options] <name-or-id>
+```
+
+**Output (`--json`)**: a bare object
+
+```text
+id: string
+name: string
+description: string | null
+color: string
+position: number
+type: string
+indefinite: boolean
+archivedAt: string | null
+createdAt: string
+updatedAt: string
+```

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

@@ -71,24 +71,24 @@ Aliases: `new`
 linear project create [options]
 ```
 
-| Option                      | Description                                    |
-| --------------------------- | ---------------------------------------------- |
-| `--name <name>`             | project name                                   |
-| `-d, --description <text>`  | project description (one-line summary)         |
-| `--description-file <path>` | read description from a file ('-' = stdin)     |
-| `--content <text>`          | project content (markdown body)                |
-| `--content-file <path>`     | read content from a file ('-' = stdin)         |
-| `--teams <key>`             | team (repeatable / comma-separated)            |
-| `-t, --team <key>`          | same as --teams (repeatable / comma-separated) |
-| `--lead <who>`              | project lead (me\|email\|name\|id)             |
-| `--member <who>`            | project member (repeatable / comma-separated)  |
-| `--state <name>`            | initial status (name, type, or id)             |
-| `--start <date>`            | planned start date (YYYY-MM-DD)                |
-| `--target <date>`           | planned target date (YYYY-MM-DD)               |
-| `-P, --priority <0-4>`      | priority (0 none, 1 urgent … 4 low)            |
-| `-l, --label <name>`        | project label (repeatable / comma-separated)   |
-| `--icon <name>`             | Linear icon name, capitalized (e.g. Rocket)    |
-| `--color <hex>`             | project color (e.g. #EB5757)                   |
+| Option                      | Description                                                            |
+| --------------------------- | ---------------------------------------------------------------------- |
+| `--name <name>`             | project name                                                           |
+| `-d, --description <text>`  | project description (one-line summary)                                 |
+| `--description-file <path>` | read description from a file ('-' = stdin)                             |
+| `--content <text>`          | project content (markdown body)                                        |
+| `--content-file <path>`     | read content from a file ('-' = stdin)                                 |
+| `--teams <key>`             | team (repeatable / comma-separated)                                    |
+| `-t, --team <key>`          | same as --teams (repeatable / comma-separated)                         |
+| `--lead <who>`              | project lead (me\|email\|name\|id)                                     |
+| `--member <who>`            | project member (repeatable / comma-separated)                          |
+| `--state <name>`            | initial status (name, type, or id)                                     |
+| `--start <date>`            | planned start date (YYYY-MM-DD)                                        |
+| `--target <date>`           | planned target date (YYYY-MM-DD)                                       |
+| `-P, --priority <0-4>`      | priority (0 none, 1 urgent … 4 low)                                    |
+| `-l, --label <name>`        | project label from `project-label list` (repeatable / comma-separated) |
+| `--icon <name>`             | Linear icon name, capitalized (e.g. Rocket)                            |
+| `--color <hex>`             | project color (e.g. #EB5757)                                           |
 
 **Output (`--json`)**: a receipt object
 
@@ -175,23 +175,23 @@ Aliases: `edit`
 linear project update [options] <id>
 ```
 
-| Option                      | Description                                        |
-| --------------------------- | -------------------------------------------------- |
-| `--name <name>`             | new name                                           |
-| `-d, --description <text>`  | new description (one-line summary)                 |
-| `--description-file <path>` | read description from a file ('-' = stdin)         |
-| `--content <text>`          | new content (markdown body)                        |
-| `--content-file <path>`     | read content from a file ('-' = stdin)             |
-| `--teams <key>`             | set teams (repeatable / comma-separated)           |
-| `--lead <who>`              | project lead (me\|email\|name\|id)                 |
-| `--member <who>`            | replace the members (repeatable / comma-separated) |
-| `--state <name>`            | status (name, type, or id)                         |
-| `--start <date>`            | planned start date (YYYY-MM-DD)                    |
-| `--target <date>`           | planned target date (YYYY-MM-DD)                   |
-| `-P, --priority <0-4>`      | priority (0 none, 1 urgent … 4 low)                |
-| `-l, --label <name>`        | replace the labels (repeatable / comma-separated)  |
-| `--icon <name>`             | Linear icon name, capitalized (e.g. Rocket)        |
-| `--color <hex>`             | project color (e.g. #EB5757)                       |
+| Option                      | Description                                                                     |
+| --------------------------- | ------------------------------------------------------------------------------- |
+| `--name <name>`             | new name                                                                        |
+| `-d, --description <text>`  | new description (one-line summary)                                              |
+| `--description-file <path>` | read description from a file ('-' = stdin)                                      |
+| `--content <text>`          | new content (markdown body)                                                     |
+| `--content-file <path>`     | read content from a file ('-' = stdin)                                          |
+| `--teams <key>`             | set teams (repeatable / comma-separated)                                        |
+| `--lead <who>`              | project lead (me\|email\|name\|id)                                              |
+| `--member <who>`            | replace the members (repeatable / comma-separated)                              |
+| `--state <name>`            | status (name, type, or id)                                                      |
+| `--start <date>`            | planned start date (YYYY-MM-DD)                                                 |
+| `--target <date>`           | planned target date (YYYY-MM-DD)                                                |
+| `-P, --priority <0-4>`      | priority (0 none, 1 urgent … 4 low)                                             |
+| `-l, --label <name>`        | replace project labels from `project-label list` (repeatable / comma-separated) |
+| `--icon <name>`             | Linear icon name, capitalized (e.g. Rocket)                                     |
+| `--color <hex>`             | project color (e.g. #EB5757)                                                    |
 
 **Output (`--json`)**: a receipt object
 

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

@@ -22,5 +22,6 @@ name: string
 displayName: string
 email: string
 admin: boolean
+authorization: {credentialType: string | null, scopeVisibility: string, scopes: string[] | null, adminScope: boolean | null, note: string}
 organization: {id: string, name: string, urlKey: string}
 ```

package/src/cli.ts

@@ -13,6 +13,8 @@ import { registerAgentSession } from "./commands/agent-session.js";
 import { registerAttach } from "./commands/attach.js";
 import { registerTeam } from "./commands/team.js";
 import { registerProject } from "./commands/project.js";
+import { registerProjectStatus } from "./commands/project-status.js";
+import { registerProjectLabel } from "./commands/project-label.js";
 import { registerProjectUpdate } from "./commands/project-update.js";
 import { registerMilestone } from "./commands/milestone.js";
 import { registerCycle } from "./commands/cycle.js";
@@ -70,6 +72,8 @@ export function createProgram(): Command {
   // Phase 2: teams, projects, milestones, cycles.
   registerTeam(program);
   registerProject(program);
+  registerProjectStatus(program);
+  registerProjectLabel(program);
   registerProjectUpdate(program);
   registerMilestone(program);
   registerCycle(program);

package/src/commands/meta.ts

@@ -38,6 +38,10 @@ import { resolveTeam } from "../lib/resolve.js";
 import { ISSUE_SORTS } from "../services/issue.js";
 import { firstTeam, type Context } from "../context.js";
 import { openUrl } from "../lib/open.js";
+import {
+  authorizationCapabilities,
+  credentialType as resolvedCredentialType,
+} from "../lib/authorization.js";
 import {
   DEFAULT_OAUTH_SCOPES,
   buildAuthorizationUrl,
@@ -59,6 +63,7 @@ export const DEFAULT_OAUTH_CLIENT_ID = "eda60862e4bb8b8af82cfb3193b65c2f";
 const whoamiAction = action(async (ctx: Context) => {
   const me = await withRetry(() => ctx.client.viewer);
   const org = await withRetry(() => ctx.client.organization);
+  const authorization = authorizationCapabilities(ctx.config);
   ctx.output.detail(
     {
       id: me.id,
@@ -66,13 +71,17 @@ const whoamiAction = action(async (ctx: Context) => {
       displayName: me.displayName,
       email: me.email,
       admin: me.admin,
+      authorization,
       organization: { id: org.id, name: org.name, urlKey: org.urlKey },
     },
     [
       ["Name", me.name],
       ["Display name", me.displayName],
       ["Email", me.email],
-      ["Admin", me.admin],
+      ["Workspace admin", me.admin],
+      ["Credential type", authorization.credentialType ?? "(none)"],
+      ["Credential scopes", authorization.scopes?.join(", ") ?? "unknown"],
+      ["Credential admin scope", authorization.adminScope ?? "unknown"],
       ["User ID", me.id],
       ["Organization", `${org.name} (${org.urlKey})`],
     ],
@@ -481,13 +490,8 @@ export function registerMeta(program: Command): void {
         const c = ctx.config;
         if (c.workspaceChoices) throw c.apiKeyError;
         const credential = c.accessToken ?? c.apiKey;
-        const credentialType = c.oauthCredential
-          ? "oauth-user"
-          : c.accessToken
-            ? "oauth-access-token"
-            : c.apiKey
-              ? "api-key"
-              : null;
+        const credentialType = resolvedCredentialType(c);
+        const authorization = authorizationCapabilities(c);
         const source = c.accessToken ? c.accessTokenSource : c.apiKeySource;
         const backend = keyring();
         ctx.output.detail(
@@ -502,6 +506,9 @@ export function registerMeta(program: Command): void {
             expiresAt: c.oauthCredential
               ? new Date(c.oauthCredential.expiresAt).toISOString()
               : null,
+            scopeVisibility: authorization.scopeVisibility,
+            adminScope: authorization.adminScope,
+            scopeNote: authorization.note,
           },
           [
             ["Authenticated", !!credential],
@@ -511,6 +518,9 @@ export function registerMeta(program: Command): void {
             ["Credential", redactKey(credential)],
             ["Keyring", backend ? backend.label : "(none on this platform)"],
             ["Scopes", c.oauthCredential?.scopes.join(", ")],
+            ["Scope visibility", authorization.scopeVisibility],
+            ["Admin scope", authorization.adminScope ?? "unknown"],
+            ["Scope note", authorization.note],
             [
               "Expires",
               c.oauthCredential ? new Date(c.oauthCredential.expiresAt).toISOString() : undefined,