@cvr/linear 0.1.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
  ```
@@ -44,26 +56,43 @@ linear team list
44
56
 
45
57
  ### Authentication
46
58
 
47
- | Command | Description |
48
- |---------|-------------|
49
- | `linear auth` | Authenticate with Linear (opens browser for API key) |
50
- | `linear auth whoami` | Show current user info |
59
+ | Command | Description |
60
+ | -------------------- | ---------------------------------------------------- |
61
+ | `linear auth` | Authenticate with Linear (opens browser for API key) |
62
+ | `linear auth whoami` | Show current user info |
51
63
 
52
64
  ### Issues
53
65
 
54
- | Command | Description |
55
- |---------|-------------|
56
- | `linear issue list` | List your assigned issues |
57
- | `linear issue view [id]` | View issue details (interactive picker if no ID) |
58
- | `linear issue start [id]` | Start working on an issue |
59
- | `linear issue create` | Create a new issue |
66
+ | Command | Description |
67
+ | ------------------------- | ------------------------------------------------ |
68
+ | `linear issue list` | List your assigned issues |
69
+ | `linear issue view [id]` | View issue details (interactive picker if no ID) |
70
+ | `linear issue start [id]` | Start working on an issue |
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
 
63
- | Command | Description |
64
- |---------|-------------|
76
+ | Command | Description |
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`
@@ -101,9 +130,10 @@ bun run src/main.ts --help
101
130
  ## Architecture
102
131
 
103
132
  Built with:
133
+
104
134
  - **[Bun](https://bun.sh)**: Fast JavaScript runtime with native compilation
105
135
  - **[Effect](https://effect.website)**: TypeScript library for type-safe, composable code
106
- - **[@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
107
137
  - **[@linear/sdk](https://github.com/linear/linear)**: Official Linear GraphQL SDK
108
138
 
109
139
  ## Credits
package/bin/linear ADDED
Binary file
package/package.json CHANGED
@@ -1,50 +1,59 @@
1
1
  {
2
2
  "name": "@cvr/linear",
3
- "version": "0.1.0",
4
- "type": "module",
3
+ "version": "0.3.0",
4
+ "repository": {
5
+ "type": "git",
6
+ "url": "https://github.com/cevr/linear-cli.git"
7
+ },
5
8
  "bin": {
6
9
  "linear": "./bin/linear"
7
10
  },
8
11
  "files": [
9
12
  "src",
10
- "bin",
13
+ "skills",
11
14
  "tsconfig.json"
12
15
  ],
16
+ "type": "module",
17
+ "publishConfig": {
18
+ "access": "public"
19
+ },
13
20
  "scripts": {
14
21
  "build": "bun build ./src/main.ts --compile --outfile bin/linear",
15
22
  "postinstall": "bun run build",
16
- "prepublishOnly": "rm -rf bin",
17
23
  "test": "vitest run",
18
24
  "test:watch": "vitest",
19
25
  "link": "ln -sf $(pwd)/bin/linear ~/.local/bin/linear",
20
- "prepare": "effect-language-service patch",
26
+ "lint": "oxlint",
27
+ "lint:fix": "oxlint --fix",
28
+ "fmt": "oxfmt",
29
+ "fmt:check": "oxfmt --check",
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",
21
33
  "version": "changeset version",
22
34
  "release": "changeset publish"
23
35
  },
24
- "publishConfig": {
25
- "access": "public"
36
+ "dependencies": {
37
+ "@effect/platform-bun": "4.0.0-beta.98",
38
+ "@linear/sdk": "^88.2.0",
39
+ "effect": "4.0.0-beta.98"
26
40
  },
27
- "repository": {
28
- "type": "git",
29
- "url": "https://github.com/cevr/linear-cli.git"
41
+ "devDependencies": {
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"
30
55
  },
31
56
  "engines": {
32
57
  "bun": ">=1.0.0"
33
- },
34
- "dependencies": {
35
- "effect": "^3.12.7",
36
- "@effect/cli": "^0.56.6",
37
- "@effect/platform": "^0.87.0",
38
- "@effect/platform-bun": "^0.87.0",
39
- "@linear/sdk": "^29.0.0"
40
- },
41
- "devDependencies": {
42
- "@changesets/changelog-github": "^0.5.0",
43
- "@changesets/cli": "^2.27.0",
44
- "@effect/language-service": "^0.65.0",
45
- "@effect/vitest": "^0.27.0",
46
- "@types/bun": "latest",
47
- "typescript": "^5.7.3",
48
- "vitest": "^2.1.8"
49
58
  }
50
59
  }
@@ -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,69 +1,90 @@
1
- import { Command } from "@effect/cli"
2
- import { Console, Effect } from "effect"
3
- import { ConfigService } from "../services/Config.js"
4
- import { LinearService } from "../services/Linear.js"
5
- import { BrowserService } from "../services/Browser.js"
6
- import { StdinService } from "../services/Stdin.js"
1
+ import { Command, Flag } from "effect/unstable/cli";
2
+ import { Console, Effect } from "effect";
3
+ import { encodeJson } from "../lib/json.js";
4
+ import { ConfigService } from "../services/Config.js";
5
+ import { LinearService } from "../services/Linear.js";
6
+ import { BrowserService } from "../services/Browser.js";
7
+ import { StdinService } from "../services/Stdin.js";
7
8
 
8
- const LINEAR_API_KEY_URL = "https://linear.app/settings/account/security"
9
+ const LINEAR_API_KEY_URL = "https://linear.app/settings/account/security";
10
+
11
+ const jsonOption = Flag.boolean("json").pipe(
12
+ Flag.withDescription("Emit stable JSON for scripts and agents"),
13
+ );
9
14
 
10
15
  // linear auth - Interactive authentication flow
11
16
  export const authCommand = Command.make("auth", {}, () =>
12
17
  Effect.gen(function* () {
13
- const browser = yield* BrowserService
14
- const config = yield* ConfigService
15
- const stdin = yield* StdinService
18
+ const browser = yield* BrowserService;
19
+ const config = yield* ConfigService;
20
+ const stdin = yield* StdinService;
16
21
 
17
- yield* Console.log(`\nTo authenticate, you'll need a Linear API key.`)
18
- yield* Console.log(`Opening: ${LINEAR_API_KEY_URL}\n`)
22
+ yield* Console.log(`\nTo authenticate, you'll need a Linear API key.`);
23
+ yield* Console.log(`Opening: ${LINEAR_API_KEY_URL}\n`);
19
24
 
20
25
  // Open browser
21
- yield* browser.open(LINEAR_API_KEY_URL).pipe(
22
- Effect.catchAll(() =>
23
- Console.log(`Could not open browser. Please visit the URL manually.`)
24
- )
25
- )
26
+ yield* browser
27
+ .open(LINEAR_API_KEY_URL)
28
+ .pipe(
29
+ Effect.catch(() => Console.log(`Could not open browser. Please visit the URL manually.`)),
30
+ );
26
31
 
27
32
  // Simple prompt using readline
28
- const token = yield* stdin.readLine("Paste your API key: ")
33
+ const token = yield* stdin.readLine("Paste your API key: ");
29
34
 
30
35
  // Validate token by making an API call
31
- yield* Console.log("\nValidating token...")
36
+ yield* Console.log("\nValidating token...");
32
37
 
33
38
  // Save token first so LinearService can use it
34
- yield* config.saveToken(token)
39
+ yield* config.saveToken(token);
35
40
 
36
41
  // Now validate with the saved token
37
- const linear = yield* LinearService
42
+ const linear = yield* LinearService;
38
43
  const viewer = yield* linear.getViewer.pipe(
39
44
  Effect.catchTag("InvalidTokenError", (e) =>
40
45
  Effect.gen(function* () {
41
- yield* Console.error(`\nError: ${e.message}`)
42
- yield* Console.error("Please try again with a valid API key.")
43
- return yield* Effect.die(e)
44
- })
45
- )
46
- )
46
+ yield* Console.error(`\nError: ${e.message}`);
47
+ yield* Console.error("Please try again with a valid API key.");
48
+ return yield* Effect.die(e);
49
+ }),
50
+ ),
51
+ );
47
52
 
48
- yield* Console.log(`\nAuthenticated as ${viewer.name} (${viewer.email})`)
49
- })
50
- )
53
+ yield* Console.log(`\nAuthenticated as ${viewer.name} (${viewer.email})`);
54
+ }),
55
+ );
51
56
 
52
57
  // linear auth whoami - Show current user
53
- export const whoamiCommand = Command.make("whoami", {}, () =>
58
+ export const whoamiCommand = Command.make("whoami", { json: jsonOption }, ({ json }) =>
54
59
  Effect.gen(function* () {
55
- const linear = yield* LinearService
56
- const viewer = yield* linear.getViewer
60
+ const linear = yield* LinearService;
61
+ const viewer = yield* linear.getViewer;
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
+ }
57
78
 
58
- yield* Console.log(`\nLogged in as:`)
59
- yield* Console.log(` Name: ${viewer.name}`)
60
- yield* Console.log(` Email: ${viewer.email}`)
61
- yield* Console.log(` Admin: ${viewer.admin ? "Yes" : "No"}`)
62
- if (viewer.statusLabel) {
63
- yield* Console.log(` Status: ${viewer.statusEmoji ?? ""} ${viewer.statusLabel}`)
79
+ yield* Console.log(`\nLogged in as:`);
80
+ yield* Console.log(` Name: ${viewer.name}`);
81
+ yield* Console.log(` Email: ${viewer.email}`);
82
+ yield* Console.log(` Admin: ${viewer.admin ? "Yes" : "No"}`);
83
+ if (viewer.statusLabel !== undefined && viewer.statusLabel !== null) {
84
+ yield* Console.log(` Status: ${viewer.statusEmoji ?? ""} ${viewer.statusLabel}`);
64
85
  }
65
- })
66
- )
86
+ }),
87
+ );
67
88
 
68
89
  // Combined auth command with subcommands
69
- export const auth = authCommand.pipe(Command.withSubcommands([whoamiCommand]))
90
+ export const auth = authCommand.pipe(Command.withSubcommands([whoamiCommand]));