genroc

    docs / Reference / CLI

    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)