Linear Command line interface (Elixir)

Table of Contents

• Installation
  • I don’t want to install
  • Download a release binary (Most should use this)
  • install.sh (builds from source, 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
    • 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 (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-ex:v0 lcls (1)
$ docker run --rm -e LINEAR_CLI_DAEMON= -e LINEAR_API_KEY="$LINEAR_API_KEY" ghcr.io/rubyists/linear-cli-ex: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 -sLO https://github.com/rubyists/linear-cli-ex/releases/latest/download/lc_macos_aarch64.tar.gz
$ curl -sLo SHA256SUMS https://github.com/rubyists/linear-cli-ex/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.

ℹ️	A Homebrew tap is planned but not yet available.

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

install.sh (builds from source, for machines without Homebrew)

$ git clone https://github.com/rubyists/linear-cli-ex.git
$ cd linear-cli-ex
$ ./install.sh

Builds a native release via mise and installs lc plus the bin/ wrapper scripts onto a directory already on your $PATH. Run ./uninstall.sh to remove exactly what it installed.

From Source (You are obviously a developer)

$ git clone https://github.com/rubyists/linear-cli-ex.git
$ cd linear-cli-ex/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

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 before you even push):

$ cd app
$ mise exec -- mix githooks.install

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