CursorCliSdk

Elixir SDK for the Cursor Agent CLI (agent). It runs Cursor's headless stream-json mode through cli_subprocess_core, projects NDJSON into typed Elixir events, exposes synchronous and streaming APIs, and provides governed launch, MCP, model, session, and ASM integration helpers.

Documentation Menu

• Getting Started
• Options
• Models
• Configuration
• Authentication
• Streaming
• Synchronous Runs
• Sessions
• Error Handling
• Architecture
• Governed Launch
• ASM Integration
• MCP
• Testing
• Provider Behavior Manifest
• Examples
• Changelog
• License

Features

• Lazy streaming with CursorCliSdk.execute/2
• One-shot text responses with CursorCliSdk.run/2
• Typed event projection for init, assistant message, thinking, tool use, tool result, result, and error events
• Shared Cursor parser and invocation contract from CliSubprocessCore.ProviderProfiles.Cursor
• Governed launch validation that rejects caller command, cwd, env, API key, and execution-surface smuggling
• Cursor command helpers for version, models, status, chat creation, sessions, and MCP commands
• Session resume and continue helpers
• Runtime configuration for timeouts, stderr buffering, and headless spawn staggering
• ASM SDK lane support through agent_session_manager

Installation

def deps do
  [
    {:cursor_cli_sdk, "~> 0.1.0"}
  ]
end

The agent binary must be available on PATH, or pass cli_command: in standalone options. Authenticate with Cursor's CLI login flow or materialize CURSOR_API_KEY through CursorCliSdk.Options.api_key, Options.env, or a governed launch authority.

Authentication

Standalone callers provide credentials explicitly:

options =
  CursorCliSdk.Options.new!(
    api_key: System.fetch_env!("CURSOR_API_KEY"),
    permission_mode: :bypass
  )

The library never reads System.get_env/1 from lib/**. Application code owns environment lookup. In governed mode, credentials come from CliSubprocessCore.GovernedAuthority; caller-supplied api_key, cwd, env, cli_command, and execution_surface are rejected.

See Authentication and Governed Launch.

Quick Start

Streaming:

options = CursorCliSdk.Options.new!(permission_mode: :bypass)

CursorCliSdk.execute("Reply with exactly: OK", options)
|> Enum.each(fn event ->
  IO.inspect(event)
end)

Synchronous:

{:ok, text} =
  CursorCliSdk.run(
    "Reply with exactly: OK",
    CursorCliSdk.Options.new!(permission_mode: :bypass)
  )

Workspace placement:

options =
  CursorCliSdk.Options.new!(
    cwd: "/workspace/app",
    model: "composer-2.5-fast",
    permission_mode: :plan
  )

cwd is the only workspace field. It becomes the process cwd and Cursor's --workspace <cwd> argv pair.

Sessions:

{:ok, sessions} = CursorCliSdk.Session.list_sessions()

events =
  CursorCliSdk.Session.resume_session(
    hd(sessions).id,
    CursorCliSdk.Options.new!(permission_mode: :bypass),
    "Continue with a one-sentence summary."
  )

Enum.to_list(events)

Examples

Run the SDK-owned example suite with:

~/scripts/with_bash_secrets bash examples/run_all.sh

See Examples for the full inventory. These are direct SDK examples; ASM provider examples live in agent_session_manager/examples.

Event Types

Struct	Meaning
CursorCliSdk.Types.InitEvent	Cursor system/init metadata such as session, model, and cwd
CursorCliSdk.Types.MessageEvent	User or assistant message content; assistant deltas set delta?: true
CursorCliSdk.Types.ThinkingEvent	Cursor thinking/progress text when emitted
CursorCliSdk.Types.ToolUseEvent	Tool call name, call id, and input
CursorCliSdk.Types.ToolResultEvent	Tool call result payload
CursorCliSdk.Types.ResultEvent	Final status, stop reason, result text, usage, and timing
CursorCliSdk.Types.ErrorEvent	Stream or CLI error projected into a typed event

Headless Invocation Contract

The canonical streaming command shape is:

agent -p --trust --output-format stream-json --stream-partial-output [options] "prompt text"

The prompt is positional. There is no --prompt flag in this SDK contract.

ASM Integration

agent_session_manager can run Cursor through either lane:

• :core lane: CliSubprocessCore.ProviderProfiles.Cursor
• :sdk lane: CursorCliSdk.Runtime.CLI when cursor_cli_sdk is present

See ASM Integration.

Troubleshooting

Symptom	Check
agent not found	Install Cursor Agent CLI or pass cli_command:
Auth failure / exit 41	Confirm CLI login or materialized CURSOR_API_KEY
Immediate exit in many concurrent runs	Lower app concurrency or increase spawn_stagger_ms
Stream timeout	Increase timeout_ms on CursorCliSdk.Options
No assistant text from run/2	Inspect streaming events with execute/2 and stderr diagnostics

Links

• Cursor CLI documentation
• cli_subprocess_core
• agent_session_manager