cmdy Documentation

Record and replay complex CLI workflows as simple commands

🚀 Quick Start

1️⃣

Install

Get cmdy globally

2️⃣

Authenticate

3️⃣

Record & Play

Save and reuse workflows

# 1. Install cmdy
npm i -g @cmdy/cli

# 2. Get your token from app.cmdy.dev and login
cmdy login <your-token>

# 3. Record a workflow
cmdy record my-workflow
# ... enter your commands ...
# exit

# 4. Replay anytime
cmdy play my-workflow

Features

🔐

Authentication

with web portal integration

🎬

Record

command sequences with complex args and inputs and save them as mnemonics

🎭

Replay

saved command sequences

👤

User management

with token-based authentication

💾

Portal App

to easily manage all the mnemonics

⚡

Cross-platform

support for macOS, and Linux

📦 Installation

Install cmdy globally using your preferred package manager:

# npm (recommended)
npm i -g @cmdy/cli

# pnpm
pnpm add -g @cmdy/cli

# yarn
yarn global add @cmdy/cli

Verify it's working:

cmdy --version
cmdy --help

🔐 Authentication

Before you start: You need to authenticate with the web portal first. All commands except login, logout, and help require authentication.

1. Get Your Token

Go to app.cmdy.dev
Sign in with Google
Go to your dashboards/token
Create and copy your API token

2. Login

cmdy login <your-token>

You'll see something like:

🔐 Validating token...
✅ Successfully authenticated!
👤 Logged in as: John Doe (john@example.com)

3. Verify (Optional)

Check your login status:

cmdy me

🎬 Core Usage

Recording Commands

Save a sequence of commands as a memorable name:

cmdy record my-deploy

Then enter your commands one by one:

🎬 Recording started. Enter commands to record.
💡 Type "exit" or ":wq" to stop recording.

📝 cmdy> npm run build
✓ Recorded: npm run build
📝 cmdy> docker build -t myapp .
✓ Recorded: docker build -t myapp .
📝 cmdy> docker push registry.com/myapp
✓ Recorded: docker push registry.com/myapp
📝 cmdy> exit

🎬 Recording stopped. Saved as "my-deploy"

Playing Commands

Run your saved workflow anytime:

cmdy play my-deploy

Preview before running (dry run):

cmdy play my-deploy --dry-run

⚡ Advanced Features

Interactive Commands

cmdy automatically captures interactive input like passwords, editor sessions, and prompts:

Example: Git workflow with commit message

cmdy record git-commit
📝 cmdy> git add .
📝 cmdy> git commit -m "Added new feature"
📝 cmdy> exit

# Later, replay with the exact same interactions
cmdy play git-commit

Example: SSH with password

cmdy record connect-server
📝 cmdy> ssh user@server.com
# Password prompt appears, you type password
📝 cmdy> exit

# Replays with the same password input
cmdy play connect-server

Dynamic Arguments

Use placeholders in your commands and fill them when replaying:

# During recording, use real values
cmdy record deploy
📝 cmdy> docker build -t myapp:v1.0.0 .
📝 cmdy> docker push registry.com/myapp:v1.0.0
📝 cmdy> exit

# In the portal, edit to use placeholders:
# docker build -t myapp:<version> .
# docker push registry.com/myapp:<version>

# Now you can replay with any version
cmdy play deploy --version=v2.0.0

Error Handling

Control what happens when commands fail:

# Stop on first error (default)
cmdy play deploy

# Continue even if commands fail
cmdy play deploy --continue

💡 Common Use Cases

Project Setup

Automate setting up new development environments:

cmdy record setup-project
📝 cmdy> npm install
📝 cmdy> cp .env.example .env
📝 cmdy> npm run db:migrate
📝 cmdy> npm run dev
📝 cmdy> exit

# Anyone can now set up the project instantly
cmdy play setup-project

Testing & CI

Bundle your entire test suite:

cmdy record run-tests
📝 cmdy> npm run lint
📝 cmdy> npm run type-check
📝 cmdy> npm test
📝 cmdy> npm run e2e
📝 cmdy> exit

cmdy play run-tests

Deployment

Deploy with version management:

cmdy record deploy
📝 cmdy> npm run build
📝 cmdy> docker build -t myapp:<version> .
📝 cmdy> docker push registry.com/myapp:<version>
📝 cmdy> kubectl set image deployment/myapp myapp=registry.com/myapp:<version>
📝 cmdy> exit

# Deploy any version
cmdy play deploy --version=v1.2.3

Database Operations

Safely manage database changes:

cmdy record db-backup-and-migrate
📝 cmdy> pg_dump mydb > backup-$(date +%Y%m%d).sql
📝 cmdy> npm run migrate
📝 cmdy> npm run seed
📝 cmdy> exit

cmdy play db-backup-and-migrate

🆘 Getting Help

Need help?

• Check command help: cmdy --help or cmdy <command> --help
• View your workflows: app.cmdy.dev
• Report issues: GitHub

System Requirements

• Node.js 22.14.0+
• macOS or Linux
• Internet connection for sync

Common Commands

• cmdy login <token> - Authenticate
• cmdy record <name> - Record workflow
• cmdy play <name> - Run workflow
• cmdy me - Check login status