Skill: cipher-shad0w/openclaw-linear (version 1.0.1)

--- name: linear description: Manage Linear issues, projects, teams, and documents from the command line using the linear CLI. Create, update, list, and track issues; manage projects and milestones; interact with the Linear GraphQL API. homepage: https://github.com/cipher-shad0w/openclaw-linear metadata: {"openclaw": {"emoji": "🖇️", "os": ["darwin", "linux", "win32"], "requires": {"bins": ["linear"]}, "install": [{"id": "brew", "kind": "brew", "formula": "schpet/tap/linear", "bins": ["linear"], "label": "Install linear CLI (brew)", "os": ["darwin", "linux"]}]}} --- # Linear A CLI to manage Linear issues from the command line, with git and jj integration. ## Prerequisites The `linear` command must be available on PATH. To check: ```bash linear --version ``` If not installed: - **Homebrew**: `brew install schpet/tap/linear` - **Deno**: `deno install -A --reload -f -g -n linear jsr:@schpet/linear-cli` - **Binaries**: https://github.com/schpet/linear-cli/releases/latest ## Setup 1. Create an API key at https://linear.app/settings/account/security 2. Authenticate: `linear auth login` 3. Configure your project: `cd my-project-repo && linear config` ## Available Commands ```text linear auth # Manage Linear authentication linear issue # Manage Linear issues linear team # Manage Linear teams linear project # Manage Linear projects linear project-update # Manage project status updates linear milestone # Manage Linear project milestones linear initiative # Manage Linear initiatives linear initiative-update # Manage initiative status updates linear label # Manage Linear issue labels linear document # Manage Linear documents linear config # Interactively generate .linear.toml configuration linear schema # Print the GraphQL schema to stdout linear api # Make a raw GraphQL API request ``` ## Common Workflows ### List and view issues ```bash # List your unstarted issues linear issue list # List issues in a specific state linear issue list -s started linear issue list -s completed # List all assignees' issues linear issue list -A # View the current branch's issue linear issue view # View a specific issue linear issue view ABC-123 ``` ### Create and manage issues ```bash # Create an issue interactively linear issue create # Create non-interactively linear issue create -t "Fix login bug" -d "Users can't log in with SSO" -s "In Progress" -a self --priority 1 # Update an issue linear issue update ABC-123 -s "Done" -t "Updated title" # Add a comment linear issue comment add ABC-123 -b "This is fixed in the latest build" # Delete an issue linear issue delete ABC-123 -y ``` ### Start working on an issue ```bash # Pick an issue interactively, creates a git branch and marks it as started linear issue start # Start a specific issue linear issue start ABC-123 # Create a PR with issue details pre-filled linear issue pr ``` ### Projects and milestones ```bash # List projects linear project list # Create a project linear project create -n "Q1 Launch" -t ENG -s started --target-date 2026-03-31 # List milestones for a project linear milestone list --project <projectId> ``` ### Documents ```bash # List documents linear document list # Create a document from a file linear document create --title "Design Spec" --content-file ./spec.md --project <projectId> # View a document linear document view <slug> ``` ### Teams ```bash # List teams linear team list # List team members linear team members ``` ## Discovering Options Run `--help` on any command for flags and options: ```bash linear --help linear issue --help linear issue list --help linear issue create --help ``` ## Using the Linear GraphQL API Directly **Prefer the CLI for all supported operations.** The `api` command is a fallback for queries not covered by the CLI. ### Check the schema ```bash linear schema -o "${TMPDIR:-/tmp}/linear-schema.graphql" grep -i "cycle" "${TMPDIR:-/tmp}/linear-schema.graphql" grep -A 30 "^type Issue " "${TMPDIR:-/tmp}/linear-schema.graphql" ``` ### Make a GraphQL request ```bash # Simple query linear api '{ viewer { id name email } }' # With variables linear api 'query($teamId: String!) { team(id: $teamId) { name } }' --variable teamId=abc123 # Complex filter via JSON linear api 'query($filter: IssueFilter!) { issues(filter: $filter) { nodes { title } } }' \ --variables-json '{"filter": {"state": {"name": {"eq": "In Progress"}}}}' # Pipe to jq linear api '{ issues(first: 5) { nodes { identifier title } } }' | jq '.data.issues.nodes[].title' ``` ### Using curl directly ```bash curl -s -X POST https://api.linear.app/graphql \ -H "Content-Type: application/json" \ -H "Authorization: $(linear auth token)" \ -d '{"query": "{ viewer { id } }"}' ``` ## Reference Documentation For detailed subcommand documentation with all flags and options: - [issue](references/issue.md) - Manage Linear issues (list, create, update, start, view, comment, PR, delete) - [team](references/team.md) - Manage Linear teams (list, create, delete, members, autolinks) - [project](references/project.md) - Manage Linear projects (list, view, create) - [document](references/document.md) - Manage Linear documents (list, view, create, update, delete) - [api](references/api.md) - Make raw GraphQL API requests ## Configuration The CLI supports environment variables or a `.linear.toml` config file: | Option | Env Var | TOML Key | Example | |---|---|---|---| | Team ID | `LINEAR_TEAM_ID` | `team_id` | `"ENG"` | | Workspace | `LINEAR_WORKSPACE` | `workspace` | `"mycompany"` | | Issue sort | `LINEAR_ISSUE_SORT` | `issue_sort` | `"priority"` or `"manual"` | | VCS | `LINEAR_VCS` | `vcs` | `"git"` or `"jj"` | Config file locations (checked in order): 1. `./linear.toml` or `./.linear.toml` (current directory) 2. `<repo-root>/linear.toml` or `<repo-root>/.linear.toml` 3. `<repo-root>/.config/linear.toml` 4. `~/.config/linear/linear.toml`

path: references/api.md
content: # api

> Make raw GraphQL API requests to Linear

## Usage

```text
linear api [query] [options]
```

**Prefer the CLI commands for all supported operations.** The `api` command should only be used as a fallback for queries not covered by the CLI.

## Options

| Flag | Description |
|---|---|
| `--variable <key=value>` | Variable in key=value format (coerces booleans, numbers, null; `@file` reads from path) |
| `--variables-json <json>` | JSON object of variables (merged with --variable, which takes precedence) |
| `--paginate` | Automatically fetch all pages using cursor pagination |
| `--silent` | Suppress response output (exit code still reflects errors) |

Query can also be read from stdin.

## Examples

### Simple queries

```bash
# Get current user info
linear api '{ viewer { id name email } }'

# Get first 5 issues
linear api '{ issues(first: 5) { nodes { identifier title state { name } } } }'
```

### Queries with variables

```bash
# String variable
linear api 'query($teamId: String!) { team(id: $teamId) { name } }' --variable teamId=abc123

# Numeric variable
linear api 'query($first: Int!) { issues(first: $first) { nodes { title } } }' --variable first=5

# Boolean variable
linear api 'query($includeArchived: Boolean) { issues(includeArchived: $includeArchived, first: 5) { nodes { title } } }' --variable includeArchived=true
```

### Complex filters via JSON

```bash
# Filter issues by state
linear api 'query($filter: IssueFilter!) { issues(filter: $filter) { nodes { identifier title } } }' \
  --variables-json '{"filter": {"state": {"name": {"eq": "In Progress"}}}}'

# Filter by assignee and state
linear api 'query($filter: IssueFilter!) { issues(filter: $filter) { nodes { identifier title assignee { name } } } }' \
  --variables-json '{"filter": {"and": [{"state": {"name": {"eq": "In Progress"}}}, {"assignee": {"isMe": {"eq": true}}}]}}'
```

### Pagination

```bash
# Fetch all issues (auto-paginate)
linear api '{ issues(first: 50) { nodes { identifier title } pageInfo { hasNextPage endCursor } } }' --paginate
```

### Piping and scripting

```bash
# Read query from stdin
echo '{ viewer { id } }' | linear api

# Pipe to jq for filtering
linear api '{ issues(first: 10) { nodes { identifier title } } }' | jq '.data.issues.nodes[].title'

# Get just issue identifiers
linear api '{ issues(first: 50) { nodes { identifier } } }' | jq -r '.data.issues.nodes[].identifier'

# Silent mode (check exit code only)
linear api '{ viewer { id } }' --silent && echo "authenticated" || echo "not authenticated"
```

### Using curl directly

For cases where you need full HTTP control:

```bash
curl -s -X POST https://api.linear.app/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: $(linear auth token)" \
  -d '{"query": "{ viewer { id name } }"}'
```

## Exploring the Schema

Before writing custom queries, explore the schema to discover available types and fields:

```bash
# Write schema to a temp file
linear schema -o "${TMPDIR:-/tmp}/linear-schema.graphql"

# Search for types
grep -i "cycle" "${TMPDIR:-/tmp}/linear-schema.graphql"

# View a specific type definition
grep -A 30 "^type Issue " "${TMPDIR:-/tmp}/linear-schema.graphql"

# Find available queries
grep -A 5 "^type Query " "${TMPDIR:-/tmp}/linear-schema.graphql"

# Find mutations
grep "Mutation" "${TMPDIR:-/tmp}/linear-schema.graphql" | head -20
```

## Common Patterns

### Mutations

```bash
# Update issue state via API (prefer `linear issue update -s` instead)
linear api 'mutation($id: String!, $stateId: String!) { issueUpdate(id: $id, input: {stateId: $stateId}) { success } }' \
  --variable id=<issue-uuid> --variable stateId=<state-uuid>
```

### Fetching related data

```bash
# Get issue with project, labels, and comments
linear api 'query($id: String!) {
  issue(id: $id) {
    identifier
    title
    state { name }
    project { name }
    labels { nodes { name } }
    comments { nodes { body createdAt user { name } } }
  }
}' --variable id=<issue-uuid>
```

## Authentication

The `api` command uses the same authentication as other commands. Manage auth with:

```bash
linear auth login       # Add credentials
linear auth whoami      # Check current user
linear auth token       # Print API token (for curl/scripts)
linear auth list        # List configured workspaces
linear auth default     # Set default workspace
```


path: references/document.md
content: # document

> Manage Linear documents

## Usage

```text
linear document [subcommand]
```

Alias: `linear docs` can be used instead of `linear document`.

Documents can be attached to projects or issues, or exist at the workspace level.

## Subcommands

### list

List documents.

```bash
linear document list [options]
```

| Flag | Description |
|---|---|
| `--project <projectId>` | Filter by project |
| `--issue <issueId>` | Filter by issue (e.g. TC-123) |
| `--json` | Output as JSON |

**Examples:**

```bash
# List all documents
linear document list

# Filter by project
linear document list --project <projectId>

# Filter by issue
linear document list --issue TC-123

# JSON output
linear document list --json
```

### view

View a document.

```bash
linear document view <slug> [options]
```

| Flag | Description |
|---|---|
| `--raw` | Output raw markdown (for piping) |
| `--web` | Open in browser |
| `--json` | Output as JSON |

**Examples:**

```bash
# View rendered in terminal
linear document view my-document

# Get raw markdown
linear document view my-document --raw

# Open in browser
linear document view my-document --web

# JSON output for scripting
linear document view my-document --json
```

### create

Create a document.

```bash
linear document create [options]
```

| Flag | Description |
|---|---|
| `--title <title>` | Document title |
| `--content <content>` | Inline markdown content |
| `--content-file <path>` | Read content from a file |
| `--project <projectId>` | Attach to a project |
| `--issue <issueId>` | Attach to an issue (e.g. TC-123) |

Content can also be piped via stdin.

**Examples:**

```bash
# Create with inline content
linear document create --title "My Doc" --content "# Hello\n\nWorld"

# Create from file
linear document create --title "Design Spec" --content-file ./spec.md

# Attach to a project
linear document create --title "Project Notes" --content-file ./notes.md --project <projectId>

# Attach to an issue
linear document create --title "Investigation" --content "findings here" --issue TC-123

# Pipe from stdin
cat spec.md | linear document create --title "Spec"
```

### update

Update a document.

```bash
linear document update <slug> [options]
```

| Flag | Description |
|---|---|
| `--title <title>` | New title |
| `--content-file <path>` | New content from file |
| `--edit` | Open in $EDITOR |

**Examples:**

```bash
# Update title
linear document update my-doc --title "New Title"

# Update content from file
linear document update my-doc --content-file ./updated.md

# Open in editor
linear document update my-doc --edit
```

### delete

Delete a document.

```bash
linear document delete <slug> [options]
```

| Flag | Description |
|---|---|
| `--permanent` | Permanent delete (default is soft delete / move to trash) |
| `--bulk <slugs...>` | Bulk delete multiple documents |

**Examples:**

```bash
# Soft delete (move to trash)
linear document delete my-doc

# Permanent delete
linear document delete my-doc --permanent

# Bulk delete
linear document delete --bulk doc-1 doc-2 doc-3
```


path: references/issue.md
content: # issue

> Manage Linear issues

## Usage

```text
linear issue [subcommand]
```

The current issue is determined by:
- **git**: the issue ID in the current branch name (e.g. `eng-123-my-feature`)
- **jj**: the `Linear-issue` trailer in the current or ancestor commits

## Subcommands

### list

List your issues in a table view.

```bash
linear issue list [options]
```

| Flag | Description | Default |
|---|---|---|
| `-s, --state <state>` | Filter by state (triage, backlog, unstarted, started, completed, canceled). Repeatable. | `unstarted` |
| `--all-states` | Show issues from all states | |
| `--assignee <username>` | Filter by assignee username | |
| `-A, --all-assignees` | Show issues for all assignees | |
| `-U, --unassigned` | Show only unassigned issues | |
| `--sort <sort>` | Sort order: `manual` or `priority` | |
| `--team <team>` | Team to list issues for | |
| `--project <project>` | Filter by project name | |
| `--limit <n>` | Max issues to fetch (0 = unlimited) | `50` |
| `-w, --web` | Open in web browser | |
| `-a, --app` | Open in Linear.app | |
| `--no-pager` | Disable automatic paging | |

**Examples:**

```bash
# List your unstarted issues
linear issue list

# List started issues for all assignees
linear issue list -s started -A

# List issues in a specific project
linear issue list --project "Q1 Launch"

# List all issues with no limit
linear issue list --all-states --limit 0
```

### create

Create a new Linear issue.

```bash
linear issue create [options]
```

| Flag | Description |
|---|---|
| `-t, --title <title>` | Title of the issue |
| `-d, --description <desc>` | Description of the issue |
| `-a, --assignee <assignee>` | Assign to `self` or someone (by username or name) |
| `-s, --state <state>` | Workflow state (by name or type) |
| `-l, --label <label>` | Issue label (repeatable) |
| `-p, --parent <parent>` | Parent issue as team_number code |
| `--priority <1-4>` | Priority (1=urgent, 4=low) |
| `--estimate <points>` | Points estimate |
| `--due-date <date>` | Due date |
| `--team <team>` | Team (if not default) |
| `--project <project>` | Project name |
| `--start` | Start the issue after creation |
| `--no-use-default-template` | Skip default template |
| `--no-interactive` | Disable interactive prompts |
| `--no-color` | Disable colored output |

**Examples:**

```bash
# Interactive creation
linear issue create

# Non-interactive with all details
linear issue create -t "Fix auth bug" -d "SSO login broken" -a self --priority 1 -s "In Progress" -l "bug"

# Create and immediately start
linear issue create -t "New feature" --start

# Create a sub-issue
linear issue create -t "Subtask" -p ENG-123
```

### update

Update a Linear issue.

```bash
linear issue update [issueId] [options]
```

| Flag | Description |
|---|---|
| `-t, --title <title>` | New title |
| `-d, --description <desc>` | New description |
| `-a, --assignee <assignee>` | New assignee |
| `-s, --state <state>` | New workflow state |
| `-l, --label <label>` | New label (repeatable) |
| `-p, --parent <parent>` | New parent issue |
| `--priority <1-4>` | New priority |
| `--estimate <points>` | New estimate |
| `--due-date <date>` | New due date |
| `--team <team>` | Move to different team |
| `--project <project>` | Move to different project |
| `--no-color` | Disable colored output |

**Examples:**

```bash
# Update current branch's issue state
linear issue update -s "Done"

# Update a specific issue
linear issue update ENG-123 -t "Updated title" --priority 2

# Assign to someone
linear issue update ENG-123 -a "jane"
```

### view

View issue details or open in browser/app.

```bash
linear issue view [issueId] [options]
```

| Flag | Description |
|---|---|
| `-w, --web` | Open in web browser |
| `-a, --app` | Open in Linear.app |
| `--no-comments` | Exclude comments |
| `--no-pager` | Disable paging |
| `-j, --json` | Output as JSON |
| `--no-download` | Keep remote URLs |

**Examples:**

```bash
# View current branch's issue
linear issue view

# View specific issue
linear issue view ENG-123

# Get JSON output
linear issue view ENG-123 --json

# Open in browser
linear issue view -w
```

### start

Start working on an issue. Creates/switches to a git branch and marks the issue as started.

```bash
linear issue start [issueId] [options]
```

| Flag | Description |
|---|---|
| `-A, --all-assignees` | Show issues for all assignees |
| `-U, --unassigned` | Show only unassigned issues |
| `-f, --from-ref <ref>` | Git ref to create branch from |
| `-b, --branch <name>` | Custom branch name |

**Examples:**

```bash
# Interactive: pick from your issues
linear issue start

# Start a specific issue
linear issue start ENG-123

# Start from a specific branch
linear issue start ENG-123 -f main
```

### pull-request (pr)

Create a GitHub pull request with issue details pre-filled (uses `gh` CLI).

```bash
linear issue pr [issueId] [options]
```

| Flag | Description |
|---|---|
| `--base <branch>` | Target branch for merge |
| `--draft` | Create as draft PR |
| `-t, --title <title>` | Custom PR title (issue ID auto-prefixed) |
| `--web` | Open PR in browser after creating |
| `--head <branch>` | Branch with commits |

### delete

Delete an issue.

```bash
linear issue delete [issueId] [options]
```

| Flag | Description |
|---|---|
| `-y, --confirm` | Skip confirmation |
| `--bulk <ids...>` | Delete multiple issues |
| `--bulk-file <file>` | Read IDs from file |
| `--bulk-stdin` | Read IDs from stdin |

### comment

Manage issue comments.

#### comment add

```bash
linear issue comment add [issueId] [options]
```

| Flag | Description |
|---|---|
| `-b, --body <text>` | Comment body |
| `-p, --parent <id>` | Parent comment ID (for replies) |
| `-a, --attach <file>` | Attach a file (repeatable) |

#### comment update

```bash
linear issue comment update <commentId> -b <text>
```

#### comment list

```bash
linear issue comment list [issueId] [--json]
```

### Other subcommands

| Command | Description |
|---|---|
| `linear issue id` | Print the issue ID from current branch |
| `linear issue title [issueId]` | Print the issue title |
| `linear issue url [issueId]` | Print the Linear URL |
| `linear issue describe [issueId]` | Print title + Linear-issue trailer |
| `linear issue commits [issueId]` | Show commits for an issue (jj only) |
| `linear issue attach <issueId> <file>` | Attach a file to an issue |


path: references/project.md
content: # project

> Manage Linear projects

## Usage

```text
linear project [subcommand]
```

## Subcommands

### list

List projects.

```bash
linear project list [options]
```

| Flag | Description |
|---|---|
| `--team <team>` | Filter by team key |
| `--all-teams` | Show projects from all teams |
| `--status <status>` | Filter by status name |
| `-w, --web` | Open in web browser |
| `-a, --app` | Open in Linear.app |

**Examples:**

```bash
# List all projects
linear project list

# Filter by team
linear project list --team ENG

# Filter by status
linear project list --status started
```

### view

View project details.

```bash
linear project view <projectId> [options]
```

| Flag | Description |
|---|---|
| `-w, --web` | Open in web browser |
| `-a, --app` | Open in Linear.app |

### create

Create a new Linear project.

```bash
linear project create [options]
```

| Flag | Description |
|---|---|
| `-n, --name <name>` | Project name (required) |
| `-d, --description <desc>` | Project description |
| `-t, --team <team>` | Team key (required, repeatable for multiple teams) |
| `-l, --lead <lead>` | Project lead (username, email, or @me) |
| `-s, --status <status>` | Status: planned, started, paused, completed, canceled, backlog |
| `--start-date <YYYY-MM-DD>` | Start date |
| `--target-date <YYYY-MM-DD>` | Target completion date |
| `--initiative <initiative>` | Add to initiative (ID, slug, or name) |
| `-i, --interactive` | Interactive mode (default if no flags) |
| `--no-color` | Disable colored output |

**Examples:**

```bash
# Interactive creation
linear project create

# Non-interactive
linear project create -n "Q1 Launch" -t ENG -s started --target-date 2026-03-31

# Multiple teams
linear project create -n "Cross-team effort" -t ENG -t DESIGN -l @me

# Add to initiative
linear project create -n "New Feature" -t ENG --initiative "2026 Roadmap"
```

## Related Commands

### project-update

Manage project status updates (timeline posts).

```bash
linear project-update list <projectId>
linear project-update create <projectId>
linear project-update view <updateId>
```

### milestone

Manage project milestones.

```bash
linear milestone list --project <projectId>
linear milestone view <milestoneId>
linear milestone create --project <projectId> --name "Q1 Goals" --target-date 2026-03-31
linear milestone update <milestoneId> --name "New Name"
linear milestone delete <milestoneId> [--force]
```

Alias: `linear m` can be used instead of `linear milestone`.

### initiative

Manage Linear initiatives.

```bash
linear initiative list
linear initiative view <initiativeId>
linear initiative create
```


path: references/team.md
content: # team

> Manage Linear teams

## Usage

```text
linear team [subcommand]
```

## Subcommands

### list

List teams.

```bash
linear team list [options]
```

| Flag | Description |
|---|---|
| `-w, --web` | Open in web browser |
| `-a, --app` | Open in Linear.app |

### id

Print the configured team ID.

```bash
linear team id
```

### members

List team members.

```bash
linear team members [teamKey] [options]
```

| Flag | Description |
|---|---|
| `-a, --all` | Include inactive members |

**Examples:**

```bash
# List members of default team
linear team members

# List members of a specific team
linear team members ENG

# Include inactive
linear team members --all
```

### create

Create a new Linear team.

```bash
linear team create [options]
```

| Flag | Description |
|---|---|
| `-n, --name <name>` | Name of the team |
| `-d, --description <desc>` | Description |
| `-k, --key <key>` | Team key (auto-generated from name if omitted) |
| `--private` | Make the team private |
| `--no-color` | Disable colored output |
| `--no-interactive` | Disable interactive prompts |

**Examples:**

```bash
# Interactive creation
linear team create

# Non-interactive
linear team create -n "Platform" -k "PLT" -d "Platform engineering team"

# Private team
linear team create -n "Security" --private
```

### delete

Delete a Linear team.

```bash
linear team delete <teamKey> [options]
```

| Flag | Description |
|---|---|
| `--move-issues <targetTeam>` | Move all issues to another team before deletion |
| `-y, --force` | Skip confirmation prompt |

**Examples:**

```bash
# Delete with confirmation
linear team delete OLD

# Move issues and force delete
linear team delete OLD --move-issues ENG -y
```

### autolinks

Configure GitHub repository autolinks for Linear issues with this team prefix.

```bash
linear team autolinks
```

This sets up GitHub autolinks so that references like `ENG-123` in commits and PRs automatically link to the corresponding Linear issue.


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)