playbooks

home / skills / openclaw / skills / linearis

linearis skill

/skills/whoisnnamdi/linearis

This skill provides a Linear.app CLI interface with JSON output to list, create, update, and search Linear issues for LLM agents.

npx playbooks add skill openclaw/skills --skill linearis

Review the files below or copy the command above to add this skill to your agents.

Files (2)
SKILL.md
2.4 KB
---
name: linearis
version: 1.0.0
description: Linear.app CLI for issue tracking. Use for listing, creating, updating, and searching Linear issues, comments, documents, cycles, and projects. Optimized for LLM agents with JSON output.
metadata: {"clawdbot":{"emoji":"📋","requires":{"bins":["linearis"]},"install":[{"id":"npm","kind":"node","package":"linearis","bins":["linearis"],"label":"Install linearis (npm)"}]}}
---

# linearis

CLI for [Linear.app](https://linear.app) with JSON output, designed for LLM agents.

## Setup

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

Auth (one of):
- `echo "lin_api_..." > ~/.linear_api_token` (recommended)
- `export LINEAR_API_TOKEN="lin_api_..."`
- `--api-token <token>` flag

Get API key: Linear Settings → Security & Access → Personal API keys

## Commands

### Issues

```bash
linearis issues list -l 20              # List recent issues
linearis issues list -l 10 --team WHO   # Filter by team
linearis issues search "bug"            # Full-text search
linearis issues read ABC-123            # Get issue details
linearis issues create --title "Fix bug" --team WHO --priority 2
linearis issues update ABC-123 --status "Done"
linearis issues update ABC-123 --title "New title" --assignee user123
linearis issues update ABC-123 --labels "Bug,Critical" --label-by adding
linearis issues update ABC-123 --parent-ticket EPIC-100  # Set parent
```

### Comments

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

### Documents

```bash
linearis documents list
linearis documents list --project "Backend"
linearis documents create --title "Spec" --content "# Overview..."
linearis documents read <doc-id>
linearis documents update <doc-id> --content "Updated"
linearis documents delete <doc-id>
```

### File Uploads/Downloads

```bash
linearis embeds upload ./screenshot.png
linearis embeds download "<url>" --output ./file.png
```

### Teams, Users, Projects

```bash
linearis teams list
linearis users list --active
linearis projects list
linearis cycles list --team WHO --active
```

### Full Usage

```bash
linearis usage  # Complete command reference (~1k tokens)
```

## Output

All commands return JSON by default. Pipe to `jq` for processing:

```bash
linearis issues list -l 5 | jq '.[].identifier'
```

## Priority Values

- 0: No priority
- 1: Urgent
- 2: High
- 3: Medium
- 4: Low

## Links

- Docs: https://github.com/czottmann/linearis
- Blog: https://zottmann.org/2025/09/03/linearis-my-linear-cli-built.html

Overview

This skill is a command-line interface for interacting with Linear.app focused on issue tracking, comments, documents, cycles, teams, and projects. It returns machine-friendly JSON by default and is optimized for use by LLM agents and automation workflows. Authentication supports a persistent token file, environment variable, or flag. The tool is lightweight and designed for scripting, backups, and agent-driven operations.

How this skill works

Commands map to Linear resources (issues, comments, documents, projects, teams, cycles) and emit JSON output for easy parsing. You authenticate with a Linear personal API key stored in a token file, environment variable, or passed as a flag. The CLI supports listing, searching, reading, creating, updating, deleting, and file embed uploads/downloads, and exposes human-friendly flags for priority, labels, assignees, and parent-child links. Use pipes and utilities like jq to integrate results into automation or agent logic.

When to use it

  • Automate creation and updates of Linear issues from scripts or workflows
  • Search and export issues, comments, or documents as JSON for backups or analytics
  • Integrate a language model agent that needs structured Linear data
  • Bulk-update priorities, labels, or assignees across issues
  • Upload and download embed files tied to Linear resources

Best practices

  • Store your token in a file (~/.linear_api_token) to avoid exposing it in process lists
  • Pipe command output to jq or other JSON tools for robust parsing
  • Use precise search queries and team/project filters to limit results and avoid rate limits
  • Test update commands with dry-run or small samples before bulk operations
  • Include identifiers (issue ID, doc ID) when scripting updates to avoid ambiguity

Example use cases

  • List recent issues for a team and feed JSON into a nightly report generator
  • Create issues from CI failures by calling the create command with title, team, and priority
  • Agent retrieves an issue, summarizes conversation, and posts a comment with recommended next steps
  • Export all documents for a project and store them in a backup repository
  • Bulk-assign a sprint cycle to a set of issues filtered by label or search

FAQ

How do I authenticate securely?

Preferred option is writing your personal API key to ~/.linear_api_token so the CLI reads it without exposing the token to process lists. Environment variable or --api-token flag are alternatives.

Is output always JSON?

Yes. All commands emit JSON by default to simplify parsing by agents and automation. Use jq or your tool of choice to extract fields.