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