linear-cli

= Linear Command line interface :toc: right :toclevels: 3 :sectanchors: :icons: font :tip-caption: 💡 :note-caption: 📝 :experimental: :plc-url: https://raw.githubusercontent.com/rubyists/linear-cli/main/oci/plc

A command line interface to https://linear.app.

== Installation

=== I don't want to install

You can use the OCI container image to run the CLI without installing it.

[source,sh]

$ podman run -w /git -v .:/git -v ~/.ssh:/root/.ssh -it --rm -e GITHUB_TOKEN="$GITHUB_TOKEN" -e LINEAR_API_KEY="$LINEAR_API_KEY" ghcr.io/rubyists/linear-cli:stable lcls <1> $ docker run -it --rm -e LINEAR_API_KEY=your-api-key ghcr.io/rubyists/linear-cli:stable lcls <2>

<1> Podman Usage <2> Docker Usage, without mounting your ssh keys and git dir. This will not be able to do git operations.

There is a {plc-url}[helper script] available to wrap this up for you.

NOTE: Git commands will require a passphrase for every operation if you are using an ssh key.

[source,sh]

$ curl -sL https://raw.githubusercontent.com/rubyists/linear-cli/main/oci/plc | sudo tee /usr/local/bin/lc $ sudo chmod +x /usr/local/bin/lc

Then you can just run 'lc' to use the CLI.

=== Gem install (Most should use this)

Requires ruby 3.2 or later

[source,sh]

$ gem install linear-cli

=== From Source (You are obviously a developer)

[source,sh]

$ git clone https://github.com/rubyists/linear-cli.git $ cd linear-cli $ bundle install $ rake install

== Usage

=== Configuration

You must set the LINEAR_API_KEY environment variable to your Linear API key. You can find your API key in your https://linear.app/settings/api[Linear Settings].

==== Tab Completion

If you are using bash or zsh, you can enable tab completion by adding the following to your .bashrc or .zshrc:

bash:

[source,sh]

eval "$(lc completion bash)" <1> eval "$(lc completion -a bash)" <2>

<1> This will enable tab completion for the 'lc' command in bash <2> This will include the subcommand aliases as well

zsh:

[source,sh]

eval "$(lc completion zsh)" <1> eval "$(lc completion -a zsh)" <2>

<1> This will enable tab completion for the 'lc' command in zsh <2> This will include the subcommand aliases as well

=== Commands

==== Help

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

[source,sh]

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

==== Who Am I?

You can use the 'w' alias for 'whoami' (or whodat, for Saints fans)

[source,sh]

$ lc whoami $ lc whodat <1> $ lc w --teams <2>

<1> Bayou style <2> Include the teams you are a member of

==== List Issues

lcls is a helper provided to list issues. It's an alias for lc issues list.

image::cinemas/listings.cinema.gif[]

[source,sh]

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

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

'i' is a shortcut for the 'issue' command

[source,sh]

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

==== Create an issue

'c' is a shortcut for the 'create' subcommand of the issue command

[source,sh]

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

NOTE: If you don't provide a title, team, labels or description, you will be prompted to enter them.

TIP: When creating an issue, you can use the --dev option to immediately start development on the issue.

==== Develop an issue

This will switch to the branch for the issue, creating the branch if it doesn't exist.

'dev' is a shortcut for the 'develop' subcommand of the issue command

[source,sh]

$ lc i dev CRY-1234

===== Create a Pull Request (Using the Semantic PR Title)

Requires the gh cli to be installed and configured.

[source,sh]

$ lc i pr CRY-1234

==== Update an issue

All of the update options can work on multiple issues, so long as it's not more than 50 at a time. You can also use the 'u' alias for 'update', and as always, the 'i' alias for 'issue'.

===== Add a comment to one or more issues

[source,sh]

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

<1> This will use the provided comment to comment on the issue <2> This will close multiple issues without prompting (reason is added as a comment) <3> This will cancel multiple issues without prompting, and move them to the trash (reason is added as a comment) <4> This will prompt for a comment (use '-' to prompt) <5> This will always prompt you for a comment ('lcomment' is an alias for 'lc issue update --comment -')

===== Close one or many issues

[source,sh]

$ lc i u --close --reason "These were closable" CRY-1234 CRY-2

=== Aliases

Some command aliases are available to make things easier to type.

[source,sh]

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