dops

<a id="readme-top"></a>

<!-- PROJECT SHIELDS --> <div align="center">

[![GitHub Release][release-shield]][release-url] [![Go Version][go-shield]][go-url] [![License][license-shield]][license-url] [![Tests][tests-shield]][tests-url] [![Security][security-shield]][security-url]

</div> <!-- PROJECT LOGO --> <div align="center"> <img src="assets/logos/logo-2048.png" alt="dops logo" width="320" /> <h3>the do(ops) cli</h3> <p>A browsable catalog of automation scripts that operators can select, parameterize, and execute directly from the terminal.</p> <p> <a href="https://demo.rundops.dev"><strong>Try the Live Demo</strong></a> &middot; <a href="https://rundops.dev/">Documentation</a> &middot; <a href="https://github.com/masonhuemmer/dops/issues">Report Bug</a> &middot; <a href="https://github.com/masonhuemmer/dops/issues">Request Feature</a> </p> </div> <br /> <div align="center"> <img src="assets/demo.gif" alt="dops demo" width="900" /> </div> <br /> <div align="center"> <em>Also available in the browser:</em> <code>dops open</code> <br /><br /> <img src="assets/web-demo.gif" alt="dops web UI demo" width="900" /> </div> <br /> <div align="center"> <em>Or let AI agents run your runbooks:</em> <code>dops mcp serve</code> <br /><br /> <img src="assets/mcp-demo.gif" alt="dops MCP demo" width="900" /> </div> <br /> <!-- TABLE OF CONTENTS --> <details> <summary>Table of Contents</summary> <ol> <li><a href="#about">About</a></li> <li><a href="#features">Features</a></li> <li><a href="#installation">Installation</a></li> <li><a href="#quick-start">Quick Start</a></li> <li><a href="#themes">Themes</a></li> <li><a href="#web-ui">Web UI</a></li> <li><a href="#mcp-integration">MCP Integration</a></li> <li><a href="#keyboard-shortcuts">Keyboard Shortcuts</a></li> <li><a href="#shell-completion">Shell Completion</a></li> <li><a href="#development">Development</a></li> <li><a href="#getting-help">Getting Help</a></li> <li><a href="#license">License</a></li> </ol> </details> <!-- ABOUT -->

About

dops is built for DevOps and platform engineering teams who need a consistent, safe way to run operational scripts. Instead of scattered shell scripts with tribal knowledge, dops organizes them into browsable catalogs with built-in parameter management, risk controls, and encrypted credential storage.

<p align="right">(<a href="#readme-top">back to top</a>)</p> <!-- FEATURES -->

Features

• Interactive TUI — sidebar catalog tree, metadata panel, live output pane, and wizard-driven parameter input
• Web UI — browser-based interface via dops open with real-time log streaming
• Catalog system — organize runbooks locally or install shared catalogs from git repositories
• Runbook aliases — short names for frequently used runbooks (dops run deploy instead of full IDs)
• Risk controls — confirmation gates for high/critical risk runbooks, per-catalog risk policies
• Encrypted vault — saved parameters encrypted with age (X25519 + ChaCha20-Poly1305)
• Smart parameter input — saved values auto-applied, only prompts for what's needed
• Live execution — real-time stdout/stderr streaming with scroll, search, and text selection
• Execution history — persistent audit trail across TUI, CLI, Web, and MCP with dops history and web UI timeline
• MCP server — expose runbooks as tools and skills to AI agents via the Model Context Protocol
• MCP skills — injectable domain knowledge for AI agents via type: skill runbooks
• 20 themes — github, dracula, gruvbox, nord, synthwave, unicorn, and more
• CLI mode — run any runbook non-interactively with dops run <id> --param key=value

<p align="right">(<a href="#readme-top">back to top</a>)</p> <!-- SCREENSHOTS --> <details> <summary><strong>Screenshots</strong> (click to expand)</summary> <br />

TUI — Startup <br /> <img src="assets/hero-startup.png" alt="dops startup" width="900" /> <br /><br />

TUI — Sidebar search <br /> <img src="assets/hero-sidebar.png" alt="dops sidebar search" width="900" /> <br /><br />

TUI — Wizard parameter input <br /> <img src="assets/hero-wizard-input.png" alt="dops wizard input" width="900" /> <br /><br />

TUI — Multi-select <br /> <img src="assets/hero-wizard-multiselect.png" alt="dops multi-select" width="900" /> <br /><br />

TUI — Risk confirmation <br /> <img src="assets/hero-confirm.png" alt="dops risk confirmation" width="900" /> <br /><br />

TUI — Live execution output <br /> <img src="assets/hero-execution.png" alt="dops execution" width="900" /> <br /><br />

TUI — Output search <br /> <img src="assets/hero-search.png" alt="dops output search" width="900" /> <br /><br />

TUI — Help overlay <br /> <img src="assets/hero-help.png" alt="dops help" width="900" /> <br /><br />

Web UI — Catalog & parameter form <br /> <img src="assets/web-ui-catalog.png" alt="dops web UI catalog" width="900" /> <br /><br />

Web UI — Execution log <br /> <img src="assets/web-ui-execution.png" alt="dops web UI execution" width="900" />

</details> <p align="right">(<a href="#readme-top">back to top</a>)</p> <!-- INSTALLATION -->

Installation

Quick install

curl -fsSL https://raw.githubusercontent.com/masonhuemmer/dops/main/install.sh | sh

Installs the latest binary to /usr/local/bin. Set DOPS_INSTALL_DIR to change the location.

Windows

winget install RunDops.dops

Or via Scoop:

scoop bucket add masonhuemmer https://github.com/masonhuemmer/scoop-bucket.git
scoop install dops

Or download the latest .zip from the releases page and add dops.exe to your PATH.

Homebrew

brew tap masonhuemmer/tap
brew install dops

Go

go install github.com/masonhuemmer/dops@latest

Docker (MCP server)

The image is private. Run docker login ghcr.io with a GitHub token that has read:packages and access to this package before pulling.

docker run -i -v ~/.dops:/data/dops ghcr.io/masonhuemmer/dops:latest

From source

git clone https://github.com/masonhuemmer/dops.git
cd dops
make build
./bin/dops

<p align="right">(<a href="#readme-top">back to top</a>)</p> <!-- QUICK START -->

Quick Start

1. Initialize dops:

dops init

This creates ~/.dops/ with a default config and a sample hello-world runbook.

2. Launch the TUI:

dops

3. Navigate with arrow keys, run with Enter, fill in parameters, and confirm.

4. Or launch the web UI:

dops open

5. Install a shared catalog:

dops catalog install https://github.com/your-org/runbooks.git

Catalog structure

Catalogs are directories of runbooks. Each runbook is a folder with a runbook.yaml and a script.sh:

my-catalog/
├── check-health/
│   ├── runbook.yaml
│   └── script.sh
└── deploy-service/
    ├── runbook.yaml
    └── script.sh

Runbook example

name: check-health
version: 1.0.0
description: Runs health checks against a service endpoint
risk_level: medium
script: script.sh
parameters:
  - name: endpoint
    type: string
    required: true
    description: The endpoint to check
    scope: global

See the runbook guide for the full YAML schema, parameter types, and shell scripting conventions.

<p align="right">(<a href="#readme-top">back to top</a>)</p> <!-- THEMES -->

Themes

dops ships with 20 built-in themes. Default: github.

dops config set theme=dracula

| | | | | |---|---|---|---| | github | dracula | gruvbox | nord | | monokai | synthwave | nightowl | one-dark | | kanagawa | everforest | solarized | espresso | | unicorn | ayu | zenburn | catppuccin-mocha | | catppuccin-latte | rosepine-dawn | doop | tokyomidnight |

Set theme=rainbow for a random theme on every launch.

Custom themes go in ~/.dops/themes/<name>.json. See the configuration reference for the theme schema.

<p align="right">(<a href="#readme-top">back to top</a>)</p> <!-- WEB UI -->

Web UI

Launch a browser-based interface with dops open:

dops open              # opens http://localhost:3000
dops open --port 8080  # custom port
dops open --no-browser # start server without opening browser

The web UI provides:

• Searchable catalog sidebar with risk indicators
• Parameter forms with saved values pre-filled
• Risk confirmation dialogs for high/critical operations
• Real-time execution log streaming with ANSI color support
• Full theme support — mirrors your configured dops theme

The SPA is embedded in the Go binary — no Node.js required at runtime. See the Web UI guide for details.

<p align="right">(<a href="#readme-top">back to top</a>)</p> <!-- MCP INTEGRATION -->

MCP Integration

dops exposes runbooks to AI agents via the Model Context Protocol. Each runbook becomes an MCP tool with a JSON Schema.

Claude Code

Add to .claude/settings.json:

{
  "mcpServers": {
    "dops": {
      "command": "dops",
      "args": ["mcp", "serve"]
    }
  }
}

Docker

Authenticate as described in Docker installation before running the private image.

# stdio transport
docker run -i -v ~/.dops:/data/dops ghcr.io/masonhuemmer/dops:latest

# HTTP transport
docker run -p 8080:8080 -v ~/.dops:/data/dops ghcr.io/masonhuemmer/dops:latest --transport http --port 8080

See the MCP guide for details on risk controls, resources, and streaming.

<p align="right">(<a href="#readme-top">back to top</a>)</p> <!-- KEYBOARD SHORTCUTS -->

Keyboard Shortcuts

| Key | Action | |-----|--------| | ↑↓ | Navigate / scroll | | Enter | Run runbook | | ←→ | Collapse/expand catalog | | / | Search | | Tab | Switch pane focus | | ? | Help overlay | | ctrl+x | Stop execution | | ctrl+shift+p | Command palette | | q | Quit |

See the full keyboard reference for output pane controls, search navigation, and wizard shortcuts.

<p align="right">(<a href="#readme-top">back to top</a>)</p> <!-- SHELL COMPLETION -->

Shell Completion

# Bash
dops completion bash > /etc/bash_completion.d/dops

# Zsh
dops completion zsh > "${fpath[1]}/_dops"

# Fish
dops completion fish > ~/.config/fish/completions/dops.fish

# PowerShell
dops completion powershell | Out-String | Invoke-Expression

<p align="right">(<a href="#readme-top">back to top</a>)</p> <!-- DEVELOPMENT -->

Development

make build        # Build binary
make test         # Run tests
make vet          # Go vet
make lint         # golangci-lint
make web          # Build web UI (requires Node.js)
make screenshots  # Regenerate README hero screenshots and demo GIF (requires VHS)
make web-demo     # Record web UI demo GIF (requires Playwright + ffmpeg)
make docker       # Build Docker image
make ci           # Run CI checks (vet + test + build)

<p align="right">(<a href="#readme-top">back to top</a>)</p> <!-- GETTING HELP -->

Getting Help

• Documentation — guides, reference, and configuration
• GitHub Issues — bug reports and feature requests
• CLI Reference — all commands and flags

<p align="right">(<a href="#readme-top">back to top</a>)</p> <!-- SUPPORT -->

Support

If you find dops useful, consider [buying me a coffee]