Skip to content

Terminal

Terminal block
Terminal block

The Terminal block provides a fully functional, interactive shell directly within your Runbook. It behaves just like your local terminal, respecting your system configuration, environment variables, and shell preferences.

To execute a command, simply type it into the code input field and hit the play button.

The terminal processes your input just as if you had typed it directly into your shell. Everything runs in the background, so you can navigate away, continue editing your Runbook, or collaborate with others while your command executes.

Everything within the input box is fed as input for the terminal, so interactive sessions can be nested as deep as you'd like. There is much more flexibility here than a normal bash script, with the following caveats

  1. We cannot detect when a command within a terminal ends - we hope to have this resolved soon, but there's an additional layer of complexity here
  2. Standard output cannot be captured directly. As we are emulating a terminal, the output contains a multitude of control codes, prompt output, etc. However, you can set template variables using $ATUIN_OUTPUT_VARS (see Variables section below). If you need to work with stdout directly, we recommend using a script block.
  3. Terminals are slower than scripts. Because we're spinning up a new pseudo-terminal in the background, startup time and resource usage will be a bit higher than a script
  4. Interactive input can sometimes feel unnatural, and the scripting process is different than writing a bash script

Variables

While terminal blocks don't support capturing stdout directly, they can set template variables when the terminal session exits. This is done by writing to the $ATUIN_OUTPUT_VARS file.

Usage:

# Simple format for single-line values
echo "name=value" >> $ATUIN_OUTPUT_VARS
echo "another_var=another_value" >> $ATUIN_OUTPUT_VARS

# Heredoc format for multiline values
echo "notes<<EOF" >> $ATUIN_OUTPUT_VARS
echo "This is line 1" >> $ATUIN_OUTPUT_VARS
echo "This is line 2" >> $ATUIN_OUTPUT_VARS
echo "EOF" >> $ATUIN_OUTPUT_VARS

# For longer multiline strings, use a command group for efficiency
{
  echo "myvar<<EOF"
  echo "Some"
  echo "Multiline"
  echo "String"
  echo "EOF"
} >> $ATUIN_OUTPUT_VARS
  • Format: Two formats supported:
  • Simple: KEY=VALUE entries, one per line
  • Heredoc: KEY<<DELIMITER followed by content lines until DELIMITER (for multiline values)
  • Timing: Variables are captured when the terminal exits
  • Location: Works with both local and remote (SSH) terminal sessions

Example:

# Set variables during an interactive session
echo "session_id=$(uuidgen)" >> $ATUIN_OUTPUT_VARS
echo "current_dir=$(pwd)" >> $ATUIN_OUTPUT_VARS

# Set a multiline variable with command output
echo "file_list<<END" >> $ATUIN_OUTPUT_VARS
ls -la >> $ATUIN_OUTPUT_VARS
echo "END" >> $ATUIN_OUTPUT_VARS

# Continue with other terminal commands
ls -la

These variables can then be referenced in other blocks:

{{var.session_id}}
{{var.current_dir}}

See the templating section for full information on template variables.

Block Output

Terminal blocks produce structured output that can be accessed in templates after the terminal session ends. See Block Output for general information on accessing block output.

Raw PTY Output

Terminal output is raw PTY data which may include control codes, escape sequences, and other terminal formatting. For clean, parsed output, consider using a Script block instead.

Accessing Terminal Results

{%- set output = doc.named['my_terminal'].output %}

Received {{ output.byte_count }} bytes

Output Fields

Field Type Description
output string Raw terminal output (UTF-8 lossy conversion from PTY bytes)
byte_count number Total number of bytes received from the PTY
cancelled boolean true if cancelled by user, false if terminal exited naturally

Example Usage

{%- set output = doc.named['debug_terminal'].output %}

{% if output.cancelled %}
  Terminal was cancelled by user
{% else %}
  Terminal exited normally
{% endif %}

Total output: {{ output.byte_count }} bytes

{# Note: output contains raw PTY data with escape codes #}

When to Use Terminal vs Script Output

Use Case Recommended Block
Capturing clean stdout/stderr Script block
Checking exit codes Script block
Raw session logging Terminal block
Interactive debugging Terminal block
Setting variables Either (via $ATUIN_OUTPUT_VARS)