linear-cli-agents 0.5.0 → 0.6.0

package/README.md

@@ -10,6 +10,9 @@ 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
+- **Comprehensive docs**: `linear info` returns full CLI documentation in one command
+- **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
 - **Issue relations**: Manage blocks, duplicates, and related issues
@@ -27,6 +30,25 @@ npm install -g linear-cli-agents
 pnpm add -g linear-cli-agents
 ```
 
+## Quick Start
+
+```bash
+# Install
+npm install -g linear-cli-agents
+
+# Authenticate
+linear auth login
+
+# Get full CLI documentation (recommended for LLMs)
+linear info
+
+# Configure default team (optional, skips --team-id on every command)
+linear config set default-team-id YOUR_TEAM_ID
+
+# Add CLI instructions to your CLAUDE.md (optional)
+linear setup
+```
+
 ## Authentication
 
 ```bash
@@ -49,6 +71,20 @@ linear me
 linear auth logout
 ```
 
+## Configuration
+
+```bash
+# Set default team (skips --team-id on create commands)
+linear config set default-team-id YOUR_TEAM_UUID
+linear config set default-team-key TEAM_KEY
+
+# Get a config value
+linear config get default-team-id
+
+# List all config
+linear config list
+```
+
 ## Usage
 
 ### Issues
@@ -89,6 +125,14 @@ 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
+
+# Bulk update multiple issues at once
+linear issues bulk-update --ids ENG-1,ENG-2,ENG-3 --state-id STATE_ID
+linear issues bulk-update --ids ENG-1,ENG-2 --priority 2 --assignee-id USER_ID
+
+# Bulk add/remove labels from multiple issues
+linear issues bulk-label --ids ENG-1,ENG-2,ENG-3 --add-labels LABEL1,LABEL2
+linear issues bulk-label --ids ENG-1,ENG-2 --remove-labels LABEL1
 ```
 
 ### Projects
@@ -225,6 +269,25 @@ 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
+```
+
 ### Users
 
 ```bash
@@ -378,25 +441,36 @@ linear issues list --format table --no-color
 
 The CLI is designed to be easily used by LLMs and AI agents:
 
-1. **Discover capabilities**: Use `linear schema` to understand available operations
+1. **Single discovery command**: Use `linear info` to get complete documentation in one JSON response
 2. **Structured output**: All responses are JSON with consistent format
-3. **Error codes**: Programmatic error handling via error codes
-4. **Raw queries**: Use `linear query` for complex operations not covered by built-in commands
+3. **Configurable defaults**: Set default team to reduce command complexity
+4. **Bulk operations**: Update multiple issues efficiently
+5. **Error codes**: Programmatic error handling via error codes
 
 ### Example LLM Workflow
 
 ```bash
-# 1. Discover what operations are available
-linear schema
+# 1. Get complete CLI documentation in one command
+linear info
 
-# 2. Get details about issues
-linear schema issues
+# 2. Or get compact version for limited context
+linear info --compact
 
-# 3. List issues assigned to current user
-linear issues list --assignee me
+# 3. Create issues (uses default team if configured)
+linear issues create --title "From LLM"
+
+# 4. Bulk update multiple issues
+linear issues bulk-update --ids ENG-1,ENG-2,ENG-3 --state-id STATE_ID
+```
+
+### Claude Code Integration
+
+```bash
+# Add CLI instructions to CLAUDE.md
+linear setup
 
-# 4. Create a new issue
-linear issues create --input '{"title":"From LLM","teamId":"xxx"}'
+# Remove instructions
+linear setup --remove
 ```
 
 ## Development

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/info.js

@@ -435,6 +435,40 @@ const COMMANDS = {
         flags: { format: { type: 'string', options: ['json', 'table', 'plain'], default: 'json' } },
         examples: ['linear me'],
     },
+    // Cycles
+    'cycles list': {
+        description: 'List cycles (sprints)',
+        flags: {
+            format: { type: 'string', options: ['json', 'table', 'plain'], default: 'json' },
+            'team-id': { type: 'string', description: 'Filter by team ID' },
+            team: { type: 'string', description: 'Filter by team key (e.g., ENG)' },
+            active: { type: 'boolean', description: 'Show only active cycles' },
+            upcoming: { type: 'boolean', description: 'Show only upcoming cycles' },
+            completed: { type: 'boolean', description: 'Show only completed cycles' },
+            first: { type: 'number', description: 'Number of results' },
+        },
+        examples: [
+            'linear cycles list',
+            'linear cycles list --team ENG',
+            'linear cycles list --active',
+        ],
+    },
+    'cycles get': {
+        description: 'Get cycle (sprint) details',
+        args: { id: { description: 'Cycle ID', required: true } },
+        flags: { format: { type: 'string', options: ['json', 'table', 'plain'], default: 'json' } },
+        examples: ['linear cycles get CYCLE_ID'],
+    },
+    'cycles current': {
+        description: 'Get the current active cycle for a team',
+        flags: {
+            format: { type: 'string', options: ['json', 'table', 'plain'], default: 'json' },
+            'team-id': { type: 'string', description: 'Team ID' },
+            team: { type: 'string', description: 'Team key (e.g., ENG)' },
+        },
+        examples: ['linear cycles current --team ENG'],
+    },
+    // Other
     search: {
         description: 'Search for issues',
         args: { query: { description: 'Search query', required: true } },
@@ -516,6 +550,20 @@ const ENTITY_SCHEMAS = {
             teams: 'Associated teams',
         },
     },
+    cycles: {
+        entity: 'cycles',
+        operations: ['list', 'get', 'current'],
+        description: 'Time-boxed iterations (sprints)',
+        fields: {
+            id: 'Unique identifier',
+            number: 'Cycle number',
+            name: 'Cycle name (optional)',
+            startsAt: 'Start date',
+            endsAt: 'End date',
+            progress: 'Completion progress (0-1)',
+            team: 'Associated team',
+        },
+    },
     teams: {
         entity: 'teams',
         operations: ['list'],
@@ -644,7 +692,7 @@ export default class Info extends Command {
                 return acc;
             }, {});
             print(success({
-                version: '0.5.0',
+                version: '0.6.0',
                 commands: compactCommands,
                 configKeys: CONFIG_KEYS,
                 note: 'Use "linear info" for full documentation with examples and workflows',
@@ -653,7 +701,7 @@ export default class Info extends Command {
         }
         // Full documentation
         print(success({
-            version: '0.5.0',
+            version: '0.6.0',
             overview: {
                 description: 'CLI for interacting with Linear, designed for LLMs and agents',
                 authentication: 'Run "linear auth login" or set LINEAR_API_KEY environment variable',

package/dist/lib/formatter.d.ts

@@ -49,6 +49,10 @@ export declare const formatPriority: (priority: number) => string;
  * Truncate string to max length with ellipsis.
  */
 export declare const truncate: (str: string | undefined | null, maxLength: number) => string;
+/**
+ * Format progress as a percentage with color.
+ */
+export declare const formatProgress: (progress: number) => string;
 /**
  * Generic formatter that outputs data in the specified format.
  */

package/dist/lib/formatter.js

@@ -166,6 +166,21 @@ export const truncate = (str, maxLength) => {
         return str;
     return str.slice(0, maxLength - 1) + '\u2026';
 };
+/**
+ * Format progress as a percentage with color.
+ */
+export const formatProgress = (progress) => {
+    const percent = Math.round(progress * 100);
+    if (percent >= 100)
+        return colors.green(`${percent}%`);
+    if (percent >= 75)
+        return colors.cyan(`${percent}%`);
+    if (percent >= 50)
+        return colors.blue(`${percent}%`);
+    if (percent >= 25)
+        return colors.yellow(`${percent}%`);
+    return colors.gray(`${percent}%`);
+};
 /**
  * Generic formatter that outputs data in the specified format.
  */