linear-cli-agents 0.1.0

package/dist/commands/issues/list.js

@@ -0,0 +1,101 @@
+import { Command, Flags } from '@oclif/core';
+import { getClient } from '../../lib/client.js';
+import { successList, print } from '../../lib/output.js';
+import { handleError } from '../../lib/errors.js';
+export default class IssuesList extends Command {
+    static description = 'List issues with optional filtering';
+    static examples = [
+        '<%= config.bin %> issues list',
+        '<%= config.bin %> issues list --team ENG',
+        '<%= config.bin %> issues list --assignee me',
+        '<%= config.bin %> issues list --filter \'{"state":{"name":{"eq":"In Progress"}}}\'',
+        '<%= config.bin %> issues list --first 50 --after cursor123',
+    ];
+    static flags = {
+        team: Flags.string({
+            char: 't',
+            description: 'Filter by team key (e.g., ENG)',
+        }),
+        assignee: Flags.string({
+            char: 'a',
+            description: 'Filter by assignee (use "me" for current user)',
+        }),
+        state: Flags.string({
+            char: 's',
+            description: 'Filter by state name (e.g., "In Progress")',
+        }),
+        filter: Flags.string({
+            char: 'f',
+            description: 'JSON filter object (IssueFilter from Linear SDK)',
+        }),
+        first: Flags.integer({
+            description: 'Number of issues to fetch (default: 50)',
+            default: 50,
+        }),
+        after: Flags.string({
+            description: 'Cursor for pagination',
+        }),
+    };
+    async run() {
+        try {
+            const { flags } = await this.parse(IssuesList);
+            const client = getClient();
+            // Build filter
+            let filter = {};
+            // Parse JSON filter if provided
+            if (flags.filter) {
+                try {
+                    filter = JSON.parse(flags.filter);
+                }
+                catch {
+                    throw new Error('Invalid JSON in --filter flag');
+                }
+            }
+            // Apply shorthand filters
+            if (flags.team) {
+                filter.team = { key: { eq: flags.team } };
+            }
+            if (flags.assignee) {
+                if (flags.assignee === 'me') {
+                    const viewer = await client.viewer;
+                    filter.assignee = { id: { eq: viewer.id } };
+                }
+                else {
+                    filter.assignee = { id: { eq: flags.assignee } };
+                }
+            }
+            if (flags.state) {
+                filter.state = { name: { eq: flags.state } };
+            }
+            // Fetch issues
+            const issues = await client.issues({
+                filter,
+                first: flags.first,
+                after: flags.after,
+            });
+            // Map to clean objects
+            const data = issues.nodes.map((issue) => ({
+                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,
+            }));
+            print(successList(data, {
+                hasNextPage: issues.pageInfo.hasNextPage,
+                hasPreviousPage: issues.pageInfo.hasPreviousPage,
+                startCursor: issues.pageInfo.startCursor,
+                endCursor: issues.pageInfo.endCursor,
+            }));
+        }
+        catch (err) {
+            handleError(err);
+            this.exit(1);
+        }
+    }
+}

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

@@ -0,0 +1,20 @@
+import { Command } from '@oclif/core';
+export default class IssuesUpdate extends Command {
+    static description: string;
+    static examples: string[];
+    static args: {
+        id: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    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>;
+        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/update.js

@@ -0,0 +1,110 @@
+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 IssuesUpdate extends Command {
+    static description = 'Update an existing issue';
+    static examples = [
+        '<%= config.bin %> issues update abc123 --input \'{"title":"Updated title"}\'',
+        '<%= config.bin %> issues update ENG-123 --title "New title"',
+        '<%= config.bin %> issues update ENG-123 --state-id xxx --assignee-id yyy',
+    ];
+    static args = {
+        id: Args.string({
+            description: 'Issue ID or identifier (e.g., ENG-123)',
+            required: true,
+        }),
+    };
+    static flags = {
+        input: Flags.string({
+            char: 'i',
+            description: 'JSON input object (IssueUpdateInput)',
+            exclusive: ['title', 'description', 'priority', 'assignee-id', 'state-id'],
+        }),
+        title: Flags.string({
+            description: 'Issue title',
+        }),
+        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 (use empty string to unassign)',
+        }),
+        '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 (replaces existing labels)',
+        }),
+    };
+    async run() {
+        try {
+            const { args, flags } = await this.parse(IssuesUpdate);
+            const client = getClient();
+            const issueId = await resolveIssueId(client, args.id);
+            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
+                input = {};
+                if (flags.title)
+                    input.title = flags.title;
+                if (flags.description)
+                    input.description = flags.description;
+                if (flags.priority !== undefined)
+                    input.priority = flags.priority;
+                if (flags['assignee-id'] !== undefined) {
+                    input.assigneeId = flags['assignee-id'] || null;
+                }
+                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(',');
+                if (Object.keys(input).length === 0) {
+                    throw new CliError(ErrorCodes.INVALID_INPUT, 'No update fields provided. Use --input or individual flags.');
+                }
+            }
+            // Update the issue
+            const payload = await client.updateIssue(issueId, input);
+            const issue = await payload.issue;
+            if (!issue) {
+                throw new CliError(ErrorCodes.API_ERROR, 'Failed to update issue');
+            }
+            print(success({
+                id: issue.id,
+                identifier: issue.identifier,
+                title: issue.title,
+                url: issue.url,
+                updatedAt: issue.updatedAt,
+            }));
+        }
+        catch (err) {
+            handleError(err);
+            this.exit(1);
+        }
+    }
+}

package/dist/commands/query.d.ts

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

package/dist/commands/query.js

@@ -0,0 +1,94 @@
+import { Command, Flags } from '@oclif/core';
+import { requireApiKey } from '../lib/config.js';
+import { success, error, print } from '../lib/output.js';
+import { handleError, CliError, ErrorCodes } from '../lib/errors.js';
+const LINEAR_API_URL = 'https://api.linear.app/graphql';
+export default class Query extends Command {
+    static description = 'Execute a raw GraphQL query against the Linear API';
+    static examples = [
+        '<%= config.bin %> query --gql "query { viewer { id name email } }"',
+        '<%= config.bin %> query --gql "query { teams { nodes { id key name } } }"',
+        '<%= config.bin %> query --gql "query($id: String!) { issue(id: $id) { title } }" --variables \'{"id":"xxx"}\'',
+    ];
+    static flags = {
+        gql: Flags.string({
+            char: 'g',
+            description: 'GraphQL query string',
+            required: true,
+        }),
+        variables: Flags.string({
+            char: 'v',
+            description: 'JSON object of query variables',
+        }),
+        timeout: Flags.integer({
+            char: 't',
+            description: 'Request timeout in seconds (default: 30)',
+            default: 30,
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(Query);
+        const controller = new AbortController();
+        let timeoutHandle;
+        const timeoutSeconds = flags.timeout ?? 30;
+        try {
+            const apiKey = requireApiKey();
+            let variables;
+            if (flags.variables) {
+                try {
+                    variables = JSON.parse(flags.variables);
+                }
+                catch {
+                    print(error('INVALID_INPUT', 'Invalid JSON in --variables flag'));
+                    this.exit(1);
+                    return;
+                }
+            }
+            timeoutHandle = setTimeout(() => controller.abort(), timeoutSeconds * 1000);
+            const response = await fetch(LINEAR_API_URL, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    Authorization: apiKey,
+                },
+                body: JSON.stringify({
+                    query: flags.gql,
+                    variables,
+                }),
+                signal: controller.signal,
+            });
+            clearTimeout(timeoutHandle);
+            if (!response.ok) {
+                print(error('API_ERROR', `Linear API returned ${response.status}: ${response.statusText}`));
+                this.exit(1);
+                return;
+            }
+            let result;
+            try {
+                result = (await response.json());
+            }
+            catch (parseError) {
+                throw new CliError(ErrorCodes.API_ERROR, `Failed to parse Linear API response: ${parseError instanceof Error ? parseError.message : 'Invalid JSON'}`, { status: response.status, statusText: response.statusText });
+            }
+            if (result.errors && result.errors.length > 0) {
+                print(error('GRAPHQL_ERROR', result.errors[0].message, {
+                    errors: result.errors,
+                }));
+                this.exit(1);
+                return;
+            }
+            print(success(result.data));
+        }
+        catch (err) {
+            if (timeoutHandle)
+                clearTimeout(timeoutHandle);
+            if (err instanceof Error && err.name === 'AbortError') {
+                print(error(ErrorCodes.API_ERROR, `Request timed out after ${timeoutSeconds} seconds`));
+                this.exit(1);
+                return;
+            }
+            handleError(err);
+            this.exit(1);
+        }
+    }
+}

package/dist/commands/schema.d.ts

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

package/dist/commands/schema.js

@@ -0,0 +1,198 @@
+import { Args, Command, Flags } from '@oclif/core';
+import { success, print } from '../lib/output.js';
+/**
+ * Schema definitions for all supported entities.
+ * This enables LLMs to discover available operations and construct valid queries.
+ */
+const ENTITY_SCHEMAS = {
+    issues: {
+        entity: 'issues',
+        operations: ['list', 'get', 'create', 'update', 'delete'],
+        description: 'Work items in Linear (bugs, features, tasks)',
+        fields: {
+            id: { type: 'ID!', description: 'Unique identifier' },
+            identifier: { type: 'String!', description: 'Human-readable identifier (e.g., ENG-123)' },
+            title: { type: 'String!', description: 'Issue title' },
+            description: { type: 'String', description: 'Issue description in markdown' },
+            priority: { type: 'Int!', description: 'Priority (0=none, 1=urgent, 2=high, 3=medium, 4=low)' },
+            priorityLabel: { type: 'String!', description: 'Priority label text' },
+            estimate: { type: 'Float', description: 'Story points estimate' },
+            url: { type: 'String!', description: 'Linear URL' },
+            createdAt: { type: 'DateTime!', description: 'Creation timestamp' },
+            updatedAt: { type: 'DateTime!', description: 'Last update timestamp' },
+        },
+        filters: {
+            team: { type: 'TeamFilter', description: 'Filter by team' },
+            assignee: { type: 'UserFilter', description: 'Filter by assignee' },
+            state: { type: 'WorkflowStateFilter', description: 'Filter by state' },
+            project: { type: 'ProjectFilter', description: 'Filter by project' },
+            priority: { type: 'IntComparator', description: 'Filter by priority' },
+            estimate: { type: 'EstimateComparator', description: 'Filter by estimate' },
+            labels: { type: 'IssueLabelFilter', description: 'Filter by labels' },
+            createdAt: { type: 'DateComparator', description: 'Filter by creation date' },
+            updatedAt: { type: 'DateComparator', description: 'Filter by update date' },
+        },
+        createInput: {
+            title: { type: 'String!', required: true, description: 'Issue title' },
+            teamId: { type: 'ID!', required: true, description: 'Team ID' },
+            description: { type: 'String', description: 'Issue description in markdown' },
+            priority: { type: 'Int', description: 'Priority (0-4)' },
+            assigneeId: { type: 'ID', description: 'Assignee user ID' },
+            stateId: { type: 'ID', description: 'Workflow state ID' },
+            projectId: { type: 'ID', description: 'Project ID' },
+            estimate: { type: 'Float', description: 'Story points estimate' },
+            labelIds: { type: '[ID!]', description: 'Array of label IDs' },
+        },
+        examples: {
+            list: 'linear issues list --team ENG --state "In Progress"',
+            get: 'linear issues get ENG-123',
+            create: 'linear issues create --title "Fix bug" --team-id xxx',
+            update: 'linear issues update ENG-123 --state-id yyy',
+            delete: 'linear issues delete ENG-123',
+        },
+    },
+    projects: {
+        entity: 'projects',
+        operations: ['list', 'get'],
+        description: 'Projects group related issues together',
+        fields: {
+            id: { type: 'ID!', description: 'Unique identifier' },
+            name: { type: 'String!', description: 'Project name' },
+            description: { type: 'String', description: 'Project description' },
+            state: { type: 'String!', description: 'Project state' },
+            url: { type: 'String!', description: 'Linear URL' },
+            startDate: { type: 'Date', description: 'Project start date' },
+            targetDate: { type: 'Date', description: 'Project target date' },
+        },
+        filters: {
+            name: { type: 'StringComparator', description: 'Filter by name' },
+            state: { type: 'StringComparator', description: 'Filter by state' },
+        },
+    },
+    teams: {
+        entity: 'teams',
+        operations: ['list', 'get'],
+        description: 'Teams organize members and issues',
+        fields: {
+            id: { type: 'ID!', description: 'Unique identifier' },
+            key: { type: 'String!', description: 'Team key (e.g., ENG)' },
+            name: { type: 'String!', description: 'Team name' },
+            description: { type: 'String', description: 'Team description' },
+        },
+    },
+    users: {
+        entity: 'users',
+        operations: ['list', 'get', 'me'],
+        description: 'Users in the Linear workspace',
+        fields: {
+            id: { type: 'ID!', description: 'Unique identifier' },
+            name: { type: 'String!', description: 'User name' },
+            email: { type: 'String!', description: 'User email' },
+            displayName: { type: 'String!', description: 'Display name' },
+            active: { type: 'Boolean!', description: 'Whether user is active' },
+        },
+    },
+    cycles: {
+        entity: 'cycles',
+        operations: ['list', 'get'],
+        description: 'Time-boxed iterations (sprints)',
+        fields: {
+            id: { type: 'ID!', description: 'Unique identifier' },
+            name: { type: 'String', description: 'Cycle name' },
+            number: { type: 'Int!', description: 'Cycle number' },
+            startsAt: { type: 'DateTime!', description: 'Cycle start date' },
+            endsAt: { type: 'DateTime!', description: 'Cycle end date' },
+        },
+    },
+    labels: {
+        entity: 'labels',
+        operations: ['list', 'get'],
+        description: 'Labels for categorizing issues',
+        fields: {
+            id: { type: 'ID!', description: 'Unique identifier' },
+            name: { type: 'String!', description: 'Label name' },
+            color: { type: 'String!', description: 'Label color' },
+            description: { type: 'String', description: 'Label description' },
+        },
+    },
+    comments: {
+        entity: 'comments',
+        operations: ['list', 'get', 'create'],
+        description: 'Comments on issues',
+        fields: {
+            id: { type: 'ID!', description: 'Unique identifier' },
+            body: { type: 'String!', description: 'Comment body in markdown' },
+            createdAt: { type: 'DateTime!', description: 'Creation timestamp' },
+        },
+        createInput: {
+            body: { type: 'String!', required: true, description: 'Comment body in markdown' },
+            issueId: { type: 'ID!', required: true, description: 'Issue ID to comment on' },
+        },
+    },
+};
+export default class Schema extends Command {
+    static description = 'Show schema information for entities (useful for LLMs to discover available operations)';
+    static examples = [
+        '<%= config.bin %> schema',
+        '<%= config.bin %> schema issues',
+        '<%= config.bin %> schema --full',
+        '<%= config.bin %> schema issues --include-examples',
+    ];
+    static args = {
+        entity: Args.string({
+            description: 'Entity name (issues, projects, teams, users, cycles, labels, comments)',
+            required: false,
+        }),
+    };
+    static flags = {
+        full: Flags.boolean({
+            description: 'Show full schema for all entities',
+            default: false,
+        }),
+        'include-examples': Flags.boolean({
+            description: 'Include usage examples',
+            default: false,
+        }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(Schema);
+        if (flags.full) {
+            // Return all schemas
+            print(success({
+                entities: Object.keys(ENTITY_SCHEMAS),
+                schemas: ENTITY_SCHEMAS,
+                note: 'Use "linear query" for raw GraphQL queries',
+            }));
+            return;
+        }
+        if (args.entity) {
+            // Return specific entity schema
+            const entityName = args.entity.toLowerCase();
+            const schema = ENTITY_SCHEMAS[entityName];
+            if (!schema) {
+                print(success({
+                    error: `Unknown entity: ${args.entity}`,
+                    availableEntities: Object.keys(ENTITY_SCHEMAS),
+                }));
+                return;
+            }
+            const result = { ...schema };
+            if (!flags['include-examples'] && 'examples' in result) {
+                delete result.examples;
+            }
+            print(success(result));
+            return;
+        }
+        // Return list of available entities with basic info
+        const entities = Object.entries(ENTITY_SCHEMAS).map(([name, schema]) => ({
+            name,
+            description: schema.description,
+            operations: schema.operations,
+        }));
+        print(success({
+            entities,
+            usage: 'Use "linear schema <entity>" for detailed schema',
+            fullSchema: 'Use "linear schema --full" for complete schema',
+        }));
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { run } from '@oclif/core';

package/dist/index.js

@@ -0,0 +1 @@
+export { run } from '@oclif/core';

package/dist/lib/client.d.ts

@@ -0,0 +1,17 @@
+import { LinearClient } from '@linear/sdk';
+/**
+ * Get a Linear client instance authenticated with the configured API key.
+ * Creates a new instance on each call (CLI commands are ephemeral).
+ *
+ * @returns A configured LinearClient instance
+ * @throws {CliError} When no API key is configured (NOT_AUTHENTICATED)
+ */
+export declare const getClient: () => LinearClient;
+/**
+ * Create a new Linear client with a specific API key.
+ * Useful for testing auth without saving the key.
+ *
+ * @param apiKey - Linear API key to authenticate with
+ * @returns A configured LinearClient instance
+ */
+export declare const createClient: (apiKey: string) => LinearClient;

package/dist/lib/client.js

@@ -0,0 +1,23 @@
+import { LinearClient } from '@linear/sdk';
+import { requireApiKey } from './config.js';
+/**
+ * Get a Linear client instance authenticated with the configured API key.
+ * Creates a new instance on each call (CLI commands are ephemeral).
+ *
+ * @returns A configured LinearClient instance
+ * @throws {CliError} When no API key is configured (NOT_AUTHENTICATED)
+ */
+export const getClient = () => {
+    const apiKey = requireApiKey();
+    return new LinearClient({ apiKey });
+};
+/**
+ * Create a new Linear client with a specific API key.
+ * Useful for testing auth without saving the key.
+ *
+ * @param apiKey - Linear API key to authenticate with
+ * @returns A configured LinearClient instance
+ */
+export const createClient = (apiKey) => {
+    return new LinearClient({ apiKey });
+};

package/dist/lib/config.d.ts

@@ -0,0 +1,33 @@
+import type { ConfigFile } from './types.js';
+/**
+ * Read the configuration file.
+ * @throws {CliError} When config file exists but cannot be parsed.
+ */
+export declare const readConfig: () => ConfigFile;
+/**
+ * Write the configuration file atomically.
+ * Uses a temp file + rename to prevent corruption.
+ */
+export declare const writeConfig: (config: ConfigFile) => void;
+/**
+ * Get the API key from config or environment.
+ * Environment variable LINEAR_API_KEY takes precedence.
+ */
+export declare const getApiKey: () => string | undefined;
+/**
+ * Get the API key or throw if not configured.
+ * @throws {CliError} When no API key is configured (NOT_AUTHENTICATED).
+ */
+export declare const requireApiKey: () => string;
+/**
+ * Save the API key to config with secure permissions.
+ */
+export declare const saveApiKey: (apiKey: string) => void;
+/**
+ * Remove the API key from config.
+ */
+export declare const removeApiKey: () => void;
+/**
+ * Get the config file path (for display purposes).
+ */
+export declare const getConfigPath: () => string;