Linear (CLI)

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 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.

Required OAuth scopes

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

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.

Create a native Linear document

rensei linear create-document writes a document directly in Linear. Markdown content renders in Linear's native document view, and the result includes Linear's document ID, title, URL, and persisted parent relationship.

For an admitted agent session, the command sends a direct request to that session's Rensei MCP endpoint. This CLI path does not depend on Codex's cached native tool discovery. Issue-bound sessions retain their assigned issue; interactive sessions must supply an explicit parent authorized by their bound project tracker. If the scoped permission refuses the request, the command returns the refusal instead of retrying through a wider credential. Human and non-session calls use their normal authorized Linear path.

Create a document from a Markdown file with an issue parent:

rensei linear create-document ENG-42 \
  --title "Deployment design" \
  --file design.md

--file is an alias for --content-file. Use --content for inline Markdown. Omit all three content flags to start with an empty Linear document; pass no more than one content source.

Every document has exactly one native parent. Select it with a positional issue reference or --issue, --project, --team, --cycle, --initiative, or --release. --project selects the document's Linear parent and does not change the CLI's active project context.

The command exposes all 16 native creation fields: title; Markdown content; the optional client ID; one of the six parents; icon, color, and sort order; owner; subscribers; template; and resource folder. Use --no-owner to send an explicit owner null. Repeating --subscriber supplies the initial subscribers; an omitted subscriber flag remains distinct from an explicit empty list.

create-document is separate from create-attachment. The attachment command keeps its existing raw file-or-URL behavior:

rensei linear create-attachment ENG-42 --url "https://example.com/spec" --title "Spec"

Use an attachment when you want to link or attach an external resource. It does not create a native Linear document or render Markdown as one.

Command reference

The following subcommands are available (flat verb-noun form, not nested). For flag and argument details, see the OSS docs.

Catalog visibility and authorization

Two properties of the proxy matter when you build on list-teams / list-projects output or mint credentials for agents:

Who may call the proxy. Human principals (browser session, WorkOS CLI user token) are always allowed. Machine principals (API keys, OAuth agents, worker runtime JWTs) must hold the linear:proxy scope: the explicit scope grant is the authorization boundary. Project fencing is deliberately not consulted at this surface, because the proxy forwards arbitrary GraphQL, which cannot be fenced per project. A project-fenced key that holds linear:proxy has therefore been explicitly granted workspace-wide proxy access; one without the scope receives 403 Missing required scope: linear:proxy.

Catalog results may be incomplete. The platform serves Linear calls on the credential the resolver selects, preferring the app-actor token. Linear hides private teams and projects from app-actor tokens: a catalog query then succeeds with only the visible subset and raises no error, so the automatic credential-recovery path (which reacts to auth failures and not-found errors) does not engage. Treat list-teams / list-projects output as the authenticated credential's view, not a complete workspace census. If a team or project you expect is missing, connect or refresh the per-org user OAuth credential via rensei project trackers connect 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.

Related pages

• 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