Skip to content

Commands

Run them from the directory that holds sanoma.config.ts. Each loads .env there first, when there is one (a variable already set wins), then the config.

Command What it does
sanoma Makes missing local signing and storage-encryption keys (only signing for an external store), respecting environment and mounted-file inputs and appending generated values to ignored .env; makes sure Postgres answers, starting the company’s own when no URL is named (see Postgres), then starts the worker (promoted, so a local worker takes every queued run) and the app in one process, and prints <name> running <workflows> and <name> at http://127.0.0.1:3000; ctrl-c to stop (the company’s name); the worker says sanoma: 2 of 5 connectors not configured yet: ghost, resend; … first when some vendors’ variables are missing or invalid (a call to one fails, naming them, until they are set; nothing when all are set). When the repo has sites, it serves the app and the sites from a dev server that shows each edit as it is saved (see Developing a site). In dev mode it runs them in a child it restarts. In an empty directory it first starts a company. The worker and the app are given the repo’s git checkout as their source, which commits to the current branch, and opens drafts: a git worktree each, at .sanoma/drafts/<id> on the branch draft/<id> from the checked-out commit, with the repo’s node_modules linked in (a link, which node_modules/ in .gitignore does not match, so .git/info/exclude names it), where a writer that must not touch the live checkout commits instead; the app runs a draft’s sanoma check in the person’s coding-agent box (Screens), never in this process, with no database URL or credential of the company’s. A draft is open while git worktree list lists it; merging its branch is by hand.
sanoma init [--name] [--you] [--email] In an empty directory, starts a company named and declared as the options say, then runs it as sanoma does.
sanoma worker, sanoma app One of the two alone, for a deployment that runs them apart (app builds the app with the sites; worker, with PORT set, answers on its port). Neither starts or probes Postgres: a URL named is the runtime’s to reach; with none they use the company’s own only while another sanoma runs it, and exit 2 otherwise. The worker makes the database’s tables (the runtime’s and the sign-ins’), the app only checks for them: start the worker first, or with the app, which waits up to a minute for them.
sanoma wakeup The wakeup service alone, on the config’s database (found as worker and app find it, never started), at SANOMA_APP_HOST and SANOMA_APP_PORT (default 3100), with /healthz.
sanoma check Writes .sanoma/api.ts and .sanoma/schema.cedarschema first, each when it changed; then tsc -p tsconfig.json; oxlint over workflows/, resources/, sites/ and apps/ (those that exist) with the repo’s .oxlintrc.json, written when missing (see the lint); every problem describeConfig finds (an import a workflow may not make, what its graph cannot draw, what the worker would refuse; a data file that does not load, or a resource it makes but does not export; a site’s call to a workflow, collection or operation the config does not have, or a public site’s start or direct call no permit lets a visitor make; a domain a host gives a site that is not public, or gives two sites); every problem in the policies, at its file:line:col with the policy’s id; with sites, the app built with them, tsc -p sites/tsconfig.json and what is wrong under content/; then, unless the policies have a problem, every scenario against the fakes, on a database of its own (<database>_check, on the company’s own Postgres when no URL is named, stopped after when check started it), each step that did not hold a problem. Prints each problem on a line, file:line:col: message or scenario › step: message, and exits 1 when there is one; before them each warning, file:line:col: warning: message (a public site’s page the sitemap cannot list the entries of, an import from one app into another), which never fails it. No vitest.
sanoma demo --out <dir> The sites as static files that run in any page, their workflows in the browser on the connectors’ fakes, seeded from scenarios/world.feature (see Demos): mount.js, its chunks/, demo.css, the files it names under files/, and index.html, into <dir>, emptied first.
sanoma env [--check] Writes .env.example: the variables sanoma reads, then every variable the connectors’ drivers declare, by vendor, with its description; optional ones commented out. --check writes nothing and exits 1 with “.env.example is out of date: run sanoma env” when the file differs, for CI.
sanoma ledger export <runId> [--out <file>] A run’s ledger records from the config’s store (the Postgres ledger on its database when it names none, the company’s own started for the read when no URL is named), as JSON lines (the shape jsonlLedger keeps), to stdout or --out.
sanoma describe [--as] [--url] [--agent] What the running app offers an agent (sanoma.describe): the company’s own workflows, direct operations and collections, as JSON on stdout. See From a terminal or an agent.
sanoma call <name> [--input <json>] [--id <id>] [--as] [--url] [--agent] Calls the running app’s POST /api/call with <name> as given and prints the answer as JSON on stdout: a workflow’s api name (or <api>.start) starts it and prints {"runId"}; <api>.result with --input '{"runId":"…"}' waits for the run’s end, asking again while it runs, up to 10 minutes; <api>.runs and the other reads of a workflow’s runs; an operation by its id. Each invocation is a new run or call unless --id names it. The runtime’s own workflows are not started here (exit 2), as /mcp refuses them.
sanoma --help The usage.

Exit codes: 2 for a mistake in the call or the repo (no sanoma.config.ts, an unknown command or option, a bad argument, an option of another command), printed with the usage where it helps; 1 for failed checks and failures while running, and for a call sanoma call or sanoma describe sends that the app refuses or that fails, or that nothing answers; 0 otherwise. SANOMA_APP_PORT is the app’s port (default 3000; 0 for any free port, which the printed address reports). SANOMA_APP_HOST is its address (default 127.0.0.1); SANOMA_DOMAINS gives a public site its domain, <site>=<hostname>[,<site>=<hostname>…] (www=sanoma.example, which a host resource’s domains sets), and a malformed one exits 2; any other address signs people in with the staff sign-in (an email code through the config’s login.sender, invite links, and GitHub once SANOMA_GITHUB_CLIENT_ID and SANOMA_GITHUB_CLIENT_SECRET are both set, in the environment or stored by the app’s Connect page (under Hosting) when it created the GitHub App; the public sites’ logins then offer visitors GitHub too, for which the App’s callback URLs need https://<site host>/auth/better-auth/callback/github), which needs SANOMA_SIGNING_KEY; a missing key, or one of the GitHub pair without the other, exits 2 before anything starts, as does a problem in the policies. There too, SANOMA_HOSTNAME is the hostname the app is served at over HTTPS (app.sanoma.example: no scheme, port or path), as a host resource’s hostname sets it on the Cloudflare host. It is the instance’s one agent address: agents sign in at https://<hostname>/mcp. An instance reached any other way (a port, an IP address, plain http) gives its own URL in SANOMA_HOST_URL instead (http://10.0.0.7:3000, with no path), which is read when there is no hostname. A value of either that names no address exits 2. With neither, people still sign in but no agent can: sanoma says so once on stderr when it starts, and /mcp says which variables to set. On SIGINT or SIGTERM the app, then the worker, then the Postgres it started, stop, and the process exits 0.

sanoma describe and sanoma call reach a sanoma that is already running, over HTTP: they start no worker and need no database, only the app. An agent with a shell uses them as a person at a terminal does: sanoma describe says what there is, then sanoma call hello --input '{"title":"Hi"}' starts a run and sanoma call hello.result --input '{"runId":"…"}' waits for its output. The answer is the one thing on stdout, as JSON (indented at a terminal, on one line otherwise); a refused or failed call exits 1 with the app’s message on stderr, its code, the run it names and, for an input that does not fit, each field’s problem. A call the policy holds (409, approval_pending) exits 1 too, with its run’s id on stderr and nothing on stdout.

  • Once: each invocation of a start or an operation’s call is a new run or call. --id <id> (letters, digits, _ and -) names it instead: the same --id again is the same call, not a second one, and with another input it is refused. When a request times out or its connection breaks after it was sent, the error names the id it used, to run the command again with.
  • Which company: the nearest directory from the working one up that holds sanoma.config.ts (short of a node_modules), then the company it is in (an app in apps/<app>/ that kept its own config is its company’s), each as the main checkout has it (from a draft in .sanoma/drafts/<id>, the company’s own directory). The first of those with a running app is the one whose app the commands ask and whose .env and people they read; with none running, the company’s. Outside any, they exit 2, unless --url names the app; then --as is needed.
  • Which app: --url; else the one the company’s .sanoma/app.json names while its process runs, when that is an http(s) address on this machine (sanoma, sanoma serve and sanoma app write it, {"url","pid"} and "signIn":true for an app that listens beyond this machine, once the app listens, and remove it when they stop; one whose process is gone is ignored); else SANOMA_APP_HOST (default 127.0.0.1) and SANOMA_APP_PORT (default 3000), after .env. A --url with a user or a password in it is refused (exit 2). With SANOMA_APP_PORT empty or 0 and no running app to say where, name it with --url (exit 2). Two sanoma started on port 0 in one directory share one discovery file, the last one’s: name the address with --url then. When nothing answers, the command exits 1 naming the address it tried and where it came from.
  • Who asks: --as, a declared person’s id, else one’s email, else one’s GitHub login (an id always wins: --as sam is the person sam, whoever’s GitHub login is sam); else the one person resources/ declares, as the app’s picker takes them; else the person git’s user.email names. Otherwise it exits 2 listing the people. A company that declares nobody needs --as.
  • For an agent: --agent <id> names a declared agent (sanoma.agent) that makes the call on that person’s behalf, as x-sanoma-agent does on /mcp: the policy and the ledger see the agent for the person.
  • Where: an app on this machine, listening on this machine alone. An app on any other address (a host, or SANOMA_APP_HOST=0.0.0.0) asks its staff sign-in who is asking, which these commands do not give: they say so when it refuses them. Their stdout holds the answer alone, SANOMA_EVENTS=1 or not: a failure is on stderr, never an error event.
  • Waiting: <api>.result asks again while the run is running, a second apart at least, for up to 10 minutes; ctrl-c stops waiting (exit 130), and the run goes on.

A parent process, such as a desktop shell, runs sanoma with SANOMA_EVENTS=1 and reads its stdout line by line: beside the lines a person reads, each event is one JSON object on a line of its own, {"sanoma":1,"event":…}; logs stay on stderr.

  • {"sanoma":1,"event":"ready","url":"http://127.0.0.1:3000","sites":{"www":"http://www.localhost:3000"}}: the app listens, right after the at <url>; ctrl-c to stop line, each time it starts (in dev mode, after each restart); url is where the app listens, on the port SANOMA_APP_PORT names (the free one it took, for 0), and sites is {} without public sites. sanoma worker has no address and prints none.
  • {"sanoma":1,"event":"error","message":"…"}: the launcher cannot start or stop, with the message it printed on stderr, then exits 2 for a mistake in the call or the config, 1 for a failure. In dev mode a child that fails prints it too, and the launcher waits for the next build to start it again.
  • {"sanoma":1,"event":"checked","ok":false,"problems":["…"],"warnings":[]}: sanoma check’s result, the lines it printed as two lists, before it exits; a check that cannot read the config ends with error instead. Read it rather than the printed lines: DBOS logs on stdout too.
  • {"sanoma":1,"event":"stage","stage":"template","status":"start"}, then "status":"done": a stage of starting a company (sanoma init, or sanoma in an empty directory), in this order: template (the files copied, named and keyed), people (you declared), git (the repository and its first commit), install (the package manager’s install), then database (the company’s own Postgres answering, from the sanoma the install brought, which then starts the worker and the app). A stage that fails has no done; an error follows. database comes on every run, not only the first, around the database event; none when a URL is named.
  • {"sanoma":1,"event":"database","how":"started","url":"postgresql://postgres:…@127.0.0.1:54012/sanoma","place":"this-computer"}: the company’s own Postgres answers, once, before the worker starts (in dev mode, from the parent, not each child): how is created (made first), started, or answered (another sanoma runs it), and url holds its password, so a parent never logs it. None when a URL is named.

With the variable, the end of stdin (the parent closing it, or exiting), or an error reading it, stops sanoma as SIGTERM does, so the parent keeps stdin open while it runs. sanoma never prompts and, without the variable, never reads stdin; it opens no browser. SIGTERM stops everything it started (the app, then the worker; in dev mode its child and the watch builds), then the company’s own Postgres when it started it and no other client is connected, and it exits 0.

These pages describe sanoma 0.11.24.