CLI

The cereyan command. Every subcommand accepts the global options first, for example cereyan --home /tmp/h run pipeline.py:etl.

cereyan [-h] [--home HOME] [--token CLIENT_TOKEN] {run,serve,backfill,mcp,runs} ...

Global options

Option	Meaning
--home HOME	runtime home directory (default: $CEREYAN_HOME or ~/.cereyan).
--token CLIENT_TOKEN	API token for a running server (also CEREYAN_TOKEN).

cereyan run

cereyan run [-h] [--param NAME=VALUE] [--quiet] target

Argument	Meaning
target	module_or_file:flow, e.g. pipeline.py:etl.

Option	Meaning
--param, -p NAME=VALUE	set a flow parameter; repeatable, values are coerced from the flow's type hints.
--quiet, -q	do not echo run logs.

cereyan serve

cereyan serve [-h] [--host HOST] [--port PORT] [--max-engines MAX_ENGINES] [--engine-max-runs ENGINE_MAX_RUNS] [--no-open] [--crash-retries CRASH_RETRIES] [--token TOKEN] [--socket SOCKET] [dir]

Argument	Meaning
dir (optional)	directory to import flows from (default: current).

Option	Meaning
--host HOST	bind address (also CEREYAN_HOST or [server] host; default 127.0.0.1).
--port PORT	TCP port (also CEREYAN_PORT or [server] port; default 4200, 0 picks a free port).
--max-engines MAX_ENGINES	size of the warm engine pool (also [server] max_engines).
--engine-max-runs ENGINE_MAX_RUNS	recycle an engine after this many runs (also [server] engine_max_runs).
--no-open	do not open the browser.
--crash-retries CRASH_RETRIES	default crash retry limit (flow decorators override).
--token TOKEN	require this API token (also CEREYAN_TOKEN or [server] token).
--socket SOCKET	also listen on this Unix socket path (also CEREYAN_SOCKET or [server] socket).

cereyan backfill

cereyan backfill [-h] --param PARAM --start START --end END [--interval INTERVAL] [--concurrency CONCURRENCY] [--reverse] [--extra NAME=VALUE] [--json] flow

Argument	Meaning
flow	flow name, optionally project/flow.

Option	Meaning
--param PARAM	date or datetime parameter name.
--start START	first value of the parameter, a date or datetime.
--end END	last value of the parameter, inclusive.
--interval INTERVAL	seconds or a duration like 1d, 12h (default 1d). Default 1d.
--concurrency CONCURRENCY	how many of the backfill's runs may execute at once. Default 1.
--reverse	create the newest value first.
--extra NAME=VALUE	fixed value for another flow parameter; repeatable.
--json	print the backfill status as JSON.

cereyan mcp

cereyan mcp [-h] [--url URL] [--socket SOCKET]

Option	Meaning
--url URL	server URL (default: from server.json).
--socket SOCKET	Unix socket path of the server.

cereyan runs

cereyan runs [-h] {ls} ...

cereyan runs ls

cereyan runs ls [-h] [--flow FLOW] [--project PROJECT] [--state STATE] [--limit LIMIT] [--json]

Option	Meaning
--flow FLOW	only runs of this flow name.
--project PROJECT	only runs of flows in this project.
--state STATE	state type, e.g. Failed.
--limit LIMIT	number of runs to show. Default 20.
--json	print the runs as JSON.

Exit codes

Every command exits 0 on success and 3 on an error, printing the reason to standard error. cereyan run also uses 1 and 2 to report the outcome of the run.

Code	Constant	Meaning
0	EXIT_OK	The run completed.
1	EXIT_FAILED	The run failed.
2	EXIT_NOTHING_RAN	Nothing ran: the store was locked and no server took the run.
3	EXIT_SCHEDULING	The flow could not be loaded, a parameter did not coerce, a server was needed but unreachable or required a token, or a backfill argument was invalid.