The photofresco command line
Drive a PhotoFresco window you approve from a terminal or script — connect, open an image, run a saved workflow, export the result and stop, with JSON output and exit codes.
The photofresco command line uses a PhotoFresco window from a terminal, a script, or an agent that can run shell commands but has no MCP client. It works through the same local connector as the MCP server, so the rules are the same. You click Allow in the window, you choose the permissions, and the agent can only reach files in the folders you name.
A typical job: open a photo, run a saved workflow on it, and export the result.
Set it up
An npm package is coming. Until then, run the command line from a clone of the public repository. You don't need to install anything except Node.js 22 or newer and Google Chrome, Microsoft Edge or Chromium 120 or newer (see What you need):
git clone https://github.com/photofresco/photofresco-agent.git ~/photofresco-agent
alias photofresco="node ~/photofresco-agent/src/bin/photofresco.js"
photofresco --helpphotofresco ops and photofresco describe <operation> work even before you connect. They list the editor operations and their parameters.
Connect, run, export, stop
photofresco connect --read ~/Pictures --write ~/Pictures/PhotoFresco
photofresco run warm.workflow.json --open ~/Pictures/beach.png --input amount=0.6 \
--export ~/Pictures/PhotoFresco/beach-warm.png
photofresco stopconnect opens PhotoFresco in its own browser window and prints a connection code:
Connection code: 6388-8654
Check that the PhotoFresco window shows the same code, then click Allow.Check that the window shows the same code, click Allow, then choose the permissions in the Agent permissions dialog. By default the command line asks for Read, Edit and Export. The AI agents guide shows both dialogs. If you haven't answered within the --wait time, connect exits with code 75; run it again to keep waiting.
Later commands reuse the same window and session. run opens the image in a new tab, runs the workflow in the editor, and writes the export only after its checksum (SHA-256) matches. A successful run prints something like:
Workflow "Invert" succeeded: 2/2 steps, 2 edits (run run_…, document doc_…)
Exported …/out/sunset-half.png (png, 2008 bytes, sha256 2129b3c3741e784c…)stop ends the session and closes the window and the connector. disconnect ends only the session and leaves the window open for you.
While the command line is connected, the window shows the same agent bar as any other agent, named "Terminal via CLI" unless you pass --client. Your own edits pause it, and Stop in the window ends it.
Commands
| Command | What it does |
|---|---|
connect | Start the connector if needed, open PhotoFresco and pair (you click Allow) |
status | Connector, window, session, permissions and granted folders |
request-access <list> | Ask for more permissions (read,edit,export,external-write,spend) |
documents | Open documents with their IDs |
attach <document-id> | Work on another open document |
open <file> | Open an image from a granted folder in a new tab |
run <workflow.json> | Run a workflow file, or --action <id> for an action saved in the editor |
export <file> | Export the document as PNG, PSD or .pfd into a granted folder |
exec <op> [params-json] | Run one editor operation |
outcome <request-id> | Get the result of an earlier request after a lost connection |
ops [prefix], describe <op> | Operations this session may run, and their parameters |
disconnect, stop | End the session; stop also closes the window and the connector |
mcp | Run the MCP server instead |
photofresco <command> --help lists each command's options. The main ones:
| Option | Used with | Meaning |
|---|---|---|
--read <folder>, --write <folder> | connect | Folders the session may open from and export into (repeatable) |
--overwrite | connect, run, export | On connect: exports may replace files in --write folders. On run or export: replace this file |
--grant <list> | connect | Permissions to ask for (default read,edit,export) |
--reason <text> | connect | Why, shown in the Permissions dialog |
--client <name> | connect | The name the window shows as "name via CLI" |
--wait <seconds> | connect, request-access | How long to wait for your answer (default 170, at most 180) |
--input name=value, --inputs <file> | run | Workflow inputs |
--consent <step-id> | run | Allow one irreversible step (export, upload, paid AI, tab changes) |
--on-failure stop or rollback | run | Keep the partial result (default) or roll the run's edits back |
--json | all | Print one JSON object on stdout, also on failure |
Exit codes and JSON
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | Unexpected internal error |
| 2 | Bad arguments, an unreadable or unsupported workflow file, or an unknown operation. Nothing ran |
| 3 | No connector or session, the pairing was denied or expired, or the browser or editor is unavailable |
| 4 | A path was refused: not in a granted folder, escapes its folder, already exists, too large or unreadable. Nothing ran |
| 5 | The editor refused or failed the operation or workflow. Nothing was written |
| 6 | Reading the export back failed or its checksum did not match. Nothing was written |
| 7 | Writing the file failed. The target was not replaced |
| 8 | Canceled (Ctrl-C, or Stop in the window). The document keeps the partial result |
| 75 | Still waiting for you in the window; run connect again |
With --json, every command prints one object with ok, command and exit_code. Failures add an error with a code, a message and a hint. Image data is left out unless you pass --include-data, so the output works as a log of what ran.
Stopping and lost connections
- Ctrl-C during
run,exec,openorexportends the whole session, the same as Stop. The editor stops before the next workflow step and keeps what was done so far. Reconnect to inspect it or roll it back. - If the command line disappears (killed, or its terminal closed), the request keeps running in the editor.
photofresco outcome <request-id>returns its result later. - Stop in the window, closing the window, or reloading ends the session.
What it runs
connect starts one background connector process for each data folder. It owns the browser window and the session, and every later command talks to it over a private local socket that only your user account can open. It does not listen on any network port. The process exits on photofresco stop, when you close its window, or after a minute with no window and no command. Privacy is the same as for the MCP server: the window starts with session recording off. See Privacy: what is sent where.
Last updated