hekma
Menu

docs · adapters

Cursor CLI#

Unreleased: after 0.11.0. This page is on Hekma's main branch and ships in the next release; Hekma 0.11.0 does not have it.

Cursor's CLI exposes an ACP mode through its agent binary's acp subcommand, so it runs under Hekma's built-in acp kind. Upstream documents the mode as a hidden/advanced command; this entry is characterized from upstream documentation and has not been run-verified here.

Register#

hekma agent config set my-cursor acp.command "agent"
hekma agent config set my-cursor acp.args "acp"
hekma agent register my-cursor --kind acp
hekma agent start my-cursor

The exec word agent is generic and collision-prone — any other agent binary earlier on PATH would be launched instead. Confirm what resolves (command -v agent) before start, or set acp.command to the CLI's absolute path on your machine.

Honesty table#

The pause and interaction levels are the acp kind's own capability declaration — identical for every ACP agent and proven by the conformance kit against a scripted stand-in; they are not per-agent promises. The metering rows are characterized from upstream documentation, not run-verified here.

SurfaceValueEvidence class
pauseguaranteed (Linux), guaranteed (macOS), best-effort (Windows)contract-validated
interactionguaranteed (all OSes)contract-validated
Metering sourceself-reportedcontract-validated
Billing-grade tokens— — no billing-grade usage in the ledger — tiers attempted: observed: not-configured; sentinel: no-lines-seen; no context usage reported (ACP usage_update is context-grain, never billed). The backend is subscription-backed and no base-URL override is documented upstreamcharacterized
Context usagean agent-reported usage_update would surface under acp_context_usage — context-grain, never billed; whether this agent reports one is unverified herecharacterized

Validation status. Upstream: experimental (documented as a hidden/advanced command; it can change without a deprecation cycle). Evidence: characterized — upstream documentation, dated 2026-10-23, NOT run-verified here. Nothing pinned.

PATH requirement#

The launch command is the bare word agent, resolved through the PATH of the environment hekma runs in. Hekma does not bundle, install or pin the Cursor CLI binary — install it yourself, keep it on the PATH, or give an absolute path (see the collision warning above). A start whose agent cannot resolve fails with the engine's launch-failure diagnostic naming the executable.

Re-validation duty#

A hidden/advanced upstream surface can change in any release; every characterization here is a snapshot by design. Re-validate against the version you install before relying on agent-specific behaviour — Re-validation states the full duty, including the contract duties that no automated kit can prove.