Linear (CLI)

The rensei linear command group is implemented in the OSS donmai runtime and documented at donmai.dev/docs/cli/linear. This page explains how the platform proxy layer changes the behavior of those commands when running under Rensei.

rensei linear exposes the donmai linear subcommands with one critical difference: agents and operators never need a LINEAR_API_KEY in their environment. All Linear API calls are routed through the Rensei platform proxy, which exchanges the call for an org-scoped OAuth token stored in the platform credential store.

How the proxy works

When rensei linear (or an agent using the rensei linear proxy internally) makes a Linear API call:

The CLI or agent issues the call to the local credential socket at RENSEI_CREDENTIAL_SOCKET.

The daemon forwards the request to the platform proxy endpoint at app.rensei.ai/api/proxy/linear.

The platform proxy authenticates the request using the org's stored Linear OAuth token (provisioned via rensei project trackers connect linear).

The Linear API response is returned through the proxy to the caller.

The OAuth token is never surfaced to the agent process. If LINEAR_API_KEY is set in the worker shell, it takes precedence over the proxy path - but this is not recommended for production use because it bypasses org-level OAuth scoping and audit.

If the proxy returns 401, the agent stops and surfaces the error - it does not hunt for credentials. The most common cause is that the Linear OAuth token needs to be re-provisioned (the app's OAuth scopes were updated). Run rensei project trackers connect linear to re-authorize.

Required OAuth scopes

The platform OAuth app requires these Linear scopes for full AgentSession functionality:

Scope	Required for
`read`	Reading issues, comments, projects
`write`	Creating and updating issues and comments
`issues:create`	Creating new Linear issues
`comments:create`	Posting agent comments
`app:assignable`	Assigning the agent app to issues
`app:mentionable`	Mentioning the agent app in comments

The app:assignable and app:mentionable scopes are required for AgentSession activity (agent thoughts and responses visible in the Linear UI). They are provisioned automatically by the OAuth flow in rensei project trackers connect linear. They are not provisioned when using --api-key.

See Linear integration for the full OAuth setup guide and AgentSession lifecycle details.

Command reference

The following subcommands are available. For flag and argument details, see the OSS docs.

Subcommand	Description	OSS docs
`rensei linear issues list`	List issues matching filters	donmai.dev/docs/cli/linear
`rensei linear issues show`	Show issue detail	donmai.dev/docs/cli/linear
`rensei linear issues create`	Create a new issue	donmai.dev/docs/cli/linear
`rensei linear issues update`	Update an existing issue	donmai.dev/docs/cli/linear
`rensei linear comments list`	List comments on an issue	donmai.dev/docs/cli/linear
`rensei linear comments create`	Post a comment	donmai.dev/docs/cli/linear
`rensei linear teams list`	List teams in the org	donmai.dev/docs/cli/linear
`rensei linear projects list`	List projects	donmai.dev/docs/cli/linear

Troubleshooting

Proxy returns 401

The org's Linear OAuth token is missing or expired.

# Re-authorize the Linear integration for the active project
rensei project trackers connect linear

If the issue persists, check whether the Linear Application has been revoked in your Linear workspace settings and re-authorize.

Agent runs but Linear UI shows no activity

The OAuth token likely lacks app:assignable + app:mentionable scopes. This happens when the connection was created with --api-key instead of the OAuth flow.

# Check current tracker configuration
rensei project trackers list

# Re-run the OAuth flow to reprovision scopes
rensei project trackers connect linear

`LINEAR_API_KEY` in agent environment

If LINEAR_API_KEY is set in the daemon's environment or inherited from the shell, it overrides the platform proxy. This bypasses org-level audit. Remove it from the daemon's env and rely on the proxy instead.

Linear integration - full OAuth setup, AgentSession lifecycle, webhook configuration
Project trackers connect linear - the CLI command that runs the OAuth flow
Sessions - Linear AgentSession - 3 trigger types, activity types, session lifecycle
OSS linear command reference - complete flag and subcommand documentation on donmai.dev

On this page