> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mirage.strukto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Linear

> Virtualize a Linear workspace from Node or the browser.

`LinearVFS` mounts a Linear workspace as read-only JSON files: teams, members,
issues with their comments, projects, cycles and documents. Set up the API key as in [Linear setup](https://docs.mirage.strukto.ai/home/setup/linear.md).

## Install

```bash theme={null}
npm install @struktoai/mirage-node
```

## Configure

```ts theme={null}
import { LinearVFS, MountMode, Workspace } from '@struktoai/mirage-node'

const linear = new LinearVFS({ apiKey: process.env.LINEAR_API_KEY! })
const ws = new Workspace({ '/linear': linear }, { mode: MountMode.READ })

const result = await ws.shell('ls /linear/teams && tree -L 2 /linear/teams')
console.log(result.stdoutText)
await ws.close()
```

`teamIds` limits the mount to some teams. `baseUrl` points at another GraphQL
endpoint, such as a proxy.

### Fields

**timeout** `number` (default: DEFAULT\_TIMEOUT)

Seconds a request may wait to connect, or between two reads of its answer, before it fails; a download that keeps flowing is never cut off.

**apiKey** `string` *required*

Linear personal API key.

**teamIds** `string[]`

Only these teams are listed or readable. Unset shows every team the key can reach.

**baseUrl** `string` (default: '[https://api.linear.app/graphql](https://api.linear.app/graphql)')

Linear GraphQL endpoint; override to point at a fake or proxy.

Fields marked secret are redacted in snapshots.

## Authentication

The mount reads with a personal API key. The key's **Read** permission is
enough; the [`linear`](https://docs.mirage.strukto.ai/home/setup/cli/linear) CLI needs **Write** or the
create permissions to change issues. A key limited to some teams sees only
those teams.

## Layout

```text theme={null}
/linear/
  teams/
    ENG__Engineering__<team-id>/
      team.json
      members/
        Alice_Chen__<user-id>.json
      issues/
        ENG-142__<issue-id>/
          issue.json
          comments.jsonl
      projects/
        Q4_Launch__<project-id>.json
      cycles/
        Cycle_12__<cycle-id>.json
      documents/
        Roadmap_2027__<document-id>.json
```

* **Names:** every name ends in `__<id>`: a team is
  `<team-key>__<team-name>__<team-id>`, an issue `<issue-key>__<issue-id>`, a
  member `<display-name>__<user-id>.json`, and a project, cycle or document
  `<name>__<id>.json`. The readable part is sanitized, so `ls` the parent
  instead of building a name.
* **`team.json`:** the team's metadata.
* **`issue.json`:** the issue, with fields such as `issue_id`, `issue_key`,
  `team_id`, `state_id` and `assignee_id` that commands take as they are.
* **`comments.jsonl`:** the issue's comments, one JSON object per line, ordered
  by `created_at`. It is a Mirage format, not a Linear one.
* **Members:** each file carries `user_id` and `email`, ready for commands such
  as `linear issue assign`.
* **Projects and cycles:** a project lists its related issues; a cycle carries
  its start and end dates.
* **Documents:** each file holds the title, the markdown content, the linked
  project and the creator.

Files hold Mirage's JSON with snake\_case keys, not Linear's raw GraphQL
response.

## Behavior

* **Read only:** the mount cannot change issues. Use the `linear` CLI to
  create, update, assign and comment on issues; the tree serves the same
  entities as JSON files.
* **Recent writes:** Linear indexes a write some time after it lands, so a
  search can miss a recent issue change. See Integration.

## Browser

The browser `LinearVFS` from `@struktoai/mirage-browser` takes the same fields.

```bash theme={null}
npm install @struktoai/mirage-browser
```

```ts theme={null}
import { LinearVFS, MountMode, Workspace } from '@struktoai/mirage-browser'

const linear = new LinearVFS({ apiKey: LINEAR_API_KEY })
const ws = new Workspace({ '/linear': linear }, { mode: MountMode.READ })
```

* The API key reaches the page, so give it only the **Read** permission.

## Integration

Linear answers this command through its own API, so fewer files are read. See
[Integration](https://docs.mirage.strukto.ai/home/integration/overview.md).

* `grep -rw` and `rg -w`: Linear's issue search runs for each word, and only
  the issues that hold every word are read, where the search names it or the
  listing keeps it. The listing keeps each issue's other fields (team,
  project, cycle, state, people, labels, dates, link) and each title or
  description word the search can miss, such as one inside a link. Every issue
  is read when the word is a key of the issue JSON (`title`, `priority`) or a
  JSON literal, has a digit or only the letters a to f, or when a search
  fails, returns 250 issues or finds nothing. `walk_limit: -1` in the mount's
  `"@all"` [command limit](https://docs.mirage.strukto.ai/home/limits.md#command-output) reads every file instead.
* `grep -r` and `rg` on members, projects, cycles and documents: the listing
  keeps their whole JSON, so only the files whose text holds the pattern's
  text in any case are read, whatever `walk_limit` is. Issues are listed once
  more, so a change since the last listing is still found. A file over 8 KiB,
  and every file for a text that is not ASCII, is read as usual. Comments are
  always read: they are fetched per issue, and Linear's comment search can
  miss a word inside a link.

## VFS.md

The [VFS.md](https://docs.mirage.strukto.ai/home/setup/vfs-md.md) an agent reads with Linear mounted at `/<path>`.

> [tab] Rendered
>
> **Virtual Filesystem**
>
> | Path | Description |
> | - | - |
> | `/<path>` | `linear`, read |
>
> **VFS Layout**
>
> **`/<path>`**
>
> ```text theme={null}
> /<path>
>   teams/
>     <team-key>__<team-name>__<team-id>/
>       team.json
>       members/
>         <display-name>__<user-id>.json
>       issues/
>         <issue-key>__<issue-id>/
>           issue.json
>           comments.jsonl
>       projects/
>         <name>__<project-id>.json
>       cycles/
>         <name>__<cycle-id>.json
>       documents/
>         <title>__<document-id>.json
> ```
>
> * A named segment is `<sanitized-name>__<id>`; the id after the last `__`
>   is exact. `ls` the parent for exact names rather than building them.
> * Files are JSON normalized by Mirage with snake\_case keys (`issue_key`,
>   `state_name`, `assignee_email`, `label_names`), not Linear's GraphQL
>   shape. `comments.jsonl` holds one comment per line.
> * `team.json` lists the team's workflow states; a project file lists its
>   issues with their state.
> * To create, update, assign, transition or comment on issues, use the
>   `linear` CLI if installed (`linear --help`).
>
> **Supported Unix Commands for VFS**
>
> Unix commands work on each path as on a local filesystem, as far as the path supports them:
>
> | Path | Supported |
> | - | - |
> | `/<path>` | Commands that read files (`ls`, `cat`, `grep`, `find`, `jq` and the rest). `grep -r` and `rg` ask `linear` which files may match. |
>
> **Limitations of Unix Commands for VFS**
>
> Where a path differs from a local filesystem:
>
> | Path | Limitations |
> | - | - |
> | `/<path>` | Read only: no command changes files. `linear` answers only for `teams/*/issues/*/issue.json`, `teams/*/members/*`, `teams/*/projects/*`, `teams/*/cycles/*` and `teams/*/documents/*`; `grep -r` and `rg` read every other file. `grep -r`, `find` and `du` stop after 1000 files; a glob matching more, `tar -c`, `cp -r` and `rm -r` are refused. |
>
> Run `man <cmd>` or `<cmd> --help` for one command's usage.

> [tab] Raw
>
> ````markdown theme={null}
> ---
> name: workspace-filesystem
> description: The virtual filesystem layout of this workspace.
> ---
>
> # Virtual Filesystem
>
> | Path | Description |
> | --- | --- |
> | `/<path>` | `linear`, read |
>
> ## VFS Layout
>
> ### `/<path>`
>
> ```text
> /<path>
>   teams/
>     <team-key>__<team-name>__<team-id>/
>       team.json
>       members/
>         <display-name>__<user-id>.json
>       issues/
>         <issue-key>__<issue-id>/
>           issue.json
>           comments.jsonl
>       projects/
>         <name>__<project-id>.json
>       cycles/
>         <name>__<cycle-id>.json
>       documents/
>         <title>__<document-id>.json
> ```
>
> - A named segment is `<sanitized-name>__<id>`; the id after the last `__`
>   is exact. `ls` the parent for exact names rather than building them.
> - Files are JSON normalized by Mirage with snake_case keys (`issue_key`,
>   `state_name`, `assignee_email`, `label_names`), not Linear's GraphQL
>   shape. `comments.jsonl` holds one comment per line.
> - `team.json` lists the team's workflow states; a project file lists its
>   issues with their state.
> - To create, update, assign, transition or comment on issues, use the
>   `linear` CLI if installed (`linear --help`).
>
> ## Supported Unix Commands for VFS
>
> Unix commands work on each path as on a local filesystem, as far as the path supports them:
>
> | Path | Supported |
> | --- | --- |
> | `/<path>` | Commands that read files (`ls`, `cat`, `grep`, `find`, `jq` and the rest). `grep -r` and `rg` ask `linear` which files may match. |
>
> ## Limitations of Unix Commands for VFS
>
> Where a path differs from a local filesystem:
>
> | Path | Limitations |
> | --- | --- |
> | `/<path>` | Read only: no command changes files. `linear` answers only for `teams/*/issues/*/issue.json`, `teams/*/members/*`, `teams/*/projects/*`, `teams/*/cycles/*` and `teams/*/documents/*`; `grep -r` and `rg` read every other file. `grep -r`, `find` and `du` stop after 1000 files; a glob matching more, `tar -c`, `cp -r` and `rm -r` are refused. |
>
> Run `man <cmd>` or `<cmd> --help` for one command's usage.
> ````


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.