From History to Runbooks: Saving Terminal Commands

The first time you lost a critical command, you started saving them somewhere. That’s how it begins for every engineer.

The way we save terminal commands has evolved dramatically. Understanding this evolution helps you choose the right approach for your team.

Generation 1: Shell History

The shell has always saved terminal commands. Unix systems have had command history since the 1970s.

# The original way to save terminal commands
history
!123  # Re-run command 123
!!    # Re-run last command

What It Got Right

• Automatic—no effort required
• Fast retrieval with ctrl+r
• Works everywhere

What It Got Wrong

• No organization or categorization
• Lost between machines
• No documentation or context
• Limited retention

Shell history was designed for convenience, not knowledge management. It’s still useful for recalling recent commands, but it’s not a system.

Generation 2: Dot Files and Aliases

Engineers started saving terminal commands in configuration files:

# .bashrc or .zshrc
alias k="kubectl"
alias gp="git push"
alias dc="docker-compose"

# Functions for complex commands
deploy() {
  git push origin main
  ssh prod "cd /app && git pull && systemctl restart app"
}

What It Got Right

• Persistent and portable (with dotfile repos)
• Fast execution
• Version controllable

What It Got Wrong

• Only works for your shell
• Hard to share with the team
• No documentation
• Complex operations become unmaintainable

Dot files work for personal productivity. They fail for team operations.

Generation 3: Wikis and Documentation

As teams grew, they needed shared ways to save terminal commands:

# Production Restart Procedure

1. SSH to production server
2. Run: `systemctl stop app`
3. Clear cache: `rm -rf /tmp/cache/*`
4. Start: `systemctl start app`
5. Verify: `curl localhost:8080/health`

Confluence, Notion, internal wikis—everyone had somewhere to document commands.

What It Got Right

• Shareable across the team
• Documentation and context
• Searchable

What It Got Wrong

• Commands go stale without anyone noticing
• Copy-paste introduces errors
• No execution, just reading
• Often forgotten and outdated

Wikis turned commands into documents. But documents don’t execute, and they decay.

Generation 4: Scripts and Automation

The next step was making saved commands executable:

#!/bin/bash
# restart-production.sh

set -e

echo "Stopping application..."
ssh prod "systemctl stop app"

echo "Clearing cache..."
ssh prod "rm -rf /tmp/cache/*"

echo "Starting application..."
ssh prod "systemctl start app"

echo "Verifying health..."
ssh prod "curl -f localhost:8080/health"

echo "Done!"

What It Got Right

• Actually executable
• Version controllable
• Reliable execution

What It Got Wrong

• All-or-nothing execution
• Hard to modify on the fly
• Scripts become complex and unmaintainable
• Separate from documentation

Scripts are powerful but inflexible. When step 3 fails, you want to investigate before continuing. Scripts don’t allow that.

Generation 5: Executable Runbooks

The current evolution: save terminal commands as executable documentation.

# Production Restart

## Stop Application

​```bash
ssh prod "systemctl stop app"
​```

## Clear Cache

​```bash
ssh prod "rm -rf /tmp/cache/*"
​```

## Start Application

​```bash
ssh prod "systemctl start app"
​```

## Verify Health

​```bash
ssh prod "curl -f localhost:8080/health"
​```

With the right tooling, each code block becomes a runnable cell. You get the documentation of a wiki with the execution of a script.

What It Gets Right

• Human-readable documentation
• Step-by-step execution
• Version controllable
• Shareable and collaborative
• Commands stay accurate because they’re used

The Trade-off

• Requires tooling to execute

The Pattern

Each generation solved the previous generation’s problems:

Generation	Problem Solved	New Problem
Shell History	Remembering commands	No organization
Dot Files	Personal efficiency	Not shareable
Wikis	Team knowledge	Commands decay
Scripts	Automation	Inflexible execution
Executable Runbooks	Living documentation	Needs tooling

What’s Next?

The next evolution is already emerging: AI-assisted runbooks that can adapt to context, suggest next steps, and even auto-remediate issues.

But the foundation remains the same: save terminal commands in a format that’s human-readable, version-controlled, and executable.

Stew is built on this foundation. Write Markdown, execute it step-by-step, keep it in Git.

Join the waitlist and save terminal commands the modern way.