Skip to content

authentication.md

Latest commit

 

History

History
68 lines (49 loc) · 1.68 KB

authentication.md

File metadata and controls

68 lines (49 loc) · 1.68 KB
Raw

Authentication

The SDK supports two authentication postures:

  • standalone: application code supplies env materialization explicitly
  • governed: a CliSubprocessCore.GovernedAuthority supplies command, cwd, env, and credential materialization

The library does not call System.get_env/1 from lib/**. Environment lookup belongs at the application boundary.

Standalone

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

api_key becomes CURSOR_API_KEY in the child process environment. It is never placed in argv.

You may also provide an explicit env map:

CursorCliSdk.Options.new!(
  env: %{"CURSOR_API_KEY" => System.fetch_env!("CURSOR_API_KEY")}
)

CLI Login

If the local Cursor CLI is already authenticated, omit api_key and env. The child process inherits the surrounding process environment according to the underlying command transport.

Governed

Governed launch rejects caller-owned auth and placement fields:

authority =
  CliSubprocessCore.GovernedAuthority.new!(
    command: "agent",
    cwd: "/workspace/app",
    env: %{"CURSOR_API_KEY" => token},
    clear_env?: true
  )

options = CursorCliSdk.Options.new!(governed_authority: authority)

When governed_authority is present, do not also set api_key, env, cwd, cli_command, or execution_surface.

Exit Codes

CursorCliSdk.Error.from_exit_code/1 maps known Cursor CLI exits:

Exit Kind
41 :auth_error
42 :input_error
52 :config_error
130 :user_cancelled

Other non-zero exits become :command_failed or runtime-specific failures.