### Linearis Installation and Development Setup

Source: https://github.com/czottmann/linearis/blob/main/README.md

Provides instructions for installing the linearis CLI from GitHub and setting up the development environment. This includes using npm for global installation and pnpm for local development, along with build and run commands.

```bash
npm install -g --install-links czottmann/linearis
git clone <repository> && cd linearis
pnpm install
pnpm run build  # Compile TypeScript to dist/
pnpm start  # Development mode (tsx)
```

--------------------------------

### Install Linearis via Git with Auto-Build

Source: https://github.com/czottmann/linearis/blob/main/docs/deployment.md

Installs the Linearis project directly from its GitHub repository. This command automatically triggers the `prepare` script, which cleans the project and builds the TypeScript code into JavaScript in the `dist/` directory.

```bash
npm install git+https://github.com/czottmann/linearis.git
# Automatically runs prepare script: clean + build
# Creates dist/ with compiled JavaScript
```

--------------------------------

### Install Development Tools with mise

Source: https://github.com/czottmann/linearis/blob/main/docs/deployment.md

Installs the necessary development tools for the Linearis project as defined in the `mise.toml` configuration file. This command ensures that the correct versions of Node.js (22) and Deno (2.2.8) are available for local development.

```bash
# Install development tools
 mise install  # Installs Node.js 22 and Deno 2.2.8
```

--------------------------------

### Link Linearis for Global CLI Access

Source: https://github.com/czottmann/linearis/blob/main/docs/deployment.md

Creates a global command-line interface (CLI) for Linearis by linking the local project. This utilizes the `bin` field in `package.json` to make the compiled `dist/main.js` executable available system-wide as the 'linear' command.

```bash
npm link  # Creates global 'linear' command
# Uses main: "dist/main.js" and bin: "dist/main.js"
```

--------------------------------

### Automated Build Script Trigger in Bash

Source: https://github.com/czottmann/linearis/blob/main/docs/development.md

The prepare script in package.json automates cleaning and building during npm install for consistent development setups. Purpose is to ensure compiled outputs are ready post-installation. Inputs are standard npm install; outputs triggered build in dist/; no manual intervention needed, but relies on npm scripts.

```bash
# prepare script runs automatically during install
npm install  # Triggers: npm run clean && npm run build
```

--------------------------------

### Build Standalone Executable with pkg

Source: https://github.com/czottmann/linearis/blob/main/docs/deployment.md

Generates standalone executables for various platforms (Linux, macOS, Windows) from the compiled JavaScript output of the Linearis project. This command uses the `pkg` tool to package the application, making it runnable without a Node.js installation on the target machine.

```bash
# Create standalone binary from compiled output
npx pkg dist/main.js --targets node22-linux-x64,node22-macos-x64,node22-win-x64
```

--------------------------------

### Dockerfile for Linearis Container Deployment

Source: https://github.com/czottmann/linearis/blob/main/docs/deployment.md

A Dockerfile defining the build process for a Linearis container image. It uses a Node.js 22 Alpine base image, copies project files, installs dependencies, and automatically builds the TypeScript code via the npm install command (which triggers the prepare script).

```dockerfile
FROM node:22-alpine
WORKDIR /app
COPY package.json pnpm-lock.yaml tsconfig.json ./
COPY src/ ./src/
RUN npm install  # Auto-builds via prepare script
ENTRYPOINT ["node", "dist/main.js"]
```

--------------------------------

### Monitor Real-World Performance with 'time'

Source: https://github.com/czottmann/linearis/blob/main/docs/performance.md

Demonstrates how to use the 'time' command in a bash shell to monitor the real-world performance of Linear CLI commands. This includes examples for listing and searching issues.

```bash
# Add timing to any command
time linearis <command>

# Example: Monitor issue listing performance
time linearis issues list -l 25

# Example: Monitor search performance  
time linearis issues search "bug" --team ABC
```

--------------------------------

### Command-Line Argument Parsing with Commander.js (TypeScript)

Source: https://github.com/czottmann/linearis/blob/main/docs/architecture.md

This snippet shows the basic setup for a command-line interface using Commander.js in TypeScript. It initializes a Commander program, defines global options, and registers subcommands. This serves as the main entry point for the application's CLI commands.

```typescript
import { Command } from "commander";

const program = new Command();

program
  .name("linearis")
  .description("CLI tool for Linear.app")
  .version("0.1.0");

program.option("-v, --verbose", "output extra debugging");

// Subcommand registration would follow here

// program.parse(process.argv);
```

--------------------------------

### Linearis CLI: Issues Management Examples

Source: https://github.com/czottmann/linearis/blob/main/README.md

Demonstrates common operations for managing issues within Linear using the linearis CLI. This includes listing, searching, creating, reading, updating, and organizing issues, as well as setting relationships and clearing labels. It showcases direct command-line interactions.

```bash
linearis
linearis issues
linearis labels
linearis issues list -l 10
linearis issues search "authentication" --team Platform --project "Auth Service"
linearis issues create "Fix login timeout" --team Backend --assignee user123 \
  --labels "Bug,Critical" --priority 1 --description "Users can't stay logged in"
linearis issues read DEV-456
linearis issues update ABC-123 --state "In Review" --priority 2
linearis issues update DEV-789 --labels "Frontend,UX" --label-by adding
linearis issues update SUB-001 --parent-ticket EPIC-100
linearis issues update ABC-123 --clear-labels
```

--------------------------------

### Linearis CLI: Comments Management Example

Source: https://github.com/czottmann/linearis/blob/main/README.md

Shows how to add comments to existing issues in Linear using the linearis CLI. This involves specifying the issue identifier and providing the comment body.

```bash
linearis comments create ABC-123 --body "Fixed in PR #456"
```

--------------------------------

### Authentication Setup - Linear API Token Retrieval

Source: https://context7.com/czottmann/linearis/llms.txt

Retrieves Linear API token from multiple sources in priority order: command flag, environment variable, or configuration file. Used internally by all commands. Returns structured token or throws error if no valid token found.

```typescript
import { getApiToken } from "./utils/auth.js";

// Priority 1: Command flag --api-token
const token1 = await getApiToken({ apiToken: "lin_api_abc123..." });

// Priority 2: Environment variable LINEAR_API_TOKEN
process.env.LINEAR_API_TOKEN = "lin_api_xyz789...";
const token2 = await getApiToken({});

// Priority 3: File at ~/.linear_api_token
// File contents: lin_api_def456...
const token3 = await getApiToken({});

// Error handling
try {
  const token = await getApiToken({});
} catch (error) {
  console.error(error.message);
  // Output: "No API token found. Use --api-token, LINEAR_API_TOKEN env var, or ~/.linear_api_token file"
}
```

--------------------------------

### Linearis CLI: File Downloads and Embeds

Source: https://github.com/czottmann/linearis/blob/main/README.md

Illustrates how to handle file attachments within Linear issues using the linearis CLI. It covers reading issue details to get file URLs and downloading these files to a local destination, with an option to overwrite existing files.

```bash
linearis issues read ABC-123
linearis embeds download "https://uploads.linear.app/.../file.png?signature=..." --output ./screenshot.png
linearis embeds download "https://uploads.linear.app/.../file.png?signature=..." --output ./screenshot.png --overwrite
```

--------------------------------

### Get Issues using GraphQL (TypeScript)

Source: https://context7.com/czottmann/linearis/llms.txt

This code snippet demonstrates how to retrieve issues using the GraphQLIssuesService. It utilizes batched GraphQL queries to reduce the number of API calls. The service resolves team and project names to UUIDs for accurate querying.

```typescript
import { GraphQLIssuesService } from "./utils/graphql-issues-service.js";
import { createGraphQLService } from "./utils/graphql-service.js";
import { createLinearService } from "./utils/linear-service.js";

const graphQLService = await createGraphQLService({ apiToken: "lin_api_abc123" });
const linearService = await createLinearService({ apiToken: "lin_api_abc123" });
const issuesService = new GraphQLIssuesService(graphQLService, linearService);

// Get issues (1 API call instead of 1 + 5N)
const issues = await issuesService.getIssues(25);

// Get issue by ID (1 API call instead of 7)
const issue = await issuesService.getIssueById("ENG-123");

// Create issue with name resolution (2 API calls instead of 7+)
const newIssue = await issuesService.createIssue({
  title: "New feature",
  teamId: "Engineering", // Resolves team name to UUID
  projectId: "Backend Services", // Resolves project name to UUID
  labelIds: ["bug", "urgent"], // Resolves label names to UUIDs
  priority: 1
});

// Update issue with label modes (2 API calls instead of 5)
const updated = await issuesService.updateIssue({
  id: "ENG-123",
  labels: ["security", "critical"]
}, "adding"); // Merge with existing labels (default: "overwriting")

// Search with filters (1-2 API calls instead of 1 + 6N)
const results = await issuesService.searchIssues({
  query: "authentication",
  teamId: "ENG",
  states: ["In Progress", "In Review"],
  limit: 10
});
```

--------------------------------

### Read Issue Details - Single Issue Query

Source: https://context7.com/czottmann/linearis/llms.txt

Gets complete issue details including all relationships and comments in a single API call. Accepts both UUID and identifier formats like "ABC-123" with automatic smart ID resolution to internal UUIDs.

```bash
# Using issue identifier (team-number format)
linearis issues read ENG-123

# Using UUID
linearis issues read a1b2c3d4-e5f6-7890-abcd-ef1234567890
```

--------------------------------

### Linearis CLI: Projects and Labels Management

Source: https://github.com/czottmann/linearis/blob/main/README.md

Demonstrates how to list available projects and labels associated with specific teams in Linear using the linearis CLI. This is useful for understanding project structures and available tagging options.

```bash
linearis projects list
linearis labels list --team Backend
```

--------------------------------

### Production Build and Execution Workflow in Bash

Source: https://github.com/czottmann/linearis/blob/main/docs/development.md

This workflow cleans, compiles TypeScript to JavaScript, makes the output executable, and runs commands for production testing. Purpose is to create optimized binaries for faster performance over tsx. Dependencies include npm scripts for clean and build; inputs are standard CLI args; outputs executable dist/main.js; limitations include no source maps in prod for size reduction.

```bash
# Clean and compile for production
npm run clean && npm run build

# Test compiled output (creates executable dist/main.js)
chmod +x dist/main.js
./dist/main.js issues list -l 5

# Time comparison (compiled is significantly faster)
time ./dist/main.js --help
time npx tsx src/main.ts --help
```

--------------------------------

### Download files from Linear storage (CLI)

Source: https://context7.com/czottmann/linearis/llms.txt

Downloads files from Linear's private cloud storage. The CLI command handles signed URLs and authentication, with options to specify output path and overwrite existing files.

```bash
linearis embeds download "https://uploads.linear.app/abc123/screenshot.png?signature=xyz789"
linearis embeds download "https://uploads.linear.app/abc123/report.pdf" --output reports/issue-report.pdf
linearis embeds download "https://uploads.linear.app/abc123/data.csv" --output data.csv --overwrite
```

```json
{
  "success": true,
  "filePath": "screenshot.png",
  "message": "File downloaded successfully to screenshot.png"
}
```

--------------------------------

### Linearis CLI: Advanced Usage with JSON Output

Source: https://github.com/czottmann/linearis/blob/main/README.md

Highlights advanced usage patterns of the linearis CLI, including generating comprehensive usage information suitable for LLM agents and piping JSON output to other command-line tools like `jq` for data manipulation and filtering.

```bash
linearis usage
linearis issues list -l 5 | jq '.[] | .identifier + ": " + .title'
```

--------------------------------

### Linearis Authentication Methods

Source: https://github.com/czottmann/linearis/blob/main/README.md

Details various methods for authenticating with the Linear API when using the linearis CLI. Options include using a direct `--api-token` flag, setting the `LINEAR_API_TOKEN` environment variable, or storing the token in a local file `~/.linear_api_token` for persistent access.

```bash
linearis --api-token <token> issues list
LINEAR_API_TOKEN=<token> linearis issues list
echo "<token>" > ~/.linear_api_token
linearis issues list
```

--------------------------------

### List active projects in Linear (CLI)

Source: https://context7.com/czottmann/linearis/llms.txt

Lists all active projects in Linear, optionally filtered by state. The output is a JSON array of project objects, including teams and project leads.

```bash
linearis projects list
linearis projects list | jq '.[] | select(.state == "started")'
```

```json
[
  {
    "id": "project-uuid",
    "name": "Q4 Platform Improvements",
    "description": "Major infrastructure upgrades and performance optimizations",
    "state": "started",
    "progress": 0.65,
    "teams": [
      {
        "id": "team-uuid",
        "key": "ENG",
        "name": "Engineering"
      }
    ],
    "lead": {
      "id": "user-uuid",
      "name": "Sarah Johnson"
    },
    "targetDate": "2024-12-31T23:59:59.000Z",
    "createdAt": "2024-10-01T00:00:00.000Z",
    "updatedAt": "2024-01-16T12:00:00.000Z"
  },
  {
    "id": "project2-uuid",
    "name": "Mobile App Redesign",
    "state": "planned",
    "progress": 0.0,
    "teams": [
      {
        "id": "team2-uuid",
        "key": "MOB",
        "name": "Mobile"
      }
    ],
    "targetDate": "2025-03-15T23:59:59.000Z",
    "createdAt": "2024-01-10T00:00:00.000Z",
    "updatedAt": "2024-01-15T09:00:00.000Z"
  }
]
```

--------------------------------

### TypeScript Async/Await Pattern

Source: https://github.com/czottmann/linearis/blob/main/docs/development.md

Demonstrates a consistent async/await style used across the project, including a wrapper for async command handlers and parallel Promise handling to avoid N+1 calls and simplify control flow.

```typescript
export function handleAsyncCommand(
  asyncFn: (...args: any[]) => Promise<void>,
): (...args: any[]) => Promise<void> {
  return async (...args: any[]) => {
    try {
      await asyncFn(...args);
    } catch (error) {
      outputError(error instanceof Error ? error : new Error(String(error)));
    }
  };
}

// Example parallel API calls in src/utils/linear-service.ts lines 128-137
const [state, team, assignee, project, labels] = await Promise.all([
  issue.state,
  issue.team,
  issue.assignee,
  issue.project,
  issue.labels(),
]);
```

--------------------------------

### Create Issue with Linearis CLI

Source: https://context7.com/czottmann/linearis/llms.txt

Creates a new issue using the Linearis CLI. Supports minimal creation with just a title and team key, or a fully featured creation with project, assignee, priority, labels, status, and parent ticket. It utilizes smart ID resolution for human-friendly names instead of UUIDs.

```bash
# Minimal issue creation with team key
linearis issues create "Fix memory leak in API server" --team ENG

# Full-featured issue with all options
linearis issues create "Implement user authentication" \
  --team "Engineering" \
  --description "Add OAuth 2.0 support with JWT tokens" \
  --assignee user-uuid \
  --priority 1 \
  --project "Backend Services" \
  --labels "feature,security" \
  --status "In Progress" \
  --parent-ticket ENG-100

# With milestone (requires project)
linearis issues create "Database migration script" \
  --team ENG \
  --project "Q4 Platform" \
  --milestone milestone-uuid
```

--------------------------------

### Read Issue with API Token

Source: https://context7.com/czottmann/linearis/llms.txt

Reads an existing issue using its identifier and an API token for authentication. Requires the `linearis` executable and an issue identifier.

```bash
linearis --api-token lin_api_abc123 issues read ENG-123
```

--------------------------------

### Authentication Token Retrieval (TypeScript)

Source: https://github.com/czottmann/linearis/blob/main/docs/architecture.md

The `getApiToken` function handles authentication by retrieving an API token from multiple potential sources, including environment variables and a configuration file. It prioritizes environment variables and provides a fallback mechanism, ensuring the application can authenticate with the Linear API. The function returns the token as a string or null if not found.

```typescript
import { cosmiconfigSync } from "cosmiconfig";

async function getApiToken(): Promise<string | null> {
  // Try environment variable first
  const envToken = process.env.LINEAR_API_TOKEN;
  if (envToken) {
    return envToken;
  }

  // Fallback to cosmiconfig
  const configExplorer = cosmiconfigSync("linearis");
  const searchResult = configExplorer.search();
  if (searchResult && searchResult.config.token) {
    return searchResult.config.token;
  }

  return null;
}
```

--------------------------------

### Development Mode Execution Commands in Bash

Source: https://github.com/czottmann/linearis/blob/main/docs/development.md

These commands run the TypeScript CLI in development using tsx for direct execution and debugging. Purpose is to test commands like listing issues or reading specifics with token flags. Inputs include API token and command arguments; outputs CLI responses; no compilation needed, but limited to dev environment; comparisons show tsx overhead vs compiled.

```bash
# Run with TypeScript execution via tsx (development only)
pnpm start issues list -l 5

# Direct execution for debugging
npx tsx src/main.ts --api-token <token> issues read ABC-123
```

--------------------------------

### Improve GraphQL API Calls: Before vs. After

Source: https://github.com/czottmann/linearis/blob/main/docs/performance.md

Demonstrates the transition from multiple sequential API calls to a single, comprehensive GraphQL query for fetching issue data. This significantly reduces the number of network requests, improving performance.

```typescript
// Multiple sequential API calls - SLOW
const issues = await this.client.issues({ first: 10 });
for (const issue of issues.nodes) {
  const state = await issue.state;
  const team = await issue.team;
  const assignee = await issue.assignee;
  const project = await issue.project;
  const labels = await issue.labels();
}
```

```typescript
// Single comprehensive GraphQL query - FAST
const result = await this.graphQLService.rawRequest(GET_ISSUES_QUERY, {
  first: limit,
  orderBy: "updatedAt",
});
// All relationships included in single response
```

--------------------------------

### Search Issues - Query and Filter Issues

Source: https://context7.com/czottmann/linearis/llms.txt

Searches issues by text query or filters by team, assignee, project, and state. Supports both UUID and human-friendly identifiers. Combines multiple filters with result limiting for targeted issue discovery.

```bash
# Text search
linearis issues search "authentication bug"

# Filter by team (supports team key, name, or UUID)
linearis issues search "login" --team ENG
linearis issues search "login" --team "Engineering"

# Filter by assignee, project, and states
linearis issues search "api" --assignee user@example.com --project "Backend Services" --states "In Progress,In Review"

# Combine filters with limit
linearis issues search "performance" --team PROD --limit 5
```

```json
[
  {
    "id": "issue-uuid",
    "identifier": "ENG-124",
    "title": "Optimize authentication API response time",
    "description": "Current latency is 500ms, target is 100ms",
    "state": {
      "id": "state-uuid",
      "name": "In Review"
    },
    "assignee": {
      "id": "user-uuid",
      "name": "John Doe"
    },
    "team": {
      "id": "team-uuid",
      "key": "ENG",
      "name": "Engineering"
    },
    "priority": 2,
    "labels": [
      {
        "id": "label-uuid",
        "name": "performance"
      }
    ],
    "comments": [],
    "createdAt": "2024-01-16T09:00:00.000Z",
    "updatedAt": "2024-01-16T15:30:00.000Z"
  }
]
```

--------------------------------

### Create Comment

Source: https://context7.com/czottmann/linearis/llms.txt

Add a comment to an issue.

```APIDOC
## POST /issues/{id}/comments

### Description
Adds a comment to a specific issue. Supports using either the issue's UUID or its identifier.

### Method
POST

### Endpoint
`/issues/{id}/comments`

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier or UUID of the issue to comment on.

#### Request Body
- **body** (string) - Required - The content of the comment.

### Request Example
```bash
# Create comment on issue using identifier
linearis comments create ENG-123 --body "Fixed in PR #456"

# Create comment using UUID
linearis comments create issue-uuid --body "Deployed to staging for testing"
```

### Response
#### Success Response (201)
- **id** (string) - The unique ID of the created comment.
- **body** (string) - The content of the comment.
- **issueId** (string) - The ID of the issue the comment belongs to.
- **userId** (string) - The ID of the user who posted the comment.
- **createdAt** (string) - Timestamp when the comment was created.
- **updatedAt** (string) - Timestamp when the comment was last updated.

#### Response Example
```json
{
  "id": "comment-uuid",
  "issueId": "issue-uuid",
  "userId": "user-uuid",
  "body": "Fixed in PR #456",
  "createdAt": "2024-01-16T17:00:00.000Z",
  "updatedAt": "2024-01-16T17:00:00.000Z"
}
```
```

--------------------------------

### Benchmark Performance Improvement Commands

Source: https://github.com/czottmann/linearis/blob/main/docs/performance.md

Provides bash commands used for benchmarking the performance of various Linear CLI operations, including single issue read, listing issues, creating issues, and searching issues. The 'time' command is used to measure execution duration.

```bash
# Single issue read
time pnpm start issues read ABC-123

# List issues  
time pnpm start issues list -l 10

# Create issue
time pnpm start issues create --title "Test" --team ABC

# Search issues
time pnpm start issues search "test" --team ABC
```

--------------------------------

### Create Issue

Source: https://context7.com/czottmann/linearis/llms.txt

Create a new issue with smart ID resolution for various fields.

```APIDOC
## POST /issues

### Description
Creates a new issue. Supports smart ID resolution for teams, projects, labels, and parent issues, allowing the use of human-friendly names instead of UUIDs.

### Method
POST

### Endpoint
`/issues`

### Parameters
#### Query Parameters
- **team** (string) - Required - The team key or name for the issue.
- **title** (string) - Required - The title of the new issue.
- **description** (string) - Optional - A detailed description for the issue.
- **assignee** (string) - Optional - The UUID of the user to assign the issue to.
- **priority** (integer) - Optional - The priority level of the issue (e.g., 1 for highest).
- **project** (string) - Optional - The project key or name for the issue.
- **labels** (string) - Optional - Comma-separated list of label names for the issue.
- **status** (string) - Optional - The initial status of the issue.
- **parent-ticket** (string) - Optional - The identifier of the parent issue.
- **milestone** (string) - Optional - The UUID of the milestone for the issue (requires project).

### Request Example
```bash
# Minimal issue creation with team key
linearis issues create "Fix memory leak in API server" --team ENG

# Full-featured issue with all options
linearis issues create "Implement user authentication" \
  --team "Engineering" \
  --description "Add OAuth 2.0 support with JWT tokens" \
  --assignee user-uuid \
  --priority 1 \
  --project "Backend Services" \
  --labels "feature,security" \
  --status "In Progress" \
  --parent-ticket ENG-100

# With milestone (requires project)
linearis issues create "Database migration script" \
  --team ENG \
  --project "Q4 Platform" \
  --milestone milestone-uuid
```

### Response
#### Success Response (200)
- **id** (string) - The unique ID of the newly created issue.
- **identifier** (string) - The human-readable identifier of the issue (e.g., ENG-125).
- **title** (string) - The title of the issue.
- **description** (string) - The description of the issue.
- **state** (object) - The state of the issue.
- **assignee** (object) - The user assigned to the issue.
- **team** (object) - The team associated with the issue.
- **project** (object) - The project the issue belongs to.
- **priority** (integer) - The priority level of the issue.
- **labels** (array) - Labels applied to the issue.
- **comments** (array) - Comments on the issue.
- **createdAt** (string) - Timestamp when the issue was created.
- **updatedAt** (string) - Timestamp when the issue was last updated.

#### Response Example
```json
{
  "id": "new-issue-uuid",
  "identifier": "ENG-125",
  "title": "Implement user authentication",
  "description": "Add OAuth 2.0 support with JWT tokens",
  "state": {
    "id": "state-uuid",
    "name": "In Progress"
  },
  "assignee": {
    "id": "user-uuid",
    "name": "John Doe"
  },
  "team": {
    "id": "team-uuid",
    "key": "ENG",
    "name": "Engineering"
  },
  "project": {
    "id": "project-uuid",
    "name": "Backend Services"
  },
  "priority": 1,
  "labels": [
    {
      "id": "label1-uuid",
      "name": "feature"
    },
    {
      "id": "label2-uuid",
      "name": "security"
    }
  ],
  "comments": [],
  "createdAt": "2024-01-16T16:00:00.000Z",
  "updatedAt": "2024-01-16T16:00:00.000Z"
}
```
```

--------------------------------

### Service Layer with Authentication and Factory

Source: https://github.com/czottmann/linearis/blob/main/docs/development.md

Encapsulates Linear API access behind a service factory that resolves authentication and returns an initialized service. This pattern centralizes token handling and separates command execution from service concerns.

```typescript
// src/utils/linear-service.ts (lines 479-484)
export async function createLinearService(
  options: CommandOptions,
): Promise<LinearService> {
  const apiToken = await getApiToken(options);
  return new LinearService(apiToken);
}
```

```typescript
import { createLinearService } from './utils/linear-service.js';

// Command setup using Commander.js (src/commands/issues.ts lines 9-16)
export function setupIssuesCommands(program: Command): void {
  const issues = program.command('issues')
    .description('Issue operations');

  // Show help when no subcommand
  issues.action(() => {
    issues.help();
  });

  // Example: execute service in a command
  program.command('start')
    .action(handleAsyncCommand(async () => {
      const service = await createLinearService(program.opts());
      await service.initialize();
      output.success('Service started');
    })));
}
```

--------------------------------

### Implementing Issue Read Command in TypeScript

Source: https://github.com/czottmann/linearis/blob/main/docs/development.md

This snippet defines a CLI command to retrieve issue details by ID or identifier using the Linear service. It wraps the async action with handleAsyncCommand for error handling and uses createLinearService to initialize the GraphQL client based on command options. Dependencies include Linear service methods like getIssueById and outputSuccess; inputs are issueId string and options; outputs formatted issue data; limitations include reliance on valid API tokens and supported ID formats.

```typescript
issues.command("read <issueId>")
  .description(
    "Get issue details (supports both UUID and identifier like ABC-123)",
  )
  .action(
    handleAsyncCommand(
      async (issueId: string, options: any, command: Command) => {
        const service = await createLinearService(
          command.parent!.parent!.opts(),
        );
        const result = await service.getIssueById(issueId);
        outputSuccess(result);
      },
    ),
  );
```

--------------------------------

### List Issues - Recent Issues Query

Source: https://context7.com/czottmann/linearis/llms.txt

Retrieves recent issues with all relationships in a single optimized GraphQL query, reducing API calls from 1 + (5 × N issues) to just 1 call. Supports limiting results and authentication via environment variables.

```bash
# List 25 most recent issues (default)
linearis issues list

# Limit to 10 issues
linearis issues list --limit 10

# Using environment variable for auth
LINEAR_API_TOKEN=lin_api_abc123 linearis issues list
```

```json
[
  {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "identifier": "ENG-123",
    "title": "Fix login bug in authentication flow",
    "description": "Users report timeout errors when logging in",
    "state": {
      "id": "state-uuid",
      "name": "In Progress"
    },
    "assignee": {
      "id": "user-uuid",
      "name": "Jane Smith"
    },
    "team": {
      "id": "team-uuid",
      "key": "ENG",
      "name": "Engineering"
    },
    "project": {
      "id": "project-uuid",
      "name": "Q4 Platform Improvements"
    },
    "priority": 1,
    "estimate": 5,
    "labels": [
      {
        "id": "label-uuid",
        "name": "bug"
      }
    ],
    "comments": [],
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-16T14:45:00.000Z"
  }
]
```

--------------------------------

### List labels in Linear (CLI)

Source: https://context7.com/czottmann/linearis/llms.txt

Lists all labels in Linear, optionally filtered by team. The output is a JSON object containing an array of label objects, including scope and team information.

```bash
linearis labels list
linearis labels list --team ENG
linearis labels list --team "Engineering"
```

```json
{
  "labels": [
    {
      "id": "label1-uuid",
      "name": "bug",
      "color": "#e5484d",
      "scope": "team",
      "team": {
        "id": "team-uuid",
        "name": "Engineering"
      }
    },
    {
      "id": "label2-uuid",
      "name": "feature",
      "color": "#0090ff",
      "scope": "team",
      "team": {
        "id": "team-uuid",
        "name": "Engineering"
      },
      "group": {
        "id": "group-uuid",
        "name": "Type"
      }
    },
    {
      "id": "label3-uuid",
      "name": "security",
      "color": "#f76808",
      "scope": "workspace"
    }
  ]
}
```

--------------------------------

### ES Modules Import Style with .js Extension

Source: https://github.com/czottmann/linearis/blob/main/docs/development.md

All source files use ES modules and import with the .js extension for compatibility. Named exports are preferred and interfaces are colocated with implementation to keep types clear.

```typescript
// Example service function (src/utils/linear-service.ts)
export async function createLinearService(
  options: CommandOptions,
): Promise<LinearService> {
  const apiToken = await getApiToken(options);
  return new LinearService(apiToken);
}

// Usage in src/main.ts (lines 3-5)
import { createLinearService } from './utils/linear-service.js';
import { output } from './utils/output.js';

const program = new Command();
program.command('start')
  .action(() => {
    output.info('Starting Linearis');
  });
program.parse();
```

```typescript
// Import/Export with .js extension (src/main.ts)
import { createLinearService } from './utils/linear-service.js';

// ... rest of imports (lines 3-5)

// Named exports and .js imports (src/utils/auth.ts)
export interface AuthConfig {
  token?: string;
  email?: string;
  password?: string;
}

export async function getApiToken(
  options: CommandOptions,
): Promise<string> {
  if (options.authConfig?.token) {
    return options.authConfig.token;
  }
  // ... additional lookup logic as needed
  throw new Error('API token not found');
}

// ... exports and async functions (lines 18, 38)
export const auth = {
  isReady(): boolean {
    // ...
    return true;
  },
};
```

--------------------------------

### Create multi-line comment in Linear (CLI)

Source: https://context7.com/czottmann/linearis/llms.txt

Creates a comment in Linear with multi-line content. The CLI command includes the issue identifier and the comment body. The output is a JSON object with the comment details.

```bash
linearis comments create ENG-123 --body "Testing results:
- Login flow: ✓
- Session persistence: ✓
- Error handling: ✓"
```

```json
{
  "id": "comment-uuid",
  "body": "Fixed in PR #456",
  "user": {
    "id": "user-uuid",
    "name": "John Doe"
  },
  "createdAt": "2024-01-16T17:00:00.000Z",
  "updatedAt": "2024-01-16T17:00:00.000Z"
}
```

--------------------------------

### GraphQL Single Query Optimization (TypeScript)

Source: https://github.com/czottmann/linearis/blob/main/docs/architecture.md

This pattern demonstrates how to replace multiple API calls with a single GraphQL query for fetching issues. It utilizes a GraphQLService to execute a raw request, optimizing data retrieval and reducing network overhead. The input `limit` and `orderBy` parameters control the query execution.

```typescript
const GET_ISSUES_QUERY = `query issues($first: Int, $orderBy: IssueOrder) {
  issues(first: $first, orderBy: $orderBy) {
    nodes {
      id
      title
      completedAt
      url
    }
  }
}`;

// Replaces 1 + (5 × N) API calls with single GraphQL query
const result = await this.graphQLService.rawRequest(GET_ISSUES_QUERY, {
  first: limit,
  orderBy: "updatedAt" as any,
});
```

--------------------------------

### GraphQL Single-Query Strategy

Source: https://github.com/czottmann/linearis/blob/main/docs/development.md

Fetches issues using a single GraphQL query with sorting and a default limit to avoid N+1 queries and reduce latency by retrieving complete results in one round-trip.

```typescript
// From src/utils/graphql-issues-service.ts lines 32-46
const GET_ISSUES_QUERY = /* GraphQL */ `
  query GetIssues($first: Int!, $orderBy: IssueOrderBy!) {
    issues(first: $first, orderBy: $orderBy) {
      nodes {
        id
        identifier
        title
        description
        state { id name }
      }
    }
  }
`;

async getIssues(
  graphQLService: GraphQLService,
  limit = 25,
): Promise<LinearIssue[]> {
  const result = await graphQLService.rawRequest(GET_ISSUES_QUERY, {
    first: limit,
    orderBy: 'updatedAt',
  });
  return result?.data?.issues?.nodes ?? [];
}
```

--------------------------------

### GraphQL Batch Resolution Pattern

Source: https://github.com/czottmann/linearis/blob/main/docs/development.md

Resolves multiple lookup keys (e.g., team, project, labels) in a single batched GraphQL request to minimize round-trips and improve performance.

```typescript
// From src/utils/graphql-issues-service.ts lines 294-301
const BATCH_RESOLVE_FOR_CREATE_QUERY = /* GraphQL */ `
  query BatchResolveForCreate(
    $teamName: String!
    $projectName: String!
    $labelNames: [String!]!
  ) {
    teams: teams(filter: { name: { eq: $teamName } }) { nodes { id name } }
    projects(filter: { name: { eq: $projectName } }) { nodes { id name } }
    labels(filter: { name: { in: $labelNames } }) { nodes { id name } }
  }
`;

// Call within GraphQL service:
// const result = await this.graphQLService.rawRequest(
//   BATCH_RESOLVE_FOR_CREATE_QUERY,
//   { teamName, projectName, labelNames },
// );
```