09-shell.md

Shell Commands

Unknown commands run as shell commands automatically.

ls -la
whoami
date

Pipes

echo "hello world" | tr a-z A-Z
ls -la | head -5

Redirects

echo "test" > /tmp/output.txt
echo "more" >> /tmp/output.txt
ls /nonexistent 2>/dev/null

Capture Output

Use backticks to capture command output into a variable:

hostname = `hostname`
puts "Running on #{hostname}"

Backticks run the command and return stdout as a trimmed string. String interpolation works inside backticks:

name = "world"
greeting = `echo hello #{name}`
puts greeting   # hello world

Mix Shell and Rugo

name = "World"
puts "Hello, #{name}!"
echo "this runs in the shell"
result = `uname -s`
puts "OS: #{result}"

Shell Exit Codes

Failed shell commands exit the script immediately, just like bash. Use try to catch failures:

# Without try — script exits on failure
rm /tmp/nonexistent-file

# With try — script continues
try rm /tmp/nonexistent-file
puts "still running"

See Error Handling for the full try/or reference.

Pipe Operator

The | pipe operator connects shell commands with Rugo functions. The left side's output flows as input to the right side.

# Shell output to a function
echo "hello world" | puts

# Chain through module functions
use "str"
echo "hello" | str.upper | puts    # HELLO

# Pipe a value to a shell command's stdin
"hello" | tr a-z A-Z | puts        # HELLO

# Assign piped result
name = echo "rugo" | str.upper
puts name                           # RUGO

Shell-to-shell pipes still work as before:

echo "hello" | tr a-z A-Z          # handled by the shell natively

Note: The pipe passes return values, not stdout. puts and print return nil, so using them in the middle of a chain is a compile error — always put them at the end:

ls | puts | head        # ✗ compile error
ls | head | puts        # ✓ puts at the end

Known Limitations

• # comments: Rugo strips # comments before shell fallback detection, so unquoted # in shell commands is treated as a comment. Use quotes: echo "issue #123" instead of echo issue #123.
• Shell variable syntax: FOO=bar is interpreted as a Rugo assignment, not a shell environment variable. Use bash -c "FOO=bar command" instead.

---

Next: Modules