Instances
The genctl commands for instances: `run`, `instances`, `get`, `detail`, `logs`, `pause`, `resume`, `cancel`, `retry`, `upgrade`, `signal`, `object`.
run
start an instance
genctl run <process> [--channel C | --version N] [--input <json|-> | -f file] [--set k=v ...] [-q]
Input comes from --input (a literal, or - for stdin), -f, or --set k=v (dotted keys nest, values are type-inferred); --set wins. Runs the latest version unless --channel or --version.
id=$(genctl run hello -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>]
[--phase <phase>] [--task <task-id>] [--children] [--sort updated|created]
[--since <when>] [--until <when>] [--json | -q]
Lists root instances; --children adds child instances and a PARENT column. A phase is shown after the status (running·external).
genctl instances --status failed
genctl instances --phase external
genctl pause $(genctl instances -q --status running)
Shows the newest 20 rows (logs: 200), oldest first, and says on stderr when rows were left out. --since and --until take a duration (2h, 45m) or a timestamp (2006-01-02 15:04), read in the local zone ($TZ).
Flags
--children include child instances
--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 phase: children, collecting or external
--process filter by exact process name, across every version
-q shorthand for --quiet
--quiet print only instance ids, one per line
--server genroc server base URL ($GENROC_SERVER) (default
http://localhost:8448)
--since show rows from this point on: a duration ago (2h) or a
timestamp
--sort sort key: created or updated (most recently active) (default
created)
--status filter by status; comma-separate several
--task filter by the task an instance is on; pair with --process
--until show rows before this point; same forms as --since
--version filter by process version
get
show one instance and what it produced
genctl get <instance-id> [--resolve] [--json]
An instance is named by its id (6fah8w2p) or @last, the one run started most recently.
Prints the status, the error and the output: block. detail adds the internal state.
--resolve inlines large values that print as refs.
Flags
--json print the raw JSON response
--resolve inline large values instead of printing their refs
--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 is named by its id (6fah8w2p) or @last, the one run started most recently.
Everything get prints, plus parent, children, lease, epochs and the full state.
--resolve inlines large values that print as refs.
Flags
--json print the raw JSON response
--resolve inline large values instead of printing their refs
--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]
[--flat] [--mode basic|detail] [--json] <instance-id>
A root id shows its whole tree with an ID column; --flat shows the root's rows only.
--json prints JSONL in UTC. Refs are not resolved; genctl object <ref> prints one.
An instance is named by its id (6fah8w2p) or @last, the one run started most recently.
Shows the newest 20 rows (logs: 200), oldest first, and says on stderr when rows were left out. --since and --until take a duration (2h, 45m) or a timestamp (2006-01-02 15:04), read in the local zone ($TZ).
Flags
--flat only this instance's rows, not its tree's
--json print the raw JSON entries, one per line (JSONL), untruncated
--level lowest level to show; debug includes request and response
bodies (default info)
--mode basic, or detail to add each entry's data on one line (default
detail)
--server genroc server base URL ($GENROC_SERVER) (default
http://localhost:8448)
--since show rows from this point on: a duration ago (2h) or a
timestamp
--time clock (time, with a line per day) or full (date and time on
every row) (default clock)
--until show rows before this point; same forms as --since
pause
stop an instance from advancing
genctl pause <instance-id> [<instance-id> ...]
Takes several ids. An id already in the target state prints "already" and does not fail, so the command is safe to re-run. Exits 1 only if an id was refused; the rest still run.
An instance is named by its id (6fah8w2p) or @last, the one run started most recently.
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. An id already in the target state prints "already" and does not fail, so the command is safe to re-run. Exits 1 only if an id was refused; the rest still run.
An instance is named by its id (6fah8w2p) or @last, the one run started most recently.
Flags
--server genroc server base URL ($GENROC_SERVER) (default
http://localhost:8448)
cancel
stop an instance for good
genctl cancel <instance-id> [<instance-id> ...]
Final: a cancelled instance cannot be resumed or retried. Use pause to stop temporarily.
Takes several ids. An id already in the target state prints "already" and does not fail, so the command is safe to re-run. Exits 1 only if an id was refused; the rest still run.
An instance is named by its id (6fah8w2p) or @last, the one run started most recently.
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> ...]
--force retries an only_once task, which may already have taken effect.
Takes several ids. An id already in the target state prints "already" and does not fail, so the command is safe to re-run. Exits 1 only if an id was refused; the rest still run.
An instance is named by its id (6fah8w2p) or @last, the one run started most recently.
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]
By process, moves the instances on --from (narrowed by --status); by id, moves those.
An instance moves only if the new version is compatible with where it is; genctl compat
checks without moving.
An instance is named by its id (6fah8w2p) or @last, the one run started most recently.
Flags
--from the version to move from: a number or a channel
--json print one JSON object per tree instead of a progress table
--server genroc server base URL ($GENROC_SERVER) (default
http://localhost:8448)
--status statuses to move, comma-separated: running, paused, failed
(default all three)
--to the version to move to: a number or a channel
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]
Answers an external task without claiming it. Sent before the task is waiting, it is buffered until it is. --code/--message sends an error instead, handled by the task's on_error. No result flags sends an empty result, allowed only without a result_schema.
An instance is named by its id (6fah8w2p) or @last, the one run started most recently.
Flags
--code answer with an error of this code (lower_snake_case) instead
of a result
-f read result/payload from a file (path)
--message with --code: human-readable cause; lands on error.message
-q shorthand for --quiet
--quiet print nothing on success
--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>
Prints a large value that other output shows as a ref: a string as itself, anything else as JSON.
Flags
--server genroc server base URL ($GENROC_SERVER) (default
http://localhost:8448)