Auto Flow MCP and CLI Agent Guide

Current status

Beta NPM install After the beta package is published, install the CLI and MCP server with npm install -g @autoflow-mcp/autoflow@beta. Publishing still requires npm login and explicit release approval.

Source checkout fallback Before the beta is published, use the local checkout commands. Do not publish or ask users to install from NPM until package dry-run, live matrix, and release approval are complete.

What MCP is vs CLI in Auto Flow

MCP

MCP means Model Context Protocol. In Auto Flow, autoflow-mcp exposes guarded local tools so an agent can ask for run status, project binding, reconciliation results, and download plans through its normal tool interface.

MCP is best when the agent supports MCP directly and should call structured tools instead of shelling out for every action.

CLI

The autoflow CLI gives the same control surface from a terminal. It is best for scripts, one-off diagnostics, CI-like verification, or agents that can run shell commands but do not have MCP configured.

CLI output should be requested as JSON for automation, especially for status, reconcile, run, and artifact planning commands.

Shared runtime Both surfaces depend on the browser extension, the local native bridge, a paired client, an open Flow project, and a signed-in Auto Flow/Flow session. They are not standalone generators.

Setup

Prerequisites

Chrome extension installed from the local dist folder or a future release build.
Local native bridge installed and enabled for the mounted extension id.
CLI or MCP client paired with the extension using a pairing token.
Flow project open in the same Chrome profile as the extension.
Signed-in Auto Flow/Flow session with access to the target project.
For video runs, Flow settings Return silent videos turned on.
For reference runs, required images attached through the Agent plus button and Add to Prompt.

Beta NPM install

Install the beta package globally after release approval.
Install or doctor the native host for the mounted extension id.
Pair the CLI or MCP client with Auto Flow.
Run read-only status before any command that can submit or spend credits.

npm install -g @autoflow-mcp/autoflow@beta
autoflow native install-host --extension-id <extension-id> --doctor
autoflow native install-host --extension-id <extension-id>
autoflow pair
autoflow status --json

Publishing still requires npm login and explicit release approval. Run npm pack --dry-run before publishing a beta.

Source checkout fallback

Open the repository checkout that contains the extension source.
Install dependencies and build the extension.
Load or reload the built dist folder in Chrome.
Install the native host for the current extension id.
Pair the CLI or MCP client with Auto Flow.
Run read-only status before any command that can submit or spend credits.

npm install
npm run build
npm run agent:install-native-host -- --extension-id <extension-id>
npm run autoflow -- pair
npm run autoflow -- status --json

Command examples below use the installed binary form, such as autoflow status --json. From source, run the same subcommands through npm run autoflow -- ... or a local link.

Command reference

Command	Use it for	Safety expectation
`autoflow status --json`	Check bridge connection, pairing state, active tab, project id, and extension readiness.	Read-only. Run this first.
`autoflow pair`	Pair the local CLI with the extension using a short-lived pairing token.	Requires user-visible pairing approval.
`autoflow native install-host --extension-id <extension-id>`	Install or doctor the Chrome native messaging host after a global NPM install.	Local machine only. Use `--doctor` before writing.
`autoflow agent reconcile --project current --json`	Compare expected rows, images, videos, and metadata against the current Flow project.	Read-only. Blocks if the current project cannot be identified.
`autoflow agent run --input ./packet.txt --project-id <project-id> --tab-id <tab-id> --json`	Start a guarded agent run against an explicitly named Flow project and Chrome tab.	Must target a project and tab. Must report planned credit-spending work before submit.
`autoflow agent artifacts download-plan --reconciled ./reconcile.json --run-name <run-id> --json`	Build a stable plan for image/video downloads, filenames, manifests, and QA artifacts.	Read-only planning. Execute downloads only after the plan is reviewed.
`autoflow-mcp`	Start the local MCP server for agents that support MCP tools.	Local process only. It should expose the same guarded status, reconcile, run, and artifact tools.

Safety model

Explicit project/tab targeting

Write commands must name the Flow project and Chrome tab. If Auto Flow sees no project, multiple candidate projects, or a stale tab binding, it should block instead of guessing.

Pairing token

Pairing is the local trust step between the extension and the CLI or MCP client. A client that is not paired can inspect nothing sensitive and cannot submit work.

Local-only bridge

The local-only bridge is for the local machine and the mounted extension id. Do not expose bridge sockets, pairing tokens, or Flow session data to remote processes.

no blind credit spends

Agents should start read-only. Any submit or retry command must show the target project, target rows, and intended work before generation starts.

Troubleshooting

Symptom	Likely cause	Fix
Bridge disconnected	The native host is not installed, points at the wrong checkout, or is not allowed for the mounted extension id.	Rebuild, reload the extension, rerun native-host install for the current extension id, then run `autoflow status --json`.
Not paired	The CLI or MCP client has no valid pairing token.	Run `autoflow pair` and approve the pairing from the extension UI.
Wrong tab/project	The active Chrome tab is not the intended Flow project, or several Flow projects are open.	Use explicit `--project-id` and `--tab-id`. Close unrelated Flow tabs if ownership is ambiguous.
Download is HTML or a tiny file	Flow returned an error page, auth expired, or media was not actually ready.	Treat it as a hard failure. Recheck auth, reconcile project outputs, and regenerate the download plan before retrying downloads.
Video cards fail with audio errors	`Return silent videos` was off before the Agent video run.	Turn it on in Flow settings, retry the affected row, reconcile again, then download only valid MP4 files.
Reference prompt ignores images	The prompt typed filenames, handles, or media ids but did not attach the actual assets.	Use the Agent plus button, select the images, click `Add to Prompt`, confirm visible prompt asset chips, then submit.
NPM install does not work	The beta package is not published yet, NPM auth is missing, or the user lacks org/package access.	Use the source checkout fallback until `npm whoami` is authenticated and the beta package is published.

Recommended agent prompt

Paste this into Claude, Codex, or another local coding agent before it touches an Auto Flow run.

You are controlling Auto Flow through its local CLI/MCP bridge.

Start read-only:
1. Run autoflow status --json.
2. Confirm the extension is connected, the client is paired, a Flow project is open, and the user is signed in.
3. Run autoflow agent reconcile --project current --json.
4. Build a download plan with autoflow agent artifacts download-plan --reconciled ./reconcile.json --run-name <run-id> --json.

Do not submit, retry, or spend credits until you have explicit project/tab targeting.
For write commands, use autoflow agent run with --project-id and --tab-id.
For video runs, confirm Flow settings Return silent videos is on before submit.
For reference-driven rows, attach the real image assets through the Agent plus button and Add to Prompt; typed filenames, handles, or media ids alone are not enough.
If the bridge is disconnected, pairing is missing, the wrong tab is active, or project ownership is ambiguous, stop and report BLOCKED.
Never guess the Flow project. Never download HTML/tiny files as successful media. Never hide a credit-spending action inside a read-only step.