How CLI Nodes Work

CLI nodes execute shell commands inside Nix-managed environments. You declare the tools you need, Radhflow enters a nix-shell with those packages, runs your command, and captures the output. Nothing is installed globally. The same pipeline runs identically on any machine with Nix.

How it works

1. Declare packages. List Nix packages in nix.packages.
2. Define the command. Write the shell command in params.command. Use {{ }} templates for input fields.
3. Radhflow enters nix-shell. At execution time, a transient shell is created with only the declared packages available.
4. Command runs. stdin, stdout, and exit code are captured.
5. Output is collected. The result is returned as a Record or Table.

No system-wide installs. No version conflicts. No “works on my machine.”

Example: convert video with ffmpeg

convert-video:
  type: deterministic
  op: cli.run
  params:
    command: >
      ffmpeg -i {{ input_path }}
      -vf scale=1280:720
      -c:v libx264 -preset fast
      -c:a aac
      {{ output_path }}
    nix:
      packages:
        - ffmpeg
  inputs:
    request:
      type: Record
      from: ref(prepare.config)
      schema:
        input_path: { type: string }
        output_path: { type: string }
  outputs:
    result:
      type: Record
      schema:
        exit_code: { type: number }
        stdout: { type: string }
        stderr: { type: string }

Radhflow resolves ffmpeg from nixpkgs, enters a shell with it available, runs the command, and returns the result. The host system does not need ffmpeg installed.

Batch execution

When the input is a Table, the command runs once per row. Template expressions resolve against each row independently.

resize-images:
  type: deterministic
  op: cli.run
  params:
    command: >
      convert {{ source }} -resize 800x600 {{ dest }}
    nix:
      packages:
        - imagemagick
  inputs:
    files:
      type: Table
      from: ref(list-images.files)
  outputs:
    results: { type: Table }

Nix configuration

The nix block declares the shell environment. Packages are pulled from nixpkgs. Pin a revision for full reproducibility.

nix:
  packages: [pandoc, texlive.combined.scheme-small]
  nixpkgs: github:NixOS/nixpkgs/nixos-24.05   # optional pin

Output capture

By default, CLI nodes capture stdout, stderr, and exit code as a Record.

Field	Type	Description
exit_code	number	Process exit code. 0 means success.
stdout	string	Standard output content.
stderr	string	Standard error content.

For commands that produce files, reference the output path in downstream nodes.

params:
  command: >
    pandoc {{ input }} -o artifacts/{{ name }}.pdf
  artifacts:
    - path: "artifacts/{{ name }}.pdf"
      type: file

Config reference

Field	Required	Default	Description
command	Yes	—	Shell command to execute. Supports {{ }} templates.
nix.packages	Yes	—	List of Nix packages available in the shell.
nix.nixpkgs	No	Latest stable	Pinned nixpkgs revision for reproducibility.
artifacts	No	—	Files produced by the command.