What is a workflow?

A workflow is a sequence you’ll want to run again. In Termorq it is one YAML file. The Editor tab shows it as a canvas and the YAML tab shows the same file as text. Changes on one tab appear on the other, because both edit the same file.

The vocabulary

How data flows

flowchart LR
  T["Trigger<br/>trigger.text"] --> A["Code block<br/>uses: trigger.text"]
  A -->|"steps.a.message"| B["HTTP block<br/>{{ steps.a.message }}"]
  B -->|"steps.b.status"| C{"Decision<br/>steps.b.status == 200"}
  C -->|when| D["AI block"]
  C -->|else| E["Code block"]

Data moves forward only through declared properties:

• A code block lists the paths it needs under uses. At run time it reads them from a JSON file whose path is in TERMORQ_INPUT.
• An HTTP, MCP, or AI block uses {{ steps.<id>.<property> }} templates in its fields.
• Every block publishes properties. A later block reads them as steps.<block id>.<property>.

Each code block runs as its own process. A shell variable set in one block doesn’t exist in the next one. To pass a value on, publish it as a property.

Workflows are not runbooks

Termorq also has collection runbooks, Markdown runbooks, and repo runbooks. These are separate features, and nothing in this course changes them.

Reference: Build a workflow

Enable Workflows and install runtimes

Steps

1. Open Settings → Experimental.
2. Turn on Workflows. It is off by default.
3. Open the page with Cmd+Shift+G (macOS) or Ctrl+Shift+G (Windows/Linux). You can also open the jump list with Ctrl+J and choose Workflows, or type @flow.

If you later turn the flag off, Termorq hides the page’s entry points and workflow settings. A workflow that is already open stays open until you leave it.

Check your runtimes

Termorq doesn’t bundle language runtimes. The code runner uses whatever is installed on your computer. Run these commands in a Termorq terminal tab:

bash --version | head -1
jq --version            # used by Bash JSON examples
pwsh --version          # PowerShell
python3 --version
dotnet --version        # needs 10.0 or later for C#
rustc --version         # needs Rust 2024 edition support
node --version          # 22.6+ runs TypeScript natively

bash --version          # Git Bash or WSL exposed on PATH
jq --version
pwsh --version
python --version
dotnet --version
rustc --version
node --version

Reference: Node types and code languages

Tour the Workflows page

The list

• The All, Yours, Included, and Workspace chips filter by source.
• The trigger pills filter by trigger type: Manual, Schedule, At startup, After workflow, File change, HTTP request, Telegram.
• Each row shows the trigger, last edited and run times, run count, disk use, and the latest result. Its actions are Runs, Edit, Copy, Export, and Delete. Delete appears when you hover over or focus the row.
• Included workflows are read-only. Use Copy to make your own editable version. A copy starts with its triggers paused.

The editor

Keyboard and navigation

Runs keep going after you leave the page. When a run is in progress, the footer shows a chip such as 1 workflow running. Click it to go back to the page.

Reference: Build a workflow

Hello, workflow (60 seconds)

Steps

1. Open Workflows (Cmd/Ctrl+Shift+G) and choose New workflow.

2. Under Settings (next to Editor), name it Hello workflow.

3. Add a Code block. New Code blocks start as Bash.

4. In Properties → Code, set the snippet to:

   echo '{"ok":true}'

5. Open Properties → Schema and add a property named ok with type boolean.

6. Click Save, then Run.

The same workflow as YAML

Open the YAML tab. You should see something like this. The block ID is generated, so yours may differ.

schema: 1
name: Hello workflow
id: hello-workflow
blocks:
  - id: hello
    name: Hello
    kind: code
    language: bash
    body: |
      echo '{"ok":true}'
    outputs:
      type: object
      properties:
        ok:
          type: boolean

Check your run

Why the last line matters

Because the block declares an output (ok), the last non-empty line of stdout must be one JSON object, and that object must include ok as a boolean. Stage 2 covers this rule in detail.

Reference: Build a workflow → In 60 seconds

Pass a value to the next block

Steps

1. Create a new workflow and paste this into the YAML tab:

schema: 1
name: Pass a value
id: pass-a-value
blocks:
  - id: make_name
    name: Make name
    kind: code
    language: python
    body: |
      import json
      print(json.dumps({"name": "Ada"}))
    outputs:
      type: object
      properties:
        name:
          type: string

  - id: greet
    name: Greet
    kind: code
    language: python
    uses: [steps.make_name.name]
    body: |
      import json, os
      with open(os.environ["TERMORQ_INPUT"], encoding="utf-8") as f:
          data = json.load(f)
      name = data["steps"]["make_name"]["name"]
      print(json.dumps({"greeting": f"Hello, {name}!"}))
    outputs:
      type: object
      properties:
        greeting:
          type: string

2. Switch to Editor. Each card shows steps.<id> near its lower edge.
3. Select Greet and open Properties → Input. Available data lists steps.make_name.name with a string pill.
4. Click Save, then Run.

What happened

• make_name printed {"name": "Ada"} as its last line. Because name is declared in outputs, Termorq published it as steps.make_name.name.

• greet listed steps.make_name.name under uses. Termorq wrote a temporary JSON file containing only that value, keeping its nesting:

  {"steps":{"make_name":{"name":"Ada"}}}

• TERMORQ_INPUT holds the path to that file, not the JSON itself.

Check your run

  - id: shout
    kind: code
    language: python
    uses: [steps.greet.greeting]
    body: |
      import json, os
      data = json.load(open(os.environ["TERMORQ_INPUT"], encoding="utf-8"))
      print(json.dumps({"loud": data["steps"]["greet"]["greeting"].upper()}))
    outputs:
      type: object
      properties:
        loud:
          type: string

Save, and fix what Save rejects

Save checks the draft before writing anything. If the check fails, Termorq doesn’t write the file, doesn’t leave the page, and doesn’t start a run. The Not saved panel lists up to 20 reasons, one per line:

Line 19: property 'foo' is not recognised.
Line 23, column 13: malformed YAML.

Steps

1. Open your Pass a value workflow in YAML.
2. Add colour: blue under the greet block and click Save. The panel says property 'colour' is not recognised.
3. Change uses: [steps.make_name.name] to uses: [steps.make_name.nme] and click Save again. Save says 'steps.make_name.nme' is not a property this block can use., because make_name doesn’t declare nme.
4. Undo both changes and Save.

Rules the checker enforces

Unsaved edits

• The title shows Unsaved until you save.
• Run uses the draft on screen. It doesn’t write the file.
• If you leave with unsaved changes (via Back, Esc, the shortcut, or the jump list), Termorq asks Stay, Discard, or Save. Focus starts on Stay.

Reference: Build a workflow → YAML

Run, watch, and inspect

Watching a run

With prefers-reduced-motion: reduce, the colours and labels stay and the motion is turned off.

Make it fail

1. In Pass a value, change the greet body’s last line to print("not json").
2. Click Run. Greet turns red, and Output says the last non-empty line must be a JSON object.
3. Open the Runs tab and select the run. Every block captured at the start of the run is listed. Blocks that never ran are marked not run.
4. Use Copy input and Copy output on a block to copy exactly what it received and returned. Secret values stay masked.
5. Fix the line and run again.

Pause and Stop

• Pause run lets the current block finish, then holds the next one.
• Stop ends the process tree immediately, without asking for confirmation.

TERMORQ_INPUT is a path

The rule

TERMORQ_INPUT is an environment variable that contains a file path. Open that file, then parse its contents.

• It’s not the JSON itself. Don’t run json.loads(os.environ["TERMORQ_INPUT"]).
• stdin is closed, so reading stdin gets you nothing.
• Code bodies are not template-expanded, so {{ ... }} inside source code stays as literal text.

The file contains only the paths listed in uses, nested exactly as their dotted paths:

uses:
  - trigger.text
  - steps.lookup.total

{"trigger":{"text":"Hello"},"steps":{"lookup":{"total":2}}}

You read data["trigger"]["text"], not a flattened data["text"].

Try it

Paste this workflow. It uses a mock HTTP block, so it makes no network calls:

schema: 1
name: Read input
id: read-input
blocks:
  - id: lookup
    kind: http
    method: GET
    url: mock://users
    outputs:
      type: object
      properties:
        path:
          type: string
  - id: show
    kind: code
    language: python
    uses: [steps.lookup.status, steps.lookup.path]
    body: |
      import json, os, sys
      path = os.environ["TERMORQ_INPUT"]
      print(f"input file: {path}", file=sys.stderr)
      with open(path, encoding="utf-8") as f:
          data = json.load(f)
      print(json.dumps({"summary": f"{data['steps']['lookup']['path']} -> {data['steps']['lookup']['status']}"}))
    outputs:
      type: object
      properties:
        summary:
          type: string

When there’s no input

• If uses is empty, a full run provides no input file, so TERMORQ_INPUT is unset.
• If a listed path isn’t available, for example because the trigger didn’t provide trigger.text, the block fails before your code starts. Listing a path doesn’t give it a default value.

set -euo pipefail
jq -c '{summary: "\(.steps.lookup.path) -> \(.steps.lookup.status)"}' "$TERMORQ_INPUT"

Reference: What TERMORQ_INPUT is for

Every path you can put in uses

Declaring inputs and secrets

schema: 1
name: Greet a city
id: greet-city
secrets:
  - WEATHER_API_KEY
inputs:
  city:
    type: string
blocks:
  - id: greet
    kind: code
    language: python
    uses: [inputs.city, secrets.WEATHER_API_KEY]
    body: |
      import json, os
      data = json.load(open(os.environ["TERMORQ_INPUT"], encoding="utf-8"))
      key_present = bool(data["secrets"]["WEATHER_API_KEY"])
      print(json.dumps({"line": f"Hello {data['inputs']['city']}", "has_key": key_present}))
    outputs:
      type: object
      properties:
        line:
          type: string
        has_key:
          type: boolean

Publishing output and the output schema

Two modes

Both modes also record exit, status, and duration_ms. A non-zero exit code fails the block.

The schema

outputs:
  type: object
  properties:
    count:   { type: number }
    names:   { type: array, items: { type: string } }
    ready:   { type: boolean }
    meta:    { type: object }
    token:   { type: string, secret: true }

The schema supports the keys type, properties, items, enum, secret, and required. Termorq checks each declared property for presence and type (string, number, boolean, object, or array). The run fails if a property is missing or has the wrong type, or if the last line isn’t a JSON object.

A property marked secret: true is drawn in the warning colour on the canvas and masked in run records.

Try it: three ways to fail

Start with this block, which passes:

schema: 1
name: Output rules
id: output-rules
blocks:
  - id: emit
    kind: code
    language: python
    body: |
      import json, sys
      print("diagnostics go to stderr", file=sys.stderr)
      print("an early stdout line is fine")
      print(json.dumps({"count": 2, "names": ["Ada", "Lin"]}))
    outputs:
      type: object
      properties:
        count: { type: number }
        names: { type: array, items: { type: string } }

Now make each of these changes in turn and run the workflow again:

1. Change "count": 2 to "count": "2". The type check fails.
2. Use json.dumps(..., indent=2). The output is pretty-printed, so the last line is just }. It fails.
3. Print [1,2] last. An array isn’t an object, so it fails.

Artifacts are different

To produce a file, such as a CSV report, write it to $TERMORQ_OUTPUT, which is the run’s files/ directory. Writing a file there doesn’t publish a property. To tell later blocks where the file is, publish its name:

import json, os
out = os.path.join(os.environ["TERMORQ_OUTPUT"], "report.csv")
open(out, "w").write("name\nAda\n")
print(json.dumps({"report": "report.csv"}))

    outputs:
      type: object
      properties:
        level:
          type: string
          enum: [low, medium, high]

Reference: Publishing code output

Returning ok

ok is an ordinary boolean property, but it’s an important convention. Shell blocks generated by session capture always end by printing {"ok":true} and declare ok: boolean. The editor’s insertable examples include Return a successful result and Return ok and a property for every language.

If a block declares ok, the last line must include it as a boolean. The string "true" fails.

outputs:
  type: object
  properties:
    ok: { type: boolean }
    summary: { type: string }

summary="3 files cleaned"
# jq -c keeps it on one line and escapes the string safely
jq -nc --arg summary "$summary" '{ok: true, summary: $summary}'

$summary = '3 files cleaned'
@{ ok = $true; summary = $summary } | ConvertTo-Json -Compress

import json
print(json.dumps({"ok": True, "summary": "3 files cleaned"}, separators=(",", ":")))

using System.Text.Json.Nodes;
Console.WriteLine(new JsonObject { ["ok"] = true, ["summary"] = "3 files cleaned" }.ToJsonString());

fn main() {
    // No JSON library without Cargo: only safe when summary has no quotes, backslashes, or newlines.
    let summary = "3 files cleaned";
    println!("{{\"ok\":true,\"summary\":\"{}\"}}", summary);
}

console.log(JSON.stringify({ ok: true, summary: "3 files cleaned" }));

const result: { ok: boolean; summary: string } = { ok: true, summary: "3 files cleaned" };
console.log(JSON.stringify(result));

if [ -d logs ]; then ok=true; else ok=false; fi
jq -nc --argjson ok "$ok" '{ok: $ok, summary: "checked logs"}'

Test one block with Execute step

Steps

1. Select a Code block and choose Open code editor.
2. Type JSON or plain text in Step input.
3. Choose Execute step. Only this block runs. The output panel shows stdout, errors, and published properties.
4. Copy output copies everything in that panel.
5. Save the workflow to keep the sample as input_sample.

How Step input becomes the input file

input_sample in YAML

- id: echo
  kind: code
  language: python
  uses: [trigger.text]
  input_sample: |-
    {"trigger":{"text":"Hello from curl"}}
  body: |
    import json, os
    data = json.load(open(os.environ["TERMORQ_INPUT"], encoding="utf-8"))
    print(json.dumps({"message": data["trigger"]["text"]}))
  outputs:
    type: object
    properties:
      message: { type: string }

input_sample is a test fixture. A trigger or a full run never uses it as a default. A passing Execute step doesn’t prove that the real trigger supplies every path in uses.

import json, os
raw = open(os.environ["TERMORQ_INPUT"], encoding="utf-8").read()
try:
    text = json.loads(raw)["trigger"]["text"]
except (ValueError, KeyError, TypeError):
    text = raw
print(json.dumps({"message": text}))

Working directory, environment, and secrets

Working directory

Each code block starts in the run’s files/ directory:

workflows/runs/<workflow id>/<run id>/
├── run.json        # the run record
├── blocks/         # masked per-block logs
└── files/          # cwd for code; artifacts go here

Your project folder (the workflow’s folder setting) isn’t the working directory, and Termorq never changes it. Use $TERMORQ_FOLDER to read from it.

Variables Termorq sets

The env map

The root env: map adds variables to every code block. Values are templates, so you can pass a secret to trusted code this way:

schema: 1
name: Env demo
id: env-demo
folder: ~/src/acme-apis
timeout_secs: 120
secrets:
  - ACME_TOKEN
env:
  ACME_REGION: eu-west
  ACME_TOKEN: "{{ secrets.ACME_TOKEN }}"
blocks:
  - id: where
    kind: code
    language: bash
    body: |
      echo "cwd=$PWD" >&2
      echo "project=$TERMORQ_FOLDER run=$TERMORQ_RUN" >&2
      test -n "$ACME_TOKEN" && has=true || has=false
      jq -nc --arg r "$ACME_REGION" --argjson has "$has" '{region:$r, has_token:$has}'
    outputs:
      type: object
      properties:
        region: { type: string }
        has_token: { type: boolean }

Timeouts

timeout_secs (default 600) limits how long each block can run. You can change the default for new workflows under Settings → Workflows.

Code file: keep source in your repo

Code file (kind: code_file) works exactly like Code: it has the same input file, the same last-line rule, and the same seven languages. The difference is that the source lives at path, resolved relative to the workflow’s folder.

Steps

1. Set the workflow’s folder to a project, for example ~/src/acme-apis.

2. Save this as scripts/echo.py in that folder:

   import json, os, sys
   data = json.load(open(os.environ["TERMORQ_INPUT"], encoding="utf-8"))
   print(json.dumps({"message": data["trigger"]["text"], "argv": sys.argv[1:]}))

3. Add the block:

- id: from_file
  name: Echo from file
  kind: code_file
  path: scripts/echo.py
  args: --mode fast --verbose
  uses: [trigger.text]
  outputs:
    type: object
    properties:
      message: { type: string }
      argv: { type: array }

Rules

• Language is inferred from the extension: .sh (and unknown extensions) → bash, .ps1 → powershell, .py → python, .cs → csharp, .rs → rust, .js/.mjs → javascript, .ts → typescript. Set language: explicitly for an unusual extension.
• args is a single string split on whitespace. Shell quoting is not applied: args: --name "Ada Lovelace" becomes three arguments, --name, "Ada, and Lovelace". Pass structured values through uses and the input file instead.
• The source is copied into a build directory, and the working directory is the run’s files/. Relative imports and companion files next to the original don’t resolve. Keep scripts self-contained, or use explicit paths built from $TERMORQ_FOLDER.
• Code file isn’t a project launcher: it doesn’t run cargo, npm install, or .csproj builds.
• Code file has no Execute step. Test it with a full run (you’ll need a trigger that supplies trigger.text, or use inputs).

Git file (not runnable yet)

The workaround

# One-time (or in a setup step you trust): check out a reviewed revision
git clone https://github.com/acme/scripts ~/src/acme-scripts
git -C ~/src/acme-scripts checkout v1.4.2

schema: 1
name: Run reviewed script
id: run-reviewed-script
folder: ~/src/acme-scripts
blocks:
  - id: report
    kind: code_file
    path: tools/report.py
    outputs:
      type: object
      properties:
        ok: { type: boolean }

Pinning to a tag or commit you’ve reviewed means the code you run is code you’ve read. That’s also why this route is safer than running whatever happens to be on a remote branch.

- id: build
  kind: code_file
  path: scripts/build.ps1
  args: -Configuration Release

Bash

language: bash

set -euo pipefail
: "${TERMORQ_INPUT:?TERMORQ_INPUT is missing}"
jq -ce '
  if (.trigger.text | type) == "string" then
    {message: .trigger.text}
  else
    error("trigger.text must be a string")
  end
' "$TERMORQ_INPUT"

Things to know

• Workflow Bash is always Bash, even if your terminal tab runs zsh or fish. On Windows, install Git Bash or expose WSL’s bash on PATH.
• set -euo pipefail together with jq -e makes parse and validation errors fail the block.
• Build output with jq -n --arg or --argjson. Never build JSON with echo "{\"message\":\"$x\"}", because quotes or newlines in $x will break it.
• .sh files, and files with unrecognised extensions, default to Bash in Code file.
• ✦ Autogenerate writes Bash that reads each value with jq.

set -euo pipefail
text=$(jq -r '.trigger.text' "$TERMORQ_INPUT")
words=$(wc -w <<<"$text" | tr -d ' ')
jq -nc --argjson words "$words" '{words: $words}'

PowerShell

language: powershell

$ErrorActionPreference = 'Stop'
if ([string]::IsNullOrWhiteSpace($env:TERMORQ_INPUT)) {
    throw 'TERMORQ_INPUT is missing'
}
$data = Get-Content -Raw -LiteralPath $env:TERMORQ_INPUT | ConvertFrom-Json
$text = $data.trigger.text
if ($text -isnot [string]) {
    throw 'trigger.text must be a string'
}
@{ message = $text } | ConvertTo-Json -Compress -Depth 10

Things to know

• Files run with -NoProfile -NonInteractive -ExecutionPolicy Bypass, so your profile isn’t loaded.
• -Raw reads the whole file. -LiteralPath stops PowerShell treating [ and * in the path as wildcards.
• Always use -Compress. Without it, ConvertTo-Json prints several lines and breaks the last-line rule. Add -Depth for nested objects.
• $ErrorActionPreference = 'Stop' turns non-terminating errors into failures.
• Captured Command Prompt commands become PowerShell blocks that call cmd.exe through %ComSpec%.

$data = Get-Content -Raw -LiteralPath $env:TERMORQ_INPUT | ConvertFrom-Json
$t = [string]$data.trigger.text
@{ upper = $t.ToUpperInvariant(); length = $t.Length } | ConvertTo-Json -Compress

Python

language: python

import json
import os

with open(os.environ["TERMORQ_INPUT"], encoding="utf-8") as stream:
    data = json.load(stream)
text = data["trigger"]["text"]
if not isinstance(text, str):
    raise ValueError("trigger.text must be a string")
print(json.dumps({"message": text}, ensure_ascii=False))

Things to know

• The runner looks for python3, then python, and runs it unbuffered (-u). Print statements appear in order.
• An uncaught exception exits with a non-zero code, so the block fails and the traceback appears in the error output.
• ensure_ascii=False keeps Unicode readable. The output is valid JSON either way.
• Use print(..., file=sys.stderr) for diagnostics.
• Only the standard library is guaranteed. If you pip install something, it’s installed for that interpreter on this computer, not for the workflow.

import json, os, re
text = json.load(open(os.environ["TERMORQ_INPUT"], encoding="utf-8"))["trigger"]["text"]
print(json.dumps({"slug": re.sub(r"[^a-z0-9]+", "-", text.lower()).strip("-")}))

C#

language: csharp

using System;
using System.IO;
using System.Text.Json;
using System.Text.Json.Nodes;

var path = Environment.GetEnvironmentVariable("TERMORQ_INPUT")
    ?? throw new InvalidOperationException("TERMORQ_INPUT is missing");
using var input = JsonDocument.Parse(File.ReadAllText(path));
var value = input.RootElement.GetProperty("trigger").GetProperty("text");
if (value.ValueKind != JsonValueKind.String)
    throw new InvalidOperationException("trigger.text must be a string");

Console.WriteLine(new JsonObject { ["message"] = value.GetString() }.ToJsonString());

Things to know

• The runner runs dotnet run snippet.cs using file-based apps. Use top-level statements: you don’t need a class or Main.
• Build output with JsonObject.ToJsonString(). Reflection-based JsonSerializer.Serialize(anonymousObject) may be disabled in file-based apps.
• The first run of a snippet compiles it, so expect a few seconds of start-up.
• An unhandled exception exits with a non-zero code, so the block fails.

Reading plain text

For Execute step with plain text:

using System.Text.Json.Nodes;
var text = File.ReadAllText(Environment.GetEnvironmentVariable("TERMORQ_INPUT")!);
Console.WriteLine(new JsonObject { ["message"] = text }.ToJsonString());

using System.Text.Json;
using System.Text.Json.Nodes;
using var doc = JsonDocument.Parse(File.ReadAllText(Environment.GetEnvironmentVariable("TERMORQ_INPUT")!));
var t = doc.RootElement.GetProperty("trigger").GetProperty("text").GetString() ?? "";
var arr = t.ToCharArray(); Array.Reverse(arr);
Console.WriteLine(new JsonObject { ["reversed"] = new string(arr) }.ToJsonString());

Rust

language: rust
outputs:
  type: object
  properties:
    input_bytes:
      type: number

use std::{env, error::Error, fs};

fn main() -> Result<(), Box<dyn Error>> {
    let path = env::var("TERMORQ_INPUT")?;
    let input = fs::read(path)?;
    println!("{{\"input_bytes\":{}}}", input.len());
    Ok(())
}

Things to know

• The runner compiles with rustc --edition 2024 -O, then runs the binary. There’s no Cargo, so crates such as serde_json aren’t available.
• The standard library has no JSON parser. Use Rust for byte, line, or number processing, and use another language for JSON field transformations.
• Use format! and println! for output. Escape { and } by doubling them. Only interpolate values that can’t contain quotes, backslashes, or newlines, or escape them yourself.
• Returning Err from main exits with a non-zero code, so the block fails.

use std::{env, fs};
fn main() {
    let text = fs::read_to_string(env::var("TERMORQ_INPUT").unwrap()).unwrap();
    println!("{{\"lines\":{}}}", text.lines().count());
}

JavaScript

language: javascript

import { readFileSync } from "node:fs";

const path = process.env.TERMORQ_INPUT;
if (!path) throw new Error("TERMORQ_INPUT is missing");
const data = JSON.parse(readFileSync(path, "utf8"));
const text = data?.trigger?.text;
if (typeof text !== "string") {
  throw new Error("trigger.text must be a string");
}
console.log(JSON.stringify({ message: text }));

Things to know

• The runner writes your code to snippet.mjs, so it’s an ES module: use import, not require. Top-level await works.
• For Code file, .js and .mjs are inferred as JavaScript.
• Node built-ins (node:fs, node:path, and fetch) are available. npm packages aren’t installed for you.
• Never use JSON.stringify(obj, null, 2) for the final line, because it prints several lines.

import { readFileSync } from "node:fs";
const { trigger } = JSON.parse(readFileSync(process.env.TERMORQ_INPUT, "utf8"));
console.log(JSON.stringify({ chars: [...new Set(trigger.text)].sort() }));

TypeScript

language: typescript

import { readFileSync } from "node:fs";

type Input = { trigger?: { text?: unknown } };
const path = process.env.TERMORQ_INPUT;
if (!path) throw new Error("TERMORQ_INPUT is missing");
const data = JSON.parse(readFileSync(path, "utf8")) as Input | null;
const text = data?.trigger?.text;
if (typeof text !== "string") {
  throw new Error("trigger.text must be a string");
}
console.log(JSON.stringify({ message: text }));

Things to know

• Termorq prefers native Node (22.6+), which strips types without type-checking them and ignores tsconfig.json. If native support isn’t available, it uses a tsx executable instead.
• Use only erasable syntax: type annotations, type, interface, and as. Avoid enum, namespace, and parameter properties, because native stripping can’t run them. See Node.js TypeScript support.
• Types don’t validate JSON at run time. Keep the typeof checks.

import { readFileSync } from "node:fs";
type In = { inputs: { names: string[] } };
const { inputs } = JSON.parse(readFileSync(process.env.TERMORQ_INPUT!, "utf8")) as In;
if (!Array.isArray(inputs.names)) throw new Error("inputs.names must be an array");
console.log(JSON.stringify({ count: inputs.names.length, first: inputs.names[0] ?? "" }));

HTTP with mock://

A url beginning with mock:// returns a canned 200 response. It makes no network request. Direct URLs are accepted only for mock://. To call a real API, you use a saved endpoint, which is covered in the next lesson.

schema: 1
name: HTTP mock
id: http-mock
blocks:
  - id: ping
    kind: http
    method: GET
    url: mock://users
    outputs:
      type: object
      properties:
        path: { type: string }
        mock: { type: boolean }
  - id: read
    kind: code
    language: python
    uses: [steps.ping.status, steps.ping.path, steps.ping.body]
    body: |
      import json, os
      d = json.load(open(os.environ["TERMORQ_INPUT"], encoding="utf-8"))["steps"]["ping"]
      print(json.dumps({"line": f"{d['status']} {d['path']} ({len(d['body'])} bytes)"}))
    outputs:
      type: object
      properties:
        line: { type: string }

What HTTP publishes

Templates work in url too, for example url: "mock://users/{{ loop.index }}".

HTTP with a saved endpoint

Steps

1. Add an HTTP endpoint block and choose your saved endpoint in Properties. Its path parameters, query string, headers, and payload are copied onto the block.
2. Build the request body in a Code block first. Don’t put text between JSON quotes in a template, because quotes and newlines in user input would break the JSON.

- id: prepare_http
  kind: code
  language: python
  uses: [steps.echo.message]
  body: |
    import json, os
    data = json.load(open(os.environ["TERMORQ_INPUT"], encoding="utf-8"))
    payload = {"message": data["steps"]["echo"]["message"]}
    print(json.dumps({"request_json": json.dumps(payload)}))
  outputs:
    type: object
    properties:
      request_json: { type: string }

- id: send_http
  kind: http
  endpoint: Create message
  method: POST
  body: "{{ steps.prepare_http.request_json }}"
  outputs:
    type: object
    properties:
      body: { type: string }

Credentials

The endpoint’s saved credentials stay in the OS keychain and are read during credential preflight, before the run starts. macOS decides whether to show a Keychain prompt. Cancel run is available while preflight is in progress. To use a secret directly, declare it under secrets: and use it in a header template such as {{ secrets.API_TOKEN }}. Termorq masks it in the record.

- id: check_created
  kind: decision
  branches:
    - when: steps.send_http.status == 201
      goto: done
    - else: true
      goto: log_failure

MCP tool

Steps

1. Add an MCP tool block. Choose the saved server, connect it, then choose the tool. Its parameters are copied onto the block.
2. Supply arguments as a template that resolves to one JSON object. As with HTTP bodies, serialise it in code first.

- id: echo_tool
  kind: mcp
  server: Demo tools
  tool: echo
  arguments: "{{ steps.prepare_http.request_json }}"
  outputs:
    type: object
    properties:
      content: { type: array }

- id: read_tool
  kind: code
  language: python
  uses: [steps.echo_tool.content]
  body: |
    import json, os
    content = json.load(open(os.environ["TERMORQ_INPUT"], encoding="utf-8"))["steps"]["echo_tool"]["content"]
    texts = [c.get("text", "") for c in content if c.get("type") == "text"]
    print(json.dumps({"reply": " ".join(texts)}))
  outputs:
    type: object
    properties:
      reply: { type: string }

What MCP publishes

• status: ok, a text representation of the result, and the top-level properties of the MCP result, such as content or structuredContent.
• JSON inside a content[].text string is not turned into workflow properties automatically. Parse it in a Code block.
• If the arguments don’t resolve to a JSON object, the block fails with MCP arguments must resolve to a JSON object.

When a run starts, Termorq connects to the saved server automatically if it isn’t connected yet. If the block fails, open @logs to see whether the credential lookup or the connection failed.

AI block

- id: summarise
  kind: ai
  connection: Summary model
  system: 'Return a single JSON object with a string property named "summary".'
  prompt: "Summarise this message in one sentence: {{ steps.echo.message }}"
  max_tokens: 128
  input_sample: |-
    {"trigger":{"text":"Deploy finished in 4m with 2 warnings"}}
  outputs:
    type: object
    properties:
      summary: { type: string }

How it works

• system and prompt are templates. Values you insert are sent to the model, and secrets are masked in the run record.
• The block always publishes text (the reply) and model.
• If you declare another property, such as summary, Termorq asks the model to end its reply with one JSON object and reads that final line. If the reply doesn’t end with that object, the block fails.
• A new AI block starts with a prompt that already includes earlier properties, and a default summary output.

Test it in isolation

Select the block and choose Open AI editor. Type JSON or plain text in Step input and choose Execute step:

The editor shows the response, errors, published output, and any skills used. Isolated tests don’t start triggers or create a Runs entry. input_sample is saved with the workflow, but a full run never uses it.

  system: 'Classify the message. Reply with one JSON object: {"severity": "info"|"warning"|"error"}.'
  prompt: "{{ steps.echo.message }}"
  outputs:
    type: object
    properties:
      severity:
        type: string
        enum: [info, warning, error]

✦ Autogenerate

Steps

1. Open a Code block’s code editor and click where you want the code to go. The panel remembers the cursor position. If you never clicked in the editor, the code is appended at the end.
2. Choose ✦ Autogenerate on the Snippet row.
3. Choose the Source node. The node wired into this block is selected first. The list shows how many steps back each node is, and shows input if the workflow declares inputs.
4. Review the fields:
   • AI, and nodes with a complete schema: lists their declared outputs and says Schema complete — nothing to add.
   • HTTP: status (number) is always included. body and any top-level JSON keys from the last run are marked Will add to this node’s output schema.
   • MCP, and code without a schema: shows an inferred checklist (text, tool-result fields, or keys from the last run). Fields whose type can’t be inferred are shown in amber with a type picker, defaulting to string. Unchecked fields are left out.
5. Check the Preview, which is written in the block’s language. If code above the cursor already opens TERMORQ_INPUT, the preview reuses that variable. Bash previews use jq.
6. Choose Insert, or Add schema & Insert if fields will be added to the source node’s schema.

What Insert changes

• The code goes on its own lines, tinted teal with an Inserted at cursor (or Appended) badge.
• Each path, such as steps.fetch_users.status, is added to this block’s uses.
• Any new fields are added to the source node’s output schema, so Available data and Save accept them.
• Undo in the notice restores the snippet, uses, and the source schema together. The tint and the notice last 10 seconds by default. You can change this to between 1 and 60 seconds under Settings → Workflows → Code editor.

Reference: Autogenerate code from an earlier node

Decision: choose one route

schema: 1
name: Decision demo
id: decision-demo
inputs:
  text:
    type: string
blocks:
  - id: echo
    kind: code
    language: python
    uses: [inputs.text]
    body: |
      import json, os
      d = json.load(open(os.environ["TERMORQ_INPUT"], encoding="utf-8"))
      print(json.dumps({"message": d["inputs"]["text"].strip()}))
    outputs:
      type: object
      properties:
        message: { type: string }

  - id: choose
    kind: decision
    branches:
      - when: steps.echo.message != ""
        goto: has_text
      - else: true
        goto: empty_text

  - id: has_text
    kind: code
    language: python
    body: |
      import json; print(json.dumps({"route": "non-empty"}))
    outputs:
      type: object
      properties:
        route: { type: string }
    then: joined

  - id: empty_text
    kind: code
    language: python
    body: |
      import json; print(json.dumps({"route": "empty"}))
    outputs:
      type: object
      properties:
        route: { type: string }
    then: joined

  - id: joined
    kind: http
    url: mock://done

Rules

• Termorq evaluates branches in order, and the first true when wins.
• else: true is the required fallback.
• goto names a block ID. Blocks that aren’t chosen are marked Skipped.
• Set then on each branch block so the routes converge. Without it, has_text would carry on to empty_text, because that’s next in file order.
• A shared continuation must not require outputs from both branches, because one of them didn’t run.

Condition language

Conditions compare workflow values. They’re not Bash, JavaScript, or C#.

In the editor, the larger When box suggests properties from earlier blocks. Drag the When and Else handles onto blocks to set their targets.

    branches:
      - when: steps.echo.message contains "urgent"
        goto: escalate
      - when: steps.echo.message != ""
        goto: has_text
      - else: true
        goto: empty_text

Loop: for each item

schema: 1
name: Loop names
id: loop-names
blocks:
  - id: names
    kind: code
    language: python
    body: |
      import json; print(json.dumps({"items": ["Ada", "Lin", "Grace"]}))
    outputs:
      type: object
      properties:
        items: { type: array, items: { type: string } }

  - id: each_name
    kind: loop
    for_each: steps.names.items
    max: 20
    body:
      - id: greet
        kind: code
        language: python
        uses: [loop.item, loop.index, loop.count]
        body: |
          import json, os
          d = json.load(open(os.environ["TERMORQ_INPUT"], encoding="utf-8"))["loop"]
          print(json.dumps({"greeting": f"Hello {d['item']} ({d['index']}/{d['count']})"}))
        outputs:
          type: object
          properties:
            greeting: { type: string }

  - id: count_passes
    kind: code
    language: python
    uses: [steps.each_name.results]
    body: |
      import json, os
      r = json.load(open(os.environ["TERMORQ_INPUT"], encoding="utf-8"))["steps"]["each_name"]["results"]
      print(json.dumps({"count": len(r), "first": r[0]["greet"]["greeting"]}))
    outputs:
      type: object
      properties:
        count: { type: number }
        first: { type: string }