run

start an instance

genctl run <process> [--channel C | --version N] [--input <json|-> | -f file] [--set k=v ...] [-q]

Input from —input (a literal, or - for stdin), -f, or —set k=v — dotted keys nest, values are type-inferred, and —set overrides the others. Latest version unless —channel or —version. -q prints only the new id: id=$(genctl run NAME -q).

Flags

  --channel  resolve the version via this channel
  -f         read input from a file (path)
  --input    input as a JSON/YAML literal, or - for stdin
  -q         shorthand for --quiet
  --quiet    print only the new instance id, e.g. id=$(genctl run NAME -q)
  --server   genroc server base URL ($GENROC_SERVER) (default
             http://localhost:8448)
  --set      set an input field: key=value (repeatable; dotted keys nest,
             values are type-inferred)
  --version  pin an explicit process version

instances

list instances (roots only unless —children)

genctl instances [--process <name>] [--version <n>] [--status <status>] [--error-code <code>]
genctl [--phase <phase>] [--task <task-id>] [--children] [--sort updated|created]
genctl [--since <when>] [--until <when>] [--json | -q]

Roots only — one row per tree, which is the unit pause/resume/cancel/retry and upgrade act on. —children adds them back and turns on a PARENT column, since nothing else on a row tells the two apart. -q prints bare ids, and nothing at all when empty, for nesting:

genctl pause $(genctl instances -q —status running)

—phase asks why a running instance is not executing a task, which status does not say, and the three answers are not one kind of thing: children is BLOCKED until its children settle, collecting has their outputs still to merge and is runnable now, external is parked until someone answers it. So this is the listing of unresolved external tasks:

genctl instances —phase external

The STATUS column carries it after a · when a row has one (running·external).

—task narrows to the task an instance sits on — where it is running, parked, or where it stopped. A task id is unique only within its definition, so pair it with —process to mean one task rather than that spelling anywhere.

Oldest to newest, so the newest is nearest the prompt. No —limit: each list shows its newest N (20; logs 200) and says on stderr when that dropped rows. —since reaches further back — a duration (2h, 45m) or a timestamp — and —until is its far end; [since, until) is half-open. Times display in, and are read in, the local zone ($TZ).

Flags

  --children    include child instances; by default the listing is roots only,
                one row per tree
  --error-code  filter by exact error code (e.g. card_declined, http.500)
  --json        print the raw items as a JSON array
  --phase       filter by why a running instance is not executing a task
                (children, collecting, external)
  --process     filter by exact process name, across every version
  -q            shorthand for --quiet
  --quiet       print only instance ids, one per line — the form to nest in
                another command
  --server      genroc server base URL ($GENROC_SERVER) (default
                http://localhost:8448)
  --since       read forward from this point: a duration back from now (2h,
                45m) or a timestamp (2006-01-02, 2006-01-02 15:04); bounds
                whichever column --sort selects
  --sort        sort key: created or updated (most recently active) (default
                created)
  --status      filter by status, comma-separated for several (running,
                completed, failing, failed, raised, pausing, paused,
                cancelling, cancelled)
  --task        filter by the exact task id the instance sits on; pair with
                --process, since a task id is unique only within its
                definition
  --until       stop at this point (same forms as --since); on its own it
                keeps the cap, giving the newest rows before that instant
  --version     filter by exact process version; with --process, that process
                at that version

get

show one instance and what it produced

genctl get <instance-id> [--resolve] [--json]

An instance id is an opaque digit-led token (6fah8w2p), or @last for the most recently started one (recorded by run). A second id is refused rather than dropped.

Prints what the instance reports OUTWARD: its status and its output: block, which is the same value a parent collects as a child’s result. The engine’s own slots are detail.

—resolve fetches the values listed under “objects” and puts them back inline; without it a large value prints as a ref.

Flags

  --json     print the raw JSON response
  --resolve  fetch the values listed under "objects" and put them back
             where they belong
  --server   genroc server base URL ($GENROC_SERVER) (default
             http://localhost:8448)

detail

show everything stored on one instance

genctl detail <instance-id> [--resolve] [--json]

An instance id is an opaque digit-led token (6fah8w2p), or @last for the most recently started one (recorded by run). A second id is refused rather than dropped.

The whole row: everything get prints, plus parent, children, lease and epochs, and the state — engine bookkeeping and all — which is what an upgrade validates and a migration rewrites. Reading it is reading internals; get is the everyday view.

—resolve fetches the values listed under “objects” and puts them back inline; without it a large value prints as a ref.

Flags

  --json     print the raw JSON response
  --resolve  fetch the values listed under "objects" and put them back
             where they belong
  --server   genroc server base URL ($GENROC_SERVER) (default
             http://localhost:8448)

logs

print an instance’s log trail

genctl logs [--level <level>] [--since <when>] [--until <when>] [--time clock|full]
genctl [--flat] [--mode basic|detail] [--json] <instance-id>

A ROOT id answers with every row in its tree, an ID column telling them apart; —flat asks for its own rows alone. A child id answers with its own rows either way — a tree is addressed by its root here, as it is for pause/resume/cancel/retry/upgrade.

—mode: basic is a line per entry, detail adds the payloads. —json prints JSONL, the one output that keeps the server’s UTC RFC3339. Refs are never resolved here — a trail is scanned, not read; genctl object <ref> fetches one. —time full puts the date on every row instead of a per-day separator.

An instance id is an opaque digit-led token (6fah8w2p), or @last for the most recently started one (recorded by run).

Oldest to newest, so the newest is nearest the prompt. No —limit: each list shows its newest N (20; logs 200) and says on stderr when that dropped rows. —since reaches further back — a duration (2h, 45m) or a timestamp — and —until is its far end; [since, until) is half-open. Times display in, and are read in, the local zone ($TZ).

Flags

  --flat    this instance's own rows only; by default a ROOT id answers
            with every row in its tree
  --json    print the raw JSON entries, one per line (JSONL), untruncated
  --level   lowest level to show: this level and everything above it (warn
            keeps errors). `debug` is the bottom, so it is the whole trail
            -- the engine records a call's request and response bodies
            there (default info)
  --mode    table density: basic (no data body) or detail (+ data, cut to
            one line -- $COLUMNS sets the width) (default detail)
  --server  genroc server base URL ($GENROC_SERVER) (default
            http://localhost:8448)
  --since   read forward from this point: a duration back from now (2h,
            45m) or a timestamp (2006-01-02, 2006-01-02 15:04); empty =
            the newest 200 entries
  --time    time column: clock (15:04:05, with a day separator per date)
            or full (2006-01-02 15:04:05 +02:00); both render in the local
            zone ($TZ) (default clock)
  --until   stop at this point (same forms as --since); on its own it
            keeps the cap, giving the newest rows before that instant

pause

stop an instance from advancing

genctl pause <instance-id> [<instance-id> ...]

Takes several ids and acts on every one, one call each. These are ASSERTIONS: an id already in the state prints “already” and does NOT fail, so a line that was only half applied can be run again as-is. Only a refusal exits 1, and it stops neither the ids after it nor the code.

An instance id is an opaque digit-led token (6fah8w2p), or @last for the most recently started one (recorded by run).

Flags

  --server  genroc server base URL ($GENROC_SERVER) (default
            http://localhost:8448)

resume

let a paused instance advance again

genctl resume <instance-id> [<instance-id> ...]

Takes several ids and acts on every one, one call each. These are ASSERTIONS: an id already in the state prints “already” and does NOT fail, so a line that was only half applied can be run again as-is. Only a refusal exits 1, and it stops neither the ids after it nor the code.

An instance id is an opaque digit-led token (6fah8w2p), or @last for the most recently started one (recorded by run).

Flags

  --server  genroc server base URL ($GENROC_SERVER) (default
            http://localhost:8448)

cancel

stop an instance for good

genctl cancel <instance-id> [<instance-id> ...]

Terminal and irreversible: a cancelled instance cannot be resumed or retried. Use pause if the tree should be able to carry on later.

Takes several ids and acts on every one, one call each. These are ASSERTIONS: an id already in the state prints “already” and does NOT fail, so a line that was only half applied can be run again as-is. Only a refusal exits 1, and it stops neither the ids after it nor the code.

An instance id is an opaque digit-led token (6fah8w2p), or @last for the most recently started one (recorded by run).

Flags

  --server  genroc server base URL ($GENROC_SERVER) (default
            http://localhost:8448)

retry

retry a failed instance’s current task

genctl retry [--force] <instance-id> [<instance-id> ...]

Takes several ids and acts on every one, one call each. These are ASSERTIONS: an id already in the state prints “already” and does NOT fail, so a line that was only half applied can be run again as-is. Only a refusal exits 1, and it stops neither the ids after it nor the code.

An instance id is an opaque digit-led token (6fah8w2p), or @last for the most recently started one (recorded by run).

—force overrides only_once protection, where a retried task may already have taken effect.

Flags

  --force   override only_once retry protection
  --server  genroc server base URL ($GENROC_SERVER) (default
            http://localhost:8448)

upgrade

move instances to another version

genctl upgrade <process> --from <version|channel> --to <version|channel> [--status running,paused,failed] [--json]
genctl upgrade <instance-id> [<instance-id> ...] --to <version|channel> [--json]

A process name sweeps its fleet and needs —from, the selector saying which rows move. Ids move those trees instead, one call each, and refuse —from/—status: an id selects already. An instance moves only where the new version is compatible with where it is parked — genctl compat asks the same question without moving anything.

An instance id is an opaque digit-led token (6fah8w2p), or @last for the most recently started one (recorded by run).

Flags

  --from    the version instances are on now: a number, or a channel name.
            Selects the sweep; instance ids need no --from
  --json    print one JSON object per tree instead of a progress table
  --server  genroc server base URL ($GENROC_SERVER) (default
            http://localhost:8448)
  --status  comma-separated states to sweep: running, paused, failed.
            Default is all three
  --to      the version to move them to: a number, or a channel name

signal

deliver an outcome to an instance’s external task by id

genctl signal <instance-id> --task <task-id> [--result <json|-> | -f file] [--set k=v ...] [--code C --message M] [-q]

No claim and no fence. It may arrive before the task arms: the server then BUFFERS it FIFO until the task parks, and the confirmation line says delivered or buffered. A worker that claimed a task answers through the API, with the token its claim returned.

—code/—message answers on the ERROR channel instead of with a result, routed through the task’s on_error rules like any other call error. No result flags at all means an empty outcome: valid for a task declaring no result_schema, refused otherwise.

An instance id is an opaque digit-led token (6fah8w2p), or @last for the most recently started one (recorded by run).

Flags

  --code     answer on the ERROR channel with this code (lower_snake_case,
             no dots)
  -f         read result/payload from a file (path)
  --message  with --code: human-readable cause; lands on error.message
  -q         shorthand for --quiet
  --quiet    on success print nothing (exit 0); by default prints a
             confirmation line
  --result   result as a JSON/YAML literal, or - for stdin
  --server   genroc server base URL ($GENROC_SERVER) (default
             http://localhost:8448)
  --set      set a result/payload field: key=value (repeatable; dotted keys
             nest, values are type-inferred)
  --task     the external task to deliver to (required)

object

print a stored object by ref

genctl object <ref>

A value too large to inline is stored once and referenced. get —resolve puts them back; logs never does, so this fetches the one payload you want.

Flags

  --server  genroc server base URL ($GENROC_SERVER) (default
            http://localhost:8448)