linear-cli-agents 0.2.1 → 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.
@@ -11,9 +11,12 @@ A CLI for interacting with [Linear](https://linear.app), designed for LLMs and a
 - **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
-- **Team management**: List and browse teams
+- **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
@@ -78,6 +81,166 @@ 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

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);
+        }
+    }
+}

package/dist/commands/issues/add-labels.d.ts

@@ -0,0 +1,13 @@
+import { Command } from '@oclif/core';
+export default class IssuesAddLabels 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>;
+        'label-ids': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/issues/add-labels.js

@@ -0,0 +1,90 @@
+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 IssuesAddLabels extends Command {
+    static description = 'Add labels to an issue';
+    static examples = ['<%= config.bin %> issues add-labels ENG-123 --label-ids LABEL_ID1,LABEL_ID2'];
+    static args = {
+        id: 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',
+        }),
+        'label-ids': Flags.string({
+            description: 'Comma-separated label IDs to add',
+            required: true,
+        }),
+    };
+    async run() {
+        try {
+            const { args, flags } = await this.parse(IssuesAddLabels);
+            const format = flags.format;
+            const client = getClient();
+            const issueId = await resolveIssueId(client, args.id);
+            const issue = await client.issue(issueId);
+            if (!issue) {
+                throw new CliError(ErrorCodes.NOT_FOUND, `Issue ${args.id} not found`);
+            }
+            // Get existing labels
+            const existingLabels = await issue.labels();
+            const existingLabelIds = existingLabels.nodes.map((l) => l.id);
+            // Parse new label IDs
+            const newLabelIds = flags['label-ids'].split(',').map((id) => id.trim());
+            // Combine existing and new labels (avoiding duplicates)
+            const combinedLabelIds = [...new Set([...existingLabelIds, ...newLabelIds])];
+            // Update the issue with combined labels
+            const payload = await client.updateIssue(issueId, {
+                labelIds: combinedLabelIds,
+            });
+            if (!payload.success) {
+                throw new CliError(ErrorCodes.API_ERROR, 'Failed to add labels to issue');
+            }
+            const updatedIssue = await payload.issue;
+            if (!updatedIssue) {
+                throw new CliError(ErrorCodes.API_ERROR, 'Issue not found in response');
+            }
+            const labels = await updatedIssue.labels();
+            const data = {
+                id: updatedIssue.id,
+                identifier: updatedIssue.identifier,
+                title: updatedIssue.title,
+                labels: labels.nodes.map((l) => ({
+                    id: l.id,
+                    name: l.name,
+                    color: l.color,
+                })),
+                labelsAdded: newLabelIds.filter((id) => !existingLabelIds.includes(id)),
+                url: updatedIssue.url,
+            };
+            if (format === 'json') {
+                print(success(data));
+            }
+            else if (format === 'table') {
+                printItem({
+                    id: data.id,
+                    identifier: data.identifier,
+                    title: data.title,
+                    labels: data.labels.map((l) => l.name).join(', '),
+                    labelsAdded: data.labelsAdded.length,
+                    url: data.url,
+                }, format);
+            }
+            else {
+                console.log(data.identifier);
+            }
+        }
+        catch (err) {
+            handleError(err);
+            this.exit(1);
+        }
+    }
+}