Skip to main content
cursor-agent (also exposed as agent). Curl-installer from cursor.com.

​
Install

curl -fsSL https://cursor.com/install -o /tmp/cursor-install.sh && bash /tmp/cursor-install.sh -y
Pre-installed via Crewship’s baseCLIPostCreate provisioning.

​
Auth

Env varNotes
CURSOR_API_KEY (cur_*)Requires Cursor subscription with API access enabled
API access is a paid-plan feature — there’s no free BYOK. If Cursor returns 401 after credential test, verify the API toggle at cursor.com/account.

​
Models

Cursor multiplexes: cursor-agent -m accepts underlying provider model IDs plus their in-house Composer:
API stringTier
composerfrontier — Cursor’s in-house, Crewship default
claude-opus-4-7 / claude-sonnet-4-6 / claude-haiku-4-5Anthropic via Cursor
gpt-5.5 / gpt-5.4 / gpt-5.3-codexOpenAI via Cursor
gemini-3.1-pro-preview / gemini-2.5-proGoogle via Cursor
grok-4.1-fastxAI via Cursor

​
Command shape

cursor-agent -p --output-format stream-json --stream-partial-output \
             --force [--approve-mcps] [-m <model>] -- <message>
  • -p — print (non-interactive) mode
  • --output-format stream-json — JSONL events
  • --stream-partial-output — token-level deltas
  • --force — REQUIRED in headless mode; without it write tools hang on permission prompts
  • --approve-mcps — added when MCP source is configured (otherwise MCP servers are listed but never invoked, see forum #143045)

​
MCP

Configured at /output/<slug>/.cursor/mcp.json: 
{
  "mcpServers": {
    "linear": {
      "url": "https://mcp.linear.app/sse",
      "headers": {"Authorization": "Bearer ${env:LINEAR_TOKEN}"}
    },
    "fs": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/work"],
      "env": {"FOO": "${env:FOO}"}
    }
  }
}
Cursor-specific env-var syntax: ${env:VAR} (NOT ${VAR}). Crewship’s writer translates the standard ${VAR} form on write.

​
Memory

Cursor reads .cursor/rules/, AGENTS.md, AND CLAUDE.md (merged). Crewship writes the full canonical set including .cursor/rules/crewship.md (Cursor priority path). On turn 1 the orchestrator also prepends the preamble inline with [SYSTEM]/[USER] delimiters because Cursor’s headless mode has no --system-prompt flag and file-discovery doesn’t fire until the second invocation.

​
Output stream

JSONL per cursor.com/docs/cli/reference/output-format:
EventDiscriminators
systemsubtype: init — apiKeySource, cwd, session_id, model, permissionMode
userechoed user message (Crewship suppresses)
assistantmessage.content[].text — multiple events form one message under --stream-partial-output
tool_callsubtype: started/completed, call_id (lifted to tool_use_id for cross-CLI correlation)
resultduration_ms, is_error, request_id, usage (token counts, since Feb 2026)

​
Troubleshooting

cur_… key but 401 — Cursor subscription doesn’t have API access toggle on. Visit cursor.com/account. Write tool hangs forever — --force flag missing from adapter command (regression check cli_adapter_versions_test.go). MCP servers listed but never invoke — --approve-mcps missing when MCP configured. The adapter only adds it when req.MCPServers, req.CrewMCPConfigJSON, or req.AgentMCPConfigJSON is non-empty. tool_call:completed events lost on reconnect — known upstream regression (forum #157593). model_call_id + timestamp_ms are captured by parser to enable chat-bridge dedup.