Kumander: A Command-Line Tool for Managing Terminal Commands

If you work heavily with the command line, you know the pain of managing complex commands. Kumander is a tool I built to solve this problem by letting you store and execute commands from markdown files.

The Problem with Command-Line Workflows

Every developer has faced these scenarios:

Scrolling through hundreds of shell history entries looking for that one AWS sync command with all the right flags
Copying complex commands from Slack, Notion, or README files into the terminal
Maintaining a sprawling .bashrc or .zshrc file full of cryptic aliases
Onboarding new team members who need to learn your project's command incantations

Traditional solutions like shell aliases work, but they have limitations. Aliases are hard to document, difficult to share, and quickly become unmaintainable as your collection grows.

What Kumander Does

Kumander turns this:

aws s3 sync . s3://my-bucket/path \
  --exclude "*.git/*" \
  --exclude "node_modules/*" \
  --exclude "vendor/*" \
  --delete

Into this:

km aws sync-my-bucket

The commands live in markdown files that are easy to read, edit, and share with your team. No more digging through shell history or maintaining scattered alias files.

Kumander Usage Demo

Quick Start

1. Install Kumander

# Using curl
curl -o- https://raw.githubusercontent.com/christopheredrian/kumander/main/install.sh | bash

# Or using wget
wget -qO- https://raw.githubusercontent.com/christopheredrian/kumander/main/install.sh | bash

The installer sets up Kumander in ~/.kumander and configures your shell automatically.

2. Open the Commands Directory

code ~/.kumander/commands

3. Create Your First Command File

Create a markdown file (e.g., aws.md) with the following structure:

# AWS Commands

## sync-my-bucket

Sync local directory to S3 bucket excluding development files

```bash
aws s3 sync . s3://my-bucket/path \
  --exclude "*.git/*" \
  --exclude "node_modules/*" \
  --exclude "vendor/*" \
  --delete
```

4. Run Your Command

# Syntax: km <filename> <command>
km aws sync-my-bucket

Key Features

Documentation-First Approach

Commands are stored in markdown files, which means they're inherently documented. The heading becomes the command name, and any text between the heading and the code block serves as documentation. This approach gives you:

Syntax highlighting in any text editor
Easy readability for team members
Version control friendly format
Commands that document themselves

Shell Completion Support

Kumander provides built-in completions for both Bash and Zsh, making command discovery fast and intuitive. Just start typing and press Tab to see available files and commands.

Customizable Command Directory

By default, commands live in ~/.kumander/commands, but you can customize this:

# Set a custom directory via environment variable
export KUMANDER_COMMANDS_DIR="/path/to/your/commands"

# Or use the --dir flag for temporary overrides
km --dir /project/commands deploy start

This flexibility enables:

Project-specific command sets
Team-shared command repositories
Multiple command collections for different contexts

Simple, Intuitive Syntax

The command structure follows a predictable pattern:

km [file] [command]

Run km alone to list all available command files
Run km <file> to list commands within a specific file
Run km <file> <command> to execute a command

Real-World Use Cases

DevOps & Deployment

# Deploy Commands

## staging

Deploy to staging environment with safety checks

```bash
./scripts/pre-deploy-check.sh && \
kubectl config use-context staging && \
kubectl apply -f k8s/staging/
```

## production

Deploy to production with confirmation

```bash
read -p "Deploy to PRODUCTION? (yes/no) " confirm && \
[[ $confirm == "yes" ]] && \
kubectl config use-context production && \
kubectl apply -f k8s/production/
```

Database Operations

# Database Commands

## backup-prod

Create a timestamped backup of production database

```bash
pg_dump $DATABASE_URL > backups/prod_$(date +%Y%m%d_%H%M%S).sql
```

## restore-local

Restore latest backup to local development database

```bash
psql -d myapp_dev < $(ls -t backups/*.sql | head -1)
```

Docker Workflows

# Docker Commands

## rebuild

Clean rebuild of all containers

```bash
docker-compose down -v && \
docker-compose build --no-cache && \
docker-compose up -d
```

## logs

Follow logs from all services

```bash
docker-compose logs -f --tail=100
```

How It Compares to Alternatives

Feature	Kumander	Shell Aliases	Makefiles	npm scripts
Documentation support	✅ Built-in	❌ None	⚠️ Comments only	⚠️ Limited
Easy to read	✅ Markdown	❌ Dense syntax	⚠️ Make syntax	❌ Single-line JSON
Multi-line commands	✅ Natural	⚠️ Awkward	✅ Yes	⚠️ Escaped
Shell completions	✅ Bash & Zsh	❌ Manual setup	❌ Manual setup	⚠️ Plugin required
Shareable	✅ Just copy files	⚠️ Export needed	✅ Yes	✅ Yes
No dependencies	✅ Pure shell	✅ Pure shell	❌ Requires make	❌ Requires Node.js

Similar Tools

If you're interested in the markdown-as-command-file concept, you might also explore makedown (Python-based, supports multiple interpreters like bash, python, and javascript with custom hashbangs) which takes a similar approach but with different trade-offs. Kumander focuses on pure shell simplicity with zero runtime dependencies beyond bash itself.

Why I Built This

I found myself repeatedly:

Searching through shell history for complex commands
Copying commands from various documentation and README files
Sharing commands with team members through chat or docs
Maintaining unwieldy alias files that no one could understand

Kumander solves these problems by providing a simple way to organize and execute commands while keeping them documented and shareable. The markdown format means your commands are always readable, whether you're viewing them in VS Code, on GitHub, or in any text editor.

Installation Details

What the Installer Does

The install script:

Creates the ~/.kumander directory
Downloads kumander.sh (the main script)
Sets up a sample commands directory
Adds configuration to your shell profile (.bashrc, .zshrc, or .bash_profile)
Creates the km alias for quick access

Uninstalling

If you decide Kumander isn't for you:

# Remove the Kumander directory
rm -rf ~/.kumander

Then remove these lines from your shell configuration file:

# Kumander Configuration
export KUMANDER_COMMANDS_DIR="$HOME/.kumander/commands"
alias km='kumander'
source $HOME/.kumander/kumander.sh

Contributing

Kumander is open source under the GPL license. Contributions are welcome:

Fork the repository
Create your feature branch
Make your changes and commit them
Submit a pull request

Whether it's bug fixes, new features, or documentation improvements, all contributions help make Kumander better for everyone.

Get Started

Ready to streamline your command-line workflow? Install Kumander today:

curl -o- https://raw.githubusercontent.com/christopheredrian/kumander/main/install.sh | bash

Links:

GitHub Repository
TrenchDevs Blog
Contact: christopheredrian@trenchapps.com