linear-cli-agents 0.1.1 → 0.2.1

package/README.md

@@ -1,12 +1,19 @@
-# 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.
 
 ## Features
 
 - **JSON output**: All commands return structured JSON, perfect for parsing by LLMs
+- **Multiple formats**: JSON (default), table (colored), or plain text output
 - **Schema introspection**: Discover available operations programmatically
 - **Full CRUD for issues**: List, create, update, and delete issues
+- **Team management**: List and browse teams
+- **Browser integration**: Open issues, teams, inbox directly in Linear
 - **Raw GraphQL queries**: Execute any GraphQL query directly
 
 ## Installation
@@ -19,9 +26,10 @@ pnpm add -g linear-cli-agents
 
 ## Authentication
 
-Get your API key from [Linear Settings > API](https://linear.app/settings/api).
-
 ```bash
+# Open Linear API settings in browser to create a key
+linear auth login --browser
+
 # Login with API key
 linear auth login --key lin_api_xxxxx
 
@@ -31,6 +39,9 @@ export LINEAR_API_KEY=lin_api_xxxxx
 # Check auth status
 linear auth status
 
+# View current user info
+linear me
+
 # Logout
 linear auth logout
 ```
@@ -49,8 +60,13 @@ linear issues list --assignee me
 linear issues list --state "In Progress"
 linear issues list --filter '{"priority":{"lte":2}}'
 
+# Output formats: json (default), table (colored), plain (IDs only)
+linear issues list --format table
+linear issues list --format plain
+
 # Get a specific issue
 linear issues get ENG-123
+linear issues get ENG-123 --format table
 
 # Create an issue
 linear issues create --title "Bug fix" --team-id <team-id>
@@ -64,6 +80,46 @@ linear issues update ENG-123 --state-id <state-id> --assignee-id <user-id>
 linear issues delete ENG-123
 ```
 
+### Teams
+
+```bash
+# List all teams
+linear teams list
+
+# With table format
+linear teams list --format table
+```
+
+### Open in Browser
+
+```bash
+# Open an issue
+linear open ENG-123
+
+# Open a team
+linear open --team ENG
+
+# Open inbox
+linear open --inbox
+
+# Open my issues
+linear open --my-issues
+
+# Open settings
+linear open --settings
+```
+
+### User Info
+
+```bash
+# Show current user
+linear me
+linear whoami
+
+# With table format
+linear me --format table
+```
+
 ### Schema Introspection (for LLMs)
 
 ```bash
@@ -93,7 +149,9 @@ linear query --gql "query(\$id: String!) { issue(id: \$id) { title } }" \
 
 ## Output Format
 
-All commands return structured JSON:
+### JSON (default)
+
+All commands return structured JSON by default, ideal for LLMs and scripts:
 
 ```json
 // Success
@@ -122,6 +180,37 @@ All commands return structured JSON:
 }
 ```
 
+### Table (human-readable)
+
+Use `--format table` for colored, human-readable output:
+
+```bash
+linear issues list --format table
+# ID        PRI     TITLE
+# ENG-123   High    Fix login bug
+# ENG-124   Medium  Add dark mode
+```
+
+### Plain (minimal)
+
+Use `--format plain` for minimal output (IDs/identifiers only):
+
+```bash
+linear issues list --format plain
+# ENG-123    Fix login bug
+# ENG-124    Add dark mode
+```
+
+### Disabling Colors
+
+Colors are automatically disabled when piping output. You can also disable them manually:
+
+```bash
+NO_COLOR=1 linear issues list --format table
+# or
+linear issues list --format table --no-color
+```
+
 ## For LLM Integration
 
 The CLI is designed to be easily used by LLMs and AI agents:
@@ -163,6 +252,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>;
+}