Running workflows from scripts

Start a saved workflow from a terminal, a script or another program on this computer, read its result, and answer its questions — the local API and the cerevisor command.

What the local API is

The local API lets a script, a terminal command or another program on this computer ask Cerevisor to run one of your saved workflows, check how it is going, answer the questions it asks, and read what it produced. It can also add items to a workflow's Factory mode queue. Programs that understand MCP (such as Claude Code or Cursor) can use it directly, and Cerevisor also has its own command, cerevisor run, for scripts. It only listens on this computer, it is off until you turn it on, and a program needs a secret token to use it. It is part of Founding membership and is included in the 7-day trial; see Plans & licensing.

Turning it on

Open Settings → Automation and find Local API. Tick Let scripts and other programs run workflows.

Once it is on, the section shows:

  • The address Cerevisor is listening on, for example http://127.0.0.1:48633/mcp. If that port is already taken by something else when Cerevisor starts, it picks a free one and shows that instead.
  • Copy MCP config — copies a block you paste into another program's MCP settings. It looks like this:

json { "mcpServers": { "cerevisor": { "type": "http", "url": "http://127.0.0.1:48633/mcp", "headers": { "Authorization": "Bearer <token>" } } } }

The first copy each time you open this section puts a new token in the block, and the note under the button says "Copied with a new token. Programs set up earlier need this new config." Copying again while the section is still open reuses that same token. A program set up with an older copy stops working until you give it the new config, so if you connect several programs, copy once and paste the same block into each. - Rotate token — makes a new token straight away. Every program using the old one is refused from that moment on.

While the local API is on, Cerevisor also writes its address and current token to a small file, .cerevisor/local-api/endpoint.json in your home folder, readable only by you. Your own scripts can read it instead of storing the token themselves. The file disappears when the local API stops.

If your plan does not include the local API, the section shows a short card explaining which plan it belongs to instead of the switch, and no address or Copy and Rotate buttons. If the local API was already on, a switch to turn it off stays.

Running from a terminal

The cerevisor command is the Cerevisor program itself, given a word telling it what to do. On Windows that is:

"C:\Program Files\Cerevisor\Cerevisor.exe" run ...

On a Mac it is /Applications/Cerevisor.app/Contents/MacOS/Cerevisor run .... The examples below write cerevisor for short.

Start a workflow and wait for it to finish, writing the result to a file:

cerevisor run "D:\Projects\Reports\reports.cerevisor-world" --workflow weekly-summary --message "Cover last week only" --set customer=ACME --file "D:\Projects\Reports\notes.pdf" --wait --out result.json
  • --workflow <id> picks one workflow in a world file. Without it, the world's active workflow runs (or the first one). A file that holds a single workflow runs that one; naming a different id is refused, and the message tells you the name and id of the workflow the file does hold.
  • --message <text> is what the first agent is asked. --set key=value (repeatable) adds named values under an Inputs heading after your message.
  • --file <path> (repeatable) attaches a file, the same as dropping it onto the workflow's input. A file that does not exist stops the request with "This file was not found: …".
  • --wait keeps the command open until the run ends. --out <file> writes the final result there.

Without --wait, the command prints the run's id. If Cerevisor was already open, it returns as soon as the run has started. If the command had to start Cerevisor itself (see below), it stays until the run ends, because that background Cerevisor is the one running it.

Check on a run you started earlier:

cerevisor status 3f2a9c1e-5b7d-4e21-9a0c-2d8e6f1b4a77

Answer a question a run is waiting on (see below):

cerevisor answer 8c41d2e0-0f6a-4b3e-a9d7-51c3e8b2f6a0 approve

Paths can be written relative to the folder you are in; the command turns them into full paths before it asks Cerevisor.

If Cerevisor is already open with the local API on, the command simply asks it. If Cerevisor is not open, the command starts it in the background with no window, runs the workflow, and closes it again once the run is finished. This works whether or not the Settings switch is on, because you are the person typing the command — but it still needs a plan that includes the local API. That background Cerevisor stays alive until its run finishes, with or without --wait, so the command you typed does not return before then, and a cerevisor status or cerevisor answer from another terminal still reaches it. If you open Cerevisor normally while a background run is going, its window appears and it becomes an ordinary Cerevisor window you close yourself.

If Cerevisor is open but the local API is off, the command stops and tells you so (exit code 4). Turn it on in Settings → Automation and try again.

Scripts on Windows

Windows does not wait for Cerevisor to finish when you start it from PowerShell or the Command Prompt, so a script that just calls it will not see its exit code. Ask Windows to wait:

PowerShell

$p = Start-Process -FilePath "C:\Program Files\Cerevisor\Cerevisor.exe" `
  -ArgumentList 'run', '"D:\Projects\Reports\reports.cerevisor-world"', '--wait', '--out', '"D:\Projects\Reports\result.json"' `
  -Wait -PassThru -NoNewWindow -RedirectStandardOutput "D:\Projects\Reports\cerevisor-output.txt"
if ($p.ExitCode -eq 0) {
  $result = Get-Content "D:\Projects\Reports\result.json" | ConvertFrom-Json
  $result.outputs
} else {
  Write-Host "Cerevisor exited with $($p.ExitCode)"
  Get-Content "D:\Projects\Reports\cerevisor-output.txt"
}

-RedirectStandardOutput is only needed if you want the lines the command prints (the run id, any questions, the final status).

Command Prompt

start "" /wait "C:\Program Files\Cerevisor\Cerevisor.exe" run "D:\Projects\Reports\reports.cerevisor-world" --wait --out result.json
echo %ERRORLEVEL%

What a run returns

--out writes, and cerevisor status prints, the same set of fields:

Field What it is
runId The id you use with status and to match questions to runs.
sessionId The same id, under the name Cerevisor uses for it internally.
ledgerRunId The id of the run's saved record, once it has one.
status running, waiting (a question is waiting for an answer), completed, failed or stopped.
costUsd What the run has cost so far, in US dollars.
overview The same summary the run window's Overview tab shows: counts, and one entry per agent.
outputs Full paths of every file the run wrote.
openPrompts The questions still waiting for an answer.
error A plain sentence when the run failed or was refused, otherwise empty.
recordDir The folder holding the run's full record on disk.

A run is only known to the Cerevisor that started it. Asking about any other run is an error, not a status: status prints "This run was not started by the Cerevisor that is open now." and exits with code 2. That is also what you get after Cerevisor closes — the record in recordDir is still there.

When a workflow asks you something

A workflow started this way behaves like one you started with the Run button: its own saved approval setting decides what needs your say. When an agent asks for permission, asks a question, needs an approval to continue, proposes a plan or asks for help, the run waits for you, and --wait prints a line like this:

prompt 8c41d2e0-0f6a-4b3e-a9d7-51c3e8b2f6a0 [permission] Researcher: Researcher needs permission — web_fetch is a moderate action.
  answer with: cerevisor answer 8c41d2e0-0f6a-4b3e-a9d7-51c3e8b2f6a0 approve|deny

Answer it from any terminal:

The run is asking for Answer with
A permission approve or deny
An approval to continue approve or reject
A plan approve or reject
A question or a help request The text of your answer, e.g. cerevisor answer <id> Use the March figures

Some things to know:

  • An answer covers that one question only. It never turns into "allow this for the rest of the run".
  • Only questions from runs started through the local API can be answered this way, and a help request only when it is addressed to you and still open.
  • Every answer is written into the run's record, saying it came from the local API.
  • If Cerevisor is open and running the workflow, the question also appears in the app, and on your paired phone, and you can answer it there instead. If Cerevisor is running in the background with no window, answer with the command.

Adding a Factory mode item

A script, a CI job or another program can add a development item to a workflow's Factory mode queue. It only adds the item: the factory is started by a person, in the app, so nothing a program adds runs until you press Start.

From a terminal:

cerevisor factory add "D:\Projects\shop\shop.cerevisor-world" --request "The checkout page shows the total twice" --title "Checkout total" --source-ref ci-1234
  • --request <text> is what should be built. It is required and cannot be empty.
  • --title <text> is optional; without it the first line of the request is the title.
  • --workflow <id> picks one workflow in a world file, exactly as for run.
  • --source <text> says where the item came from (one line, up to 64 characters). Without it, the item's source column reads local-api.
  • --source-ref <key> is a stable key for the thing that caused the item, such as a build or issue number (one line, up to 200 characters). The same key is not queued twice while its item is still waiting, running, needs you or failed.

The command prints queued <id> for a new item, or already queued <id> with the id of the item already in the list for that key. Paths can be relative, as for run. If Cerevisor is not open, the command starts it in the background, queues the item and closes it again.

Programs that speak MCP use the add_factory_item tool. Its inputs are path (the workflow file), request, and the optional workflowId, title, source and sourceRef, with the same meaning and limits as above. It answers { itemId, duplicate }, where duplicate is true when an unfinished item with that sourceRef was already queued and itemId is that item's id.

Some things to know:

  • The workflow must have its Factory mode switched on ("Switch on Factory mode for this workflow first."), and your plan must include both the local API and Factory mode.
  • The workflow file goes through the same checks as run: it must be a Cerevisor workflow on this computer, not on a network share.
  • Pictures cannot be added this way yet. Add them to the item in the factory panel.
  • The agents read the request exactly as if you had typed it into the panel, so only let programs you trust add items.

The exit codes are the same as for status: 0 when the item was queued (or was already queued), 2 when the request was refused, with the reason printed, 3 when your plan does not include the local API or Factory mode, 4 when Cerevisor is open but the local API is off, and 5 when Cerevisor could not be reached.

Exit codes

Code Meaning
0 The run completed (with --wait), the run started (without --wait), the answer was accepted, the status was printed, or the factory item was queued (or already queued).
1 The run failed or was stopped.
2 Something was wrong with the request: a mistyped command, a file that is not a Cerevisor workflow, a shared workflow package (open it in Cerevisor first), a file that was not found or is on a network share, a workflow id the file does not hold, a workflow that is already running, a workflow whose access grew since you last ran it in the app, no model provider set up, an unknown run, a question that is not open, or a factory item for a workflow whose Factory mode is off, with an empty request, or with a source that is too long. The reason is printed.
3 Your plan does not include the local API (or, for factory add, Factory mode).
4 Cerevisor is open but the local API is off.
5 Cerevisor could not be reached: it is open but did not answer in time or did not accept the token, or the background Cerevisor could not start listening. Try again in a moment; if the token was refused, rotate it in Settings.

Limits

  • One computer. The local API listens only on this computer. Nothing is reachable from your network or the internet, and nothing leaves the machine that a normal run would not send.
  • One run of a workflow at a time. Asking for a second run of a workflow that is still running is refused, whether that run was started from the app or from a script; wait for the first to finish. Different workflows can run at the same time.
  • Cerevisor has to be running — either the app with the local API switched on, or the background Cerevisor the command starts for you.
  • The same permissions you have, never more. A script cannot change a workflow's approval setting or give an agent extra access. Everything runs with the workflow's own saved settings, exactly as if you had pressed Run.
  • New access is confirmed in the app first. If a workflow has been given more access since you last ran it in the app (for example, an agent may now run commands or reach the web), a script's request to run it is refused with a sentence saying so. Run it once from the app, where you see and confirm the new access; after that scripts can run it again.
  • Files on this computer only. A workflow file or attached file on a network share is refused. Copy it to this computer first.
  • What is on disk is what runs. A world file is read as it was last saved; unsaved changes in an open window are not included.

Back to docs