CmdGPT

CmdGPT is an AI-powered terminal assistant that lets developers execute commands using natural language. It detects your project type, interprets your request, generates the right commands, and executes them safely.

💡 No API key required — works fully offline using built-in pattern matching. Optionally connect OpenAI or Anthropic for smarter responses.

cmdgpt start my app
cmdgpt show my docker containers
cmdgpt push my code
cmdgpt setup laravel project
cmdgpt fix

---

⚡ CmdGPT in Action

🎬 Demo GIF coming soon — see assets/README.md for instructions on recording your own.

Run cmdgpt fix after a failed command — CmdGPT analyzes the error and suggests or applies the fix automatically.

---

Getting Started

npm install -g @devabdool/cmdgpt

Then just type what you want to do:

cmdgpt start my app
# → Detects your project type and runs the right start command

cmdgpt fix
# → Analyzes your last terminal error and suggests a fix

cmdgpt explain docker compose up -d
# → Explains what the command does in plain English

No configuration needed. For AI-powered responses, optionally add your API key:

export OPENAI_API_KEY=sk-...   # or ANTHROPIC_API_KEY

---

Features

Feature	Description
🧠 Natural Language Execution	Convert plain English into terminal commands
🔍 Project Detection	Auto-detect Laravel, Node, React, Next.js, Django, Docker, Kubernetes, Flutter, Go, Python, and more
🔐 Security Filter	Block dangerous commands like rm -rf /, shutdown, mkfs, fork bombs
🐛 Error Analyzer	Explain terminal errors and suggest or apply fixes
💡 Command Explainer	Describe what any shell command does
🚀 Project Setup	Scaffold new projects with a single command
🔌 Plugin Architecture	Modular plugins for Laravel, Node, Docker, Git, Flutter, Kubernetes
🤖 Multi-Provider AI	Optional AI-powered interpretation via OpenAI (GPT-4o-mini) or Anthropic (Claude)
⚙️ Provider Config	Choose your AI provider with cmdgpt config set provider <openai|anthropic>

---

Installation

npm install -g @devabdool/cmdgpt

Or run locally after cloning:

git clone https://github.com/devabdool/CmdGPT.git
cd CmdGPT
npm install
npm link          # makes `cmdgpt` available globally

---

Real-World Examples

🐘 Run a Laravel App

cd my-laravel-project
cmdgpt start my app
# → php artisan serve

🐳 Fix a Docker Error

# After a failed `docker compose up`:
cmdgpt fix
# → CmdGPT reads the error, explains the cause, and suggests a fix

cmdgpt fix --error "Cannot connect to the Docker daemon"
# → sudo systemctl start docker

🚀 Push Code to GitHub

cmdgpt push my code
# → git add . && git commit -m "chore: update files" && git push

🛠️ Set Up a Brand-New Project

cmdgpt setup react
# → npx create-react-app my-app

cmdgpt setup laravel
# → composer create-project laravel/laravel my-app

☸️ Manage Kubernetes Pods

cmdgpt list pods
# → kubectl get pods

cmdgpt restart deployment api
# → kubectl rollout restart deployment/api

---

Usage

Natural Language Command Execution

cmdgpt start my app
cmdgpt run "start my app"
cmdgpt run --dry-run "start my app"   # preview without executing

CmdGPT detects your project type and maps the intent:

Project	Intent	Command(s)
Laravel	start my app	php artisan serve
Node.js	start my app	npm start
Flutter	start my app	flutter run
Django	start my app	python manage.py runserver

Docker Commands

cmdgpt show my docker containers    # → docker ps
cmdgpt show all containers          # → docker ps -a
cmdgpt stop containers              # → docker compose down
cmdgpt start containers             # → docker compose up -d

Git Commands

cmdgpt push my code                 # → git add . && git commit -m "update" && git push
cmdgpt git status                   # → git status
cmdgpt git log                      # → git log --oneline -20

Kubernetes Commands

cmdgpt list pods                    # → kubectl get pods
cmdgpt get services                 # → kubectl get services
cmdgpt apply config                 # → kubectl apply -f .

Explain a Command

cmdgpt explain docker compose up -d
cmdgpt explain git rebase
cmdgpt explain kubectl get pods

Fix Terminal Errors

# Save an error to analyze later
cmdgpt save-error "npm ERR! Cannot read properties of undefined"

# Analyze and optionally fix
cmdgpt fix

# Or pass error text directly
cmdgpt fix --error "bash: flutter: command not found"

Setup a New Project

cmdgpt setup laravel
cmdgpt setup react
cmdgpt setup flutter
cmdgpt setup node

Detect Project Type

cmdgpt detect
# ✔ Project type: Next.js (React) (nextjs)

View and Set Configuration

# Show current config
cmdgpt config get

# Set AI provider
cmdgpt config set provider openai      # use OpenAI (GPT-4o-mini by default)
cmdgpt config set provider anthropic   # use Anthropic (Claude)

# Override the model used by a provider
cmdgpt config set openaiModel gpt-4o
cmdgpt config set anthropicModel claude-3-5-sonnet-20241022

# Show a single key
cmdgpt config get provider

---

AI Provider Integration (Optional)

CmdGPT works fully offline using built-in pattern matching. For advanced AI-powered interpretation, configure a provider.

OpenAI

export OPENAI_API_KEY=sk-...
# or pin it in config:
cmdgpt config set provider openai

CmdGPT will use GPT-4o-mini by default. Override:

cmdgpt config set openaiModel gpt-4o

Anthropic (Claude)

export ANTHROPIC_API_KEY=sk-ant-...
# or pin it in config:
cmdgpt config set provider anthropic

CmdGPT will use Claude 3 Haiku by default. Override:

cmdgpt config set anthropicModel claude-3-5-sonnet-20241022

Provider Priority

When both API keys are set, CmdGPT picks the provider in this order:

1. provider field in ~/.cmdgpt.json (set with cmdgpt config set provider)
2. OPENAI_API_KEY env var → openai
3. ANTHROPIC_API_KEY env var → anthropic
4. No AI (offline pattern matching only)

---

Project Structure

cmdgpt/
├── bin/
│   └── cmdgpt.js          # CLI entry point
├── core/
│   ├── config.js           # Read/write ~/.cmdgpt.json; resolve provider/model/key
│   ├── aiProvider.js       # Unified AI provider (OpenAI + Anthropic)
│   ├── projectDetector.js  # Detects project type from working directory files
│   ├── aiInterpreter.js    # Interprets natural language into commands
│   ├── commandExecutor.js  # Executes commands sequentially with streaming output
│   ├── securityFilter.js   # Blocks dangerous commands
│   └── errorAnalyzer.js    # Analyzes terminal errors and suggests fixes
├── plugins/
│   ├── laravel.js          # Laravel / PHP commands
│   ├── node.js             # Node.js / React / Next.js / Vue / Angular commands
│   ├── docker.js           # Docker / Docker Compose commands
│   ├── git.js              # Git commands
│   ├── flutter.js          # Flutter / Dart commands
│   └── kubernetes.js       # Kubernetes / kubectl commands
├── utils/
│   └── logger.js           # Colored console logger
├── tests/
│   ├── config.test.js
│   ├── securityFilter.test.js
│   ├── projectDetector.test.js
│   ├── aiInterpreter.test.js
│   └── errorAnalyzer.test.js
└── package.json

---

Supported Project Types

Indicator File	Detected Type
artisan	Laravel
pubspec.yaml	Flutter
manage.py	Django
requirements.txt / setup.py / pyproject.toml	Python
go.mod	Go
docker-compose.yml	Docker
Dockerfile	Docker
package.json (with next)	Next.js
package.json (with react)	React
package.json (with vue)	Vue.js
package.json (with @angular/core)	Angular
package.json (with express)	Express.js
package.json (with @nestjs/core)	NestJS
package.json	Node.js
Gemfile	Ruby / Rails
pom.xml / build.gradle	Java / Spring
Cargo.toml	Rust

---

Security

CmdGPT blocks dangerous commands before execution. Blocked patterns include:

• rm -rf / and variants
• shutdown, reboot, halt, poweroff
• mkfs, dd if=... of=/dev/...
• sudo rm, sudo mkfs
• Fork bombs (:(){ :|:& };:)
• Disk-wiping commands

All commands are shown to the user with a confirmation prompt before being executed.

---

Development

# Install dependencies
npm install

# Run tests
npm test

# Run CLI locally
node bin/cmdgpt.js --help

---

Plugin API

Each plugin exports a resolve(intent) function and a commands map:

// plugins/myPlugin.js
const commands = {
  'my intent': ['my-tool command'],
};

function resolve(intent) {
  const lower = intent.toLowerCase();
  for (const [key, cmds] of Object.entries(commands)) {
    if (lower.includes(key)) return cmds;
  }
  return null;
}

module.exports = { resolve, commands };

Register your plugin in core/aiInterpreter.js by adding it to PROJECT_PLUGIN_MAP.

---

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines on how to get started.

---

License

MIT © devabdool