Skip to content

options.md

Latest commit

 

History

History
73 lines (58 loc) · 2.26 KB

options.md

File metadata and controls

73 lines (58 loc) · 2.26 KB
Raw

Options

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.