linear-cli-agents 0.4.1 → 0.5.1

package/README.md

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

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

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

package/dist/commands/config/get.js

@@ -0,0 +1,37 @@
+import { Args, Command } from '@oclif/core';
+import { success, print } from '../../lib/output.js';
+import { handleError, CliError, ErrorCodes } from '../../lib/errors.js';
+import { getDefaults, isValidConfigKey, configKeyToDefaultsKey, CONFIG_KEYS } from '../../lib/config.js';
+export default class ConfigGet extends Command {
+    static description = 'Get a configuration value';
+    static examples = [
+        '<%= config.bin %> config get default-team-id',
+        '<%= config.bin %> config get default-team-key',
+    ];
+    static args = {
+        key: Args.string({
+            description: `Config key (${CONFIG_KEYS.join(', ')})`,
+            required: true,
+        }),
+    };
+    async run() {
+        try {
+            const { args } = await this.parse(ConfigGet);
+            if (!isValidConfigKey(args.key)) {
+                throw new CliError(ErrorCodes.INVALID_INPUT, `Invalid config key: ${args.key}. Valid keys: ${CONFIG_KEYS.join(', ')}`);
+            }
+            const defaults = getDefaults();
+            const defaultsKey = configKeyToDefaultsKey(args.key);
+            const value = defaults[defaultsKey];
+            print(success({
+                key: args.key,
+                value: value ?? null,
+                isSet: value !== undefined,
+            }));
+        }
+        catch (err) {
+            handleError(err);
+            this.exit(1);
+        }
+    }
+}

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

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

package/dist/commands/config/list.js

@@ -0,0 +1,30 @@
+import { Command } from '@oclif/core';
+import { success, print } from '../../lib/output.js';
+import { handleError } from '../../lib/errors.js';
+import { getDefaults, getApiKey, getConfigPath, CONFIG_KEYS, configKeyToDefaultsKey } from '../../lib/config.js';
+export default class ConfigList extends Command {
+    static description = 'List all configuration values';
+    static examples = ['<%= config.bin %> config list'];
+    async run() {
+        try {
+            const defaults = getDefaults();
+            const apiKey = getApiKey();
+            const config = {};
+            // Add all config keys with their values
+            for (const key of CONFIG_KEYS) {
+                const defaultsKey = configKeyToDefaultsKey(key);
+                config[key] = defaults[defaultsKey] ?? null;
+            }
+            print(success({
+                configPath: getConfigPath(),
+                authenticated: apiKey !== undefined,
+                apiKeySource: apiKey ? (process.env.LINEAR_API_KEY ? 'environment' : 'config') : null,
+                defaults: config,
+            }));
+        }
+        catch (err) {
+            handleError(err);
+            this.exit(1);
+        }
+    }
+}

package/dist/commands/config/set.d.ts

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

package/dist/commands/config/set.js

@@ -0,0 +1,40 @@
+import { Args, Command } from '@oclif/core';
+import { success, print } from '../../lib/output.js';
+import { handleError, CliError, ErrorCodes } from '../../lib/errors.js';
+import { setDefault, isValidConfigKey, configKeyToDefaultsKey, CONFIG_KEYS } from '../../lib/config.js';
+export default class ConfigSet extends Command {
+    static description = 'Set a configuration value';
+    static examples = [
+        '<%= config.bin %> config set default-team-id d1ad1a80-9267-4ebc-979a-eaf885898a2c',
+        '<%= config.bin %> config set default-team-key MITO',
+    ];
+    static args = {
+        key: Args.string({
+            description: `Config key (${CONFIG_KEYS.join(', ')})`,
+            required: true,
+        }),
+        value: Args.string({
+            description: 'Config value',
+            required: true,
+        }),
+    };
+    async run() {
+        try {
+            const { args } = await this.parse(ConfigSet);
+            if (!isValidConfigKey(args.key)) {
+                throw new CliError(ErrorCodes.INVALID_INPUT, `Invalid config key: ${args.key}. Valid keys: ${CONFIG_KEYS.join(', ')}`);
+            }
+            const defaultsKey = configKeyToDefaultsKey(args.key);
+            setDefault(defaultsKey, args.value);
+            print(success({
+                key: args.key,
+                value: args.value,
+                message: `Configuration "${args.key}" set successfully`,
+            }));
+        }
+        catch (err) {
+            handleError(err);
+            this.exit(1);
+        }
+    }
+}

package/dist/commands/info.d.ts

@@ -0,0 +1,9 @@
+import { Command } from '@oclif/core';
+export default class Info extends Command {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        compact: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}