linear-tui

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

Built with ratatui and the Linear GraphQL API.

• Sidebar navigation, like Linear's — My Issues, your Favorites (in Linear's order, with folders), and the current team's Issues / Cycles / Projects / Views under a team switcher
• Favorites — favorite projects, cycles, issues, and views open right in the terminal; favorites of kinds the TUI has no page for (documents, labels, …) open on linear.app
• Saved views — issue and project views, on the workspace Views page and each team's own, with Linear's Issues / Projects tabs; Linear evaluates each view's filter, so it shows exactly what it shows on linear.app
• Grouped lists — issues stacked under collapsible status headers (or by assignee, priority, project), sub-issues nested under their parent, and Linear's Active / Backlog / All issues presets
• Rich rows — priority and status glyphs in the workspace's own colours, label chips, project, estimate, assignee avatar, and date, dropping columns gracefully as the terminal narrows
• Issue detail like the web app — rendered Markdown (bold, code, lists, headings, quotes, code blocks) with proper Japanese line breaking, threaded comment cards, sub-issues, and a properties panel with status, priority, assignee, creator, estimate, due date, cycle, labels, project and milestone; step to the next/previous issue with J/K
• Mouse support — click sidebar entries, preset chips, group headers, popup entries; click a row to select it and again to open it; scroll with the wheel
• Issue management — create issues, change status, priority, and assignee, and comment
• 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 go places, plus vim-style j/k
• 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

cargo install linear-tui

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

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.

Just run it:

linear-tui

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

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.

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.

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

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.

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

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.

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.

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"
sidebar = true               # Show the sidebar (it hides itself below 100 columns)
sidebar_width = 26           # Sidebar width in columns (18-48)
group_by = "status"          # "status" | "assignee" | "priority" | "project" | "none"

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.

The GIF above is scripted with VHS, so it can be re-recorded after a UI change. Sign linear-tui in to a throwaway workspace, fill it with demo data once, then record:

python3 demo/seed.py                        # issues, projects, cycles, views
LINEAR_DEMO_TEAM=<team name> demo/record.sh # writes assets/demo.gif

record.sh needs vhs, ttyd, and ffmpeg, and runs linear-tui with a throwaway config so your own settings stay out of the recording.

MIT