Exit codes and the discovery file

CLI exit codes

Code	Meaning
0	Success. For cereyan run, the run completed; for cereyan check, no errors were found.
1	cereyan run: the run failed. cereyan check: errors were found, or warnings under --strict.
2	cereyan run only: nothing ran, because the store was locked and no server took the run.
3	An error before or outside the run: the flow could not be loaded, a parameter did not coerce, a server was needed but unreachable or required a token, a backfill argument was invalid, or cereyan check was given a directory it could not check.

The full command reference, generated from the parser, is on the CLI page.

The runtime home

One home per machine, resolved from --home, then CEREYAN_HOME, then ~/.cereyan. It contains:

Entry	Meaning
db.sqlite	The store: flows, runs, task runs, logs, events, rules, artifacts, variables, settings. WAL mode, so db.sqlite-wal and db.sqlite-shm appear while it is open.
db.lock	OS advisory lock held by the process that owns the store: a running server, or an offline script while it writes.
server.json	Written by a running server and removed on shutdown; see below.
secret.key	Created when the first secret variable is set; encrypts secrets at rest.
storage/	Persisted task results and cache entries.
backups/	Copies of the database: db-<time>.sqlite from scheduled, on-demand, and reset backups, and pre-migration-v<n>-<time>.sqlite written before a schema upgrade.

A corrupted db.sqlite is moved aside on open and a fresh store is created; history is a cache and the code plus targets are the source of truth.

The home is created readable only by the account that creates it, and everything in the table above is protected by that rather than by permissions set on each file. A home from an earlier version that is broader is narrowed when it is opened, and cereyan says so once. On Windows a home under your user profile inherits the same protection; a CEREYAN_HOME pointed somewhere else is yours to protect.

server.json

A running server records how to reach it so scripts, the CLI, cereyan mcp, and engines find it:

{
  "host": "127.0.0.1",
  "port": 4200,
  "url": "http://127.0.0.1:4200",
  "pid": 12345,
  "started_at": 1788998400000000,
  "version": "1.5.0",
  "auth": true,
  "socket": "/tmp/cereyan.sock",
  "exposed": false,
  "token_file": null
}

Field	Meaning
host, port	What the listener bound. host is 0.0.0.0 when the server was started on every interface.
url	Where to reach it from this machine. When the server bound an unspecified address, this is loopback rather than the bind address, because 0.0.0.0 is not somewhere a client can connect.
pid	The server process; clients check it is alive before trusting a stale file.
started_at	Microseconds since the Unix epoch.
version	The cereyan version.
auth	Whether a token is required. The token itself is never written.
socket	The Unix socket path when one is served, else null.
exposed	true when the server is bound beyond loopback with no token required, which takes allow_unauthenticated.
token_file	The path of <home>/token when the server generated its token at start, else null. Clients on the same machine read the token from it.

cereyan.client.read_discovery() returns it and cereyan.client.find_server() turns it into a client after checking /api/health.