linear-cli-agents 0.2.0 → 0.4.0

package/README.md

@@ -1,7 +1,7 @@
 # linear-cli-agents
 
 [![npm version](https://img.shields.io/npm/v/linear-cli-agents.svg)](https://www.npmjs.com/package/linear-cli-agents)
-[![CI](https://github.com/nchgn/linear-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/nchgn/linear-cli/actions/workflows/ci.yml)
+[![CI](https://github.com/nchgn/linear-cli-agents/actions/workflows/ci.yml/badge.svg)](https://github.com/nchgn/linear-cli-agents/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 A CLI for interacting with [Linear](https://linear.app), designed for LLMs and agents.
@@ -9,8 +9,14 @@ A CLI for interacting with [Linear](https://linear.app), designed for LLMs and a
 ## Features
 
 - **JSON output**: All commands return structured JSON, perfect for parsing by LLMs
+- **Multiple formats**: JSON (default), table (colored), or plain text output
 - **Schema introspection**: Discover available operations programmatically
-- **Full CRUD for issues**: List, create, update, and delete issues
+- **Full CRUD**: Issues, projects, labels, comments, templates, milestones
+- **Issue relations**: Manage blocks, duplicates, and related issues
+- **Project management**: Projects, milestones, and status updates
+- **Team management**: List and browse teams, states, users
+- **Browser integration**: Open issues, teams, inbox directly in Linear
+- **Search**: Find issues across workspace
 - **Raw GraphQL queries**: Execute any GraphQL query directly
 
 ## Installation
@@ -23,9 +29,10 @@ pnpm add -g linear-cli-agents
 
 ## Authentication
 
-Get your API key from [Linear Settings > API](https://linear.app/settings/api).
-
 ```bash
+# Open Linear API settings in browser to create a key
+linear auth login --browser
+
 # Login with API key
 linear auth login --key lin_api_xxxxx
 
@@ -35,6 +42,9 @@ export LINEAR_API_KEY=lin_api_xxxxx
 # Check auth status
 linear auth status
 
+# View current user info
+linear me
+
 # Logout
 linear auth logout
 ```
@@ -53,8 +63,13 @@ linear issues list --assignee me
 linear issues list --state "In Progress"
 linear issues list --filter '{"priority":{"lte":2}}'
 
+# Output formats: json (default), table (colored), plain (IDs only)
+linear issues list --format table
+linear issues list --format plain
+
 # Get a specific issue
 linear issues get ENG-123
+linear issues get ENG-123 --format table
 
 # Create an issue
 linear issues create --title "Bug fix" --team-id <team-id>
@@ -66,6 +81,206 @@ linear issues update ENG-123 --state-id <state-id> --assignee-id <user-id>
 
 # Delete an issue (moves to trash)
 linear issues delete ENG-123
+
+# Archive/unarchive an issue
+linear issues archive ENG-123
+linear issues archive ENG-123 --unarchive
+
+# Manage labels on issues
+linear issues add-labels ENG-123 --label-ids LABEL_ID1,LABEL_ID2
+linear issues remove-labels ENG-123 --label-ids LABEL_ID1
+```
+
+### Projects
+
+```bash
+# List projects
+linear projects list
+linear projects list --team ENG
+linear projects list --state started
+
+# Get project details
+linear projects get PROJECT_ID
+
+# Create a project
+linear projects create --name "Q1 Goals" --team-ids TEAM_ID
+linear projects create --name "Feature X" --team-ids TEAM_ID --target-date 2024-06-30
+
+# Update a project
+linear projects update PROJECT_ID --name "Updated Name"
+linear projects update PROJECT_ID --state completed
+
+# Delete a project
+linear projects delete PROJECT_ID
+
+# Archive/unarchive a project
+linear projects archive PROJECT_ID
+linear projects archive PROJECT_ID --unarchive
+```
+
+### Project Milestones
+
+```bash
+# List milestones for a project
+linear milestones list PROJECT_ID
+
+# Get milestone details
+linear milestones get MILESTONE_ID
+
+# Create a milestone
+linear milestones create PROJECT_ID --name "Alpha Release" --target-date 2024-03-01
+
+# Update a milestone
+linear milestones update MILESTONE_ID --name "Beta Release"
+```
+
+### Project Updates
+
+```bash
+# List status updates for a project
+linear project-updates list PROJECT_ID
+
+# Get update details
+linear project-updates get UPDATE_ID
+
+# Create a status update
+linear project-updates create PROJECT_ID --body "Sprint completed" --health onTrack
+
+# Update a status update
+linear project-updates update UPDATE_ID --body "Updated status"
+```
+
+### Issue Relations
+
+```bash
+# List relations for an issue
+linear relations list ENG-123
+
+# Create a relation
+linear relations create ENG-123 ENG-456 --type blocks
+linear relations create ENG-123 ENG-456 --type duplicate
+linear relations create ENG-123 ENG-456 --type related
+
+# Delete a relation
+linear relations delete RELATION_ID
+```
+
+### Labels
+
+```bash
+# List labels
+linear labels list
+linear labels list --team ENG
+
+# Create a label
+linear labels create --name "Bug" --color "#FF0000"
+linear labels create --name "Feature" --color "#00FF00" --team-id TEAM_ID
+
+# Update a label
+linear labels update LABEL_ID --name "Critical Bug" --color "#FF0000"
+
+# Delete a label
+linear labels delete LABEL_ID
+```
+
+### Templates
+
+```bash
+# List templates
+linear templates list
+linear templates list --team ENG
+
+# Get template details
+linear templates get TEMPLATE_ID
+
+# Create a template
+linear templates create --name "Bug Report" --type issue --team-id TEAM_ID \
+  --template-data '{"title":"Bug: ","priority":2}'
+
+# Update a template
+linear templates update TEMPLATE_ID --name "Updated Template"
+```
+
+### Comments
+
+```bash
+# List comments on an issue
+linear comments list ENG-123
+
+# Add a comment
+linear comments add ENG-123 --body "This looks good!"
+
+# Update a comment
+linear comments update COMMENT_ID --body "Updated comment"
+
+# Delete a comment
+linear comments delete COMMENT_ID
+```
+
+### States
+
+```bash
+# List workflow states
+linear states list
+linear states list --team ENG
+```
+
+### Users
+
+```bash
+# List users
+linear users list
+
+# Get user details
+linear users get USER_ID
+```
+
+### Search
+
+```bash
+# Search issues
+linear search "login bug"
+linear search "SSO" --team ENG
+```
+
+### Teams
+
+```bash
+# List all teams
+linear teams list
+
+# With table format
+linear teams list --format table
+```
+
+### Open in Browser
+
+```bash
+# Open an issue
+linear open ENG-123
+
+# Open a team
+linear open --team ENG
+
+# Open inbox
+linear open --inbox
+
+# Open my issues
+linear open --my-issues
+
+# Open settings
+linear open --settings
+```
+
+### User Info
+
+```bash
+# Show current user
+linear me
+linear whoami
+
+# With table format
+linear me --format table
 ```
 
 ### Schema Introspection (for LLMs)
@@ -97,7 +312,9 @@ linear query --gql "query(\$id: String!) { issue(id: \$id) { title } }" \
 
 ## Output Format
 
-All commands return structured JSON:
+### JSON (default)
+
+All commands return structured JSON by default, ideal for LLMs and scripts:
 
 ```json
 // Success
@@ -126,6 +343,37 @@ All commands return structured JSON:
 }
 ```
 
+### Table (human-readable)
+
+Use `--format table` for colored, human-readable output:
+
+```bash
+linear issues list --format table
+# ID        PRI     TITLE
+# ENG-123   High    Fix login bug
+# ENG-124   Medium  Add dark mode
+```
+
+### Plain (minimal)
+
+Use `--format plain` for minimal output (IDs/identifiers only):
+
+```bash
+linear issues list --format plain
+# ENG-123    Fix login bug
+# ENG-124    Add dark mode
+```
+
+### Disabling Colors
+
+Colors are automatically disabled when piping output. You can also disable them manually:
+
+```bash
+NO_COLOR=1 linear issues list --format table
+# or
+linear issues list --format table --no-color
+```
+
 ## For LLM Integration
 
 The CLI is designed to be easily used by LLMs and AI agents:

package/dist/commands/comments/add.d.ts

@@ -0,0 +1,13 @@
+import { Command } from '@oclif/core';
+export default class CommentsAdd extends Command {
+    static description: string;
+    static examples: string[];
+    static args: {
+        issue: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        format: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        body: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/comments/add.js

@@ -0,0 +1,89 @@
+import { Args, Command, Flags } from '@oclif/core';
+import { getClient } from '../../lib/client.js';
+import { success, print, printItem } from '../../lib/output.js';
+import { handleError, CliError, ErrorCodes } from '../../lib/errors.js';
+import { resolveIssueId } from '../../lib/issue-utils.js';
+export default class CommentsAdd extends Command {
+    static description = 'Add a comment to an issue';
+    static examples = [
+        '<%= config.bin %> comments add ENG-123 --body "This is a comment"',
+        '<%= config.bin %> comments add ENG-123 --body "Looks good!" --format table',
+    ];
+    static args = {
+        issue: Args.string({
+            description: 'Issue ID or identifier (e.g., ENG-123)',
+            required: true,
+        }),
+    };
+    static flags = {
+        format: Flags.string({
+            char: 'F',
+            description: 'Output format',
+            options: ['json', 'table', 'plain'],
+            default: 'json',
+        }),
+        body: Flags.string({
+            char: 'b',
+            description: 'Comment body (supports markdown)',
+            required: true,
+        }),
+    };
+    async run() {
+        try {
+            const { args, flags } = await this.parse(CommentsAdd);
+            const format = flags.format;
+            const client = getClient();
+            const issueId = await resolveIssueId(client, args.issue);
+            const issue = await client.issue(issueId);
+            if (!issue) {
+                throw new CliError(ErrorCodes.NOT_FOUND, `Issue ${args.issue} not found`);
+            }
+            const payload = await client.createComment({
+                issueId,
+                body: flags.body,
+            });
+            if (!payload.success || !payload.comment) {
+                throw new CliError(ErrorCodes.API_ERROR, 'Failed to create comment');
+            }
+            const comment = await payload.comment;
+            const user = await comment.user;
+            const data = {
+                id: comment.id,
+                body: comment.body,
+                createdAt: comment.createdAt,
+                user: user
+                    ? {
+                        id: user.id,
+                        name: user.name,
+                        email: user.email,
+                    }
+                    : null,
+                issue: {
+                    id: issue.id,
+                    identifier: issue.identifier,
+                    title: issue.title,
+                },
+            };
+            if (format === 'json') {
+                print(success(data));
+            }
+            else if (format === 'table') {
+                printItem({
+                    id: data.id,
+                    issue: data.issue.identifier,
+                    user: data.user?.name ?? 'Unknown',
+                    body: data.body,
+                    createdAt: data.createdAt,
+                }, format);
+            }
+            else {
+                // plain: just the comment ID
+                console.log(data.id);
+            }
+        }
+        catch (err) {
+            handleError(err);
+            this.exit(1);
+        }
+    }
+}

package/dist/commands/comments/delete.d.ts

@@ -0,0 +1,12 @@
+import { Command } from '@oclif/core';
+export default class CommentsDelete extends Command {
+    static description: string;
+    static examples: string[];
+    static args: {
+        id: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        format: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/comments/delete.js

@@ -0,0 +1,50 @@
+import { Args, Command, Flags } from '@oclif/core';
+import { getClient } from '../../lib/client.js';
+import { success, print } from '../../lib/output.js';
+import { handleError, CliError, ErrorCodes } from '../../lib/errors.js';
+export default class CommentsDelete extends Command {
+    static description = 'Delete a comment';
+    static examples = ['<%= config.bin %> comments delete COMMENT_ID'];
+    static args = {
+        id: Args.string({
+            description: 'Comment ID',
+            required: true,
+        }),
+    };
+    static flags = {
+        format: Flags.string({
+            char: 'F',
+            description: 'Output format',
+            options: ['json', 'table', 'plain'],
+            default: 'json',
+        }),
+    };
+    async run() {
+        try {
+            const { args, flags } = await this.parse(CommentsDelete);
+            const format = flags.format;
+            const client = getClient();
+            const payload = await client.deleteComment(args.id);
+            if (!payload.success) {
+                throw new CliError(ErrorCodes.API_ERROR, 'Failed to delete comment');
+            }
+            const data = {
+                id: args.id,
+                deleted: true,
+            };
+            if (format === 'json') {
+                print(success(data));
+            }
+            else if (format === 'table') {
+                console.log(`Comment ${args.id} deleted successfully`);
+            }
+            else {
+                console.log(args.id);
+            }
+        }
+        catch (err) {
+            handleError(err);
+            this.exit(1);
+        }
+    }
+}

package/dist/commands/comments/list.d.ts

@@ -0,0 +1,14 @@
+import { Command } from '@oclif/core';
+export default class CommentsList extends Command {
+    static description: string;
+    static examples: string[];
+    static args: {
+        issue: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        format: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        first: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+        after: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/comments/list.js

@@ -0,0 +1,103 @@
+import { Args, Command, Flags } from '@oclif/core';
+import { getClient } from '../../lib/client.js';
+import { successList, print, printList } from '../../lib/output.js';
+import { handleError, CliError, ErrorCodes } from '../../lib/errors.js';
+import { resolveIssueId } from '../../lib/issue-utils.js';
+import { colors, truncate } from '../../lib/formatter.js';
+const COLUMNS = [
+    {
+        key: 'userName',
+        header: 'USER',
+        format: (value) => colors.cyan(String(value)),
+    },
+    {
+        key: 'body',
+        header: 'COMMENT',
+        format: (value) => truncate(String(value).replace(/\n/g, ' '), 60),
+    },
+    {
+        key: 'createdAt',
+        header: 'DATE',
+        format: (value) => {
+            const date = new Date(value);
+            return colors.dim(date.toLocaleDateString());
+        },
+    },
+];
+export default class CommentsList extends Command {
+    static description = 'List comments on an issue';
+    static examples = [
+        '<%= config.bin %> comments list ENG-123',
+        '<%= config.bin %> comments list ENG-123 --format table',
+    ];
+    static args = {
+        issue: Args.string({
+            description: 'Issue ID or identifier (e.g., ENG-123)',
+            required: true,
+        }),
+    };
+    static flags = {
+        format: Flags.string({
+            char: 'F',
+            description: 'Output format',
+            options: ['json', 'table', 'plain'],
+            default: 'json',
+        }),
+        first: Flags.integer({
+            description: 'Number of comments to fetch (default: 50)',
+            default: 50,
+        }),
+        after: Flags.string({
+            description: 'Cursor for pagination',
+        }),
+    };
+    async run() {
+        try {
+            const { args, flags } = await this.parse(CommentsList);
+            const format = flags.format;
+            const client = getClient();
+            const issueId = await resolveIssueId(client, args.issue);
+            const issue = await client.issue(issueId);
+            if (!issue) {
+                throw new CliError(ErrorCodes.NOT_FOUND, `Issue ${args.issue} not found`);
+            }
+            const comments = await issue.comments({
+                first: flags.first,
+                after: flags.after,
+            });
+            const data = await Promise.all(comments.nodes.map(async (comment) => {
+                const user = await comment.user;
+                return {
+                    id: comment.id,
+                    body: comment.body,
+                    createdAt: comment.createdAt,
+                    updatedAt: comment.updatedAt,
+                    userId: user?.id ?? '',
+                    userName: user?.name ?? 'Unknown',
+                    userEmail: user?.email ?? '',
+                };
+            }));
+            const pageInfo = {
+                hasNextPage: comments.pageInfo.hasNextPage,
+                hasPreviousPage: comments.pageInfo.hasPreviousPage,
+                startCursor: comments.pageInfo.startCursor,
+                endCursor: comments.pageInfo.endCursor,
+            };
+            if (format === 'json') {
+                print(successList(data, pageInfo));
+            }
+            else {
+                printList(data, format, {
+                    columns: COLUMNS,
+                    primaryKey: 'userName',
+                    secondaryKey: 'body',
+                    pageInfo,
+                });
+            }
+        }
+        catch (err) {
+            handleError(err);
+            this.exit(1);
+        }
+    }
+}

package/dist/commands/comments/update.d.ts

@@ -0,0 +1,13 @@
+import { Command } from '@oclif/core';
+export default class CommentsUpdate extends Command {
+    static description: string;
+    static examples: string[];
+    static args: {
+        id: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        format: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        body: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/comments/update.js

@@ -0,0 +1,81 @@
+import { Args, Command, Flags } from '@oclif/core';
+import { getClient } from '../../lib/client.js';
+import { success, print, printItem } from '../../lib/output.js';
+import { handleError, CliError, ErrorCodes } from '../../lib/errors.js';
+export default class CommentsUpdate extends Command {
+    static description = 'Update a comment';
+    static examples = ['<%= config.bin %> comments update COMMENT_ID --body "Updated comment text"'];
+    static args = {
+        id: Args.string({
+            description: 'Comment ID',
+            required: true,
+        }),
+    };
+    static flags = {
+        format: Flags.string({
+            char: 'F',
+            description: 'Output format',
+            options: ['json', 'table', 'plain'],
+            default: 'json',
+        }),
+        body: Flags.string({
+            char: 'b',
+            description: 'Comment body (supports markdown)',
+            required: true,
+        }),
+    };
+    async run() {
+        try {
+            const { args, flags } = await this.parse(CommentsUpdate);
+            const format = flags.format;
+            const client = getClient();
+            const payload = await client.updateComment(args.id, {
+                body: flags.body,
+            });
+            if (!payload.success || !payload.comment) {
+                throw new CliError(ErrorCodes.API_ERROR, 'Failed to update comment');
+            }
+            const comment = await payload.comment;
+            const [user, issue] = await Promise.all([comment.user, comment.issue]);
+            const data = {
+                id: comment.id,
+                body: comment.body,
+                createdAt: comment.createdAt,
+                updatedAt: comment.updatedAt,
+                user: user
+                    ? {
+                        id: user.id,
+                        name: user.name,
+                        email: user.email,
+                    }
+                    : null,
+                issue: issue
+                    ? {
+                        id: issue.id,
+                        identifier: issue.identifier,
+                        title: issue.title,
+                    }
+                    : null,
+            };
+            if (format === 'json') {
+                print(success(data));
+            }
+            else if (format === 'table') {
+                printItem({
+                    id: data.id,
+                    issue: data.issue?.identifier ?? 'N/A',
+                    user: data.user?.name ?? 'Unknown',
+                    body: data.body,
+                    updatedAt: data.updatedAt,
+                }, format);
+            }
+            else {
+                console.log(data.id);
+            }
+        }
+        catch (err) {
+            handleError(err);
+            this.exit(1);
+        }
+    }
+}