linear-tui

A TUI client for Linear.app — manage issues, projects, and cycles from your terminal.

Built with ratatui and the Linear GraphQL API.

Features

• Issue management — Browse, search, filter, create, and mutate issues (status, priority, assignee, comments)
• Multiple views — Issues, My Issues, Projects, Cycles with tab-based navigation
• Project & Cycle detail — Drill into projects/cycles to see their issues
• Never blocks — Every API call runs off the UI thread, so navigation and input stay responsive while data loads
• Search — Filter as you type locally, or Ctrl+G to search all of Linear
• Open & copy — Jump to the issue in your browser, or copy its identifier, URL, or suggested branch name
• Linear's own keybindings — c to create, s/p/a/i to update, g+key to switch views, plus vim-style j/k and mouse scrolling
• One-command sign-in — linear-tui auth login opens the browser; no application to register, no client secret, or use a personal API key instead
• Theme support — Default (dark), Light, and Ocean color schemes
• Pagination — Cursor-based infinite scrolling across every list

Installation

From crates.io

cargo install linear-tui

From GitHub Releases

Pre-built binaries are available for Linux, macOS (Intel/Apple Silicon), and Windows on the Releases page.

From source

git clone https://github.com/k1-c/linear-tui.git
cd linear-tui
cargo install --path .

Building needs only a Rust toolchain — see Development for the mise setup.

Getting Started

Just run it:

linear-tui

On first launch it asks how you want to connect, and nothing else has to be set up beforehand.

Signing in through the browser

linear-tui auth login

This opens Linear in your browser, and the authorization screen appears as k1-c/tui — the application linear-tui is registered as. (Linear does not allow "Linear" in an application's name, which is why it is not called linear-tui there.)

Approving it hands a token back to a local callback on port 53681, 53682, or 53683. Tokens are stored in ~/.config/linear-tui/tokens.json with 0600 permissions and refreshed automatically.

No client secret is involved: Linear's PKCE flow makes one optional, so linear-tui ships as a public OAuth client.

Signing in with a personal API key

Useful when the browser flow cannot reach your terminal — over SSH, for example, where the callback would land on the wrong machine.

Create a key under Settings > Account > Security & access, then:

linear-tui auth token <your-api-key>

The key is verified before it is saved.

Checking and clearing credentials

linear-tui auth status        # which credentials are in use, and who they belong to
linear-tui auth logout        # forget the OAuth token
linear-tui auth logout --all  # forget the API key in config.toml as well

Using your own Linear application

Some workspaces require third-party applications to be approved by an admin. If that blocks you — or you would simply rather authorize against your own — register one at Linear Settings > API with http://localhost:53681/callback (plus 53682 and 53683) as its redirect URIs:

linear-tui auth set-oauth <client-id> [client-secret]

LINEAR_CLIENT_ID and LINEAR_CLIENT_SECRET override the config file.

Keybindings

Shortcuts follow Linear's own keyboard shortcuts wherever a terminal allows it, so muscle memory carries over from the web app.

Navigation

Issue actions

Copy and open

Search and filtering

Text fields (search, comments, the new-issue form) accept readline-style editing: Ctrl+w, Ctrl+u, Ctrl+k, Ctrl+a, Ctrl+e, and arrow keys.

Differences from Linear

A terminal cannot deliver every shortcut the web app uses, and a few of Linear's actions have no meaning here. Where they differ:

Copying uses the OSC 52 terminal escape, so it works over SSH. If nothing lands on your clipboard, enable it in your terminal — under tmux that means set -g set-clipboard on.

Configuration

Config file: ~/.config/linear-tui/config.toml

[auth]
# OAuth tokens are managed automatically via `linear-tui auth login`
# To use a personal API key instead:
# api_key = "lin_api_xxxxx"
# To authorize against your own Linear application:
# oauth_client_id = "..."
# oauth_client_secret = "..."   # optional — PKCE does not require one

[ui]
default_team = "Core"       # Auto-select this team on startup
items_per_page = 50          # Issues per page (pagination)
theme = "default"            # "default" | "light" | "ocean"

Themes

Development

The Rust toolchain is pinned in mise.toml, so mise is all you need to install:

git clone https://github.com/k1-c/linear-tui.git
cd linear-tui
mise install       # fetch the pinned toolchain
mise run dev       # run the TUI from source
mise run verify    # format, lint, test, build

mise run fmt, lint, test, and build run the steps individually. Without mise, any stable rustup toolchain works — cargo run, cargo test, and the rest behave the same.

There is nothing else to install: TLS goes through rustls, so no system OpenSSL or pkg-config is involved.

License

MIT