linear-cli-agents 0.1.1 → 0.2.0

package/README.md

@@ -1,4 +1,8 @@
-# linear-cli
+# linear-cli-agents
+
+[![npm version](https://img.shields.io/npm/v/linear-cli-agents.svg)](https://www.npmjs.com/package/linear-cli-agents)
+[![CI](https://github.com/nchgn/linear-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/nchgn/linear-cli/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 A CLI for interacting with [Linear](https://linear.app), designed for LLMs and agents.
 
@@ -163,6 +167,51 @@ pnpm build
 pnpm test
 ```
 
+## Troubleshooting
+
+### Authentication Issues
+
+**"Not authenticated" error:**
+
+```bash
+# Check current auth status
+linear auth status
+
+# Re-authenticate
+linear auth login --key lin_api_xxxxx
+```
+
+**Using environment variable:**
+
+```bash
+export LINEAR_API_KEY=lin_api_xxxxx
+linear auth status  # Should show source: environment
+```
+
+### Common Errors
+
+| Error Code          | Cause                      | Solution                                        |
+| ------------------- | -------------------------- | ----------------------------------------------- |
+| `NOT_AUTHENTICATED` | No API key configured      | Run `linear auth login` or set `LINEAR_API_KEY` |
+| `INVALID_API_KEY`   | API key expired or invalid | Generate a new key in Linear settings           |
+| `NOT_FOUND`         | Resource doesn't exist     | Check the issue/team identifier                 |
+| `RATE_LIMITED`      | Too many requests          | Wait before retrying                            |
+
+### Getting Help
+
+```bash
+# See all commands
+linear --help
+
+# Get help for a specific command
+linear issues --help
+linear issues create --help
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.
+
 ## License
 
 MIT

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

@@ -0,0 +1 @@
+export {};

package/dist/commands/auth/__tests__/status.test.js

@@ -0,0 +1,23 @@
+import { describe, it, expect } from 'vitest';
+/**
+ * Note: Full integration tests for auth commands require mocking
+ * the Linear API client, which is complex with oclif's command runner.
+ *
+ * For now, we test the output format contracts and defer
+ * integration testing to manual verification or E2E tests.
+ *
+ * The underlying utilities (output.ts, errors.ts) are fully tested.
+ */
+describe('auth status command', () => {
+    it('should have proper command structure', async () => {
+        // Dynamic import to verify module loads correctly
+        const { default: AuthStatus } = await import('../status.js');
+        expect(AuthStatus.description).toBe('Check authentication status');
+        expect(AuthStatus.examples).toHaveLength(1);
+    });
+    it('should export as oclif Command', async () => {
+        const { default: AuthStatus } = await import('../status.js');
+        const { Command } = await import('@oclif/core');
+        expect(AuthStatus.prototype).toBeInstanceOf(Command.prototype.constructor);
+    });
+});

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

@@ -4,6 +4,7 @@ export default class AuthLogin extends Command {
     static examples: string[];
     static flags: {
         key: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        browser: import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };
     static args: {
         key: import("@oclif/core/interfaces").Arg<string | undefined, Record<string, unknown>>;

package/dist/commands/auth/login.js

@@ -1,12 +1,16 @@
 import { Args, Command, Flags } from '@oclif/core';
+import open from 'open';
 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';
+import { success, error, print } from '../../lib/output.js';
+import { handleError } from '../../lib/errors.js';
+import { colors } from '../../lib/formatter.js';
+const LINEAR_API_SETTINGS_URL = 'https://linear.app/settings/api';
 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',
+        '<%= config.bin %> auth login --browser',
         'LINEAR_API_KEY=lin_api_xxxxx <%= config.bin %> auth login',
     ];
     static flags = {
@@ -15,6 +19,11 @@ export default class AuthLogin extends Command {
             description: 'Linear API key (or set LINEAR_API_KEY env var)',
             env: 'LINEAR_API_KEY',
         }),
+        browser: Flags.boolean({
+            char: 'b',
+            description: 'Open Linear API settings in browser to create a key',
+            default: false,
+        }),
     };
     static args = {
         key: Args.string({
@@ -26,8 +35,35 @@ export default class AuthLogin extends Command {
         try {
             const { args, flags } = await this.parse(AuthLogin);
             const apiKey = flags.key || args.key;
+            // If --browser flag, open Linear API settings
+            if (flags.browser) {
+                await open(LINEAR_API_SETTINGS_URL);
+                print(success({
+                    message: 'Opened Linear API settings in browser',
+                    url: LINEAR_API_SETTINGS_URL,
+                    instructions: [
+                        '1. Click "Create key" or "New API key"',
+                        '2. Give it a label (e.g., "CLI")',
+                        '3. Copy the generated key (starts with lin_api_)',
+                        '4. Run: linear auth login --key YOUR_KEY',
+                    ],
+                }));
+                return;
+            }
+            // If no API key provided, show helpful instructions
             if (!apiKey) {
-                throw new CliError(ErrorCodes.MISSING_REQUIRED_FIELD, 'API key is required. Use --key flag or set LINEAR_API_KEY environment variable.');
+                console.log(colors.bold('\nTo authenticate with Linear CLI, you need an API key.\n'));
+                console.log(colors.cyan('Option 1: Open browser to create a key'));
+                console.log('  linear auth login --browser\n');
+                console.log(colors.cyan('Option 2: If you already have a key'));
+                console.log('  linear auth login --key lin_api_xxxxx\n');
+                console.log(colors.cyan('Option 3: Set environment variable'));
+                console.log('  export LINEAR_API_KEY=lin_api_xxxxx\n');
+                console.log(colors.dim(`Manual URL: ${LINEAR_API_SETTINGS_URL}`));
+                console.log('');
+                print(error('MISSING_API_KEY', 'No API key provided. Use --browser to create one or --key to provide an existing key.', { url: LINEAR_API_SETTINGS_URL }));
+                this.exit(1);
+                return;
             }
             // Validate the API key by making a test request
             const client = createClient(apiKey);

package/dist/commands/issues/delete.js

@@ -48,9 +48,7 @@ export default class IssuesDelete extends Command {
                 identifier,
                 deleted: true,
                 permanent: flags.permanent,
-                message: flags.permanent
-                    ? `Issue ${identifier} permanently deleted`
-                    : `Issue ${identifier} moved to trash`,
+                message: flags.permanent ? `Issue ${identifier} permanently deleted` : `Issue ${identifier} moved to trash`,
             }));
         }
         catch (err) {

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

@@ -5,5 +5,8 @@ export default class IssuesGet extends Command {
     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/issues/get.js

@@ -1,13 +1,14 @@
-import { Args, Command } from '@oclif/core';
+import { Args, Command, Flags } from '@oclif/core';
 import { getClient } from '../../lib/client.js';
-import { success, print } from '../../lib/output.js';
+import { success, print, printItem } from '../../lib/output.js';
 import { handleError, CliError, ErrorCodes } from '../../lib/errors.js';
 import { resolveIssueId } from '../../lib/issue-utils.js';
 export default class 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',
+        '<%= config.bin %> issues get ENG-123 --format table',
+        '<%= config.bin %> issues get abc123',
     ];
     static args = {
         id: Args.string({
@@ -15,9 +16,18 @@ export default class IssuesGet extends Command {
             required: true,
         }),
     };
+    static flags = {
+        format: Flags.string({
+            char: 'F',
+            description: 'Output format',
+            options: ['json', 'table', 'plain'],
+            default: 'json',
+        }),
+    };
     async run() {
         try {
-            const { args } = await this.parse(IssuesGet);
+            const { args, flags } = await this.parse(IssuesGet);
+            const format = flags.format;
             const client = getClient();
             const issueId = await resolveIssueId(client, args.id);
             const issue = await client.issue(issueId);
@@ -32,7 +42,7 @@ export default class IssuesGet extends Command {
                 issue.labels(),
                 issue.comments(),
             ]);
-            print(success({
+            const data = {
                 id: issue.id,
                 identifier: issue.identifier,
                 title: issue.title,
@@ -71,7 +81,30 @@ export default class IssuesGet extends Command {
                     color: label.color,
                 })),
                 commentsCount: comments.nodes.length,
-            }));
+            };
+            if (format === 'json') {
+                print(success(data));
+            }
+            else if (format === 'table') {
+                printItem({
+                    identifier: data.identifier,
+                    title: data.title,
+                    state: data.state?.name ?? 'N/A',
+                    priority: data.priorityLabel,
+                    team: data.team?.key ?? 'N/A',
+                    assignee: data.assignee?.name ?? 'Unassigned',
+                    labels: data.labels.map((l) => l.name).join(', ') || 'None',
+                    estimate: data.estimate ?? 'None',
+                    comments: data.commentsCount,
+                    url: data.url,
+                    createdAt: data.createdAt,
+                    updatedAt: data.updatedAt,
+                }, format);
+            }
+            else {
+                // plain: just the identifier
+                console.log(data.identifier);
+            }
         }
         catch (err) {
             handleError(err);

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

@@ -3,6 +3,7 @@ export default class IssuesList extends Command {
     static description: string;
     static examples: string[];
     static flags: {
+        format: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         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>;

package/dist/commands/issues/list.js

@@ -1,17 +1,42 @@
 import { Command, Flags } from '@oclif/core';
 import { getClient } from '../../lib/client.js';
-import { successList, print } from '../../lib/output.js';
+import { successList, print, printList } from '../../lib/output.js';
 import { handleError } from '../../lib/errors.js';
+import { colors, truncate, formatPriority } from '../../lib/formatter.js';
+const COLUMNS = [
+    {
+        key: 'identifier',
+        header: 'ID',
+        format: (value) => colors.cyan(String(value)),
+    },
+    {
+        key: 'priority',
+        header: 'PRI',
+        format: (value) => formatPriority(Number(value)),
+    },
+    {
+        key: 'title',
+        header: 'TITLE',
+        format: (value) => truncate(String(value), 50),
+    },
+];
 export default class IssuesList extends Command {
     static description = 'List issues with optional filtering';
     static examples = [
         '<%= config.bin %> issues list',
+        '<%= config.bin %> issues list --format table',
         '<%= 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 = {
+        format: Flags.string({
+            char: 'F',
+            description: 'Output format',
+            options: ['json', 'table', 'plain'],
+            default: 'json',
+        }),
         team: Flags.string({
             char: 't',
             description: 'Filter by team key (e.g., ENG)',
@@ -39,6 +64,7 @@ export default class IssuesList extends Command {
     async run() {
         try {
             const { flags } = await this.parse(IssuesList);
+            const format = flags.format;
             const client = getClient();
             // Build filter
             let filter = {};
@@ -78,20 +104,31 @@ export default class IssuesList extends Command {
                 id: issue.id,
                 identifier: issue.identifier,
                 title: issue.title,
-                description: issue.description,
+                description: issue.description ?? undefined,
                 priority: issue.priority,
                 priorityLabel: issue.priorityLabel,
-                estimate: issue.estimate,
+                estimate: issue.estimate ?? undefined,
                 url: issue.url,
                 createdAt: issue.createdAt,
                 updatedAt: issue.updatedAt,
             }));
-            print(successList(data, {
+            const pageInfo = {
                 hasNextPage: issues.pageInfo.hasNextPage,
                 hasPreviousPage: issues.pageInfo.hasPreviousPage,
                 startCursor: issues.pageInfo.startCursor,
                 endCursor: issues.pageInfo.endCursor,
-            }));
+            };
+            if (format === 'json') {
+                print(successList(data, pageInfo));
+            }
+            else {
+                printList(data, format, {
+                    columns: COLUMNS,
+                    primaryKey: 'identifier',
+                    secondaryKey: 'title',
+                    pageInfo,
+                });
+            }
         }
         catch (err) {
             handleError(err);

package/dist/commands/me.d.ts

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

package/dist/commands/me.js

@@ -0,0 +1,76 @@
+import { Command, Flags } from '@oclif/core';
+import { getClient } from '../lib/client.js';
+import { success, print, printItem } from '../lib/output.js';
+import { handleError } from '../lib/errors.js';
+export default class Me extends Command {
+    static description = 'Show current user information';
+    static aliases = ['whoami'];
+    static examples = [
+        '<%= config.bin %> me',
+        '<%= config.bin %> me --format table',
+        '<%= config.bin %> whoami',
+    ];
+    static flags = {
+        format: Flags.string({
+            char: 'F',
+            description: 'Output format',
+            options: ['json', 'table', 'plain'],
+            default: 'json',
+        }),
+    };
+    async run() {
+        try {
+            const { flags } = await this.parse(Me);
+            const format = flags.format;
+            const client = getClient();
+            const viewer = await client.viewer;
+            const [teams, organization] = await Promise.all([viewer.teams(), viewer.organization]);
+            const data = {
+                id: viewer.id,
+                name: viewer.name,
+                email: viewer.email,
+                displayName: viewer.displayName,
+                active: viewer.active,
+                admin: viewer.admin,
+                timezone: viewer.timezone,
+                createdAt: viewer.createdAt,
+                organization: organization
+                    ? {
+                        id: organization.id,
+                        name: organization.name,
+                        urlKey: organization.urlKey,
+                    }
+                    : null,
+                teams: teams.nodes.map((team) => ({
+                    id: team.id,
+                    key: team.key,
+                    name: team.name,
+                })),
+            };
+            if (format === 'json') {
+                print(success(data));
+            }
+            else if (format === 'table') {
+                printItem({
+                    id: data.id,
+                    name: data.name,
+                    email: data.email,
+                    displayName: data.displayName,
+                    active: data.active ? 'Yes' : 'No',
+                    admin: data.admin ? 'Yes' : 'No',
+                    timezone: data.timezone,
+                    organization: data.organization?.name ?? 'N/A',
+                    teams: data.teams.map((t) => t.key).join(', '),
+                }, format);
+            }
+            else {
+                // plain: just the email
+                console.log(data.email);
+            }
+        }
+        catch (err) {
+            handleError(err);
+            this.exit(1);
+        }
+    }
+}

package/dist/commands/open.d.ts

@@ -0,0 +1,15 @@
+import { Command } from '@oclif/core';
+export default class Open extends Command {
+    static description: string;
+    static examples: string[];
+    static args: {
+        issue: import("@oclif/core/interfaces").Arg<string | undefined, Record<string, unknown>>;
+    };
+    static flags: {
+        team: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        inbox: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        settings: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'my-issues': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/open.js

@@ -0,0 +1,100 @@
+import { Args, Command, Flags } from '@oclif/core';
+import open from 'open';
+import { getClient } from '../lib/client.js';
+import { success, print } from '../lib/output.js';
+import { handleError } from '../lib/errors.js';
+import { parseIdentifier, isUUID, resolveIssueId } from '../lib/issue-utils.js';
+export default class Open extends Command {
+    static description = 'Open Linear resources in browser';
+    static examples = [
+        '<%= config.bin %> open ENG-123',
+        '<%= config.bin %> open --team ENG',
+        '<%= config.bin %> open --inbox',
+        '<%= config.bin %> open --settings',
+        '<%= config.bin %> open --my-issues',
+    ];
+    static args = {
+        issue: Args.string({
+            description: 'Issue identifier (e.g., ENG-123) or ID to open',
+            required: false,
+        }),
+    };
+    static flags = {
+        team: Flags.string({
+            char: 't',
+            description: 'Open team page by key (e.g., ENG)',
+            exclusive: ['inbox', 'settings', 'my-issues'],
+        }),
+        inbox: Flags.boolean({
+            description: 'Open inbox',
+            exclusive: ['team', 'settings', 'my-issues'],
+        }),
+        settings: Flags.boolean({
+            description: 'Open workspace settings',
+            exclusive: ['team', 'inbox', 'my-issues'],
+        }),
+        'my-issues': Flags.boolean({
+            description: 'Open my issues view',
+            exclusive: ['team', 'inbox', 'settings'],
+        }),
+    };
+    async run() {
+        try {
+            const { args, flags } = await this.parse(Open);
+            const client = getClient();
+            // Get organization for URL building
+            const viewer = await client.viewer;
+            const organization = await viewer.organization;
+            if (!organization) {
+                throw new Error('Could not determine organization');
+            }
+            const orgKey = organization.urlKey;
+            let url;
+            if (args.issue) {
+                // Open specific issue
+                const parsed = parseIdentifier(args.issue);
+                if (parsed) {
+                    url = `https://linear.app/${orgKey}/issue/${args.issue}`;
+                }
+                else if (isUUID(args.issue)) {
+                    // Need to fetch issue to get identifier for URL
+                    const issueId = await resolveIssueId(client, args.issue);
+                    const issue = await client.issue(issueId);
+                    url = issue.url;
+                }
+                else {
+                    throw new Error(`Invalid issue identifier: ${args.issue}`);
+                }
+            }
+            else if (flags.team) {
+                // Open team page
+                url = `https://linear.app/${orgKey}/team/${flags.team}`;
+            }
+            else if (flags.inbox) {
+                // Open inbox
+                url = `https://linear.app/${orgKey}/inbox`;
+            }
+            else if (flags.settings) {
+                // Open settings
+                url = `https://linear.app/${orgKey}/settings`;
+            }
+            else if (flags['my-issues']) {
+                // Open my issues
+                url = `https://linear.app/${orgKey}/my-issues`;
+            }
+            else {
+                // Default: open workspace home
+                url = `https://linear.app/${orgKey}`;
+            }
+            await open(url);
+            print(success({
+                opened: true,
+                url,
+            }));
+        }
+        catch (err) {
+            handleError(err);
+            this.exit(1);
+        }
+    }
+}

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

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