Cursor + OrchStep

Cursor's agent is happy to run commands in your terminal. The trouble is what comes back: a wall of stdout it has to read like a human, guessing whether the deploy worked from the last few lines before the prompt returned. When the output is ambiguous, the agent guesses — and that's where the wheels come off.

OrchStep fixes the output side of that loop. Your procedures live as workflows, and any of them can hand back structured JSON instead of scrollback — so when Cursor drives OrchStep, it's reading a result object, not interpreting log soup.

The workflow Cursor drives

Say you spin up a preview environment per pull request. That's a procedure, not a one-off, so it's a workflow:

name: preview-env
defaults:
  pr: "1287"
  target: preview

tasks:
  # `orchstep run up --var pr=1287 --output json`
  up:
    steps:
      - name: build
        func: shell
        do: echo "building preview for PR-{{ vars.pr }}"
      - name: deploy
        func: shell
        do: echo "deploying PR-{{ vars.pr }} to {{ vars.target }}"
      - name: report
        func: shell
        do: echo "preview ready for PR-{{ vars.pr }}"

Tell Cursor to drive it

You don't paste YAML into Cursor's chat. You tell it which command to run, and the key flag is --output json:

orchstep run up --var pr=1287 --output json

Instead of three lines of echo output, the agent gets back a result object — the task name, overall status, and a list of steps with their status and outputs. Cursor reads status: "success" from a field, not from a heuristic on the last log line. If a step fails, it sees which step and why, and can act on it instead of re-running the whole thing to find out.

That's the contract that makes agent-driven automation reliable: the agent passes the inputs it decided on (--var pr=1287), and gets a machine-readable answer it can branch on.

Capture first, drive later

Where do these workflows come from? Often, from Cursor itself. When the agent works through a multi-step task interactively — set up the preview, fix the build, get it green — that session is the procedure. The orchstep-capture skill turns it into a clean orchstep.yml with the hardcoded values lifted into variables. The next PR doesn't get re-derived; it gets orchstep run up --var pr=1342.

What changes in the loop

OrchStep doesn't replace what Cursor is good at — writing and editing code. It gives the agent a clean handle on the procedures around the code, so driving them is a tool call with a structured answer instead of a terminal it has to squint at.

Where to go next

• LLM Agent Integration — running workflows with --output json
• Skills — capturing a Cursor session into a workflow
• Variables & Outputs — --var and the scoping model
• Previewing with Dry Run — see the plan before it runs

Already running terminal commands from Cursor? Capture the next multi-step task and drive it with --output json instead.