@context-fs/linear

Virtual filesystem that exposes your Linear workspace as files and directories. Browse issues, teams, and users with standard filesystem tools.

Installation

npm install -g @context-fs/linear

Or run directly:

npx @context-fs/linear --mount /tmp/linear

Quick Start

# Mount your Linear workspace
npx @context-fs/linear --mount /tmp/linear

# Browse issues
ls /tmp/linear/issues/by-id/
cat /tmp/linear/issues/by-id/ENG-123/content.md

# Search
ls /tmp/linear/issues/search/authentication\ bug/

# View team issues
ls /tmp/linear/teams/ENG-engineering/issues/active/

Authentication

The CLI will prompt for your Linear API key on first run. Get one from Linear Settings > API.

API keys are stored securely in your system keychain:

• macOS: Keychain Access (via security CLI)
• Linux: Secret Service API (GNOME Keyring, KWallet, etc. via secret-tool)

Alternatively, set the LINEAR_API_KEY environment variable:

LINEAR_API_KEY=lin_api_xxx npx @context-fs/linear --mount /tmp/linear

To reset stored credentials:

npx @context-fs/linear --reset

Filesystem Structure

/
├── user.json                    # Current authenticated user
├── organization.json            # Workspace organization info
├── ctl/
│   └── refresh-cache            # Read to clear all caches
│
├── issues/
│   ├── by-id/
│   │   └── <id>/                # By UUID or identifier (e.g., ENG-123)
│   │       ├── content.md       # Issue content (read/write)
│   │       ├── team             # Symlink to team
│   │       ├── assignee         # Symlink to assignee
│   │       └── creator          # Symlink to creator
│   └── search/
│       └── <query>/             # Search results as symlinks
│
├── teams/
│   └── <teamKey>/               # e.g., ENG-engineering
│       ├── info.json            # Team metadata
│       └── issues/
│           ├── new              # Write here to create issue
│           ├── all/             # All team issues
│           ├── active/          # Started/unstarted issues
│           └── triage/          # Triage issues (if enabled)
│
└── users/
    └── <displayName>/           # e.g., john-doe
        ├── info.json            # User metadata
        └── issues/
            ├── assigned/        # Open assigned issues
            ├── completed/       # Completed issues
            └── created/         # Issues created by user

Reading Issues

Issue content is served as Markdown with YAML frontmatter:

cat /tmp/linear/issues/by-id/ENG-123/content.md

---
id: abc-123-def
identifier: ENG-123
title: Fix authentication bug
state: In Progress
priority: 2
assignee: john-doe
team: ENG
labels:
  - bug
  - security
url: https://linear.app/myorg/issue/ENG-123
createdAt: 2024-01-15T10:30:00.000Z
updatedAt: 2024-01-16T14:22:00.000Z
---

Users are unable to log in after password reset.

## Steps to reproduce

1. Request password reset
2. Click link in email
3. Set new password
4. Try to log in

## Expected behavior

User should be able to log in with new password.

Writing Issues

Edit Existing Issue

Modify content.md to update the title or description:

# Edit with your favorite editor
vim /tmp/linear/issues/by-id/ENG-123/content.md

# Or programmatically
cat > /tmp/linear/issues/by-id/ENG-123/content.md << 'EOF'
---
title: Fix authentication bug (updated)
---

Updated description here.
EOF

Only title and the body (description) are writable. Other frontmatter fields are read-only.

Create New Issue

Write to the new file in a team's issues directory:

cat > /tmp/linear/teams/ENG-engineering/issues/new << 'EOF'
---
title: Implement dark mode
---

Add dark mode support to the settings page.
EOF

Searching

URL-encode your search query in the path:

# Simple search
ls /tmp/linear/issues/search/login%20bug/

# Results are symlinks to actual issues
cat /tmp/linear/issues/search/login%20bug/ENG-123/content.md

Symlinks

Issues include symlinks to related entities:

# Follow team symlink
cat /tmp/linear/issues/by-id/ENG-123/team/info.json

# Follow assignee symlink
cat /tmp/linear/issues/by-id/ENG-123/assignee/info.json

# Check where a symlink points
readlink /tmp/linear/issues/by-id/ENG-123/team
# /teams/ENG-engineering

Caching

Data is cached to minimize API calls. To refresh:

cat /tmp/linear/ctl/refresh-cache

CLI Options

Usage: linear-fs [options]

Options:
  --mount <path>    Mount point directory
  --host <host>     Server bind address (default: 127.0.0.1)
  --port <port>     Server port (default: 2049)
  --reset           Clear stored API key
  -h, --help        Show help

Programmatic Usage

import { createLinearFileSystem } from "@context-fs/linear";
import { mount } from "@context-fs/nfs";

const vfs = await createLinearFileSystem(process.env.LINEAR_API_KEY!);

await using handle = await mount(vfs, {
  mountPoint: "/tmp/linear",
});

// Filesystem is now mounted

Use Cases

• AI/LLM context: Give AI assistants access to your issue tracker
• Scripting: Automate issue management with shell scripts
• Search: Use grep, find, ripgrep across your issues
• Backup: Copy issues to local files
• Integration: Pipe issue content to other tools

Related Packages

• @context-fs/core - Virtual filesystem core
• @context-fs/cli - CLI framework
• @context-fs/nfs - NFS server

License

MIT