cyberine
Providers

Cursor Agent CLI (headless)

  • Kind: headless coding agent (subprocess)
  • Official docs: https://cursor.com/docs/cli/overview · https://cursor.com/docs/cli/reference/authentication · https://cursor.com/install
  • Cyberine adapter: CliAgentAdapter via makeCursorAgentAdapter (build worker cursor-agent)
  • Researched/verified: 2026-09-18 (task kryzh) — confidence medium: the CLI invocation and auth mechanisms are measured against the codebase's existing adapter and probe (src/adapters/CliAgentAdapter.ts, src/core/cliAvailability.ts); the billing facts below are sourced from Cursor's own docs (retrieval dates noted per fact) rather than a live spend test on this machine.

Cyberine invocation

agent -p --force --workspace <task.cwd> --output-format stream-json "<prompt>"

Binary is agent (the cursor-agent name is a back-compat alias). --force is mandatory for the CLI to actually apply file edits rather than only propose them; -p is the non-interactive/headless flag; --workspace pins the repo root. Output is stream-json, parsed with the same parseClaudeStreamJson helper used for Claude Code and other Claude-Code-shaped CLIs — the result event mirrors Claude Code's shape but carries no usage/cost fields (subscription model, no per-call token accounting exposed). There is no per-invocation --model flag; the account's configured model is inherited.

Auth (2 methods)

Source: https://cursor.com/docs/cli/reference/authentication (retrieved 2026-09-18).

  1. Browser login — cursor-agent login (or agent login) opens a browser flow and authenticates against your Cursor account; NO_OPEN_BROWSER=1 prints the URL instead of opening one. Credentials are stored locally. Not for headless/CI use.
  2. API key — CURSOR_API_KEY env var (or --api-key), generated from the Cursor Dashboard -> API Keys, or a Cursor Enterprise service-account key. This is the documented, recommended path for CI/CD, cron jobs and other non-interactive environments. Cyberine's checkCursorAgent() (src/core/cliAvailability.ts) checks CURSOR_API_KEY first, falling back to a ~/.cursor/auth.json file or any file under ~/.cursor/ as a coarser signal of a stored browser-login session.

Billing (researched 2026-09-18, task kryzh)

Sources: https://cursor.com/docs/account/enterprise/service-accounts and https://cursor.com/docs/account/pricing (both retrieved 2026-09-18); corroborated by the adapter's own pre-existing comment in src/adapters/CliAgentAdapter.ts ("Cursor is a PAID SUBSCRIPTION. The agent CLI draws from the SAME credit pool as the IDE — there is no separate lane").

  • Both auth methods draw from the same plan-tied usage pool, never a separate metered API account. The service-accounts doc states plainly: "Service accounts consume usage from your team's usage pool, just like human users." A personal CURSOR_API_KEY (from the Dashboard, not a service account) likewise bills against that same user's own Cursor plan usage pool — there is no alternate raw pay-per-token billing identity a bare API key can attach to. A service-account key bills the team pool that owns it; a personal-user key bills that user's own plan.
  • Every plan is usage-based since mid-2025: each plan (Hobby/free, Pro, Pro+, Ultra, Teams, Enterprise) includes a fixed monthly usage allotment across two pools (Cursor Models and Other Models). Exhausting the included allotment does not stop the CLI — the account can add on-demand usage, billed "at the same API rates" as pay-as-you-go, still against the same account/team, not a separate credential.
  • There is no observed "credits" (metered, pay-per-call, unbounded) billing class for cursor-agent distinct from the account's own plan — whichever credential authenticates, the class is the account's subscription/plan pool (base allotment plus optional on-demand overage tied to that same account).

resolveBillingClass (src/core/billingClass.ts) therefore classifies cursor-agent as subscription whenever either credential is present — CURSOR_API_KEY or a ~/.cursor/ session file — since neither mechanism draws a separate metered pool; only the account/team plan pays. With neither credential present, billing cannot be proven and falls back to credits with a warning, matching every other worker profile with no evidence.

Gotchas

  • No per-invocation --model flag — the account's Cursor-configured default model is used; fan-out model-vs-model comparisons are not possible through this adapter.
  • Heavy automation burns the account's shared pool fast — the CLI and the IDE compete for the same included usage and on-demand budget; a heavy fleet run can visibly dent a human operator's own Cursor usage for the month.
  • ~/.cursor/auth.json absence is not proof of no session — the probe also treats any non-empty ~/.cursor/ directory as a coarse "logged in" signal, so a stale or partial directory can read as logged-in when the stored session is actually expired; only a real dispatch proves the credential still authenticates.
  • Service-account vs personal-key billing differs only in WHICH pool is charged (team vs individual), never in the billing CLASS — both are still subscription-class usage, never raw per-token credits.

Sources

On this page

Cyberine invocationAuth (2 methods)Billing (researched 2026-09-18, task kryzh)GotchasSources