linear-cli

To use the Linear CLI, the linear command must be available on your PATH. You can verify your installation by checking the version.

If you do not want to install it globally, you can run any command using npx @schpet/linear-cli instead of linear.

# Check if installed
linear --version

# If not installed globally, use npx
npx @schpet/linear-cli --version

To enable AI agents using Claude Code to interact with Linear via this CLI, install the skill using the Claude Code plugin system.

From within Claude Code:

/plugin marketplace add schpet/linear-cli
/plugin install linear-cli@linear-cli

From your terminal (bash):

claude plugin marketplace add schpet/linear-cli
claude plugin install linear-cli@linear-cli

To update the skill:

claude plugin marketplace update linear-cli
claude plugin update linear-cli@linear-cli

# from claude code
/plugin marketplace add schpet/linear-cli
/plugin install linear-cli@linear-cli

# from bash
claude plugin marketplace add schpet/linear-cli
claude plugin install linear-cli@linear-cli

# to update
claude plugin marketplace update linear-cli
claude plugin update linear-cli@linear-cli

The Linear CLI supports multiple authentication methods. The CLI resolves credentials using the following precedence (from highest to lowest):

1. --api-key flag (explicit key for a single command)
2. LINEAR_API_KEY environment variable
3. api_key in the project's .linear.toml config
4. --workspace flag (triggers lookup in stored credentials)
5. workspace config in .linear.toml (triggers lookup in stored credentials)
6. The default workspace from stored credentials

Recommended Method: Stored Credentials

For most users, it is recommended to use the linear auth login command. This stores API keys in your system's native keyring (macOS Keychain, Linux libsecret, or Windows Credential Manager) and keeps workspace metadata in ~/.config/linear/credentials.toml. This allows you to manage multiple workspaces securely without committing keys to version control.

When running linear-cli via Deno, the CLI requires the --allow-all flag. This is necessary because Linear issues often contain images, attachments, and comments hosted on arbitrary external domains, making fine-grained --allow-net restrictions impractical.

In addition to network access, the CLI requires permissions for:

• File system access: For managing configuration and temporary files.
• Environment variables: To access API keys and editor settings.
• Subprocess execution: To interact with git, text editors, and pagers.
• System info: To retrieve the hostname.

If you are running tasks defined in deno.json (such as dev, install, or test), these tasks are pre-configured with the necessary permission flags.

To improve the command-line experience, you can generate and source completions for bash, zsh, or fish. Add the resulting command to your shell's configuration file (e.g., ~/.bashrc or ~/.zshrc).

# For bash
source <(linear completions bash)

# For zsh
source <(linear completions zsh)

# For fish
linear completions fish | source

You can install the linear CLI using several package managers depending on your environment:

Homebrew (macOS/Linux)

brew install schpet/tap/linear

Deno (via JSR)

deno install -A --reload -f -g -n linear jsr:@schpet/linear-cli

npm / bun / pnpm

Install as a dev dependency to pin the version to your project:

npm install -D @schpet/linear-cli
# or
bun add -D @schpet/linear-cli
# or
pnpm add -D @schpet/linear-cli

Then run via your package manager:

npx linear issue list
bunx linear issue list

Binaries

Download pre-built binaries from the GitHub releases page.

For AI agents that support skills.sh, you can install the linear-cli skill using npx.

npx skills add schpet/linear-cli

You can access help documentation for any specific command or subcommand by appending the --help flag. This is useful for discovering available subcommands, flags, and argument requirements for a specific domain (e.g., issue, project, or auth).

# Get help for a top-level command
linear <command> --help

# Get help for a specific subcommand
linear <command> <subcommand> --help

To use the CLI, you need a Personal API key from Linear:

1. Navigate to linear.app/settings/account/security.
2. Scroll to the Personal API keys section.
3. Click Create key.
4. Provide a label (e.g., CLI).
5. Copy the generated key (it will start with lin_api_).

Note: You must have member access to create API keys; guest accounts cannot create them.

When providing multi-line Markdown for issue descriptions or comment bodies, always prefer file-based flags over inline arguments. This prevents shell escaping issues, avoids literal \n sequences, and ensures correct formatting in the Linear UI.

Recommended flags:

• --description-file for issue create and issue update.
• --body-file for comment add and comment update.

Only use --description or --body for simple, single-line text.

# Recommended workflow for multi-line content
cat > /tmp/description.md <<'EOF'
## Summary
- Item 1
- Item 2

## Details
Properly formatted content.
EOF

linear issue create --title "My Issue" --description-file /tmp/description.md