Linear Command line interface (Elixir)

Table of Contents

• Installation
  • I don’t want to install
  • Download a release binary (Most should use this)
  • Homebrew (macOS Apple Silicon, Linux x86_64)
  • install.sh (fetches a release binary, for machines without Homebrew)
  • From Source (You are obviously a developer)
• Usage
  • Configuration
  • Commands
    • Command Aliases
    • Help
    • Who Am I?
    • List Issues
    • Assign one or more issues to yourself (take em!)
    • Create an issue
    • Develop an issue
    • Update an issue
    • Default team/project (profiles)
    • Favorite teams/projects
    • Post a project status update
  • Wrapper scripts
• Development
  • Build a release binary
  • Build the container
  • Conventional Commits (semantic commit messages)
• License

A command line interface to https://linear.app - list, take, create, develop, and update issues without leaving your terminal.

This is an Elixir/OTP port of linear-cli-rb (the original Ruby CLI): same commands, same wrapper scripts (lcls, lcreate, …​), but shipped as a single standalone binary - no Ruby runtime or gem install - via Burrito, and real concurrency (Task.async_stream) for operations that touch several issues at once. Looking up 10 issues by id, for example, runs in ~1.5s here vs ~5s doing it one at a time.

Installation

I don’t want to install

You can run the CLI from the container image without installing anything.

$ podman run --rm -e LINEAR_CLI_DAEMON= -e LINEAR_API_KEY="$LINEAR_API_KEY" ghcr.io/rubyists/linear-cli:v0 lcls (1)
$ docker run --rm -e LINEAR_CLI_DAEMON= -e LINEAR_API_KEY="$LINEAR_API_KEY" ghcr.io/rubyists/linear-cli:v0 lcls (2)

1. Podman usage

2. Docker usage - :v0 tracks the latest 0.x release; pin :v0.1.2 (or whichever version) for a fixed image

❗	The image sets LINEAR_CLI_DAEMON=true by default so its own entrypoint can also run as the long-lived Oban scheduling daemon. Override it to an empty value (as above) for one-off interactive CLI usage - otherwise lc/the wrapper scripts never see your command at all.

Download a release binary (Most should use this)

Grab the tarball for your platform from the latest release - macOS (Apple Silicon), Linux (x86_64), and Windows (x86_64) are all built as standalone executables with no Erlang/Elixir install required. Each tarball bundles lc with the wrapper scripts (lcreate, lcls, lclose, lcomment, lproj).

$ curl --retry 5 --retry-all-errors -sLO https://github.com/rubyists/linear-cli/releases/latest/download/lc_macos_aarch64.tar.gz
$ curl --retry 5 --retry-all-errors -sLo SHA256SUMS https://github.com/rubyists/linear-cli/releases/latest/download/SHA256SUMS
$ grep -q lc_macos_aarch64.tar.gz SHA256SUMS && grep lc_macos_aarch64.tar.gz SHA256SUMS | shasum -a 256 -c - (1)
$ mkdir lc && tar -xzf lc_macos_aarch64.tar.gz -C lc
$ sudo mv lc/* /usr/local/bin/

1. Linux: sha256sum -c - instead of shasum -a 256 -c -.

Every release also publishes sbom.cdx.json - a CycloneDX SBOM covering the app, its Hex dependencies, and the Erlang/OTP and Elixir versions it was built with. The container image has its own separate SBOM (its OS packages - irrelevant if you’re not using the container), published as a workflow artifact on the release’s build rather than a release asset.

On macOS, Gatekeeper blocks lc itself (the wrapper scripts are plain shell, so they’re unaffected) since it isn’t signed/notarized yet:

$ xattr -d com.apple.quarantine /usr/local/bin/lc

Homebrew (macOS Apple Silicon, Linux x86_64)

$ brew tap rubyists/tap
$ brew install lc

See https://github.com/rubyists/homebrew-tap for the formula itself.

install.sh (fetches a release binary, for machines without Homebrew)

$ curl --retry 5 --retry-all-errors -fsSL https://raw.githubusercontent.com/rubyists/linear-cli/main/install.sh | bash

Detects your platform, downloads and checksum-verifies the matching release tarball (the same one the "Download a release binary" section above uses), and installs lc plus the bin/ wrapper scripts onto a directory already on your $PATH - no Erlang/Elixir/Zig toolchain required. LC_VERSION pins a specific release tag instead of the latest one; LC_INSTALL_DIR pins a specific install directory.

$ curl --retry 5 --retry-all-errors -fsSL https://raw.githubusercontent.com/rubyists/linear-cli/main/uninstall.sh | bash

Removes exactly what install.sh installed, by replaying the manifest it wrote - not a guess at where things ended up.

From Source (You are obviously a developer)

$ git clone https://github.com/rubyists/linear-cli.git
$ cd linear-cli/app
$ mise install
$ mise exec -- mix deps.get
$ mise exec -- env MIX_ENV=prod mix release lc
$ ./burrito_out/lc_<target> --version

Usage

Configuration

You must set the LINEAR_API_KEY environment variable to your Linear API key. You can find your API key in your Linear Settings.

Commands

Command Aliases

Short aliases are available for the top-level commands and some subcommands, so you don’t have to type the full name every time:

Command	Aliases
whoami	me, w, who, whodat
version	v
issue	i, issues
team	t, teams
project	p, projects
issue create	c, new, add
issue develop	d, dev
issue list	l, ls
issue update	u
issue pr	pull-request
team list	l, ls
project list	l, ls

$ lc w --teams
$ lc i ls
$ lc i dev CRY-1234

issue take has no alias.

Help

You can get help/usage for any command or subcommand by using the --help flag.

$ lc --help
$ lc [COMMAND] --help
$ lc [COMMAND] [SUBCOMMAND] --help

Who Am I?

$ lc whoami
$ lc whoami --teams (1)

1. Include the teams you are a member of

List Issues

lcls is a wrapper script provided to list issues. It’s an alias for lc issue list.

$ lcls
$ lcls --full
$ lcls -f CRY-1

Assign one or more issues to yourself (take em!)

$ lc issue take CRY-1234
$ lc issue take CRY-456 CRY-789

Create an issue

$ lc issue create --title "My new issue" --description "This is a new issue" --labels Bug,Feature --team CRY
$ lc issue create -t "My new issue" -T CRY -l Improvement,Feature

ℹ️	If you don’t provide a title, team, labels, or description, you will be prompted to enter them.

💡	When creating an issue, you can use the --dev (or --develop) option to immediately start development on the issue.

Develop an issue

Switches to the branch for the issue, creating the branch if it doesn’t exist.

$ lc issue develop CRY-1234

Create a Pull Request (using the semantic PR title)

Requires the gh CLI to be installed and configured.

$ lc issue pr CRY-1234

Update an issue

All of the update options can work on multiple issues at a time.

Add a comment to one or more issues

$ lc issue update --comment "Here is a comment" CRY-1234 (1)
$ lc issue update --close --reason "I do not like you" CRY-14 CRY-15 (2)
$ lc issue update --cancel --trash --reason "I have no idea why you are here" CRY-16 CRY-17 (3)
$ lc issue update --comment - CRY-14 CRY-15 (4)
$ lcomment CRY-1234 CRY-3 (5)

1. Comments on the issue with the provided text

2. Closes multiple issues without prompting (reason is added as a comment)

3. Cancels multiple issues without prompting and moves them to the trash (reason is added as a comment)

4. Opens your editor for the comment (use - to prompt)

5. Always prompts for a comment (lcomment is a wrapper for lc issue update --comment -)

Close one or many issues

$ lc issue update --close --reason "These were closable" CRY-1234 CRY-2

Default team/project (profiles)

Not in Ruby’s linear-cli - save a named team/project bundle once, then switch to it instead of passing --team/--project on every issue create/issue list.

$ lc profile create manhattan --team CRY --project Manhattan
$ lc profile use manhattan
$ lc profile list
$ lc profile show
$ lc profile delete manhattan

An explicit --team/--project on the command line always overrides the active profile.

Issue commands also accept a bare number (lc issue develop 1234) in place of a full team-prefixed identifier - it’s resolved via the active profile’s team, then favorited teams, then a prompt across every team you belong to.

Favorite teams/projects

Not in Ruby’s linear-cli - favorite the teams/projects you actually care about, and once any exist, team list/project list default to showing just favorites of that kind. --all bypasses the favorites filter only - it doesn’t change team list’s `--no-mine or project list’s `--mine/--team scope, it just shows everything within whatever scope you already asked for.

$ lc team favorite CRY
$ lc team list
$ lc team list --all
$ lc team unfavorite CRY
$ lc project favorite Manhattan
$ lc project list

Post a project status update

Not in Ruby’s linear-cli - a status post on a project (Linear’s own "Project Update" feature), not an edit to the project itself.

$ lc project update Manhattan --body "Shipping ahead of schedule" --health onTrack

Wrapper scripts

The bin/ wrapper scripts (ported verbatim from linear-cli’s own `exe/scripts/) make the common commands shorter to type. They just exec lc …​, so they work anywhere lc is on your $PATH.

$ lcls
$ lcreate --description "This is a new issue" --labels Bug,Feature --team CRY
$ lclose --reason "This issue sucks" CRY-1234 CRY-456
$ lcomment CRY-1234
$ lproj list --mine

Development

First, activate the repo’s git hooks (enforces conventional-commit subjects on every commit, and again on every commit about to be pushed):

$ mix setup

Run the development checkout directly from the repository root with mix lc. It compiles and starts the application as needed, then forwards arguments, interactive input, output, and exit status to the same CLI entry point used by the release binary:

$ mix lc whoami
$ mix lc issue list --output json

The project uses ExUnit and mix format. Run tests with:

$ cd app
$ mise exec -- mix test
$ mise exec -- mix format --check-formatted

Build a release binary

$ cd app
$ mise exec -- env MIX_ENV=prod BURRITO_TARGET=<target> mix release lc

<target> is one of macos_aarch64, linux_x86_64, or windows_x86_64.

Build the container

$ ./ci/build_image.sh <tag_name>

Conventional Commits (semantic commit messages)

This project follows the Conventional Commits specification.

To contribute, please follow that commit message format, or your pull request may be rejected.

License

WTFPL