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,worker,check,backup,backfill,retry,pause,resume,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] [--at AT] [--in DURATION] [--json] 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.
--at AT	instead of running now, create the run on the running server for this ISO 8601 time (naive means UTC).
--in DURATION	instead of running now, create the run on the running server this long from now: seconds, or 10m, 2h, 1d.
--json	with --at or --in, print the created run as JSON.

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] [--base-path BASE_PATH] [--enable-auth] [--auth-cookie AUTH_COOKIE] [--auth-scope AUTH_SCOPE] [--login-url LOGIN_URL] [--allowed-host HOST] [--allow-unauthenticated] [--mcp-read-only] [--metrics-public] [--public-url PUBLIC_URL] [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, the processors on the Queue page (default 1, at most the CPU count; 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).
--base-path BASE_PATH	serve everything under this URL path, e.g. /cereyan (also CEREYAN_BASE_PATH or [server] base_path; default: the root).
--enable-auth	validate credentials with the registered @app.authenticator (also CEREYAN_ENABLE_AUTH or [server] enable_auth).
--auth-cookie AUTH_COOKIE	cookie the authenticator reads the credential from when there is no bearer header (also CEREYAN_AUTH_COOKIE or [server] auth_cookie).
--auth-scope AUTH_SCOPE	api checks /api/* and /mcp; all also checks the UI and custom routes, and needs --enable-auth (also CEREYAN_AUTH_SCOPE or [server] auth_scope; default api).
--login-url LOGIN_URL	sign-in page linked from 401 responses and the UI (also CEREYAN_LOGIN_URL or [server] login_url).
--allowed-host HOST	also answer to this host name and accept browser pages from it; repeat for more (also CEREYAN_ALLOWED_HOSTS, comma-separated, or [server] allowed_hosts).
--allow-unauthenticated	serve without a token when bound beyond loopback instead of generating one into /token (also CEREYAN_ALLOW_UNAUTHENTICATED or [server] allow_unauthenticated).
--mcp-read-only	list and allow only MCP tools that change nothing (also CEREYAN_MCP_READ_ONLY or [server] mcp_read_only).
--metrics-public	serve /api/metrics without a token, as /api/health (also CEREYAN_METRICS_PUBLIC or [server] metrics_public).
--public-url PUBLIC_URL	the address people reach the UI at, used for run links in rule templates (also CEREYAN_PUBLIC_URL or [server] public_url).

cereyan worker

cereyan worker [-h] [--host HOST] [--name NAME] [--processors PROCESSORS] [--labels LABELS] [--shared-path PATH] [--token WORKER_TOKEN] [--token-file TOKEN_FILE] [--status-host STATUS_HOST] [--status-port STATUS_PORT] [dir]

Argument	Meaning
dir (optional)	this machine's checkout of the project (default: current directory).

Option	Meaning
--host HOST	the server's URL, e.g. https://cereyan.internal (also [worker] host).
--name NAME	how the server lists this worker (default: the hostname; also [worker] name; "server" is taken).
--processors PROCESSORS	engines this worker may run at once, at most its CPU count (default 1; also [worker] processors).
--labels LABELS	k=v pairs shown on the Workers tab, e.g. gpu=true,zone=eu (also [worker] labels).
--shared-path PATH	a path this machine shares with the server; a LocalTarget elsewhere is reported (repeat for more; also [worker] shared_paths).
--token WORKER_TOKEN	the server's API token (also CEREYAN_TOKEN).
--token-file TOKEN_FILE	read the server's API token from this file (also [worker] token_file).
--status-host STATUS_HOST	interface for the worker's read-only status page (default 127.0.0.1; also [worker] status_host).
--status-port STATUS_PORT	port for the status page (default 0: one the OS picks; also [worker] status_port).

cereyan check

cereyan check [-h] [--json] [--strict] [--now NOW] [dir]

Argument	Meaning
dir (optional)	directory to check (default: current directory).

Option	Meaning
--json	print the report as one JSON object.
--strict	treat warnings as errors.
--now NOW	reference instant for schedule previews, ISO 8601 (default: now; naive means UTC).

cereyan backup

cereyan backup [-h] [--json]

Option	Meaning
--json	print the copy's path as JSON.

cereyan backfill

cereyan backfill [-h] --param PARAM [--start START] [--end END] [--values VALUE[,VALUE...]] [--missing-only] [--force] [--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 (not with --values).
--end END	last value of the parameter, inclusive.
--values VALUE[,VALUE...]	explicit values instead of a range; repeatable or comma separated.
--missing-only	leave out values whose latest run completed.
--force	restate: the runs ignore targets, caches, checkpoints and bulk_complete.
--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 retry

cereyan retry [-h] [--from POINT] [--json] run_id

Argument	Meaning
run_id	the run to retry.

Option	Meaning
--from POINT	failure (default), start, or a task's dynamic key such as transform-0. Default failure.
--json	print the retry response as JSON.

cereyan pause

cereyan pause [-h] [--reason REASON] [--until UNTIL] [--suppress-rules] [--json]

Option	Meaning
--reason REASON	shown in the UI banner and recorded on the event.
--until UNTIL	resume on its own at this ISO 8601 time (naive means UTC).
--suppress-rules	record rules that would fire as suppressed instead of acting.
--json	print the scheduler status as JSON.

cereyan resume

cereyan resume [-h] [--json]

Option	Meaning
--json	print the scheduler 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,compare} ...

cereyan runs ls

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

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

cereyan runs compare

cereyan runs compare [-h] [--json] baseline other

Argument	Meaning
baseline	run id of the baseline, usually the last good run.
other	run id of the run in question.

Option	Meaning
--json	print the comparison 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.