@cvr/linear 0.2.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -33,9 +33,21 @@ linear issue start ABC-123
33
33
  # View issue details
34
34
  linear issue view ABC-123
35
35
 
36
+ # Read one or many issues as JSON
37
+ linear issue view ABC-123 ABC-124 --json
38
+
39
+ # Include comments, sub-issues, and relations
40
+ linear issue view ABC-123 --comments --children --relations --json
41
+
36
42
  # Create a new issue
37
43
  linear issue create
38
44
 
45
+ # Non-interactive creation with validation
46
+ linear issue create --team ABC --title "Title" --project "Tech Debt" --dry-run
47
+
48
+ # List projects
49
+ linear project list --json
50
+
39
51
  # List teams
40
52
  linear team list
41
53
  ```
@@ -57,6 +69,7 @@ linear team list
57
69
  | `linear issue view [id]` | View issue details (interactive picker if no ID) |
58
70
  | `linear issue start [id]` | Start working on an issue |
59
71
  | `linear issue create` | Create a new issue |
72
+ | `linear issue comment ID` | Add a comment, with `--dry-run` support |
60
73
 
61
74
  ### Teams
62
75
 
@@ -64,6 +77,22 @@ linear team list
64
77
  | ------------------ | -------------- |
65
78
  | `linear team list` | List all teams |
66
79
 
80
+ ### Projects and GraphQL
81
+
82
+ | Command | Description |
83
+ | ---------------------------- | ----------------------------------------------- |
84
+ | `linear project list --json` | List projects with stable machine-readable data |
85
+ | `linear api graphql` | Authenticated GraphQL escape hatch |
86
+
87
+ ## Agent usage
88
+
89
+ - Add `--json` to reads; commands return stable JSON and meaningful exit codes.
90
+ - `issue view --json` always returns an array and accepts multiple identifiers or Linear issue URLs.
91
+ - Use `--comments`, `--children`, and `--relations` only when that context is needed.
92
+ - Run supported mutations with `--dry-run` before executing them.
93
+ - Prefer typed commands. Use `linear api graphql` only for operations the typed CLI cannot express.
94
+ - Never read or interpolate the token directly; the CLI owns authentication.
95
+
67
96
  ## Configuration
68
97
 
69
98
  - **Token**: `~/.config/linear/token`
@@ -104,7 +133,7 @@ Built with:
104
133
 
105
134
  - **[Bun](https://bun.sh)**: Fast JavaScript runtime with native compilation
106
135
  - **[Effect](https://effect.website)**: TypeScript library for type-safe, composable code
107
- - **[@effect/cli](https://github.com/Effect-TS/effect/tree/main/packages/cli)**: CLI framework with prompts and argument parsing
136
+ - **[Effect CLI](https://github.com/Effect-TS/effect/tree/main/packages/effect/src/unstable/cli)**: CLI framework with prompts and argument parsing
108
137
  - **[@linear/sdk](https://github.com/linear/linear)**: Official Linear GraphQL SDK
109
138
 
110
139
  ## Credits
package/bin/linear CHANGED
Binary file
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cvr/linear",
3
- "version": "0.2.0",
3
+ "version": "0.3.0",
4
4
  "repository": {
5
5
  "type": "git",
6
6
  "url": "https://github.com/cevr/linear-cli.git"
@@ -10,6 +10,7 @@
10
10
  },
11
11
  "files": [
12
12
  "src",
13
+ "skills",
13
14
  "tsconfig.json"
14
15
  ],
15
16
  "type": "module",
@@ -22,34 +23,35 @@
22
23
  "test": "vitest run",
23
24
  "test:watch": "vitest",
24
25
  "link": "ln -sf $(pwd)/bin/linear ~/.local/bin/linear",
25
- "lint": "oxlint --fix",
26
+ "lint": "oxlint",
27
+ "lint:fix": "oxlint --fix",
26
28
  "fmt": "oxfmt",
27
29
  "fmt:check": "oxfmt --check",
28
- "typecheck": "bunx tsc --noEmit",
29
- "gate": "concurrently -n type,lint,fmt,test -c blue,yellow,magenta,green \"bun run typecheck\" \"bun run lint\" \"bun run fmt\" \"bun run test\"",
30
- "prepare": "lefthook install",
30
+ "typecheck": "tsgo --noEmit",
31
+ "gate": "concurrently -n type,style,build,test -c blue,yellow,cyan,green \"bun run typecheck\" \"bun run lint && bun run fmt:check\" \"bun run build\" \"bun run test\"",
32
+ "prepare": "lefthook install && effect-tsgo patch",
31
33
  "version": "changeset version",
32
34
  "release": "changeset publish"
33
35
  },
34
36
  "dependencies": {
35
- "@effect/cli": "^0.73.1",
36
- "@effect/platform": "^0.94.2",
37
- "@effect/platform-bun": "^0.87.1",
38
- "@linear/sdk": "^71.0.0",
39
- "effect": "^3.19.15"
37
+ "@effect/platform-bun": "4.0.0-beta.98",
38
+ "@linear/sdk": "^88.2.0",
39
+ "effect": "4.0.0-beta.98"
40
40
  },
41
41
  "devDependencies": {
42
- "@changesets/changelog-github": "^0.5.0",
43
- "@changesets/cli": "^2.27.0",
44
- "@effect/language-service": "^0.72.0",
45
- "@effect/vitest": "^0.27.0",
46
- "@types/bun": "latest",
47
- "concurrently": "^9.2.1",
48
- "lefthook": "^2.0.15",
49
- "oxfmt": "^0.26.0",
50
- "oxlint": "^1.41.0",
51
- "typescript": "^5.7.3",
52
- "vitest": "^4.0.18"
42
+ "@changesets/changelog-github": "^0.7.0",
43
+ "@changesets/cli": "^2.31.1",
44
+ "@effect/tsgo": "^0.23.0",
45
+ "@effect/vitest": "4.0.0-beta.98",
46
+ "@types/bun": "^1.3.14",
47
+ "@typescript/native-preview": "7.0.0-dev.20260707.2",
48
+ "concurrently": "^10.0.3",
49
+ "lefthook": "^2.1.10",
50
+ "oxfmt": "^0.59.0",
51
+ "oxlint": "^1.74.0",
52
+ "oxlint-plugin-effect": "latest",
53
+ "typescript": "^7.0.2",
54
+ "vitest": "^4.1.10"
53
55
  },
54
56
  "engines": {
55
57
  "bun": ">=1.0.0"
@@ -0,0 +1,141 @@
1
+ ---
2
+ name: linear
3
+ description: Interact with Linear issues, comments, projects, teams, and GraphQL from the command line. Use for ticket context, bulk issue reads, starting work, or explicitly requested Linear mutations.
4
+ allowed-tools: [Bash]
5
+ ---
6
+
7
+ # Linear CLI
8
+
9
+ Use the `linear` CLI for Linear work. It owns authentication, stable JSON output, issue URL normalization, and actionable exit codes.
10
+
11
+ ## Agent rules
12
+
13
+ 1. Use typed commands before raw GraphQL.
14
+ 2. Add `--json` to reads and parse the complete response. Do not truncate with `head` or `tail`.
15
+ 3. Never read `~/.config/linear/token` directly and never put the token in `curl`, Python, logs, or shell history.
16
+ 4. Treat issue identifiers and Linear issue URLs as equivalent inputs.
17
+ 5. Do not mutate Linear unless the user explicitly requested the mutation.
18
+ 6. For supported mutations, run `--dry-run` first, validate the result, then run the same command without `--dry-run`.
19
+ 7. Use `linear api graphql` only when no typed command can express the operation. For GraphQL mutations, the user's request itself must explicitly authorize the write.
20
+ 8. Trust exit codes: nonzero means the operation failed. Do not infer success from partial stdout.
21
+
22
+ If `/linear` is invoked without an issue or task, run `linear issue list --json` and summarize the available work.
23
+
24
+ ## Common reads
25
+
26
+ ```bash
27
+ linear auth whoami --json
28
+ linear issue list --json
29
+ linear issue list --state started --limit 10 --json
30
+ linear team list --json
31
+ linear project list --json
32
+ ```
33
+
34
+ ### Read one or many issues
35
+
36
+ ```bash
37
+ linear issue view BITE-123 --json
38
+ linear issue view https://linear.app/acme/issue/BITE-123/slug --json
39
+ linear issue view BITE-123 BITE-124 BITE-125 --json
40
+ ```
41
+
42
+ `issue view --json` always returns an array, including for one issue. Each item includes its ID, identifier, title, description, URL, branch name, priority, state, team, assignee, project, parent, and labels.
43
+
44
+ Request potentially larger relationships only when needed:
45
+
46
+ ```bash
47
+ linear issue view BITE-123 --children --json
48
+ linear issue view BITE-123 --comments --json
49
+ linear issue view BITE-123 --relations --json
50
+ linear issue view BITE-123 --children --comments --relations --json
51
+ ```
52
+
53
+ Use the returned `branchName`; do not invent a branch name from the title.
54
+
55
+ ## Mutations
56
+
57
+ ### Start work
58
+
59
+ ```bash
60
+ linear issue start BITE-123
61
+ ```
62
+
63
+ This moves the issue to the team's started state and returns the Linear branch name. It does not create or check out a Git branch.
64
+
65
+ ### Create an issue
66
+
67
+ Interactive:
68
+
69
+ ```bash
70
+ linear issue create
71
+ ```
72
+
73
+ Non-interactive agent flow:
74
+
75
+ ```bash
76
+ linear issue create \
77
+ --team BITE \
78
+ --title "Concise title" \
79
+ --description "Markdown description" \
80
+ --parent BITE-100 \
81
+ --project "Tech Debt" \
82
+ --priority 3 \
83
+ --dry-run
84
+
85
+ linear issue create \
86
+ --team BITE \
87
+ --title "Concise title" \
88
+ --description "Markdown description" \
89
+ --parent BITE-100 \
90
+ --project "Tech Debt" \
91
+ --priority 3 \
92
+ --json
93
+ ```
94
+
95
+ `--team` accepts a team key or UUID. `--project` accepts a project name, slug, or UUID. `--parent` accepts an issue identifier or UUID. Priority is `0` through `4`.
96
+
97
+ ### Add a comment
98
+
99
+ ```bash
100
+ linear issue comment BITE-123 --body "Markdown comment" --dry-run
101
+ linear issue comment BITE-123 --body "Markdown comment" --json
102
+ ```
103
+
104
+ Comments are external messages. Only send one when the user explicitly requested it.
105
+
106
+ ## GraphQL escape hatch
107
+
108
+ Use this only when typed commands cannot express the operation:
109
+
110
+ ```bash
111
+ linear api graphql \
112
+ --query 'query Issue($id: String!) { issue(id: $id) { id identifier title } }' \
113
+ --variables '{"id":"BITE-123"}'
114
+ ```
115
+
116
+ For multiline documents, keep the query in a file:
117
+
118
+ ```bash
119
+ linear api graphql --query-file /path/to/query.graphql --variables '{"id":"BITE-123"}'
120
+ ```
121
+
122
+ The command uses the configured credential and emits only the GraphQL `data` object as JSON. Keep variables separate from the query. Prefer one bulk GraphQL operation over shell loops when migrating a large issue tree.
123
+
124
+ ## Authentication and configuration
125
+
126
+ ```bash
127
+ linear auth
128
+ linear auth whoami --json
129
+ ```
130
+
131
+ Token resolution order:
132
+
133
+ 1. `~/.config/linear/token`
134
+ 2. `LINEAR_API_KEY`
135
+ 3. Actionable authentication error
136
+
137
+ Project defaults live in `.linear.toml`:
138
+
139
+ ```toml
140
+ team_id = "BITE"
141
+ ```
@@ -0,0 +1,67 @@
1
+ import { Console, Effect, FileSystem, Option, Schema } from "effect";
2
+ import { Command, Flag } from "effect/unstable/cli";
3
+ import { InvalidInputError } from "../lib/errors.js";
4
+ import { encodeJson } from "../lib/json.js";
5
+ import { LinearService } from "../services/Linear.js";
6
+
7
+ const queryOption = Flag.string("query").pipe(
8
+ Flag.withDescription("GraphQL document"),
9
+ Flag.optional,
10
+ );
11
+
12
+ const queryFileOption = Flag.string("query-file").pipe(
13
+ Flag.withDescription("Read the GraphQL document from a file"),
14
+ Flag.optional,
15
+ );
16
+
17
+ const variablesOption = Flag.string("variables").pipe(
18
+ Flag.withDescription("GraphQL variables as a JSON object"),
19
+ Flag.withDefault("{}"),
20
+ );
21
+
22
+ const VariablesJson = Schema.fromJsonString(Schema.Record(Schema.String, Schema.Unknown));
23
+ const decodeVariables = Schema.decodeUnknownEffect(VariablesJson);
24
+
25
+ export const graphqlCommand = Command.make(
26
+ "graphql",
27
+ { query: queryOption, queryFile: queryFileOption, variables: variablesOption },
28
+ ({ query, queryFile, variables }) =>
29
+ Effect.gen(function* () {
30
+ if (Option.isSome(query) && Option.isSome(queryFile)) {
31
+ return yield* InvalidInputError.make({
32
+ message: "Use exactly one of --query or --query-file",
33
+ });
34
+ }
35
+
36
+ const document = yield* Option.match(query, {
37
+ onSome: Effect.succeed,
38
+ onNone: () =>
39
+ Option.match(queryFile, {
40
+ onNone: () =>
41
+ InvalidInputError.make({ message: "--query or --query-file is required" }),
42
+ onSome: (path) =>
43
+ FileSystem.FileSystem.use((fileSystem) =>
44
+ fileSystem.readFileString(path).pipe(
45
+ Effect.mapError((error) =>
46
+ InvalidInputError.make({
47
+ message: `Could not read GraphQL query file ${path}: ${error}`,
48
+ }),
49
+ ),
50
+ ),
51
+ ),
52
+ }),
53
+ });
54
+ const parsedVariables = yield* decodeVariables(variables).pipe(
55
+ Effect.mapError((error) =>
56
+ InvalidInputError.make({ message: `--variables must be a JSON object: ${error}` }),
57
+ ),
58
+ );
59
+ const linear = yield* LinearService;
60
+ const data = yield* linear.rawQuery(document, parsedVariables);
61
+ yield* Console.log(encodeJson(data));
62
+ }),
63
+ );
64
+
65
+ export const api = Command.make("api", {}, () =>
66
+ Console.log("Use 'linear api graphql' for GraphQL operations not covered by typed commands."),
67
+ ).pipe(Command.withSubcommands([graphqlCommand]));
@@ -1,5 +1,6 @@
1
- import { Command } from "@effect/cli";
1
+ import { Command, Flag } from "effect/unstable/cli";
2
2
  import { Console, Effect } from "effect";
3
+ import { encodeJson } from "../lib/json.js";
3
4
  import { ConfigService } from "../services/Config.js";
4
5
  import { LinearService } from "../services/Linear.js";
5
6
  import { BrowserService } from "../services/Browser.js";
@@ -7,6 +8,10 @@ import { StdinService } from "../services/Stdin.js";
7
8
 
8
9
  const LINEAR_API_KEY_URL = "https://linear.app/settings/account/security";
9
10
 
11
+ const jsonOption = Flag.boolean("json").pipe(
12
+ Flag.withDescription("Emit stable JSON for scripts and agents"),
13
+ );
14
+
10
15
  // linear auth - Interactive authentication flow
11
16
  export const authCommand = Command.make("auth", {}, () =>
12
17
  Effect.gen(function* () {
@@ -21,9 +26,7 @@ export const authCommand = Command.make("auth", {}, () =>
21
26
  yield* browser
22
27
  .open(LINEAR_API_KEY_URL)
23
28
  .pipe(
24
- Effect.catchAll(() =>
25
- Console.log(`Could not open browser. Please visit the URL manually.`),
26
- ),
29
+ Effect.catch(() => Console.log(`Could not open browser. Please visit the URL manually.`)),
27
30
  );
28
31
 
29
32
  // Simple prompt using readline
@@ -52,16 +55,32 @@ export const authCommand = Command.make("auth", {}, () =>
52
55
  );
53
56
 
54
57
  // linear auth whoami - Show current user
55
- export const whoamiCommand = Command.make("whoami", {}, () =>
58
+ export const whoamiCommand = Command.make("whoami", { json: jsonOption }, ({ json }) =>
56
59
  Effect.gen(function* () {
57
60
  const linear = yield* LinearService;
58
61
  const viewer = yield* linear.getViewer;
59
62
 
63
+ if (json) {
64
+ yield* Console.log(
65
+ encodeJson({
66
+ id: viewer.id,
67
+ name: viewer.name,
68
+ email: viewer.email,
69
+ admin: viewer.admin,
70
+ status: {
71
+ emoji: viewer.statusEmoji ?? undefined,
72
+ label: viewer.statusLabel ?? undefined,
73
+ },
74
+ }),
75
+ );
76
+ return;
77
+ }
78
+
60
79
  yield* Console.log(`\nLogged in as:`);
61
80
  yield* Console.log(` Name: ${viewer.name}`);
62
81
  yield* Console.log(` Email: ${viewer.email}`);
63
82
  yield* Console.log(` Admin: ${viewer.admin ? "Yes" : "No"}`);
64
- if (viewer.statusLabel) {
83
+ if (viewer.statusLabel !== undefined && viewer.statusLabel !== null) {
65
84
  yield* Console.log(` Status: ${viewer.statusEmoji ?? ""} ${viewer.statusLabel}`);
66
85
  }
67
86
  }),