json-cli

AI-powered CLI task runner. Describe your goal in plain English — AI generates a validated JSON command plan — runner executes it step by step.

Installation

npm install -g @ekaone/json-cli

pnpm install -g @ekaone/json-cli

yarn global add @ekaone/json-cli

Setup

export ANTHROPIC_API_KEY=your_key_here

Windows PowerShell: $env:ANTHROPIC_API_KEY="your_key_here"

---

Usage

Single intent

json-cli "please run tests"
json-cli "please build"
json-cli "check git status"

Multi-intent — the fun part 🔥

Chain multiple commands in plain English using "then", "and", "after that":

json-cli "run tests and then build"

json-cli "run typecheck, test, and then check git status"

json-cli "please run dev with port 5000"

json-cli "install deps, run tests, then build"

Full release flow in one command 🚀

json-cli "run tests, build, git add all, commit with message 'release v0.1.0', push, then publish"

📋 Plan (6 steps):
  1. pnpm test                → Run test suite
  2. pnpm build               → Build package
  3. git add .                → Stage all changes
  4. git commit -m "release v0.1.0"  → Commit release
  5. git push                 → Push to remote
  6. pnpm publish             → Publish to npm

Proceed? › y

More crazy examples

# Full dev startup
json-cli "install deps and run dev on port 3000"

# Audit and fix
json-cli "run npm audit, then update all deps"

# Branch and commit workflow
json-cli "check git status, add all files, commit with message 'feat: add multi-intent support', then push"

# Test everything before shipping
json-cli "run typecheck, run tests, build, then publish"

# Clone and install
json-cli "clone https://github.com/ekaone/json-cli and then install deps"

# Check before commit
json-cli "run tests, check git diff, then git add and commit with message 'fix: catalog types'"

# Full CI-like flow locally
json-cli "install deps, run typecheck, run tests, build, git add, commit with message 'ci: local pipeline passed', push"

---

How it works

User Prompt (plain English)
    │
    ▼
AI Provider         ← Claude / OpenAI / Ollama
    │               extracts ALL intents, sequences them
    ▼
JSON Plan           ← validated by Zod schema (max 10 steps)
    │
    ▼
Catalog Check       ← whitelist prevents hallucinated commands
    │
    ▼
Confirm (y/n)       ← review the full plan before execution
    │
    ▼
Runner              ← executes step by step, streams output live
                       stops immediately on first failure

---

Allowed commands

Type	Commands
pnpm	install, run, build, test, publish, add, remove, update, dlx, why
npm	install, run, build, test, publish, ci, init, outdated, audit
yarn	install, run, build, test, publish, add, remove, why, upgrade
bun	install, run, build, test, publish, add, remove, x, update
git	init, add, commit, push, pull, clone, status, log, branch, checkout, merge, diff, stash
fs	mkdir, touch, cp, mv, ls (coming soon)
shell	any (escape hatch — always requires extra confirmation)

Note: Flags and arguments are unrestricted — --port 5000, -m "message", --force etc. are all passed freely. Only the command itself is whitelisted.

---

AI Providers

# Claude (default)
json-cli "run tests and build"

# OpenAI
json-cli "run tests and build" --provider openai

# Ollama (local, no API key needed)
json-cli "run tests and build" --provider ollama

Environment variables

ANTHROPIC_API_KEY=sk-ant-...   # for Claude
OPENAI_API_KEY=sk-...          # for OpenAI

---

Local development

pnpm install
pnpm dev "please run tests"
pnpm test
pnpm build

---

License

MIT © Eka Prasetia

Links

• npm Package
• GitHub Repository
• Issue Tracker

⭐ If this library helps you, please consider giving it a star on GitHub!