#cursor#cli#ci#output-format#automation

Cursor CLI Output Formats and CI Integration

4 min read

The previous post 10-headless-scripts used -p --force to change files from scripts. This one is about output format: for the same Agent run you can choose “final text only,” “full structured JSON,” or “streaming JSON as it runs”—for CI you parse results, measure time, or show progress using these three formats.

Three output formats

Format Flag Best for
text Default, or --output-format text Human reading, final answer only, writing to a file
json --output-format json Script parsing, CI pass/fail, extracting fields
stream-json --output-format stream-json Live progress, tool-call tracking, long-run monitoring

text: Clean final answer

cursor agent -p "What is the entry point of this repo?"

Without --output-format you get text: output is only the final reply, no tool calls or intermediate steps—good for pasting into docs or as a short description.

In CI, to write the Agent’s conclusion to a file:

cursor agent -p "Generate release notes for this version from CHANGELOG" > release_notes.txt

json: For scripts and CI

cursor agent -p --output-format json "Analyze src/ dependencies and return JSON: { \"entry\": \"...\", \"deps\": [...] }"

Output is structured JSON, possibly with result, duration_ms, or fields you asked for in the prompt.
In CI you can:

  • Use jq to get fields, check for empty, or look for keywords
  • Use exit code and content to decide job pass/fail

Conceptual example:

cursor agent -p --output-format json "Do a short code review; return {\"ok\": true/false, \"summary\": \"...\"}" | jq -r '.result'
# Then use .ok or .summary for next steps or to fail the build

Exact fields depend on Cursor’s docs; the point here is “json is for programmatic parsing.”

stream-json: Live progress and tool tracking

cursor agent -p --output-format stream-json --stream-partial-output "Analyze project and write analysis.txt"
  • Each line is a JSON event (e.g. system, assistant, tool_call, result)
  • --stream-partial-output sends assistant text as incremental deltas, so you can show “live character count” or “progress %”
  • Parse tool_call started/completed to see which file the Agent is reading/writing and how long it took

Good for: long runs, showing “processing file N” in CI logs or a UI, or counting tool calls and duration.

CI integration tips

Need Suggestion
Only care “did it finish and what’s the conclusion” text + redirect to file or variable; check exit code
Pass/fail based on content json + jq parsing
Live log or progress stream-json + parse line by line by type/subtype
Agent should edit files Add --force (see 10-headless-scripts)
Running in CI Set CURSOR_API_KEY; use --model to pin model if needed

Handling failures

  • When the Agent run fails, the CLI typically returns a non-zero exit code
  • In scripts use if [ $? -ne 0 ]; then exit 1; fi or set -e so CI fails correctly
  • With json, you can also check for an error field or your custom ok: false for extra safety

Summary

  • text: Default, human-readable, minimal output; good for writing to a file or as description
  • json: Structured for jq or scripts; good for CI decisions and extraction
  • stream-json + --stream-partial-output: Live event stream; good for progress and tool tracking
  • In CI: set CURSOR_API_KEY, respect exit code, and parse JSON for pass/fail when needed

Next: 12-sessions-cloud — Session resume with --resume and cloud execution with -c.