genroc

    docs / Guides / Getting started

    Your first process

    Write a definition, apply it, run an instance and watch it through to completion.

    Define it

    Genroc processes are defined via .genroc.yaml files. If you've just initialized your project with genctl init, you will see hello.genroc.yaml in the definitions folder.

    # definitions/hello.genroc.yaml
    nameUnique process identifier.: helloUnique process identifier.
    input_schemaJSON Schema used to validate the input payload when starting a new instance.:
      typeThe value's JSON type, or a list of types it may take.: objectThe value's JSON type, or a list of types it may take.
      propertiesThe named members of an object, each a schema.:
        who: { typeThe value's JSON type, or a list of types it may take.: stringThe value's JSON type, or a list of types it may take., defaultThe value used when this one is absent. Annotation only — it does not make a required property optional.: "world" }
    tasksOrdered list of execution tasks. Control advances linearly unless a switch case redirects.:
      - idTask identifier, unique within the definition.: greetTask identifier, unique within the definition.
        outputtasks.greet.output — object{greeting}:
          greetinggreeting — string: "hello, ${inputinput → object{who}.whoinput.who → string}"
        switchRequired. Routing: a shorthand ("next", "end", "$task-id") or an ordered list of cases.:
          - goto"end" to terminate, "next" to advance, or "$task-id" to jump to a task.: end"end" to terminate, "next" to advance, or "$task-id" to jump to a task.
    
    outputoutputs.greet → object{greeting}: "$: outputsoutputs → object{greet}.greetoutputs.greet → object{greeting}"

    Apply it

    Genroc server now doesn't know about this process, we first need to apply it.

    Full command to do this:

    genctl apply -f definitions/hello.genroc.yaml

    Init makes this easier for you: the .genroc file has a glob for definitions. With a setup like this, you can run the command without specifying the file.

    genctl apply        # uses definitions glob from .genroc

    You can also list existing definitions with genctl definitions:

    > genctl definitions
    NAME   VERSION  REGISTERED  BY                 RAISES
    hello  v1       just now    no-auth:anonymous  

    Run it

    You can now run the definition with a run command:

    genctl run hello --input '{"who": "genroc user"}'

    The command creates an instance of our hello process.

    Processes accept input in the form of JSON.

    You can use an equivalent, more user friendly version with the --set parameter:

    genctl run hello --set "who=genroc user"

    If the instance starts correctly, genctl will print a summary with an instance id.

    > genctl run hello --set "who=genroc user"
    started: 4cqpdx8z  hello@v1  (running)

    Checking the instance state

    We can now check the instance status with get command and the instance id.

    genctl get 4cqpdx8z
    # or
    genctl get @last

    But a more convenient way is to use the @last alias, which names the instance genctl run started most recently.

    > genctl get @last
    ID:       4cqpdx8z
    Process:  hello@v1
    Status:   completed
    Task:     greet
    Created:  2026-09-08 13:44:24  (just now)
    Updated:  2026-09-08 13:44:24  (just now)
    
    Output:
    greeting: hello, genroc user

    The example process basically just copies your input and prints it out into the output. So it finishes instantly.

    The @last alias is genctl shorthand: genctl remembers it on your machine, so it only knows instances you started there with genctl run.

    Checking the logs

    The instance also produces logs which you can list through logs command (@last works as well).

    > genctl logs @last
    TIME      LEVEL  ID        EVENT             TASK
    --- 2026-09-08 +02:00 ---
    13:44:24  INFO   4cqpdx8z  inst_created                      by=no-auth:anonymous input={"who":"genroc user"}
    13:44:24  INFO   4cqpdx8z  inst_completed    greet           output={"greeting":"hello, genroc user"}

    You can see what the input was and what the final output is.