@rusintez/linear

Simple CLI wrapper for Linear GraphQL API. Supports multiple workspaces. Markdown I/O by default.

Install

npm install -g @rusintez/linear

Or run directly with npx:

npx @rusintez/linear --help

Setup

Add your Linear API keys (get from Linear > Settings > Security & access):

linear config add work <api-key-1>
linear config add personal <api-key-2>
linear config add client <api-key-3>
linear config default work

Or use env var for one-off commands:

LINEAR_API_KEY=lin_api_xxx linear me

Usage

Config Management

linear config list              # List all workspaces
linear config add <name> <key>  # Add/update workspace
linear config remove <name>     # Remove workspace
linear config default <name>    # Set default workspace

Direct GraphQL (full API access)

# Inline query
linear gql '{ viewer { id name email } }'

# With variables
linear gql 'query($id: String!) { issue(id: $id) { title } }' -v '{"id":"ABC-123"}'

# From file
linear gql @query.graphql -v @vars.json

# Different workspace
linear -w personal gql '{ teams { nodes { name } } }'

# Any mutation
linear gql 'mutation { issueArchive(id: "ABC-123") { success } }'

Shortcuts

# Info
linear me                       # Current user
linear teams                    # List teams  
linear users                    # List users
linear projects                 # List projects
linear labels                   # List labels
linear states                   # List workflow states
linear states -t <teamId>       # States for specific team
linear cycles -t <teamId>       # List cycles/sprints

# Issues
linear issues                   # List issues (most recent)
linear issues -t <teamId>       # Issues for team
linear issues -n 100            # Limit results
linear issue ABC-123            # Get single issue (full detail)
linear search "bug login"       # Search issues by title/description

# Create/Update
linear create-issue -t <teamId> --title "Bug: Login broken" -d "Details here" -p 2
linear update-issue ABC-123 -s <stateId>
linear update-issue ABC-123 --title "New title" -a <userId>
linear comment ABC-123 "This is a comment"

Documents (Pages)

linear docs                     # List all documents
linear docs -n 10               # Limit results
linear doc <slugId>             # Get document by slug ID
linear doc <uuid>               # Get document by UUID
linear doc "search term"        # Find document by title substring
linear doc "https://linear.app/org/document/title-slug-4a64dbbffb28"  # From URL

Output Formats

linear teams              # Markdown table (default) - readable
linear teams -f json      # JSON - best for parsing/scripting
linear teams -f minimal   # Minimal - one item per line, tab-separated

Multi-workspace

linear -w work issues          # Use 'work' workspace
linear -w personal me          # Use 'personal' workspace
linear -w client projects      # Use 'client' workspace

Output

• Markdown (default): Tables for lists, formatted objects for details
• JSON (-f json): Machine-readable, ideal for scripting
• Minimal (-f minimal): Tab-separated, one item per line
• Errors go to stderr with exit code 1

Sync (Local Data Cache)

Sync all Linear data to local JSON files for offline access, searching, and integration with other tools.

linear sync                     # Incremental sync all workspaces
linear sync --full              # Full sync (re-fetch all, detect deletions)
linear sync -w work             # Sync specific workspace only
linear sync -c issues,projects  # Sync specific collections only

Data is stored at ~/.local/share/linear/{workspace}/{collection}/{id}.json

Synced Collections

• teams - Teams with name, key, color
• users - Workspace members
• issues - All issues with full details
• projects - Projects with progress tracking
• milestones - Project milestones
• cycles - Sprints/iterations
• workflowStates - Workflow states (Todo, Done, etc.)
• labels - Issue labels
• documents - Documents/pages with full content
• notifications - Inbox notifications

Sync Management

linear sync-status              # Show sync status for all workspaces
linear sync-status myworkspace  # Status for specific workspace
linear sync-reset myworkspace   # Reset state (next sync = full)

See schema.md for full field documentation.

Config Location

~/.config/linear-cli/config.json

License

MIT