Brian Munene | Full Stack Developer

The scene: You just switched to your backend project.

The question: Is it npm run dev, npm start, or python manage.py runserver?

Your action: Open README. Scroll. Find command. Copy. Run.

The problem: You do this 20 times a day.

I got tired of it. So I built runbook-cli.

The Friction We Ignore

Every developer faces this. Multiple projects, different commands:

Project A (Node.js):

npm run dev

Project B (Python):

python manage.py runserver

Project C (Go):

go run main.go

Project D (Node.js, but different):

npm start

The pattern: Context switch → forget command → check README → run.

It's small friction. But 20 times a day? That's 30 minutes wasted just remembering commands.

Why Existing Solutions Don't Work

"Just use package.json scripts"

{
  "scripts": {
    "dev": "vite"
  }
}

Problems:

Node.js only (what about Python, Go, Rust?)
Need to remember to check package.json
Still need to open the file

"Just use Makefiles"

dev:
    npm run dev

Problems:

Need to create Makefile for every project
Still need to remember make dev vs make start
Makefile syntax is arcane

"Just check the README"

Problems:

Have to open a file
Have to scroll/search
Documentation goes stale

"Just remember"

Problems:

You have 10+ projects
Commands change
New team members are lost

None of these solve the real problem: Too much mental overhead for simple tasks.

Enter runbook-cli

The idea: Set commands once. Run them forever. From anywhere.

Set Once

cd my-project
runbook set dev "npm run dev"
runbook set test "npm test"
runbook set build "npm run build"

Run Forever

# 3 months later, from any subfolder
cd my-project/src/components
runbook dev

# Output:
# → Running: npm run dev
# [your dev server starts]

That's it.

How It Works: The Magic

1. Finds Git Root Automatically

cd my-project/src/pages/user/profile
runbook dev

runbook-cli walks up the directory tree until it finds .git. That's your project root.

Works from anywhere in your project.

2. Stores Commands in `.runbook`

{
  "dev": "npm run dev",
  "test": "npm test",
  "build": "npm run build"
}

Simple JSON file in project root. Human-readable. Git-committable.

3. Runs Commands in Project Root

Even if you run runbook dev from a subfolder, it executes in the project root where it matters.

No more cd ../../../ && npm run dev

Real-World Usage

My Workflow (Before runbook-cli)

Switch to project
"Wait, how do I run this?"
Open README
Scroll past installation, features, screenshots
Find "Development" section
Copy command
Run it
Time wasted: 45 seconds

My Workflow (After runbook-cli)

Switch to project
runbook dev
Time wasted: 0 seconds

Savings: 45 seconds × 20 times/day = 15 minutes/day = 91 hours/year

Beyond Simple Commands

Multi-Step Commands

# Install dependencies AND start server
runbook set dev "npm install && npm run dev"

# Build AND deploy
runbook set deploy "npm run build && firebase deploy"

# Run tests AND lint AND commit
runbook set commit "npm test && npm run lint && git commit"

Background Services

# Start Docker services
runbook set up "docker-compose up -d"

# Start multiple servers
runbook set full "cd backend && python manage.py runserver & cd frontend && npm start"

Different Environments

runbook set dev "npm run dev"
runbook set staging "NODE_ENV=staging npm start"
runbook set prod "NODE_ENV=production npm start"

Team Benefits: The Game Changer

Onboarding (Before)

New dev joins your team:

"Hey, how do I run this project?"

"Oh, you need to install dependencies, set up env vars, run migrations, then start the server. Let me show you..."

30 minutes of explanation.

Onboarding (After)

New dev joins your team:

"Hey, how do I run this project?"

"runbook dev"

10 seconds.

How It Works

You set up commands: runbook set dev "npm install && npm run dev"
You commit .runbook to git
New dev clones the repo
They run runbook dev
They're coding in 10 seconds

No documentation needed. No explanation needed. Just works.

Cross-Language Projects

I work on:

Frontend (Node.js)
Backend (Python)
CLI tools (Go)
Scripts (Bash)

Each has different commands. runbook-cli handles them all:

Frontend

cd frontend
runbook set dev "npm run dev"

Backend

cd backend
runbook set dev "python manage.py runserver"

CLI Tool

cd cli-tool
runbook set dev "go run main.go"

Monorepo

cd my-monorepo
runbook set frontend "cd frontend && npm start"
runbook set backend "cd backend && python manage.py runserver"
runbook set all "docker-compose up"

One tool. Every language. Every project.

Comparison: runbook vs Alternatives

Feature	runbook	README	Makefile	package.json
Works in subfolders	✅ Yes	❌ No	❌ No	❌ No
Cross-language	✅ Yes	✅ Yes	✅ Yes	❌ Node only
Zero config	✅ Yes	❌ Write docs	❌ Write Makefile	❌ Edit JSON
Instant recall	✅ `runbook` shows all	❌ Search file	❌ Read Makefile	❌ Open file
Team sharing	✅ Commit `.runbook`	⚠️ Maintain docs	⚠️ Maintain Makefile	⚠️ Node projects
Learning curve	✅ 30 seconds	N/A	❌ Make syntax	N/A

Real User Feedback

From @dev_mike on Twitter:

"I have 15 microservices. Each runs differently. runbook-cli saved my sanity. Thank you!"

From @sarah_codes:

"Onboarded 3 new devs this week. All of them said 'wait, that's it?' when I told them to run runbook dev. Best tool ever."

From Reddit r/node:

"Why didn't this exist before? This should be built into npm."

Building runbook-cli: Technical Deep Dive

For the devs who want to know how it works:

Tech Stack

TypeScript: Type safety, great DX
Commander.js: CLI argument parsing
Node.js child_process: Execute commands
fs module: Read/write .runbook file

Key Functions

Finding project root:

function findGitRoot(startPath: string): string | null {
  let currentPath = startPath;
  
  while (true) {
    if (existsSync(join(currentPath, '.git'))) {
      return currentPath;
    }
    
    const parentPath = join(currentPath, '..');
    if (parentPath === currentPath) {
      return null; // Reached filesystem root
    }
    
    currentPath = parentPath;
  }
}

Storing commands:

function saveCommand(name: string, command: string): void {
  const runbookPath = join(getProjectRoot(), '.runbook');
  const commands = loadCommands(); // Read existing
  commands[name] = command;
  writeFileSync(runbookPath, JSON.stringify(commands, null, 2));
}

Running commands:

function runCommand(name: string): void {
  const command = getCommand(name);
  
  spawn(command, [], {
    shell: true,
    stdio: 'inherit',
    cwd: getProjectRoot() // Always run in project root
  });
}

Total lines of code: ~300

Total complexity: Low

Why it works: Solves one problem really well.

Installation & Quick Start

Install Globally

npm install -g runbook-cli

In Your Project

cd my-project

# Set commands
runbook set dev "npm run dev"
runbook set test "npm test"
runbook set build "npm run build"

# Commit to git
git add .runbook
git commit -m "Add runbook commands"

# Run from anywhere
cd src/components
runbook dev

List Commands

runbook list

# or just
runbook

Short Alias

rb dev  # Same as runbook dev

Advanced Usage

Project-Specific Commands

# E-commerce project
runbook set seed "node scripts/seed-db.js"
runbook set workers "node workers/queue.js"

# Mobile app
runbook set ios "cd ios && pod install && npm run ios"
runbook set android "cd android && ./gradlew clean && npm run android"

# Microservices
runbook set auth "cd services/auth && go run main.go"
runbook set api "cd services/api && python main.py"
runbook set web "cd services/web && npm start"

Chaining Commands

runbook set deploy "npm test && npm run build && git push && vercel deploy"

Environment Variables

runbook set dev "PORT=3000 NODE_ENV=development npm start"
runbook set prod "PORT=8080 NODE_ENV=production node dist/server.js"

What's Next

Coming Features

Command aliases (e.g., d for dev)
Command history (see what you ran recently)
Global commands (set commands that work everywhere)
Interactive mode (GUI for setting commands)
Bash completion (tab to autocomplete)

Open Source

Full source code: github.com/brian-mwirigi/runbook-cli

Want a feature? Open an issue

Found a bug? Submit a PR

The Philosophy

runbook-cli embodies a simple principle:

Developer tools should remove friction, not add ceremony.

No config files
No setup wizards
No documentation to read
Just: set, run, done

This is what productivity looks like.

Try It Today

Install

npm install -g runbook-cli

Set Your First Command

cd your-project
runbook set dev "YOUR_DEV_COMMAND"

Run It

runbook dev

Never Forget Again

Other Tools I've Built:

aitoken-cli - Track AI API costs
codesession-cli - Track coding sessions

Follow my journey: @brian_mwirigi

Read more: brianmunene.me/blog

TL;DR: Stop checking README for project commands. Use runbook-cli. Set once, run forever, from any subfolder. Works for Node, Python, Go, Rust – any language. Free, open source, takes 30 seconds to set up.

Spending 15 minutes/day remembering project commands? Install runbook-cli and get that time back.

npm install -g runbook-cli

Stop Remembering Project Commands: I Built a Tool

The Friction We Ignore

Why Existing Solutions Don't Work

"Just use package.json scripts"

"Just use Makefiles"

"Just check the README"

"Just remember"

Enter runbook-cli

Set Once

Run Forever

How It Works: The Magic

1. Finds Git Root Automatically

2. Stores Commands in .runbook

3. Runs Commands in Project Root

Real-World Usage

My Workflow (Before runbook-cli)

My Workflow (After runbook-cli)

Beyond Simple Commands

Multi-Step Commands

Background Services

Different Environments

Team Benefits: The Game Changer

Onboarding (Before)

Onboarding (After)

How It Works

Cross-Language Projects

Frontend

Backend

CLI Tool

Monorepo

Comparison: runbook vs Alternatives

Real User Feedback

From @dev_mike on Twitter:

From @sarah_codes:

From Reddit r/node:

Building runbook-cli: Technical Deep Dive

Tech Stack

Key Functions

Installation & Quick Start

Install Globally

In Your Project

List Commands

Short Alias

Advanced Usage

Project-Specific Commands

Chaining Commands

Environment Variables

What's Next

Coming Features

Open Source

The Philosophy

Try It Today

Install

Set Your First Command

Run It

Never Forget Again

2. Stores Commands in `.runbook`