Getting Started

Copy Markdown View Source

CursorCliSdk runs the Cursor Agent CLI (agent) from Elixir. The SDK expects the CLI to be installed and authenticated before live commands run.

Prerequisites

  • Elixir 1.19 or later
  • Cursor Agent CLI available as agent on PATH, or an explicit cli_command
  • Cursor authentication through CLI login or a caller-provided CURSOR_API_KEY

Install

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

Stream Events

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

CursorCliSdk.execute("Reply with exactly: OK", options)
|> Enum.each(fn
  %CursorCliSdk.Types.MessageEvent{role: :assistant, content: text} ->
    IO.write(text)

  _event ->
    :ok
end)

execute/2 returns a lazy enumerable. The subprocess is started when the stream is enumerated and is closed when the stream finishes.

One-Shot Text

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

Use run/2 when only final assistant text matters. Use execute/2 when tool events, init metadata, thinking text, usage, stderr diagnostics, or partial assistant deltas matter.

Workspace

options =
  CursorCliSdk.Options.new!(
    cwd: "/workspace/app",
    permission_mode: :plan
  )

cwd is the only workspace option. It is used as the process cwd and mapped to Cursor's --workspace <cwd> flag. There is no :workspace option.

Real Examples

Run the checked examples under the repository root:

mix run examples/simple_stream.exs
mix run examples/promotion_path/sdk_direct_cursor.exs

For live credentials in this workspace, use the shared wrapper:

~/scripts/with_bash_secrets mix run examples/simple_stream.exs
~/scripts/with_bash_secrets bash examples/run_all.sh

The HexDocs Examples page is sourced from examples/README.md.