CursorCliSdk.Options is the typed input for streaming and synchronous Cursor
invocations.
options =
CursorCliSdk.Options.new!(
cwd: "/workspace/app",
model: "composer-2.5-fast",
mode: :ask,
permission_mode: :bypass,
approve_mcps: true
)Core Fields
| Field | Meaning |
|---|---|
:cli_command | Optional command path. Defaults to provider resolution for agent. |
:cwd | Process cwd and Cursor --workspace <cwd>. This is the only workspace field. |
:model | Model name passed as --model. |
:api_key | Materialized as CURSOR_API_KEY in the child env, never argv. |
:env | Additional child environment map for standalone runs. |
:timeout_ms | Stream receive timeout. |
:max_stderr_buffer_bytes | Tail buffer size for stderr diagnostics. |
Cursor Native Fields
| Field | CLI behavior |
|---|---|
:mode | Cursor operational mode. :ask becomes --mode ask; :agent omits the flag. |
:permission_mode | Provider permission posture. :bypass maps to --force; :plan maps to --mode plan. |
:trust | Emits --trust when true. |
:output_format | Defaults to stream-json. |
:stream_partial_output | Emits --stream-partial-output when true. |
:resume | Emits --resume <session_id>. |
:continue | Tracks latest-session continuation intent for runtimes that expose it. |
:sandbox | Emits --sandbox <value> for string or true values. |
:approve_mcps | Emits --approve-mcps. |
:worktree | Emits --worktree or --worktree <value>. |
:worktree_base | Emits --worktree-base <path>. |
:skip_worktree_setup | Emits --skip-worktree-setup. |
:plugin_dirs | Repeated --plugin-dir <path>. |
:headers | Repeated -H <header>. |
Permission Mode vs Mode
:ask is a Cursor mode, not a permission mode:
CursorCliSdk.Options.new!(mode: :ask, permission_mode: :default)Bypass is a permission posture:
CursorCliSdk.Options.new!(permission_mode: :bypass)Governed Fields
governed_authority switches the SDK into governed launch mode. In that mode
caller-owned launch placement is rejected:
:api_key:cli_command:cwd:env- non-empty
:execution_surface
See Governed Launch.