linear-cli-agents 0.5.1 → 0.7.0

package/README.md

@@ -14,7 +14,7 @@ A CLI for interacting with [Linear](https://linear.app), designed for LLMs and a
 - **Configurable defaults**: Set default team to skip `--team-id` on every command
 - **Bulk operations**: Update multiple issues at once with `bulk-update` and `bulk-label`
 - **Schema introspection**: Discover available operations programmatically
-- **Full CRUD**: Issues, projects, labels, comments, templates, milestones
+- **Full CRUD**: Issues, projects, labels, comments, templates, milestones, documents, initiatives
 - **Issue relations**: Manage blocks, duplicates, and related issues
 - **Project management**: Projects, milestones, and status updates
 - **Team management**: List and browse teams, states, users
@@ -106,9 +106,12 @@ linear issues list --format plain
 # Get a specific issue
 linear issues get ENG-123
 linear issues get ENG-123 --format table
+linear issues get ENG-123 --with-attachments  # Include linked PRs, commits
 
 # Create an issue
 linear issues create --title "Bug fix" --team-id <team-id>
+linear issues create --title "Task" --team-id <team-id> --due-date 2024-12-31
+linear issues create --title "Sprint work" --team-id <team-id> --cycle-id <cycle-id>
 linear issues create --input '{"title":"Feature","teamId":"xxx","priority":2}'
 
 # Update an issue
@@ -269,6 +272,89 @@ linear states list
 linear states list --team ENG
 ```
 
+### Cycles (Sprints)
+
+```bash
+# List all cycles
+linear cycles list
+linear cycles list --team ENG
+
+# Filter by status
+linear cycles list --active      # Currently running
+linear cycles list --upcoming    # Future cycles
+linear cycles list --completed   # Past cycles
+
+# Get current cycle for a team
+linear cycles current --team ENG
+
+# Get cycle details
+linear cycles get CYCLE_ID
+```
+
+### Documents
+
+```bash
+# List documents
+linear documents list
+
+# Get document details
+linear documents get DOCUMENT_ID
+
+# Create a document
+linear documents create --title "Meeting Notes"
+linear documents create --title "Specs" --content "# Overview\n\nDetails here..."
+linear documents create --title "Project Doc" --project-id PROJECT_ID
+
+# Update a document
+linear documents update DOCUMENT_ID --title "New Title"
+linear documents update DOCUMENT_ID --content "Updated content"
+
+# Delete a document
+linear documents delete DOCUMENT_ID
+```
+
+### Initiatives
+
+```bash
+# List initiatives
+linear initiatives list
+linear initiatives list --status Active
+linear initiatives list --status Completed
+
+# Get initiative details
+linear initiatives get INITIATIVE_ID
+
+# Create an initiative
+linear initiatives create --name "Q1 Goals"
+linear initiatives create --name "Product Launch" --status Active --target-date 2024-12-31
+
+# Update an initiative
+linear initiatives update INITIATIVE_ID --name "New Name"
+linear initiatives update INITIATIVE_ID --status Completed
+
+# Archive/unarchive an initiative
+linear initiatives archive INITIATIVE_ID
+linear initiatives archive INITIATIVE_ID --unarchive
+
+# Delete an initiative
+linear initiatives delete INITIATIVE_ID
+```
+
+### Upload Files
+
+```bash
+# Upload a file and get the asset URL
+linear upload ./screenshot.png
+linear upload ./document.pdf
+
+# Output as markdown (for embedding in descriptions)
+linear upload ./image.png --markdown
+# Returns: ![image.png](https://linear-uploads.s3.amazonaws.com/...)
+
+# Specify content type
+linear upload ./file.dat --content-type application/octet-stream
+```
+
 ### Users
 
 ```bash

package/dist/commands/cycles/current.d.ts

@@ -0,0 +1,11 @@
+import { Command } from '@oclif/core';
+export default class CyclesCurrent extends Command {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        format: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        'team-id': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        team: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/cycles/current.js

@@ -0,0 +1,104 @@
+import { 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 CyclesCurrent extends Command {
+    static description = 'Get the current active cycle for a team';
+    static examples = [
+        '<%= config.bin %> cycles current --team ENG',
+        '<%= config.bin %> cycles current --team-id TEAM_ID',
+        '<%= config.bin %> cycles current --team ENG --format table',
+    ];
+    static flags = {
+        format: Flags.string({
+            char: 'F',
+            description: 'Output format',
+            options: ['json', 'table', 'plain'],
+            default: 'json',
+        }),
+        'team-id': Flags.string({
+            description: 'Team ID',
+            exclusive: ['team'],
+        }),
+        team: Flags.string({
+            description: 'Team key (e.g., ENG)',
+            exclusive: ['team-id'],
+        }),
+    };
+    async run() {
+        try {
+            const { flags } = await this.parse(CyclesCurrent);
+            const format = flags.format;
+            const client = getClient();
+            if (!flags['team-id'] && !flags.team) {
+                throw new CliError(ErrorCodes.MISSING_REQUIRED_FIELD, 'Team is required. Use --team or --team-id');
+            }
+            // Build filter for active cycle
+            const now = new Date();
+            const filter = {
+                startsAt: { lte: now },
+                endsAt: { gte: now },
+            };
+            if (flags['team-id']) {
+                filter.team = { id: { eq: flags['team-id'] } };
+            }
+            else if (flags.team) {
+                filter.team = { key: { eq: flags.team } };
+            }
+            const cycles = await client.cycles({
+                first: 1,
+                filter,
+            });
+            if (cycles.nodes.length === 0) {
+                throw new CliError(ErrorCodes.NOT_FOUND, 'No active cycle found for this team');
+            }
+            const cycle = cycles.nodes[0];
+            const [team, issues] = await Promise.all([cycle.team, cycle.issues()]);
+            const issuesSummary = {
+                total: issues.nodes.length,
+                completed: issues.nodes.filter((i) => i.completedAt).length,
+            };
+            const data = {
+                id: cycle.id,
+                number: cycle.number,
+                name: cycle.name ?? null,
+                description: cycle.description ?? null,
+                startsAt: cycle.startsAt,
+                endsAt: cycle.endsAt,
+                progress: cycle.progress,
+                team: team
+                    ? {
+                        id: team.id,
+                        key: team.key,
+                        name: team.name,
+                    }
+                    : null,
+                issues: issuesSummary,
+                daysRemaining: Math.ceil((new Date(cycle.endsAt).getTime() - now.getTime()) / (1000 * 60 * 60 * 24)),
+            };
+            if (format === 'json') {
+                print(success(data));
+            }
+            else if (format === 'table') {
+                printItem({
+                    id: data.id,
+                    number: data.number,
+                    name: data.name ?? 'Unnamed',
+                    team: data.team?.key ?? 'N/A',
+                    startsAt: data.startsAt,
+                    endsAt: data.endsAt,
+                    progress: `${Math.round(data.progress * 100)}%`,
+                    issues: `${issuesSummary.completed}/${issuesSummary.total} completed`,
+                    daysRemaining: `${data.daysRemaining} days`,
+                }, format);
+            }
+            else {
+                console.log(data.id);
+            }
+        }
+        catch (err) {
+            handleError(err);
+            this.exit(1);
+        }
+    }
+}

package/dist/commands/cycles/get.d.ts

@@ -0,0 +1,12 @@
+import { Command } from '@oclif/core';
+export default class CyclesGet 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/cycles/get.js

@@ -0,0 +1,86 @@
+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 CyclesGet extends Command {
+    static description = 'Get cycle (sprint) details';
+    static examples = [
+        '<%= config.bin %> cycles get CYCLE_ID',
+        '<%= config.bin %> cycles get CYCLE_ID --format table',
+    ];
+    static args = {
+        id: Args.string({
+            description: 'Cycle 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(CyclesGet);
+            const format = flags.format;
+            const client = getClient();
+            const cycle = await client.cycle(args.id);
+            if (!cycle) {
+                throw new CliError(ErrorCodes.NOT_FOUND, `Cycle ${args.id} not found`);
+            }
+            const [team, issues] = await Promise.all([cycle.team, cycle.issues()]);
+            const issuesSummary = {
+                total: issues.nodes.length,
+                completed: issues.nodes.filter((i) => i.completedAt).length,
+            };
+            const data = {
+                id: cycle.id,
+                number: cycle.number,
+                name: cycle.name ?? null,
+                description: cycle.description ?? null,
+                startsAt: cycle.startsAt,
+                endsAt: cycle.endsAt,
+                completedAt: cycle.completedAt ?? null,
+                progress: cycle.progress,
+                scopeHistory: cycle.scopeHistory,
+                completedScopeHistory: cycle.completedScopeHistory,
+                team: team
+                    ? {
+                        id: team.id,
+                        key: team.key,
+                        name: team.name,
+                    }
+                    : null,
+                issues: issuesSummary,
+                createdAt: cycle.createdAt,
+                updatedAt: cycle.updatedAt,
+            };
+            if (format === 'json') {
+                print(success(data));
+            }
+            else if (format === 'table') {
+                printItem({
+                    id: data.id,
+                    number: data.number,
+                    name: data.name ?? 'Unnamed',
+                    team: data.team?.key ?? 'N/A',
+                    startsAt: data.startsAt,
+                    endsAt: data.endsAt,
+                    completedAt: data.completedAt ?? 'In progress',
+                    progress: `${Math.round(data.progress * 100)}%`,
+                    issues: `${issuesSummary.completed}/${issuesSummary.total} completed`,
+                }, format);
+            }
+            else {
+                console.log(data.id);
+            }
+        }
+        catch (err) {
+            handleError(err);
+            this.exit(1);
+        }
+    }
+}

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

@@ -0,0 +1,16 @@
+import { Command } from '@oclif/core';
+export default class CyclesList extends Command {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        format: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        'team-id': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        team: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        active: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        upcoming: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        completed: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        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/cycles/list.js

@@ -0,0 +1,147 @@
+import { Command, Flags } from '@oclif/core';
+import { getClient } from '../../lib/client.js';
+import { successList, print, printList } from '../../lib/output.js';
+import { handleError } from '../../lib/errors.js';
+import { colors, truncate, formatProgress } from '../../lib/formatter.js';
+const COLUMNS = [
+    {
+        key: 'number',
+        header: '#',
+        format: (value) => colors.dim(String(value)),
+    },
+    {
+        key: 'name',
+        header: 'NAME',
+        format: (value) => (value ? colors.bold(truncate(String(value), 25)) : colors.gray('Unnamed')),
+    },
+    {
+        key: 'teamKey',
+        header: 'TEAM',
+        format: (value) => colors.cyan(String(value)),
+    },
+    {
+        key: 'startsAt',
+        header: 'START',
+        format: (value) => colors.dim(new Date(value).toISOString().split('T')[0]),
+    },
+    {
+        key: 'endsAt',
+        header: 'END',
+        format: (value) => colors.dim(new Date(value).toISOString().split('T')[0]),
+    },
+    {
+        key: 'progress',
+        header: 'PROGRESS',
+        format: (value) => formatProgress(Number(value)),
+    },
+];
+export default class CyclesList extends Command {
+    static description = 'List cycles (sprints)';
+    static examples = [
+        '<%= config.bin %> cycles list',
+        '<%= config.bin %> cycles list --team-id TEAM_ID',
+        '<%= config.bin %> cycles list --team ENG',
+        '<%= config.bin %> cycles list --format table',
+        '<%= config.bin %> cycles list --active',
+    ];
+    static flags = {
+        format: Flags.string({
+            char: 'F',
+            description: 'Output format',
+            options: ['json', 'table', 'plain'],
+            default: 'json',
+        }),
+        'team-id': Flags.string({
+            description: 'Filter by team ID',
+        }),
+        team: Flags.string({
+            description: 'Filter by team key (e.g., ENG)',
+        }),
+        active: Flags.boolean({
+            description: 'Show only active cycles',
+            default: false,
+        }),
+        upcoming: Flags.boolean({
+            description: 'Show only upcoming cycles',
+            default: false,
+        }),
+        completed: Flags.boolean({
+            description: 'Show only completed cycles',
+            default: false,
+        }),
+        first: Flags.integer({
+            description: 'Number of cycles to fetch (default: 50)',
+            default: 50,
+        }),
+        after: Flags.string({
+            description: 'Cursor for pagination',
+        }),
+    };
+    async run() {
+        try {
+            const { flags } = await this.parse(CyclesList);
+            const format = flags.format;
+            const client = getClient();
+            // Build filter
+            const filter = {};
+            if (flags['team-id']) {
+                filter.team = { id: { eq: flags['team-id'] } };
+            }
+            else if (flags.team) {
+                filter.team = { key: { eq: flags.team } };
+            }
+            const now = new Date();
+            if (flags.active) {
+                filter.startsAt = { lte: now };
+                filter.endsAt = { gte: now };
+            }
+            else if (flags.upcoming) {
+                filter.startsAt = { gt: now };
+            }
+            else if (flags.completed) {
+                filter.completedAt = { neq: null };
+            }
+            const cycles = await client.cycles({
+                first: flags.first,
+                after: flags.after,
+                filter: Object.keys(filter).length > 0 ? filter : undefined,
+            });
+            const data = await Promise.all(cycles.nodes.map(async (cycle) => {
+                const team = await cycle.team;
+                return {
+                    id: cycle.id,
+                    number: cycle.number,
+                    name: cycle.name ?? null,
+                    startsAt: cycle.startsAt,
+                    endsAt: cycle.endsAt,
+                    completedAt: cycle.completedAt ?? null,
+                    progress: cycle.progress,
+                    teamId: team?.id ?? '',
+                    teamKey: team?.key ?? '',
+                    teamName: team?.name ?? '',
+                };
+            }));
+            const pageInfo = {
+                hasNextPage: cycles.pageInfo.hasNextPage,
+                hasPreviousPage: cycles.pageInfo.hasPreviousPage,
+                startCursor: cycles.pageInfo.startCursor,
+                endCursor: cycles.pageInfo.endCursor,
+            };
+            if (format === 'json') {
+                print(successList(data, pageInfo));
+            }
+            else {
+                printList(data, format, {
+                    columns: COLUMNS,
+                    primaryKey: 'name',
+                    secondaryKey: 'number',
+                    pageInfo,
+                });
+            }
+        }
+        catch (err) {
+            handleError(err);
+            this.exit(1);
+        }
+    }
+}

package/dist/commands/documents/create.d.ts

@@ -0,0 +1,13 @@
+import { Command } from '@oclif/core';
+export default class DocumentsCreate extends Command {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        title: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        content: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'project-id': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        icon: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        color: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/documents/create.js

@@ -0,0 +1,68 @@
+import { 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 DocumentsCreate extends Command {
+    static description = 'Create a new document';
+    static examples = [
+        '<%= config.bin %> documents create --title "My Document"',
+        '<%= config.bin %> documents create --title "Project Doc" --project-id PROJECT_ID',
+        '<%= config.bin %> documents create --title "Notes" --content "# Heading\\n\\nContent here"',
+    ];
+    static flags = {
+        title: Flags.string({
+            char: 't',
+            description: 'Document title',
+            required: true,
+        }),
+        content: Flags.string({
+            char: 'c',
+            description: 'Document content (markdown)',
+        }),
+        'project-id': Flags.string({
+            description: 'Project ID to associate with',
+        }),
+        icon: Flags.string({
+            description: 'Document icon (emoji)',
+        }),
+        color: Flags.string({
+            description: 'Document color (hex)',
+        }),
+    };
+    async run() {
+        try {
+            const { flags } = await this.parse(DocumentsCreate);
+            const client = getClient();
+            const input = {
+                title: flags.title,
+            };
+            if (flags.content)
+                input.content = flags.content;
+            if (flags['project-id'])
+                input.projectId = flags['project-id'];
+            if (flags.icon)
+                input.icon = flags.icon;
+            if (flags.color)
+                input.color = flags.color;
+            const payload = await client.createDocument(input);
+            if (!payload.success) {
+                throw new CliError(ErrorCodes.API_ERROR, 'Failed to create document');
+            }
+            const document = await payload.document;
+            if (!document) {
+                throw new CliError(ErrorCodes.API_ERROR, 'Document not returned');
+            }
+            const project = await document.project;
+            print(success({
+                id: document.id,
+                title: document.title,
+                project: project ? { id: project.id, name: project.name } : null,
+                createdAt: document.createdAt,
+            }));
+        }
+        catch (err) {
+            handleError(err);
+            this.exit(1);
+        }
+    }
+}

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

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

package/dist/commands/documents/delete.js

@@ -0,0 +1,32 @@
+import { Args, Command } 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 DocumentsDelete extends Command {
+    static description = 'Delete a document (moves to trash)';
+    static examples = ['<%= config.bin %> documents delete DOCUMENT_ID'];
+    static args = {
+        id: Args.string({
+            description: 'Document ID',
+            required: true,
+        }),
+    };
+    async run() {
+        try {
+            const { args } = await this.parse(DocumentsDelete);
+            const client = getClient();
+            const payload = await client.deleteDocument(args.id);
+            if (!payload.success) {
+                throw new CliError(ErrorCodes.API_ERROR, 'Failed to delete document');
+            }
+            print(success({
+                id: args.id,
+                deleted: true,
+            }));
+        }
+        catch (err) {
+            handleError(err);
+            this.exit(1);
+        }
+    }
+}

package/dist/commands/documents/get.d.ts

@@ -0,0 +1,12 @@
+import { Command } from '@oclif/core';
+export default class DocumentsGet 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>;
+}