CLI reference

The tide binary has five subcommands. A bare tide <file> is shorthand for tide run <file>.

tide run     [options] <file>
tide resume  <invocation-id> --action <action> [options] <file>
tide test    [options] [paths...]
tide schema  <file>
tide serve   [options]
tide --version
tide --help

`tide run`

Run (or replay) a workflow once.

tide run workflow.ts --input '{"name":"Ada"}'
tide run workflow.ts -i order-001 --input '{"name":"Ada"}'   # explicit id
tide run workflow.ts -i order-001                            # replay

Flag	Default	Description
`-i, --invocation-id <id>`	random UUID	Names the journal. Re-running with the same id replays it. Omit it and every run is a fresh one-shot.
`--input <json>`	—	JSON input, validated against the workflow schema.
`--input-file <path>`	—	Read JSON input from a file. Mutually exclusive with `--input`.
`--store <fs\|sqlite\|postgres>`	`fs`	Durable store backend for the journal. See Storage.
`--argon <url>`	embedded	Run `state.*` against a remote `ox runtime serve` `/v1` endpoint instead of the embedded Argon engine.
`--json`	off	Emit one machine-readable JSON result object instead of streaming console output (see below).

The shipped binary embeds Argon and runs against a durable main world. Two embedded-only flags tune that world on run/resume:

Flag	Default	Description
`--world-dir <dir>`	`<project>/.tide/world`	Root the durable `main` event log elsewhere.
`--fresh`	off	Wipe the durable world before this run (start from the `.oxbin` seed; equivalent to `rm -rf .tide/world`).

Tide prints the invocation id to stderr at startup (invocation: <id>). Workflow log / console.log output goes to stdout; console.error to stderr.

`--json` output

For driving tide run programmatically. One JSON object to stdout:

{
  "status": "completed",
  "output": [{ "level": "log", "message": "hired Ada …" }],
  "error": null,
  "pendingHumanWait": null,
  "invocationId": "…"
}

status is completed, failed, or waitingHuman. A waitingHuman status carries pendingHumanWait (task id + wait ordinal) so a caller can issue the matching tide resume. See Driving Tide programmatically.

`tide resume`

Resolve a workflow suspended at hitl.wait and continue it.

tide resume order-001 workflow.ts --action approved \
  --payload '{"note":"ok"}' --comment "verified"

Argument / flag	Description
`<invocation-id>` (positional)	The suspended invocation.
`<file>` (positional)	The workflow file to replay.
`--action <action>`	Required. The human decision (e.g. `approved` / `rejected`).
`--payload <json>`	Optional JSON payload attached to the decision.
`--comment <text>`	Optional free-text comment.
`--store <fs\|sqlite\|postgres>`	Store backend (default `fs`).
`--argon <url>`	Remote Argon endpoint (as for `run`).

tide resume records the decision into the journal, replays the run to the suspension point, and resumes. See Human-in-the-loop.

`tide test`

Discover and run *.test.ts / *.spec.ts files through the built-in describe / test / assert / expect harness.

tide test                 # discover from the current directory
tide test workflows/      # restrict to a path
tide test --json          # structured per-suite / per-case results

Flag	Default	Description
`[paths...]`	`.`	Files or directories to search for tests.
`--store <fs\|sqlite\|postgres>`	`fs`	Store backend.
`--json`	off	Print `{ status, suites: [...] }` JSON.

Each test case runs in its own isolated, throwaway world store — one case's writes never leak into the next, and tests never touch the persistent .tide/world. Exit code is non-zero if any case fails.

`tide schema`

Print a workflow's input schema as JSON — the machine-readable manifest of the inputs it accepts.

tide schema workflow.ts

`tide serve`

Run the HTTP /v1 control surface over the workflow runner. Flags and routes are documented in the serve guide.

tide serve --workflows workflows --port 4100 --workers 4

Flag	Default	Description
`--port <port>`	`4100`	TCP port (bound on `127.0.0.1`).
`--workflows <dir>`	`workflows`	Workflow source root (`<dir>/<name>/main.ts`).
`--store <fs\|sqlite\|postgres>`	`fs`	Store backend.
`--workers <n>`	`1`	Worker-pool size; `>1` runs invocations in parallel.
`--argon <url>`	embedded	Serve against a remote Argon endpoint.

Exit codes

Code	Meaning
`0`	Success — `completed`, or `waitingHuman` (suspended, awaiting `tide resume`).
non-zero	A `failed` run, a test failure, or a usage / infrastructure error.

Driving Tide programmatically

tide is built to be driven by a coding agent with three commands and no other tooling:

Discover the input. tide schema workflow.ts prints the input schema as JSON — the manifest for constructing a valid --input.
Run it. tide run workflow.ts --input '<json>' --json runs the workflow and prints one JSON result object (status, console output, error, pending human wait, invocation id). On waitingHuman, issue tide resume <invocationId> --action <action>.
Test it. tide test --json prints { status, suites: [...] }, each suite carrying per-case status and error, exiting non-zero on any failure.

Your first workflow — run and replay in context.
Human-in-the-loop — the resume model.
tide serve — the HTTP control surface.
Storage — the --store backends.

CLI reference

On this page