---
title: openplanr linear
description: "openplanr linear: Linear.app integration: init, push, sync, status mapping, task checklists. Subcommands: init, sync, status, push, tasklist-sync."
url: https://openplanr.dev/docs/cli/linear
updated: 2026-10-06
related:
  - https://openplanr.dev/docs/cli/dashboard.md
  - https://openplanr.dev/docs/cli/diagram.md
  - https://openplanr.dev/docs/cli/operate.md
---

# openplanr linear

Linear.app integration: init, push, sync, status mapping, task checklists

```text
openplanr linear [options] [command]
```

```text
Subcommands:
  init              Store PAT, choose allowed teams, save a default team
  sync              Pull workflow status (features/stories) + bidirectional task checkboxes
  push <artifact>   Create/update Linear entities at any granularity:
                      EPIC-XXX  → project + features + stories + tasklists
                      FEAT-XXX  → feature + its stories + its tasklist
                      US-XXX    → one story sub-issue
                      TASK-XXX  → one tasklist sub-issue
  status            Show local OpenPlanr ↔ Linear mapping (no API calls)
  tasklist-sync     Sync TASK checkbox lines with Linear task-list issues

Common flags:
  --dry-run         Show planned work without writes (push: no API; sync: read-only to Linear, no local writes)
  --update-only     push: only update existing linked entities, never create
  --push-parents    push: if a parent is not yet in Linear, push it first without prompting
  --team <id|key>   push: target any team selected during linear init

Examples:
  openplanr linear sync
  openplanr linear sync --dry-run
  openplanr linear push EPIC-001 --dry-run
  openplanr linear push FEAT-XXX --dry-run
  openplanr linear push US-054
  openplanr linear push TASK-015 --push-parents
  openplanr linear status --scope EPIC-001
```

## openplanr linear init

Validate a Linear PAT, choose teams, and save a default team

```text
openplanr linear init [options]
```

## openplanr linear sync

Pull workflow status (features & stories) from Linear, then sync task checklists bidirectionally

```text
openplanr linear sync [options]
```

Options:

- `--dry-run`: Read from Linear to compare, but do not write local files or update Linear issue bodies; default `false`
- `--update-only`: Same as default for this command (only artifacts with Linear links are considered); reserved for future use; default `false`
- `--on-conflict <mode>`: Status + task-checkbox conflicts: prompt | local | linear (default: prompt; non-interactive runs default to linear); default `"prompt"`

## openplanr linear status

Show local OpenPlanr id ↔ Linear id/url mapping from frontmatter (no Linear API calls)

```text
openplanr linear status [options]
```

Options:

- `--scope <epicId>`: Limit rows to an epic and its features, stories, and tasks in that scope

## openplanr linear push

Create or update Linear project/issues for any planning artifact (EPIC/FEAT/US/TASK)

```text
openplanr linear push [options] <artifactId>
```

Arguments:

- `artifactId` (required): Artifact id: accepts EPIC-XXX (epic + subtree), FEAT-XXX (feature + stories + tasklist), US-XXX (one story), or TASK-XXX (one tasklist)

Options:

- `--dry-run`: Show what would be created/updated without calling the Linear API; default `false`
- `--update-only`: Only update entities that already have Linear ids in frontmatter; never create new project/issues; default `false`
- `--push-parents`: If a parent in the chain is not yet pushed to Linear, push it first (upward attachment only: does NOT push the parent's siblings); default `false`
- `--no-cascade`: Push only the target artifact (and minimum parent chain when --push-parents is set). EPIC/FEAT pushes skip their descendants.
- `--team <id-or-key>`: Target a team selected during `openplanr linear init`
- `--as <strategy>`: Epic-only: mapping strategy. One of: project | milestone-of:<projectId> | label-on:<projectId>

## openplanr linear tasklist-sync

Bidirectionally sync task checkbox state between local TASK files and Linear TaskList issues

```text
openplanr linear tasklist-sync [options]
```

Options:

- `--on-conflict <mode>`: When local and Linear differ: prompt, local, or linear (default: prompt; in CI, linear is used when not set); default `"prompt"`
- `--dry-run`: Show what would change without writing local files or mutating Linear issue bodies; default `false`