linear-cli-agents 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,168 @@
+# linear-cli
+
+A CLI for interacting with [Linear](https://linear.app), designed for LLMs and agents.
+
+## Features
+
+- **JSON output**: All commands return structured JSON, perfect for parsing by LLMs
+- **Schema introspection**: Discover available operations programmatically
+- **Full CRUD for issues**: List, create, update, and delete issues
+- **Raw GraphQL queries**: Execute any GraphQL query directly
+
+## Installation
+
+```bash
+npm install -g linear-cli
+# or
+pnpm add -g linear-cli
+```
+
+## Authentication
+
+Get your API key from [Linear Settings > API](https://linear.app/settings/api).
+
+```bash
+# Login with API key
+linear auth login --key lin_api_xxxxx
+
+# Or use environment variable
+export LINEAR_API_KEY=lin_api_xxxxx
+
+# Check auth status
+linear auth status
+
+# Logout
+linear auth logout
+```
+
+## Usage
+
+### Issues
+
+```bash
+# List all issues
+linear issues list
+
+# List with filters
+linear issues list --team ENG
+linear issues list --assignee me
+linear issues list --state "In Progress"
+linear issues list --filter '{"priority":{"lte":2}}'
+
+# Get a specific issue
+linear issues get ENG-123
+
+# Create an issue
+linear issues create --title "Bug fix" --team-id <team-id>
+linear issues create --input '{"title":"Feature","teamId":"xxx","priority":2}'
+
+# Update an issue
+linear issues update ENG-123 --title "Updated title"
+linear issues update ENG-123 --state-id <state-id> --assignee-id <user-id>
+
+# Delete an issue (moves to trash)
+linear issues delete ENG-123
+```
+
+### Schema Introspection (for LLMs)
+
+```bash
+# List available entities
+linear schema
+
+# Get schema for a specific entity
+linear schema issues
+
+# Get full schema (all entities)
+linear schema --full
+
+# Include usage examples
+linear schema issues --include-examples
+```
+
+### Raw GraphQL Queries
+
+```bash
+# Execute any GraphQL query
+linear query --gql "query { viewer { id name email } }"
+
+# With variables
+linear query --gql "query(\$id: String!) { issue(id: \$id) { title } }" \
+  --variables '{"id":"xxx"}'
+```
+
+## Output Format
+
+All commands return structured JSON:
+
+```json
+// Success
+{
+  "success": true,
+  "data": { ... }
+}
+
+// Success with pagination
+{
+  "success": true,
+  "data": [...],
+  "pageInfo": {
+    "hasNextPage": true,
+    "endCursor": "abc123"
+  }
+}
+
+// Error
+{
+  "success": false,
+  "error": {
+    "code": "NOT_FOUND",
+    "message": "Issue ENG-123 not found"
+  }
+}
+```
+
+## For LLM Integration
+
+The CLI is designed to be easily used by LLMs and AI agents:
+
+1. **Discover capabilities**: Use `linear schema` to understand available operations
+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
+
+### Example LLM Workflow
+
+```bash
+# 1. Discover what operations are available
+linear schema
+
+# 2. Get details about issues
+linear schema issues
+
+# 3. List issues assigned to current user
+linear issues list --assignee me
+
+# 4. Create a new issue
+linear issues create --input '{"title":"From LLM","teamId":"xxx"}'
+```
+
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Build
+pnpm build
+
+# Run in development
+./bin/dev.js issues list
+
+# Run tests
+pnpm test
+```
+
+## License
+
+MIT

package/bin/dev.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import {execute} from '@oclif/core'
+
+await execute({development: true, dir: import.meta.url})

package/bin/run.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import {execute} from '@oclif/core'
+
+await execute({dir: import.meta.url})

package/dist/commands/auth/login.d.ts

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

package/dist/commands/auth/login.js

@@ -0,0 +1,52 @@
+import { Args, Command, Flags } from '@oclif/core';
+import { createClient } from '../../lib/client.js';
+import { saveApiKey, getConfigPath } from '../../lib/config.js';
+import { success, print } from '../../lib/output.js';
+import { handleError, CliError, ErrorCodes } from '../../lib/errors.js';
+export default class AuthLogin extends Command {
+    static description = 'Authenticate with Linear using an API key';
+    static examples = [
+        '<%= config.bin %> auth login --key lin_api_xxxxx',
+        'LINEAR_API_KEY=lin_api_xxxxx <%= config.bin %> auth login',
+    ];
+    static flags = {
+        key: Flags.string({
+            char: 'k',
+            description: 'Linear API key (or set LINEAR_API_KEY env var)',
+            env: 'LINEAR_API_KEY',
+        }),
+    };
+    static args = {
+        key: Args.string({
+            description: 'Linear API key (alternative to --key flag)',
+            required: false,
+        }),
+    };
+    async run() {
+        try {
+            const { args, flags } = await this.parse(AuthLogin);
+            const apiKey = flags.key || args.key;
+            if (!apiKey) {
+                throw new CliError(ErrorCodes.MISSING_REQUIRED_FIELD, 'API key is required. Use --key flag or set LINEAR_API_KEY environment variable.');
+            }
+            // Validate the API key by making a test request
+            const client = createClient(apiKey);
+            const viewer = await client.viewer;
+            // Save the API key
+            saveApiKey(apiKey);
+            print(success({
+                message: 'Successfully authenticated',
+                user: {
+                    id: viewer.id,
+                    name: viewer.name,
+                    email: viewer.email,
+                },
+                configPath: getConfigPath(),
+            }));
+        }
+        catch (err) {
+            handleError(err);
+            this.exit(1);
+        }
+    }
+}

package/dist/commands/auth/logout.d.ts

@@ -0,0 +1,6 @@
+import { Command } from '@oclif/core';
+export default class AuthLogout extends Command {
+    static description: string;
+    static examples: string[];
+    run(): Promise<void>;
+}

package/dist/commands/auth/logout.js

@@ -0,0 +1,26 @@
+import { Command } from '@oclif/core';
+import { removeApiKey, getConfigPath, getApiKey } from '../../lib/config.js';
+import { success, print } from '../../lib/output.js';
+import { handleError, CliError, ErrorCodes } from '../../lib/errors.js';
+export default class AuthLogout extends Command {
+    static description = 'Remove stored Linear API key';
+    static examples = ['<%= config.bin %> auth logout'];
+    async run() {
+        await this.parse(AuthLogout);
+        try {
+            const apiKey = getApiKey();
+            if (!apiKey) {
+                throw new CliError(ErrorCodes.NOT_AUTHENTICATED, 'Not currently authenticated');
+            }
+            removeApiKey();
+            print(success({
+                message: 'Successfully logged out',
+                configPath: getConfigPath(),
+            }));
+        }
+        catch (err) {
+            handleError(err);
+            this.exit(1);
+        }
+    }
+}

package/dist/commands/auth/status.d.ts

@@ -0,0 +1,6 @@
+import { Command } from '@oclif/core';
+export default class AuthStatus extends Command {
+    static description: string;
+    static examples: string[];
+    run(): Promise<void>;
+}

package/dist/commands/auth/status.js

@@ -0,0 +1,40 @@
+import { Command } from '@oclif/core';
+import { getApiKey, getConfigPath } from '../../lib/config.js';
+import { createClient } from '../../lib/client.js';
+import { success, print } from '../../lib/output.js';
+import { handleError } from '../../lib/errors.js';
+export default class AuthStatus extends Command {
+    static description = 'Check authentication status';
+    static examples = ['<%= config.bin %> auth status'];
+    async run() {
+        await this.parse(AuthStatus);
+        try {
+            const apiKey = getApiKey();
+            if (!apiKey) {
+                print(success({
+                    authenticated: false,
+                    message: 'Not authenticated',
+                    configPath: getConfigPath(),
+                }));
+                return;
+            }
+            // Verify the API key is still valid
+            const client = createClient(apiKey);
+            const viewer = await client.viewer;
+            print(success({
+                authenticated: true,
+                user: {
+                    id: viewer.id,
+                    name: viewer.name,
+                    email: viewer.email,
+                },
+                source: process.env.LINEAR_API_KEY ? 'environment' : 'config',
+                configPath: getConfigPath(),
+            }));
+        }
+        catch (err) {
+            handleError(err);
+            this.exit(1);
+        }
+    }
+}

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

@@ -0,0 +1,18 @@
+import { Command } from '@oclif/core';
+export default class IssuesCreate extends Command {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        input: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        title: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'team-id': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        description: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        priority: import("@oclif/core/interfaces").OptionFlag<number | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'assignee-id': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'state-id': 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>;
+        estimate: import("@oclif/core/interfaces").OptionFlag<number | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'label-ids': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/issues/create.js

@@ -0,0 +1,109 @@
+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 IssuesCreate extends Command {
+    static description = 'Create a new issue';
+    static examples = [
+        '<%= config.bin %> issues create --input \'{"title":"Bug fix","teamId":"xxx"}\'',
+        '<%= config.bin %> issues create --title "New feature" --team-id xxx',
+        '<%= config.bin %> issues create --title "Task" --team-id xxx --description "Details here" --priority 2',
+    ];
+    static flags = {
+        input: Flags.string({
+            char: 'i',
+            description: 'JSON input object (IssueCreateInput)',
+            exclusive: ['title'],
+        }),
+        title: Flags.string({
+            description: 'Issue title',
+            exclusive: ['input'],
+        }),
+        'team-id': Flags.string({
+            description: 'Team ID',
+        }),
+        description: Flags.string({
+            char: 'd',
+            description: 'Issue description (markdown supported)',
+        }),
+        priority: Flags.integer({
+            char: 'p',
+            description: 'Priority (0=none, 1=urgent, 2=high, 3=medium, 4=low)',
+        }),
+        'assignee-id': Flags.string({
+            description: 'Assignee user ID',
+        }),
+        'state-id': Flags.string({
+            description: 'State ID',
+        }),
+        'project-id': Flags.string({
+            description: 'Project ID',
+        }),
+        estimate: Flags.integer({
+            description: 'Estimate points',
+        }),
+        'label-ids': Flags.string({
+            description: 'Comma-separated label IDs',
+        }),
+    };
+    async run() {
+        try {
+            const { flags } = await this.parse(IssuesCreate);
+            const client = getClient();
+            let input;
+            if (flags.input) {
+                // Parse JSON input
+                try {
+                    input = JSON.parse(flags.input);
+                }
+                catch {
+                    throw new CliError(ErrorCodes.INVALID_INPUT, 'Invalid JSON in --input flag');
+                }
+            }
+            else {
+                // Build input from individual flags
+                if (!flags.title) {
+                    throw new CliError(ErrorCodes.MISSING_REQUIRED_FIELD, 'Title is required. Use --title or --input');
+                }
+                if (!flags['team-id']) {
+                    throw new CliError(ErrorCodes.MISSING_REQUIRED_FIELD, 'Team ID is required. Use --team-id or --input');
+                }
+                input = {
+                    title: flags.title,
+                    teamId: flags['team-id'],
+                };
+                if (flags.description)
+                    input.description = flags.description;
+                if (flags.priority !== undefined)
+                    input.priority = flags.priority;
+                if (flags['assignee-id'])
+                    input.assigneeId = flags['assignee-id'];
+                if (flags['state-id'])
+                    input.stateId = flags['state-id'];
+                if (flags['project-id'])
+                    input.projectId = flags['project-id'];
+                if (flags.estimate !== undefined)
+                    input.estimate = flags.estimate;
+                if (flags['label-ids'])
+                    input.labelIds = flags['label-ids'].split(',');
+            }
+            // Create the issue
+            const payload = await client.createIssue(input);
+            const issue = await payload.issue;
+            if (!issue) {
+                throw new CliError(ErrorCodes.API_ERROR, 'Failed to create issue');
+            }
+            print(success({
+                id: issue.id,
+                identifier: issue.identifier,
+                title: issue.title,
+                url: issue.url,
+                createdAt: issue.createdAt,
+            }));
+        }
+        catch (err) {
+            handleError(err);
+            this.exit(1);
+        }
+    }
+}

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

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

package/dist/commands/issues/delete.js

@@ -0,0 +1,61 @@
+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';
+import { resolveIssueId } from '../../lib/issue-utils.js';
+export default class IssuesDelete extends Command {
+    static description = 'Delete an issue (moves to trash)';
+    static examples = [
+        '<%= config.bin %> issues delete abc123',
+        '<%= config.bin %> issues delete ENG-123',
+        '<%= config.bin %> issues delete ENG-123 --permanent',
+    ];
+    static args = {
+        id: Args.string({
+            description: 'Issue ID or identifier (e.g., ENG-123)',
+            required: true,
+        }),
+    };
+    static flags = {
+        permanent: Flags.boolean({
+            description: 'Permanently delete (cannot be undone)',
+            default: false,
+        }),
+    };
+    async run() {
+        try {
+            const { args, flags } = await this.parse(IssuesDelete);
+            const client = getClient();
+            const issueId = await resolveIssueId(client, args.id);
+            // Get issue info before deletion
+            const issue = await client.issue(issueId);
+            if (!issue) {
+                throw new CliError(ErrorCodes.NOT_FOUND, `Issue ${args.id} not found`);
+            }
+            const identifier = issue.identifier;
+            // Delete the issue
+            if (flags.permanent) {
+                // Archive first, then delete permanently
+                await client.archiveIssue(issueId);
+                await client.deleteIssue(issueId);
+            }
+            else {
+                // Just archive (trash)
+                await client.archiveIssue(issueId);
+            }
+            print(success({
+                id: issueId,
+                identifier,
+                deleted: true,
+                permanent: flags.permanent,
+                message: flags.permanent
+                    ? `Issue ${identifier} permanently deleted`
+                    : `Issue ${identifier} moved to trash`,
+            }));
+        }
+        catch (err) {
+            handleError(err);
+            this.exit(1);
+        }
+    }
+}

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

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

@@ -0,0 +1,81 @@
+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';
+import { resolveIssueId } from '../../lib/issue-utils.js';
+export default class IssuesGet extends Command {
+    static description = 'Get a single issue by ID or identifier';
+    static examples = [
+        '<%= config.bin %> issues get abc123',
+        '<%= config.bin %> issues get ENG-123',
+    ];
+    static args = {
+        id: Args.string({
+            description: 'Issue ID or identifier (e.g., ENG-123)',
+            required: true,
+        }),
+    };
+    async run() {
+        try {
+            const { args } = await this.parse(IssuesGet);
+            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`);
+            }
+            // Fetch related data
+            const [state, assignee, team, labels, comments] = await Promise.all([
+                issue.state,
+                issue.assignee,
+                issue.team,
+                issue.labels(),
+                issue.comments(),
+            ]);
+            print(success({
+                id: issue.id,
+                identifier: issue.identifier,
+                title: issue.title,
+                description: issue.description,
+                priority: issue.priority,
+                priorityLabel: issue.priorityLabel,
+                estimate: issue.estimate,
+                url: issue.url,
+                createdAt: issue.createdAt,
+                updatedAt: issue.updatedAt,
+                state: state
+                    ? {
+                        id: state.id,
+                        name: state.name,
+                        color: state.color,
+                        type: state.type,
+                    }
+                    : null,
+                assignee: assignee
+                    ? {
+                        id: assignee.id,
+                        name: assignee.name,
+                        email: assignee.email,
+                    }
+                    : null,
+                team: team
+                    ? {
+                        id: team.id,
+                        key: team.key,
+                        name: team.name,
+                    }
+                    : null,
+                labels: labels.nodes.map((label) => ({
+                    id: label.id,
+                    name: label.name,
+                    color: label.color,
+                })),
+                commentsCount: comments.nodes.length,
+            }));
+        }
+        catch (err) {
+            handleError(err);
+            this.exit(1);
+        }
+    }
+}

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

@@ -0,0 +1,14 @@
+import { Command } from '@oclif/core';
+export default class IssuesList extends Command {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        team: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        assignee: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        state: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        filter: import("@oclif/core/interfaces").OptionFlag<string | undefined, 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>;
+}