### Install Linearis from Git

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

Clone the repository and install dependencies to prepare the environment.

```bash
git clone https://github.com/linearis-oss/linearis.git
cd linearis
npm install
```

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

### Quick Start Commands

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

Common operations for interacting with Linear issues and comments.

```bash
# Discover available commands
linearis usage

# Drill into a domain
linearis issues usage

# List recent issues
linearis issues list --limit 10

# Search for issues
linearis issues search "authentication bug"

# Create an issue
linearis issues create "Fix login flow" --team Platform --priority 2

# Add a comment
linearis comments create ENG-42 --body "Investigating this now"
```

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

### AI Agent System Prompt Example

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

Example configuration for integrating Linearis into AI agent system prompts.

```markdown
## Linear (project management)

Tool: `linearis` CLI via Bash. All output is JSON.

Discovery: Run `linearis usage` once to see available domains. Run `linearis <domain> usage` for full command reference of a specific domain. Do NOT guess flags or subcommands -- check usage first.

Ticket format: "ABC-123". Always reference tickets by their identifier.

Workflow rules:
- When creating a ticket, ask the user which project to assign it to if unclear.
- For subtasks, inherit the parent ticket's project by default.
- When a task in a ticket description changes status, update the description.
- For progress beyond simple checkbox changes, add a comment instead of editing the description.

File handling: `issues read` returns an `embeds` array with signed download URLs and expiration timestamps. Use `files download` to retrieve them. Use `files upload` to attach new files, then reference the returned URL in comments or descriptions.
```

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

### Initialize Development Environment

Source: https://github.com/linearis-oss/linearis/blob/main/CONTRIBUTING.md

Commands to clone the repository, install dependencies, and run development tasks.

```bash
git clone https://github.com/linearis-oss/linearis.git
cd linearis
npm install        # Install deps, codegen, and lefthook (via prepare hook)
npm start          # Development mode (tsx, no compilation)
npm test           # Run tests
npm run build      # Compile to dist/
npm run check      # Biome format + lint (auto-fix)
npm run generate   # Regenerate GraphQL types from .graphql files
```

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

### Get Full Command Reference

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

Retrieve the complete documentation for a specific domain.

```bash
linearis <domain> usage
```

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

### Conventional Commit Examples

Source: https://github.com/linearis-oss/linearis/blob/main/CONTRIBUTING.md

Examples of valid commit messages following the project conventions.

```text
fix: resolve null pointer in auth flow
feat(api): add rate limiting endpoint
docs: update README with new commands
```

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

### Install Dependencies and Run Commands

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

Commands for installing project dependencies, running in development mode using tsx, building for production, and running tests.

```bash
# Install dependencies (also runs GraphQL codegen)
npm install
```

```bash
# Run in development mode (uses tsx)
npm start issues list -l 5
```

```bash
# Run with explicit token
npx tsx src/main.ts --api-token <token> issues list
```

```bash
# Build for production
npm run build
```

```bash
# Run tests
npm test
```

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

### Install via Direct Git URL

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

Install the package directly from the remote repository using npm.

```bash
npm install git+https://github.com/linearis-oss/linearis.git
```

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

### Run integration tests

Source: https://github.com/linearis-oss/linearis/blob/main/docs/testing.md

Setup and execution commands for integration tests requiring an API token.

```bash
export LINEAR_API_TOKEN="lin_api_..."
npm run build
npx vitest run tests/integration
```

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

### Install Dependencies and Run GraphQL Codegen

Source: https://github.com/linearis-oss/linearis/blob/main/docs/build-system.md

Installs project dependencies and automatically runs GraphQL codegen as a postinstall hook.

```bash
npm install
```

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

### Install Linearis

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

Install the CLI globally via npm. Requires Node.js version 22 or higher.

```bash
npm install -g linearis
```

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

### CLI operation timing output

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

Example output showing the total wall time for a list operation.

```text
npm start issues list -l 1 < /dev/null  0.62s user 0.08s system 77% cpu 0.904 total
```

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

### Define Domain Meta for Usage Documentation

Source: https://github.com/linearis-oss/linearis/blob/main/AGENTS.md

Example of defining `DomainMeta` for a command group, including its name, summary, context, arguments, and related commands.

```typescript
export const ENTITY_META: DomainMeta = {
  name: "entity",
  summary: "short one-line description",
  context: "data model explanation",
  arguments: { name: "description" },
  seeAlso: ["related-domain command"],
};
```

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

### Mocking Dependencies in Unit Tests

Source: https://github.com/linearis-oss/linearis/blob/main/CLAUDE.md

Examples of mocking dependencies for different test targets.

```typescript
{ sdk: { teams: vi.fn() } } as unknown as LinearSdkClient
```

```typescript
{ request: vi.fn() } as unknown as GraphQLClient
```

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

### Implement a resolver test

Source: https://github.com/linearis-oss/linearis/blob/main/docs/testing.md

Full example of a resolver test file covering happy paths and error handling.

```typescript
import { describe, expect, it, vi } from "vitest";
import type { LinearSdkClient } from "../../../src/client/linear-client.js";
import { resolveTeamId } from "../../../src/resolvers/team-resolver.js";

describe("resolveTeamId", () => {
  it("should return UUID as-is", async () => {
    const client = { sdk: {} } as unknown as LinearSdkClient;
    const result = await resolveTeamId(client, "550e8400-e29b-41d4-a716-446655440000");
    expect(result).toBe("550e8400-e29b-41d4-a716-446655440000");
  });

  it("should resolve team by key", async () => {
    const mockSdk = {
      teams: vi.fn().mockResolvedValue({
        nodes: [{ id: "uuid-456", key: "ENG" }],
      }),
    };
    const client = { sdk: mockSdk } as unknown as LinearSdkClient;

    const result = await resolveTeamId(client, "ENG");
    expect(result).toBe("uuid-456");
  });

  it("should throw when team is not found", async () => {
    const mockSdk = {
      teams: vi.fn().mockResolvedValue({ nodes: [] }),
    };
    const client = { sdk: mockSdk } as unknown as LinearSdkClient;

    await expect(resolveTeamId(client, "NOPE")).rejects.toThrow();
  });
});
```

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

### GraphQL Query Definition (GraphQL)

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

Example of a GraphQL query definition for fetching issues, including parameters and fields. This file should be placed in `graphql/queries/`.

```graphql
# graphql/queries/issues.graphql
query GetIssues($first: Int) {
  issues(first: $first, orderBy: updatedAt) {
    nodes {
      id
      identifier
      title
      ...
    }
  }
}
```

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

### Mock network layer in client tests

Source: https://github.com/linearis-oss/linearis/blob/main/docs/testing.md

Minimal mock setup for client-level tests.

```typescript
const mockClient = { rawRequest: vi.fn() };
```

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

### Register Command Groups

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

Example of how to register new command groups, such as entity commands, within the main application file (`src/main.ts`).

```typescript
import { setupEntityCommands } from "./commands/entity.js";
setupEntityCommands(program);
```

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

### Linearis Data Flow

Source: https://github.com/linearis-oss/linearis/blob/main/docs/files.md

Illustrates the data flow within the Linearis application, starting from CLI input and progressing through command execution, resolver and service layers, to the final JSON output. Key components like context creation, SDK usage for identifier conversion, and GraphQL for CRUD operations are highlighted.

```text
CLI Input --> Command --> Resolver --> Service --> JSON Output
                |            |            |
           createContext()   SDK       GraphQL
                          (name->UUID)  (CRUD)
```

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

### Create an initiative

Source: https://context7.com/linearis-oss/linearis/llms.txt

Create a new initiative with specified metadata.

```bash
linearis initiatives create "Platform Modernization" \
  --description "Modernize core platform infrastructure" \
  --owner "jane@example.com" \
  --status active \
  --target-date 2025-09-30
```

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

### Create a Document

Source: https://context7.com/linearis-oss/linearis/llms.txt

Creates a new document with a title, content, and optional project association, icon, and color. Use for drafting new documentation.

```bash
linearis documents create \
  --title "API Design Doc" \
  --content "# API Design\n\n## Overview\n..." \
  --project "Mobile App" \
  --icon "document" \
  --color "#4B5563"
```

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

### Discover Available Commands

Source: https://context7.com/linearis-oss/linearis/llms.txt

Use the usage command to explore available domains and their specific operations.

```bash
# Get overview of all domains (~200 tokens)
linearis usage

# Get detailed usage for a specific domain (~300-500 tokens)
linearis issues usage
linearis comments usage
linearis projects usage
```

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

### Publish Project Version

Source: https://github.com/linearis-oss/linearis/blob/main/CONTRIBUTING.md

Command to trigger the local release process.

```bash
npm run release    # Runs tests, builds, and publishes via clean-publish
```

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

### Generate Usage Documentation

Source: https://github.com/linearis-oss/linearis/blob/main/docs/build-system.md

Executes the command to generate token-optimized usage documentation for LLM agents, capturing the output to USAGE.md.

```bash
npm run generate:usage
```

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

### Test pure functions

Source: https://github.com/linearis-oss/linearis/blob/main/docs/testing.md

Example of testing pure functions in the common directory which require no mocks.

```typescript
import { isUuid } from "../../src/common/identifier.js";

expect(isUuid("550e8400-e29b-41d4-a716-446655440000")).toBe(true);
expect(isUuid("ABC-123")).toBe(false);
```

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

### Provide API Token via CLI or Environment

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

Alternative methods for providing authentication tokens without using the local store.

```bash
# Via CLI flag
linearis --api-token <token> issues list

# Via environment variable
LINEAR_API_TOKEN=<token> linearis issues list
```

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

### Execute Production Build

Source: https://github.com/linearis-oss/linearis/blob/main/docs/build-system.md

Runs the compiled JavaScript entry point from the dist/ directory with a specified command.

```bash
node dist/main.js <command>
```

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

### Adding Unit Tests

Source: https://github.com/linearis-oss/linearis/blob/main/CLAUDE.md

Guidelines for writing unit tests for resolvers, services, and common modules. Emphasizes mocking dependencies at a single layer deep.

```text
Need tests?
  → Add tests/unit/{resolvers,services,common}/*.test.ts
  → Mock ONE layer deep (see Testing section below)
```

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

### Define a Service Function

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

Example of a plain exported function for a service, adhering to the preference for functions over classes in resolvers and services.

```typescript
// Good: plain function
export async function listIssues(client: GraphQLClient, limit?: number): Promise<Issue[]> { ... }
```

```typescript
// Avoid: class with methods
class IssueService { async listIssues(...) { ... } }
```

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

### Linearis Functionality Decision Tree

Source: https://github.com/linearis-oss/linearis/blob/main/AGENTS.md

Workflow guide for adding new GraphQL operations, resolvers, services, or CLI commands.

```text
Need a new GraphQL operation?
  → Add/edit graphql/{queries,mutations}/*.graphql
  → Run: npm run generate
  → Import DocumentNode + types from src/gql/graphql.js

Need to resolve a human-friendly ID?
  → Add/edit src/resolvers/*-resolver.ts
  → Use LinearSdkClient, return UUID string
  → Pattern: UUID passthrough → SDK lookup → notFoundError()

Need business logic / CRUD?
  → Add/edit src/services/*-service.ts
  → Use GraphQLClient, accept pre-resolved UUIDs only
  → Import codegen DocumentNode + types

Need a CLI command?
  → Add/edit src/commands/*.ts
  → Use createContext() → resolve IDs → call service → outputSuccess()
  → Register in src/main.ts (setupXCommands + META in allMetas[])
  → Add DomainMeta export + usage subcommand

Need tests?
  → Add tests/unit/{resolvers,services,common}/*.test.ts
  → Mock ONE layer deep (see Testing section below)
```

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

### Discover Commands

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

Retrieve usage information for the CLI or specific domains.

```bash
# Discovery
linearis usage                # overview of all domains
linearis issues usage         # detailed usage for one domain
```

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

### Implement Command Pattern for Issue Creation

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

Sets up a 'create' command for issues, handling user input, resolving team IDs, and calling the issue creation service. Requires wrapping action handlers with `handleCommand` for error output.

```typescript
import { Command } from "commander";
import { createContext } from "../common/context.js";
import { handleCommand, outputSuccess } from "../common/output.js";
import { resolveTeamId } from "../resolvers/team-resolver.js";
import { createIssue } from "../services/issue-service.js";

export function setupIssuesCommands(program: Command): void {
  const issues = program.command("issues");

  issues
    .command("create <title>")
    .option("--team <id>", "Team key, name, or UUID")
    .action(handleCommand(async (title, options, command) => {
      const ctx = await createContext(command.parent!.parent!.opts());
      const teamId = options.team
        ? await resolveTeamId(ctx.sdk, options.team)
        : undefined;
      const result = await createIssue(ctx.gql, { title, teamId });
      outputSuccess(result);
    }));
}
```

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

### Manage Projects

Source: https://context7.com/linearis-oss/linearis/llms.txt

Commands to list, read, create, and update projects, including team assignments and status tracking.

```bash
linearis projects list --limit 100
linearis projects read "Mobile App"
linearis projects create "Q2 Platform Upgrade" \
  --teams "Platform,Infrastructure" \
  --description "Major platform upgrade for Q2" \
  --lead "jane@example.com" \
  --members "john@example.com,bob@example.com" \
  --priority 1 \
  --status "Planned" \
  --start-date 2025-04-01 \
  --target-date 2025-06-30 \
  --labels "strategic,platform"
linearis projects update "Q2 Platform Upgrade" \
  --status "Started" \
  --priority 2 \
  --target-date 2025-07-15
```

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

### Get Cycles Around Active Cycle

Source: https://context7.com/linearis-oss/linearis/llms.txt

Retrieves cycles within a specified window around the active cycle. Useful for planning or reviewing adjacent sprints.

```bash
linearis cycles list --team ENG --window 2
```

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

### Run Project Tests

Source: https://github.com/linearis-oss/linearis/blob/main/CONTRIBUTING.md

Commands for executing unit tests and generating coverage reports.

```bash
npm test               # Run all unit tests
npm run test:coverage  # Coverage report
npm run build          # Compile TypeScript (required before integration tests)
```

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

### Creating New CLI Commands

Source: https://github.com/linearis-oss/linearis/blob/main/CLAUDE.md

Steps for adding new CLI commands. This includes using createContext(), resolving IDs, calling services, outputting success messages, and registering the command in src/main.ts.

```text
Need a CLI command?
  → Add/edit src/commands/*.ts
  → Use createContext() → resolve IDs → call service → outputSuccess()
  → Register in src/main.ts (setupXCommands + META in allMetas[])
  → Add DomainMeta export + usage subcommand
```

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

### GraphQL Workflow Steps

Source: https://github.com/linearis-oss/linearis/blob/main/AGENTS.md

Outlines the standard workflow for editing GraphQL files, generating code, and using typed queries with a client.

```text
1. Edit:   graphql/{queries,mutations}/*.graphql
2. Run:    npm run generate
3. Import: import { FooDocument, type FooQuery } from "../gql/graphql.js"
4. Use:    client.request<FooQuery>(FooDocument, variables)
```

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

### Run the test suite

Source: https://github.com/linearis-oss/linearis/blob/main/docs/project-overview.md

This command executes the project's test suite using Vitest. Ensure all tests pass before merging changes or deploying.

```bash
npm test
```

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

### Open Vitest Browser UI

Source: https://github.com/linearis-oss/linearis/blob/main/docs/build-system.md

Launches the Vitest browser-based user interface for interactive testing.

```bash
npm run test:ui
```

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

### Manage project links

Source: https://context7.com/linearis-oss/linearis/llms.txt

Link or unlink projects to initiatives.

```bash
linearis initiatives add-project "Q2 Growth" "Mobile App"
```

```bash
linearis initiatives remove-project "Q2 Growth" "Mobile App"
```

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

### Publish Package

Source: https://github.com/linearis-oss/linearis/blob/main/docs/build-system.md

Publishes the package to the registry, triggering pre-publish checks including build, test, and verification of the executable binary.

```bash
npm publish
```

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

### Unit Test Directory Structure

Source: https://github.com/linearis-oss/linearis/blob/main/docs/files.md

Unit tests are organized to mirror the source structure, with specific directories for resolvers, services, and common utilities. Resolver tests mock the SDK client, while service tests mock the GraphQL client. Common tests require no mocks.

```bash
tests/unit/
  resolvers/   # e.g., team-resolver.test.ts
  services/    # e.g., issue-service.test.ts
  common/      # e.g., identifier.test.ts
```

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

### List Users with Pagination

Source: https://context7.com/linearis-oss/linearis/llms.txt

Lists users with specified limits and cursor for pagination. Useful for large workspaces.

```bash
linearis users list --limit 50 --after cursor
```

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

### Run Linearis in Docker

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

Build the image and execute commands by passing the API token as an environment variable.

```bash
docker build -t linearis .
docker run -e LINEAR_API_TOKEN=lin_api_... linearis issue list
```

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

### Create an initiative update

Source: https://context7.com/linearis-oss/linearis/llms.txt

Post a new status update with health indicators.

```bash
linearis initiatives updates create \
  --initiative "Q2 Growth" \
  --body "## Weekly Update\n\nMade significant progress on mobile app..." \
  --health onTrack
```

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

### Project File Map

Source: https://github.com/linearis-oss/linearis/blob/main/CLAUDE.md

Overview of the project directory structure.

```text
src/
  main.ts              # entry point, command registration
  client/              # GraphQLClient, LinearSdkClient
  resolvers/           # ID resolution (human → UUID)
  services/            # business logic (GraphQL CRUD)
  commands/            # CLI definitions (Commander.js)
  common/              # context, output, errors, types, auth, usage
  gql/                 # GENERATED — do not edit
graphql/
  queries/             # .graphql query definitions
  mutations/           # .graphql mutation definitions
tests/
  unit/                # mirrors src/ structure
  integration/         # CLI integration tests (need API token)
```

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

### Run Linearis Development Commands

Source: https://github.com/linearis-oss/linearis/blob/main/AGENTS.md

Common npm scripts for managing dependencies, testing, building, and generating code.

```bash
npm install          # install deps, codegen, and lefthook (via prepare hook)
npm test             # unit tests (vitest)
npm run build        # compile to dist/
npm run generate     # regenerate GraphQL types from .graphql files
npm run check        # biome format + lint (auto-fix)
npm run check:ci     # biome format + lint (CI, no fix)
npm run generate:usage  # regenerate USAGE.md
```

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

### List Teams with Pagination

Source: https://context7.com/linearis-oss/linearis/llms.txt

Lists teams with specified limits and cursor for pagination. Useful for workspaces with a large number of teams.

```bash
linearis teams list --limit 20 --after cursor
```

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

### Containerize Linearis with Docker

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

Use this Dockerfile to build a container image for the CLI tool.

```dockerfile
FROM node:22-alpine
WORKDIR /app
COPY package.json package-lock.json tsconfig.json codegen.config.ts ./
COPY src/ ./src/
COPY graphql/ ./graphql/
RUN npm install
ENTRYPOINT ["node", "dist/main.js"]
```

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

### Manage Milestones

Source: https://context7.com/linearis-oss/linearis/llms.txt

Commands to track project phases and deadlines by listing, reading, creating, or updating milestones.

```bash
linearis milestones list --project "Mobile App"
linearis milestones read "Beta Release" --project "Mobile App" --limit 50
linearis milestones create "Alpha Release" \
  --project "Mobile App" \
  --description "First internal alpha build" \
  --target-date 2025-02-15
linearis milestones update "Alpha Release" \
  --project "Mobile App" \
  --target-date 2025-02-20 \
  --description "Updated timeline for alpha"
```

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

### Run Vitest commands

Source: https://github.com/linearis-oss/linearis/blob/main/docs/testing.md

Standard npm scripts for executing tests, watching for changes, and generating reports.

```bash
npm test                # Run all tests once
npm run test:watch      # Watch mode (re-runs on changes)
npm run test:ui         # Interactive UI
npm run test:coverage   # Generate coverage report
npm run test:commands   # CLI command coverage report
```

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

### Run Unit Tests with Vitest

Source: https://github.com/linearis-oss/linearis/blob/main/AGENTS.md

Execute unit tests using npm or directly with Vitest. You can run all tests or target specific suites.

```bash
npm test                        # unit tests
```

```bash
npx vitest run tests/unit/resolvers  # specific suite
```

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

### Read initiative details

Source: https://context7.com/linearis-oss/linearis/llms.txt

Retrieve full details of a specific initiative by name.

```bash
linearis initiatives read "Q2 Growth"
```

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

### CLI Testing Commands

Source: https://github.com/linearis-oss/linearis/blob/main/CLAUDE.md

Common commands for running unit tests, specific suites, and coverage reports.

```bash
npm test                        # unit tests
npx vitest run tests/unit/resolvers  # specific suite
npm run test:coverage           # coverage report
```

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

### Compile to production build

Source: https://github.com/linearis-oss/linearis/blob/main/docs/project-overview.md

Execute this command to compile the project's TypeScript code into JavaScript, outputting the results to the dist/ directory. This is typically done before deployment.

```bash
npm run build
```

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

### Build and Link Linearis

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

Compile the TypeScript source and create a global command alias.

```bash
npm run build
npm link
```

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

### Run Development Server with Command

Source: https://github.com/linearis-oss/linearis/blob/main/docs/build-system.md

Runs the codegen process and then executes a specified command using tsx for on-the-fly TypeScript execution.

```bash
npm start <command>
```

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

### List Labels with Pagination

Source: https://context7.com/linearis-oss/linearis/llms.txt

Lists labels with specified limits and cursor for pagination. Useful for workspaces with many labels.

```bash
linearis labels list --limit 100 --after cursor
```

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

### Execute Build Cleanup and Regeneration

Source: https://github.com/linearis-oss/linearis/blob/main/docs/build-system.md

Use this command sequence to resolve build failures by cleaning artifacts and regenerating types before rebuilding.

```bash
npm run clean && npm run generate && npm run build
```

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

### Download File with Custom Output Path

Source: https://context7.com/linearis-oss/linearis/llms.txt

Downloads a file from a Linear storage URL and saves it to a specified output path and filename. Allows for organized file management.

```bash
linearis files download "https://uploads.linear.app/xxxxx/file.pdf" --output ./downloads/report.pdf
```

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

### Authenticate with Linear API

Source: https://context7.com/linearis-oss/linearis/llms.txt

Manage authentication via interactive login, environment variables, or CLI flags.

```bash
# Interactive login (opens browser, stores encrypted token in ~/.linearis/token)
linearis auth login

# Check authentication status
linearis auth status
# Output: {"authenticated":true,"source":"~/.linearis/token","user":{"id":"...","name":"John Doe","email":"john@example.com"}}

# Using token via CLI flag
linearis --api-token lin_api_xxxxx issues list

# Using token via environment variable
LINEAR_API_TOKEN=lin_api_xxxxx linearis issues list

# Remove stored token
linearis auth logout
# Output: {"message":"Authentication token removed."}
```

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

### Manage initiative relations

Source: https://context7.com/linearis-oss/linearis/llms.txt

Create or remove parent/child relationships between initiatives.

```bash
linearis initiatives relate "Company OKRs" "Q2 Growth"
```

```bash
linearis initiatives unrelate "Company OKRs" "Q2 Growth"
```

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

### List initiative updates

Source: https://context7.com/linearis-oss/linearis/llms.txt

Retrieve a list of status updates for a specific initiative.

```bash
linearis initiatives updates list --initiative "Q2 Growth" --limit 10
```

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

### Format and Lint Code with Biome

Source: https://github.com/linearis-oss/linearis/blob/main/CLAUDE.md

Applies code formatting and linting rules using Biome, with auto-fixing enabled.

```bash
npm run check
```

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

### Generate coverage report

Source: https://github.com/linearis-oss/linearis/blob/main/docs/testing.md

Commands to generate and view the HTML coverage report.

```bash
npm run test:coverage
open coverage/index.html
```

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

### Command Action Handler Pattern

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

This pattern demonstrates how to handle commands by resolving necessary IDs using resolvers and then calling service functions. It includes context creation and output handling.

```typescript
.action(
  handleCommand(
    async (...args: unknown[]) => {
      const [options, command] = args as [OptionsType, Command];
      const ctx = await createContext(command.parent!.parent!.opts());

      // Resolve IDs
      const teamId = await resolveTeamId(ctx.sdk, options.team);
      const labelIds = await resolveLabelIds(ctx.sdk, options.labels.split(','));

      // Call service
      const result = await createIssue(ctx.gql, {
        teamId,
        labelIds,
        title: options.title,
      });

      outputSuccess(result);
    }
  )
)
```

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

### Use Correct Client in Resolver

Source: https://github.com/linearis-oss/linearis/blob/main/AGENTS.md

Illustrates the incorrect use of GraphQLClient in a resolver and the correct use of LinearSdkClient.

```typescript
// WRONG: resolver uses GraphQLClient
async function resolveTeamId(client: GraphQLClient) { ... }
```

```typescript
// RIGHT: resolver uses LinearSdkClient
async function resolveTeamId(client: LinearSdkClient) { ... }
```

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

### List All Users

Source: https://context7.com/linearis-oss/linearis/llms.txt

Retrieves a list of all users in the workspace. Useful for understanding team composition and for assignment purposes.

```bash
linearis users list
```

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

### Run in development mode

Source: https://github.com/linearis-oss/linearis/blob/main/docs/project-overview.md

Use this command to run the project in development mode using tsx. This is useful for quick iteration during development.

```bash
npm start
```

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

### List Documents in a Project

Source: https://context7.com/linearis-oss/linearis/llms.txt

Filters and lists documents associated with a specific project. Useful for organizing documentation by project.

```bash
linearis documents list --project "Mobile App"
```

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

### Create Document and Attach to Issue

Source: https://context7.com/linearis-oss/linearis/llms.txt

Creates a new document and directly associates it with a specific issue. Useful for documenting issue-specific findings or plans.

```bash
linearis documents create \
  --title "Investigation Notes" \
  --content "# Root Cause Analysis\n\n..." \
  --issue ENG-42
```

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

### Create New Issues

Source: https://context7.com/linearis-oss/linearis/llms.txt

Create issues with required team assignment and optional metadata like priority, labels, and project.

```bash
# Basic issue creation
linearis issues create "Fix login flow" --team ENG
# Output: {"id":"...","identifier":"ENG-43","title":"Fix login flow","status":{"name":"Backlog"},...}

# Full issue creation with all options
linearis issues create "Implement OAuth2 flow" \
  --team Platform \
  --description "Add support for OAuth2 authentication with Google and GitHub providers" \
  --priority 2 \
  --assignee "john@example.com" \
  --labels "feature,auth" \
  --project "Authentication Rewrite" \
  --status "Todo" \
  --estimate 5 \
  --due-date 2025-03-15
```

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

### Login for interactive authentication

Source: https://github.com/linearis-oss/linearis/blob/main/docs/project-overview.md

Initiates an interactive authentication flow for the Linearis CLI. This command opens Linear.app in your browser to authorize the CLI and securely stores the token locally.

```bash
linearis auth login
```

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

### Run CI Verification Checks

Source: https://github.com/linearis-oss/linearis/blob/main/AGENTS.md

Execute the full suite of checks required before claiming work is complete, including linting, formatting, type checking, and unit tests.

```bash
npm run check:ci       # biome lint + format check
```

```bash
npx tsc --noEmit       # type check
```

```bash
npm test               # unit tests
```

```bash
npm run build          # full build (includes codegen + usage generation)
```

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

### Run Command Coverage Analysis

Source: https://github.com/linearis-oss/linearis/blob/main/docs/build-system.md

Performs an analysis of command coverage for the project's command-line interface.

```bash
npm run test:commands
```

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

### Implementing Business Logic/CRUD Operations

Source: https://github.com/linearis-oss/linearis/blob/main/CLAUDE.md

Instructions for adding business logic or CRUD operations within services. Services should accept pre-resolved UUIDs and use the GraphQLClient. Import generated types and DocumentNodes.

```text
Need business logic / CRUD?
  → Add/edit src/services/*-service.ts
  → Use GraphQLClient, accept pre-resolved UUIDs only
  → Import codegen DocumentNode + types
```

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

### List and Search Issues

Source: https://context7.com/linearis-oss/linearis/llms.txt

Retrieve issues using filters, full-text search, and cursor-based pagination.

```bash
# List recent issues (default limit: 50)
linearis issues list --limit 10
# Output: {"nodes":[{"id":"...","identifier":"ENG-42","title":"Fix login flow","status":{"name":"In Progress"},...}],"pageInfo":{"hasNextPage":true,"endCursor":"..."}}

# Full-text search
linearis issues search "authentication bug" --limit 5
# Output: {"nodes":[{"id":"...","identifier":"ENG-123","title":"Authentication bug in OAuth flow",...}],"pageInfo":{...}}

# Filter by team, status, assignee, and priority
linearis issues list --team ENG --status "In Progress" --assignee "john@example.com" --priority 1

# Filter by project and labels
linearis issues list --project "Mobile App" --label "bug,urgent"

# Filter by dates
linearis issues list --created-after 2025-01-01 --due-before 2025-06-30

# Filter by cycle (sprint)
linearis issues list --team ENG --cycle "Sprint 5"

# Filter blocked issues
linearis issues list --has-blockers
linearis issues list --is-blocking

# Pagination with cursor
linearis issues list --limit 20 --after "cursor_from_previous_response"
```

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

### Upload a File

Source: https://context7.com/linearis-oss/linearis/llms.txt

Uploads a local file to Linearis storage. The output provides the URL for accessing the uploaded file.

```bash
linearis files upload ./screenshot.png
```

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

### Integration test for Cycles CLI

Source: https://github.com/linearis-oss/linearis/blob/main/docs/testing.md

Demonstrates how to list cycles as JSON using the CLI, with conditional execution based on the presence of an API token.

```typescript
import { describe, expect, it } from "vitest";
import { exec } from "child_process";
import { promisify } from "util";

const execAsync = promisify(exec);
const hasApiToken = !!process.env.LINEAR_API_TOKEN;

describe("Cycles CLI", () => {
  it.skipIf(!hasApiToken)("should list cycles as JSON", async () => {
    const { stdout } = await execAsync("node ./dist/main.js cycles list");
    const cycles = JSON.parse(stdout);
    expect(Array.isArray(cycles)).toBe(true);
  });
});
```

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

### Download a File from Linear Storage URL

Source: https://context7.com/linearis-oss/linearis/llms.txt

Downloads a file from a given Linear storage URL to the current directory. Useful for retrieving previously uploaded assets.

```bash
linearis files download "https://uploads.linear.app/xxxxx/file.pdf"
```

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

### Update an initiative

Source: https://context7.com/linearis-oss/linearis/llms.txt

Modify the status or description of an existing initiative.

```bash
linearis initiatives update "Platform Modernization" \
  --status completed \
  --description "Successfully modernized platform"
```

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

### Create Issues with Metadata and Relations

Source: https://context7.com/linearis-oss/linearis/llms.txt

Commands to create issues with specific team assignments, cycles, milestones, parent-child relationships, and issue blocking or linking.

```bash
linearis issues create "API refactoring" \
  --team ENG \
  --cycle "Sprint 6" \
  --project "Backend Improvements" \
  --project-milestone "Phase 1"
```

```bash
linearis issues create "Write unit tests" \
  --team ENG \
  --parent-ticket ENG-42
```

```bash
linearis issues create "Database migration" \
  --team ENG \
  --blocks ENG-50 \
  --blocked-by ENG-48 \
  --relates-to ENG-45
```

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

### Create an Attachment

Source: https://context7.com/linearis-oss/linearis/llms.txt

Adds a new external resource link to an issue. Requires the issue ID, a title, and the URL of the resource. Optional subtitle can be provided.

```bash
linearis attachments create ENG-42 \
  --title "Design Mockup" \
  --url "https://figma.com/file/xxxxx" \
  --subtitle "Login screen redesign"
```

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

### Download File with Overwrite

Source: https://context7.com/linearis-oss/linearis/llms.txt

Downloads a file from a Linear storage URL, overwriting the destination file if it already exists. Use when you need the latest version.

```bash
linearis files download "https://uploads.linear.app/xxxxx/file.pdf" --output ./file.pdf --overwrite
```

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

### CLI performance test commands

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

Commands used to benchmark the performance of various CLI operations.

```bash
time npm start issues read ABC-123
time npm start issues list -l 10
time npm start issues create --title "Test" --team ABC
time npm start issues search "test" --team ABC
```

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

### Cycles (Sprints)

Source: https://context7.com/linearis-oss/linearis/llms.txt

List and read cycles (time-boxed iterations) for teams. Cycles contain issues and have start/end dates.

```APIDOC
## Cycles (Sprints)

### Description
List and read cycles (time-boxed iterations) for teams. Cycles contain issues and have start/end dates.

### Method
GET

### Endpoint
/linearis/cycles

### Parameters
#### Path Parameters
None

#### Query Parameters
- **team** (string) - Required - The name or ID of the team.
- **limit** (integer) - Optional - The maximum number of cycles to return.

### Request Example
```bash
# List cycles for a team
linearis cycles list --team "Backend Team" --limit 10

# Read a specific cycle
linearis cycles read "Sprint 6" --team "Backend Team"
```

### Response
#### Success Response (200)
- **nodes** (array) - A list of cycle objects.
  - **id** (string) - The unique identifier of the cycle.
  - **name** (string) - The name of the cycle (e.g., "Sprint 6").
  - **startDate** (string) - The start date of the cycle.
  - **endDate** (string) - The end date of the cycle.
  - **issues** (object) - A list of issues within the cycle.

#### Response Example
```json
{
  "nodes": [{
    "id": "cycle-uuid",
    "name": "Sprint 6",
    "startDate": "2025-01-01",
    "endDate": "2025-01-15",
    "issues": {"nodes": [...]}
  }],
  "pageInfo": {}
}
```
```