# bim-linear

> Read and write Linear issues from the command line. List the queue, open and update issues, comment, and run raw GraphQL. All calls brokered through oauthr — the driver never holds a Linear token.

## Authentication

bim-linear stores no Linear token. Every Linear API call is brokered through oauthr (DESIGN.md §15), tried in this order:

1. Control-plane direct — env `OAUTHR_CONTROL_URL` + `OAUTHR_INTERNAL_SECRET` + `OAUTHR_PRINCIPAL_ID`; a short-lived token is fetched per call.
2. Local proxy — a running oauthr proxy discovered at `%LOCALAPPDATA%\bim-cli\instances\oauthr-*.json`; the proxy injects the `Authorization` header.

```
bim doctor --json   # surfaces oauthr availability + Linear session status
bim linear version  # {"ok":true,"result":{"version":"0.1.0"}}
```

Error when no session is found:
```json
{"ok":false,"error":{"kind":"auth-required","hint":"oauthr connect linear","remediation":{"verb":"oauthr connect linear"}}}
```

## Issue verbs

```
bim linear list   [--team <key>] [--limit N] [--state unstarted|started|completed|cancelled]
bim linear get    <id>
bim linear create --title "<str>" [--team <key>] [--description "<md>"]
bim linear comment <id> --body "<md>"
bim linear status <id> --state "<name>"
bim linear exec   --gql "<query>" [--variables '<json>']
```

`list` — open issues; defaults to unstarted + started. `--limit` defaults to 50. `--state` filters by state **type**.

`get` — single issue by identifier, e.g. `DIM-120` (positional arg).

`create` — opens an issue. `--team` is the team key (e.g. `DIM`); omit to use the first available team. Destructive.

`comment` — append a markdown comment to `<id>`. Destructive.

`status` — set workflow state by **name** (`In Progress`, `Done`, `Cancelled`, …), resolved against the issue's team. Destructive.

`exec` — arbitrary Linear GraphQL query or mutation. `--variables` is a JSON object string, e.g. `'{"id":"DIM-1"}'`. Destructive.

Note: `list --state` takes a state **type**; `status --state` takes a state **name**. Different fields.

## Composition

```
# File model warnings as a tracked issue
bim revit warnings list | bim linear create --title "Model warnings" --team DIM

# Read the active queue into context
bim linear list --team DIM --state started

# Raw GraphQL passthrough
bim linear exec --gql 'query($id:String!){ issue(id:$id){ title state{ name } } }' --variables '{"id":"DIM-120"}'
```

## Requirements

- `oauthr:linear` — the `linear` service connected in oauthr.
- `network:api.linear.app` — outbound network to Linear's API.

Docs: https://bimcli.com/linear/llms.txt