← Back to blog

Save Terminal Commands as Executable Docs

· 4 min read · Stew Team
save terminal commandsdocumentationexecutable runbooks

You have two choices for operational knowledge: documentation that nobody reads, or scripts that nobody understands.

There’s a third option. Save terminal commands as executable documentation—files that are both human-readable and machine-runnable.

The Documentation vs. Automation Dilemma

Most teams face a painful trade-off:

Option A: Documentation

# Restart API Service

1. Check current pod status
2. Run: kubectl rollout restart deployment/api -n prod
3. Watch the rollout until complete
4. Verify health endpoint responds

Problem: Nobody runs documentation during incidents. They improvise, make mistakes, and skip steps.

Option B: Automation Scripts

#!/bin/bash
kubectl get pods -n prod -l app=api
kubectl rollout restart deployment/api -n prod
kubectl rollout status deployment/api -n prod
curl -f http://api.internal/health

Problem: When something goes wrong mid-script, you’re stuck. Scripts don’t explain themselves, and modifying them on the fly is risky.

The Third Option: Executable Documentation

What if you could save terminal commands in a format that’s both?

# Restart API Service

Check current pod status before proceeding:

​```bash
kubectl get pods -n prod -l app=api
​```

Restart the deployment:

​```bash
kubectl rollout restart deployment/api -n prod
​```

Watch rollout progress (wait for completion before proceeding):

​```bash
kubectl rollout status deployment/api -n prod
​```

Verify the health endpoint:

​```bash
curl -f http://api.internal/health
​```

With the right tooling, you can run each code block as a cell—see output, make decisions, then proceed.

Why This Works Better

1. Commands Stay Accurate

When you save terminal commands as executable documentation, you discover errors immediately. A typo in a wiki goes unnoticed for months. A typo in an executable runbook fails the first time someone runs it.

2. Context Survives

Scripts strip context. Documentation preserves it. Executable documentation gives you both:

## Clear Redis Cache

**When to use:** Users report stale data after deployment

**Warning:** This affects all users immediately

​```bash
redis-cli -h redis.internal FLUSHDB
​```

**Verification:** Check that the data_version key is gone:

​```bash
redis-cli -h redis.internal GET data_version
​```

3. Flexibility During Incidents

At 3am, you need flexibility:

  • Run step 1, check the output
  • Modify step 2 based on what you see
  • Skip step 3 because it doesn’t apply
  • Add an ad-hoc command

Scripts can’t do this. Executable documentation can.

4. Easier Code Review

Pull requests for documentation feel pointless. Pull requests for scripts feel risky. Executable documentation hits the sweet spot—reviewers can read the explanation AND verify the commands.

5. Onboarding Accelerates

New team members can read the documentation to understand procedures, then execute them with guardrails. They’re not blindly running scripts or improvising from wiki pages.

How to Save Terminal Commands This Way

Use Markdown

Markdown is the universal format. It’s readable everywhere, version-controllable, and simple to write:

## Section Title

Explanation of what this does.

​```bash
command --with --flags
​```

Store in Git

Put your runbooks in the same repository as your code:

my-service/
├── src/
├── runbooks/
│   ├── deploy.md
│   ├── rollback.md
│   └── debug-latency.md
└── README.md

Use Descriptive File Names

When you save terminal commands, name files for what they do, not what they are:

# Good
restart-api.md
clear-redis-cache.md
failover-database.md

# Bad
procedure-1.md
runbook.md
commands.md

Include Metadata

Add frontmatter for searchability:

---
title: Restart API Service
owner: platform-team
last-tested: 2024-01-15
services: [api, kubernetes]
---

# Restart API Service
...

Making It Executable

Markdown alone isn’t executable. You need tooling that:

  1. Parses Markdown files
  2. Identifies code blocks
  3. Lets you run them individually
  4. Displays output inline
  5. Handles SSH for remote execution

That’s what Stew provides. Take your existing Markdown, open it in Stew, and each code block becomes a runnable cell.

Start Simple

You don’t need to rewrite everything. Start with one procedure:

  1. Pick your most common incident response command
  2. Save terminal commands in a Markdown file
  3. Add context around each command
  4. Put it in Git
  5. Use it next time that incident occurs

Once you see the benefit, expand from there.

Join the waitlist and make your saved commands executable.