AI memory layer for developers — remembers your workflows, heals your errors.
Nebula-CLI is a terminal agent that learns from your commands and automatically fixes failures. When a command fails, it analyzes the error, suggests a fix, and lets you apply it with one keystroke.
Core capabilities:
- Self-healing: Detects command failures, diagnoses the issue, suggests and applies fixes
- Workflow memory: Remembers successful command patterns and suggests them proactively
- Natural language: Convert descriptions into shell commands
- Session persistence: Resume interrupted work with full context
Demo flow (30 seconds)
- Command failure: Run
nebula docker compose up -dwhen port is occupied - Error analysis: Nebula captures the exit code and error output
- Fix suggestion: AI diagnoses the issue and suggests a fix command
- Apply fix: User presses
yto apply the suggested fix - Success: Command completes successfully with the suggested fix applied
The GIF above is a placeholder while the recording is produced. Here is what a real session looks like:
$ nebula docker compose up -d
Bind for 0.0.0.0:5432 failed: port is already allocated
Nebula is analyzing the failure...
Suggested fix: docker compose up -d -p 5433:5432
Apply? [y/n]: y
Container started on 0.0.0.0:5433
Fix saved to workflow memory — the same error will be healed instantly next time.
Prerequisites: Node.js 20+.
# Install from source (npm package pending release)
git clone git@github.com:sagar0163/Nebula_cli.git
cd Nebula_cli
npm install
npm link
# Run setup wizard (configures AI provider and API keys)
nebula setup
# Start interactive session
nebula
# Or run a one-shot command with auto-healing
nebula docker compose up -dOnce published, the same install works in one line: npm install -g @sagar/nebula-cli.
Nebula-CLI includes a layered safety system for every command it runs.
Preview what a command would do without executing it:
nebula --dry-run "kubectl delete pod nginx"
nebula -d "rm -rf build/" # short formIn dry-run mode commands are skipped, and each attempt is recorded in the audit log with an dry-run outcome.
Every suggestion and executed command is rated 0 (very safe) → 100 (very dangerous):
| Score | Meaning |
|---|---|
| 0 | Read-only / safe (e.g. ls, kubectl get pods) |
| 10 | Safe read verbs (get, describe, list, status) |
| 50 | Unknown / manual execution required |
| 90 | High danger ($(command) injection, unsafe pipes) |
| 100 | Critical (rm -rf /, mkfs, kubectl delete) |
View the score for any command:
nebula analyze "rm -rf ."- Syntax check — parses every command with
bash-parser; unparseable commands are blocked (fail-closed). - Block list — destructive patterns (
rm -rf,mkfs,dd, DB drops,kubectl delete,git push --force, secret dumping, fork bombs, path traversal, SQL injection). - Pipe/executor guard — only known-safe filter utilities are allowed as pipe targets; interpreters (
bash,python,node -e…) are blocked.
Every command execution is recorded to ~/.nebula/audit/audit.jsonl:
{"id":"…","timestamp":"…","user":"sagar","command":"kubectl get pods","risk":"low","score":0,"outcome":"success","cwd":"/project","message":"exit=0"}Fields: id, timestamp, user, hostname, command, risk, score, outcome, cwd, message.
Enterprise export (JSON or CSV):
NEBULA_AUDIT_DIR=/var/log/nebula nebula status # see where logs live
node -e "import('./src/utils/audit-logger.js').then(m => console.log(m.exportAudit({format:'csv'})))"Configurable per-environment rules via nebula-safety.json (or ~/.nebula/safety.json), selected by NEBULA_ENV:
{
"defaultEnvironment": "development",
"environments": {
"development": { "allowDestructive": true, "maxScore": 90, "blockedPatterns": [] },
"staging": { "allowDestructive": false, "maxScore": 50, "blockedPatterns": ["/drop\\s+database/i"] },
"production": { "allowDestructive": false, "maxScore": 30, "blockedPatterns": ["/rm\\s+-rf\\s+\\//", "/mkfs/"] }
},
"sandbox": { "enabled": false, "image": "node:20-alpine", "network": "none", "cpus": "0.5", "memory": "256m" },
"rollback": { "enabled": true, "snapshotDir": "~/.nebula/snapshots" },
"audit": { "enabled": true, "dir": "~/.nebula/audit" }
}Untrusted code can be executed inside an isolated Docker container with network blocking and resource limits:
--network none— blocks all egress for suspicious code--cpus 0.5and--memory 256m— resource limits prevent fork bombs- Falls back to local execution when Docker is unavailable
File operations are snapshot-backed. Before a risky mutation Nebula snapshots the affected files to ~/.nebula/snapshots/<id>/ and can restore them:
import { createSnapshot, restoreSnapshot, listSnapshots } from './src/utils/rollback.js';
const id = createSnapshot(['package.json']);
// ... risky change ...
restoreSnapshot(id); // undo
listSnapshots(); // inspect available snapshotsRun nebula status to view current safety posture: active environment, Docker sandbox availability, pending snapshots, audit log location, and dry-run mode.
The setup wizard walks you through:
- Selecting an AI provider (OpenAI, Anthropic, Google Gemini, Groq, or local Ollama)
- Entering your API key (stored in
.env, never committed) - Choosing a model (defaults to cost-effective options)
- Enabling optional features (memory encryption, auto-heal)
Starting nebula without arguments opens an interactive shell where:
- Every command you run is monitored for failures
- Failed commands trigger automatic error analysis
- Fixes are suggested and can be applied with one keystroke
- Successful patterns are remembered for future suggestions
$ nebula docker compose up -d
Error: Bind for 0.0.0.0:5432 failed: port is already allocated
# Nebula analyzes the error and suggests:
Suggested: docker compose up -d -p 5433:5432
Apply? [y/n]: y$ nebula git push
error: failed to push some refs to 'origin'
hint: Updates were rejected because the remote contains work you do not have locally.
# Nebula suggests the safe resolution:
Suggested: git pull --rebase origin main && git push
Apply? [y/n]: y$ nebula npm test
FAIL src/api/auth.test.js
● Authentication middleware › should reject invalid tokens
# Nebula analyzes test output and explains:
The test expects a 401 status but receives 500.
Check: src/middleware/auth.js line 42 - token validation logic$ nebula find all TypeScript files modified in the last week, excluding node_modules
Generated: find . -name "*.ts" -type f -mtime -7 ! -path "*/node_modules/*"
Run? [y/n]: y| Command | Description |
|---|---|
nebula |
Start interactive session (default) |
nebula setup |
Configuration wizard for API keys and models |
nebula <command> |
Run command with auto-healing on failure |
nebula ask "<question>" |
Get step-by-step plan for a task |
nebula chat "<prompt>" |
General AI chat (planning/design) |
nebula predict |
Scan project and predict next command |
nebula analyze "<cmd>" |
Analyze command for risks |
nebula pty "<cmd>" |
Run interactive command (vim, htop, ssh) |
nebula run "<cmd>" |
Smart run with auto-PTY detection |
nebula status |
Show project context and configuration |
nebula efficiency |
Show token usage and cache statistics |
nebula release |
Interactive semantic version release |
# Required: Your AI provider API key (at least one)
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GOOGLE_API_KEY=AI...
GROQ_API_KEY=gsk_...
# Optional: Local LLM via Ollama
OLLAMA_BASE_URL=http://localhost:11434{
"ai": {
"provider": "openai",
"model": "gpt-4o-mini",
"fallback": "groq"
},
"memory": {
"enabled": true,
"retentionDays": 90
},
"selfHeal": {
"maxRetries": 3,
"autoApply": false
}
}- Command execution: You run a command (manually or via Nebula)
- Failure detection: Nebula captures the exit code and error output
- Pattern matching: Checks vector memory for similar past failures
- AI diagnosis: If no cached fix, sends error context to your AI provider
- Fix suggestion: Presents a specific, actionable fix command
- Safety check: Validates the fix isn't destructive before suggesting
- Learning: Stores successful fixes for instant recall next time
| Feature | Nebula-CLI | GitHub Copilot CLI | Warp | ai-shell |
|---|---|---|---|---|
| Self-healing errors | Yes | No | No | No |
| Workflow memory | Yes | No | Limited | No |
| Natural language → cmd | Yes | Yes | Yes | Yes |
| Local LLM support | Yes (Ollama) | No | No | Yes |
| Interactive PTY | Yes | No | Yes | No |
| Open source | Yes | Partial | No | Yes |
| Session persistence | Yes | No | Yes | No |
| Cost | BYOK (your API key) | $10/mo | Free tier + paid | BYOK |
Honest assessment: Copilot CLI has tighter GitHub integration. Warp has a better terminal UX. Nebula-CLI's advantage is self-healing and workflow memory — it learns from your specific failures and fixes.
Ensure nebula's global bin is on your PATH after npm link:
npm config get prefix # Should show a path in your PATH
export PATH="$(npm config get prefix)/bin:$PATH"Run setup again:
nebula setupOr manually create .env in your project root with your API key.
Reinstall dependencies:
npm install
# If you installed globally, re-link instead:
npm linkSelf-healing only activates when a command fails (non-zero exit code). If your command succeeds but produces errors in stdout, Nebula won't catch it. Use nebula analyze "<cmd>" to pre-check commands.
Memory builds over time. The first time you encounter an error, Nebula asks the AI. The second time, it uses the cached fix. Run nebula status to verify memory is enabled.
(Quotes and case studies coming soon once the project reaches v1.0!)
# Clone and install
git clone git@github.com:sagar0163/Nebula_cli.git
cd Nebula_cli
npm install
# Run tests
npm test
# Run with coverage
npm run coverage
# Lint
npm run lint
# Type check
npm run type-checkMIT — see LICENSE for details.
- Built with Commander.js
- AI powered by Google Gemini, Groq, Ollama
- Inspired by GitHub Copilot CLI and Warp