Skip to content

Commit a783b2f

Browse files
schpetschpet
committed
feat: add multi-workspace authentication support
Add built-in credential storage for managing multiple Linear workspaces: - ~/.config/linear/credentials.toml stores API keys by workspace slug - auth login: add credentials (auto-detects workspace from API) - auth logout: remove credentials - auth list: show configured workspaces with org/user info - auth default: set the default workspace - global -w/--workspace flag to target specific workspace API key precedence: CLI flag > env var > config > workspace flag > project workspace > default
1 parent 1f11e94 commit a783b2f

32 files changed

+1413
-237
lines changed

‎CHANGELOG.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,15 @@
22

33
## [Unreleased]
44

5+
### Added
6+
7+
- built-in credential storage at `~/.config/linear/credentials.toml` for managing multiple Linear workspaces
8+
- `linear auth login` to add workspace credentials (auto-detects workspace from API key)
9+
- `linear auth logout` to remove workspace credentials
10+
- `linear auth list` to show configured workspaces with org/user info
11+
- `linear auth default` to set the default workspace
12+
- global `-w, --workspace` flag to target a specific workspace by slug
13+
514
## [1.8.1] - 2026-01-23
615

716
### Fixed

‎README.md‎

Lines changed: 5 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -66,24 +66,20 @@ deno task install
6666

6767
1. create an API key at [linear.app/settings/account/security](https://linear.app/settings/account/security)[^1]
6868

69-
2. add the API key to your shell environment:
69+
2. authenticate with the CLI:
7070

7171
```sh
72-
# in ~/.bashrc or ~/.zshrc:
73-
export LINEAR_API_KEY="lin_api_..."
74-
75-
# or in fish:
76-
set -Ux LINEAR_API_KEY "lin_api_..."
72+
linear auth login
7773
```
7874

79-
3. run the configuration wizard:
75+
3. configure your project:
8076

8177
```sh
8278
cd my-project-repo
8379
linear config
8480
```
8581

86-
_this will create a `.linear.toml` config file in your repository with your workspace and team settings._
82+
see [docs/authentication.md](docs/authentication.md) for multi-workspace support and other authentication options.
8783

8884
the CLI works with both git and jj version control systems:
8985

@@ -209,8 +205,7 @@ the CLI supports configuration via environment variables or a `.linear.toml` con
209205

210206
| option | env var | toml key | example | description |
211207
| --------------- | ------------------------ | ----------------- | -------------------------- | ------------------------------------- |
212-
| API key | `LINEAR_API_KEY` | `api_key` | `"lin_api_..."` | your Linear API key (required) |
213-
| Team ID | `LINEAR_TEAM_ID` | `team_id` | `"TEAM_abc123"` | default team for operations |
208+
| Team ID | `LINEAR_TEAM_ID` | `team_id` | `"ENG"` | default team for operations |
214209
| Workspace | `LINEAR_WORKSPACE` | `workspace` | `"mycompany"` | workspace slug for web/app URLs |
215210
| Issue sort | `LINEAR_ISSUE_SORT` | `issue_sort` | `"priority"` or `"manual"` | how to sort issue lists |
216211
| VCS | `LINEAR_VCS` | `vcs` | `"git"` or `"jj"` | version control system (default: git) |

‎deno.lock‎

Lines changed: 31 additions & 2 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎docs/authentication.md‎

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
# authentication
2+
3+
the CLI supports multiple authentication methods with the following precedence:
4+
5+
1. `--api-key` flag (explicit key for single command)
6+
2. `LINEAR_API_KEY` environment variable
7+
3. `api_key` in project `.linear.toml` config
8+
4. `--workspace` / `-w` flag → stored credentials lookup
9+
5. project's `workspace` config → stored credentials lookup
10+
6. default workspace from stored credentials
11+
12+
## stored credentials (recommended)
13+
14+
credentials are stored in `~/.config/linear/credentials.toml` and support multiple workspaces.
15+
16+
### commands
17+
18+
```bash
19+
linear auth login # add a workspace (prompts for API key)
20+
linear auth login --key <key> # add with key directly (for scripts)
21+
linear auth list # list configured workspaces
22+
linear auth default # interactively set default workspace
23+
linear auth default <slug> # set default workspace directly
24+
linear auth logout <slug> # remove a workspace
25+
linear auth logout <slug> -f # remove without confirmation
26+
linear auth whoami # show current user and workspace
27+
linear auth token # print the resolved API key
28+
```
29+
30+
### adding workspaces
31+
32+
```bash
33+
# first workspace becomes the default
34+
$ linear auth login
35+
Enter your Linear API key: ***
36+
Logged in to workspace: Acme Corp (acme)
37+
User: Jane Developer <jane@acme.com>
38+
Set as default workspace
39+
40+
# add additional workspaces
41+
$ linear auth login
42+
Enter your Linear API key: ***
43+
Logged in to workspace: Side Project (side-project)
44+
User: Jane Developer <jane@example.com>
45+
```
46+
47+
### listing workspaces
48+
49+
```bash
50+
$ linear auth list
51+
WORKSPACE ORG NAME USER
52+
* acme Acme Corp Jane Developer <jane@acme.com>
53+
side-project Side Project Jane Developer <jane@example.com>
54+
```
55+
56+
the `*` indicates the default workspace.
57+
58+
### switching workspaces
59+
60+
```bash
61+
# set a new default
62+
linear auth default side-project
63+
64+
# or use -w flag for a single command
65+
linear -w side-project issue list
66+
linear -w acme issue create --title "Bug fix"
67+
```
68+
69+
### credentials file format
70+
71+
```toml
72+
# ~/.config/linear/credentials.toml
73+
default = "acme"
74+
acme = "lin_api_xxx"
75+
side-project = "lin_api_yyy"
76+
```
77+
78+
## environment variable
79+
80+
for simpler setups or CI environments, you can use an environment variable:
81+
82+
```sh
83+
# bash/zsh
84+
export LINEAR_API_KEY="lin_api_..."
85+
86+
# fish
87+
set -Ux LINEAR_API_KEY "lin_api_..."
88+
```
89+
90+
this takes precedence over stored credentials. if you have `LINEAR_API_KEY` set and try to use `linear auth login`, you'll see a warning:
91+
92+
```
93+
Warning: LINEAR_API_KEY environment variable is set.
94+
It takes precedence over stored credentials.
95+
Remove it from your shell config to use multi-workspace auth.
96+
```
97+
98+
## project config
99+
100+
you can also set the API key in a project's `.linear.toml`:
101+
102+
```toml
103+
api_key = "lin_api_..."
104+
workspace = "acme"
105+
team_id = "ENG"
106+
```
107+
108+
this is useful for project-specific credentials but less secure than stored credentials since it may be committed to version control.
109+
110+
## workspace matching
111+
112+
when your project config has a `workspace` setting:
113+
114+
```toml
115+
# .linear.toml
116+
workspace = "acme"
117+
team_id = "ENG"
118+
```
119+
120+
the CLI will automatically use the stored credentials for that workspace, even if a different workspace is your default. this lets you work on multiple projects with different workspaces without constantly switching.
121+
122+
## creating an API key
123+
124+
1. go to [linear.app/settings/account/security](https://linear.app/settings/account/security)
125+
2. scroll to "Personal API keys"
126+
3. click "Create key"
127+
4. give it a label (e.g., "CLI")
128+
5. copy the key (starts with `lin_api_`)
129+
130+
note: creating an API key requires member access; it is not available for guest accounts.

‎skills/linear-cli/SKILL.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ allowed-tools: Bash(linear:*), Bash(curl:*)
88

99
A CLI to manage Linear issues from the command line, with git and jj integration.
1010

11-
Generated from linear CLI v1.8.0
11+
Generated from linear CLI v1.8.1
1212

1313
## Prerequisites
1414

0 commit comments

Comments
 (0)