bim-linear

Read and write Linear issues without leaving the terminal. List the queue, open and update issues, drop comments, move workflow states, and run raw GraphQL for anything the typed verbs don't cover. Credentials are brokered by oauthr, so the driver never sees a Linear token — pipe a model warning straight into a tracked issue, or read a sprint into an agent's context.

List, read, create, comment on, and update Linear issues from the command line. Token-free auth via oauthr.

Authentication

bim-linear never stores a Linear token. Every API call is brokered through oauthr, the credential broker, following DESIGN.md §15. Two paths are supported, tried in order:

1. Control-plane direct — set OAUTHR_CONTROL_URL, OAUTHR_INTERNAL_SECRET, and OAUTHR_PRINCIPAL_ID. The driver fetches a short-lived token per call.
2. Local proxy — a running oauthr proxy instance discovered at %LOCALAPPDATA%\bim-cli\instances\oauthr-*.json; the driver routes Linear traffic through it and the proxy injects the Authorization header.

bim doctor --json     # surfaces oauthr availability + Linear session status
bim linear version    # driver version

When no session is found, verbs return a structured auth-required error:

{"ok":false,"error":{"kind":"auth-required","hint":"oauthr connect linear"}}

Connect the linear service once via oauthr, then every call authenticates silently.

Issue verbs

Verb	What it does
bim linear list [--team <key>] [--limit N] [--state <type>]	List open issues; defaults to unstarted + started. --state is one of unstarted, started, completed, cancelled
bim linear get <id>	Fetch a single issue by identifier (e.g. DIM-120)
bim linear create --title "..." [--team <key>] [--description "<md>"]	Create an issue; uses the first available team if --team is omitted
bim linear comment <id> --body "<md>"	Add a comment to an issue
bim linear status <id> --state "<name>"	Update workflow state, resolved by name (e.g. In Progress, Done, Cancelled)
bim linear exec --gql "<query>" [--variables '<json>']	Run an arbitrary Linear GraphQL query or mutation

<id> is the human identifier Linear shows on an issue, e.g. DIM-120. --team takes the team key (e.g. DIM).

Pipe compositions

# File a model warning as a tracked Linear issue
bim revit warnings list | bim linear create --title "Model warnings $(date +%F)" --team DIM

# Read the active queue into an agent's context
bim linear list --team DIM --state started

# Move an issue to Done once work lands
bim linear status DIM-120 --state Done

# Anything the typed verbs don't cover — raw GraphQL
bim linear exec --gql 'query($id:String!){ issue(id:$id){ title state{ name } } }' --variables '{"id":"DIM-120"}'

Gotchas

• The driver holds no token. If bim linear returns auth-required, connect the linear service in oauthr (hint: "oauthr connect linear") — re-running the verb won't help until a session exists.
• --state on list filters by state type (unstarted/started/completed/cancelled); --state on status takes a state name (In Progress, Done, …). They are different fields.
• create without --team picks the first team available to your principal. Pass --team explicitly when you belong to more than one.
• create, comment, status, and exec are marked destructive (they mutate Linear) — they will not run in a read-only dry context.
• Requires network access to api.linear.app.

For agent use: /linear/llms.txt