linear-cli

A CLI for Linear via the GraphQL API.

Install

Homebrew (macOS Apple Silicon)

brew tap aliou/toolbox
brew install linear-cli

From release binaries

Download the latest binary from Releases for your platform:

• linear-darwin-arm64 (macOS Apple Silicon)
• linear-linux-arm64 (Linux ARM64)
• linear-linux-x64 (Linux x64)

chmod +x linear-*
mv linear-* /usr/local/bin/linear

With Nix

# flake.nix
{
  inputs.linear-cli.url = "github:aliou/linear-cli";
  # ...
  # Add linear-cli.packages.${system}.default to your packages
}

From source

Requires Bun.

git clone https://github.com/aliou/linear-cli.git
cd linear-cli
bun install
bun run src/index.ts --help

Authentication

Get a personal API token from Linear Settings > API > Personal API keys.

# Interactive login
linear auth login

# With token directly
linear auth login --token <token>

# Save under a specific workspace profile name
linear auth login --token <token> --workspace personal

# Via API token environment variable
export LINEAR_API_TOKEN=<token>

# Workspace selection for config-stored credentials
export LINEAR_WORKSPACE=acme
linear --workspace personal issue list

# Via pipe
echo <token> | linear auth login

Interactive linear auth login prompts for your API token and validates it before saving.

You do not need a special - argument for stdin. Piped input is detected automatically.

Config is stored in ~/.config/linear-cli/config.json with 0600 permissions.

List and switch workspace profiles:

linear auth list
linear auth use <name>
# Set workspace only for current project
linear auth use <name> --local

Config format

{
  "$schema": "https://raw.githubusercontent.com/aliou/linear-cli/v0.2.2/schemas/config.schema.json",
  "defaultWorkspace": "acme",
  "workspaces": {
    "acme": {
      "apiToken": "...",
      "orgName": "Acme Inc",
      "defaultTeamKey": "ENG",
      "outputFormat": "table"
    },
    "personal": {
      "apiToken": "...",
      "orgName": "Personal Workspace"
    }
  },
  "defaultTeamKey": "ENG",
  "outputFormat": "table"
}

Credentials are stored per workspace profile under workspaces.<name>. The CLI auto-detects workspace profile name from Linear organization urlKey during login. Use --workspace to override the profile name.

The CLI writes and updates $schema automatically, pointing to the schema file for the CLI version used to write the config.

Usage

linear <command> <subcommand> [flags]

Commands

Command	Subcommands	Description
auth	login, logout, status, list, use	Manage authentication
issue	list, get, create, update, close	Issue operations
team	list, get	Team operations
project	list, get	Project operations
cycle	list, get	Cycle operations
comment	list, create, update, delete	Comment operations
document	list, get, create, update, delete	Document operations
label	list, create, update, delete	Label operations
milestone	list, get, create, update, delete	Milestone operations
initiative	list, get	Initiative operations
user	list, get, me	User operations
state	list	Workflow state operations
search	issues, documents, projects	Search
graphql	-	Run arbitrary GraphQL queries and mutations

Examples

# List issues for a team
linear issue list --team ENG --limit 10

# Get a specific issue
linear issue get ENG-123

# Create an issue
linear issue create --team ENG --title "Fix bug" --priority 2

# Create an issue with assignee and delegate/agent
linear issue create --team ENG --title "Fix bug" --assignee me --agent "Linear AI"

# Update an issue to assign a delegate/agent
linear issue update ENG-123 --delegate "agent@example.com"

# Clear delegate from an issue
linear issue update ENG-123 --delegate none

# List issues filtered by delegate/agent
linear issue list --agent "Linear AI"

# List users to discover agents (look for app=true)
linear user list

# Close an issue
linear issue close ENG-456

# Search issues
linear search issues "login bug"

# List projects
linear project list --status started

# JSON output
linear issue list --json

# List and switch workspace profiles
linear auth list
linear auth use personal
linear auth use personal --local

# Run an arbitrary GraphQL query
linear graphql 'query { viewer { id name email } }'

# Run GraphQL with variables
linear graphql 'query Issue($id: String!) { issue(id: $id) { id title } }' \
  --variables '{"id":"ENG-123"}'

# Read long values from files
linear issue create --team ENG --title "Spec" --description-file ./issue.md
linear comment create --issue ENG-123 --body-file ./comment.md
linear document create --title "Runbook" --content-file ./runbook.md
linear graphql --query-file ./query.graphql --variables-file ./variables.json

# Use - to read from stdin
cat ./comment.md | linear comment update cmt_123 --body-file -

# Or pipe a query via stdin
echo 'query { viewer { id name } }' | linear graphql

Global flags

-h, --help                Show help
-v, --version             Show version
-w, --workspace <name>    Use a specific workspace profile
--json                    Output as JSON (available on all commands)
complete <shell>          Generate shell completion (bash, zsh, fish, powershell)

Shell completion

# Bash
source <(linear complete bash)

# Zsh
source <(linear complete zsh)

# Fish
linear complete fish | source

# PowerShell
linear complete powershell | Out-String | Invoke-Expression

Configuration

Global config

Stored at ~/.config/linear-cli/config.json:

{
  "$schema": "https://raw.githubusercontent.com/aliou/linear-cli/v0.2.2/schemas/config.schema.json",
  "defaultWorkspace": "acme",
  "workspaces": {
    "acme": {
      "apiToken": "...",
      "orgName": "Acme Inc"
    },
    "personal": {
      "apiToken": "...",
      "orgName": "Personal Workspace"
    }
  },
  "defaultTeamKey": "ENG",
  "outputFormat": "table"
}

Local config

Place a config file in your project directory to set defaults per-project. Searched paths (walking up from cwd):

• .agents/linear.json
• .linear.json
• .linear/config.json

{
  "workspace": "acme",
  "defaultTeamKey": "ENG",
  "outputFormat": "json"
}

Local config overrides global/workspace defaults for defaultTeamKey and outputFormat, and can select the active profile via workspace.

Set defaults with optional local override:

# Global defaults
linear config workspace acme
linear config team ENG

# Same commands, but local to current project
linear config workspace acme --local
linear config team ENG --local

Agent Delegation

Linear supports delegating issues to AI agents (app users). The CLI provides first-class support for this:

Discovering Agents

# List all users, agents will have app=true
linear user list

# Get details for a specific user
linear user get <uuid>

Assigning Agents to Issues

# Create an issue with an agent
linear issue create --team ENG --title "Research" --agent "Linear AI"

# Assign an agent to an existing issue
linear issue update ENG-123 --delegate "agent@example.com"

# Clear the agent from an issue
linear issue update ENG-123 --agent none

Filtering by Agent

# List issues assigned to a specific agent
linear issue list --agent "Linear AI"

# List issues with no agent
linear issue list --agent none

Both --delegate and --agent flags are aliases and accept:

• UUID of the agent user
• Email address
• Display name or name
• none to clear the assignment

Note: Only users with app=true can be assigned as delegates. Regular users cannot be delegates.

License

MIT