@ekaone/json-cli

AI-powered CLI task runner. Just write in plain English, AI generates a validated JSON command plan, and the runner executes it step by step.

Think safety first

For safety, json-cli will generate the plan and ask for confirmation before running the steps. You can also use the --dry-run flag to preview the plan without executing it.

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"

More examples

💡 There are a lot cool examples in the examples file.

Options

json-cli
# or
json-cli --help

  json-cli — AI-powered CLI task runner

  Usage
    json-cli "<your goal>" [options]

  Alias
    jc "<your goal>" [options]

  Options
    --provider <name>   AI provider: claude | openai | ollama  (default: claude)
    --catalogs <list>   Force specific catalogs: package,git,docker,fs,shell (comma-separated)
    --yes               Skip confirmation prompt
    --dry-run           Show plan without executing
    --debug             Show system prompt and raw AI response
    --resume            Resume from last failed step
    --history           Browse and re-run past commands
    --history --clear   Clear command history
    --help              Show this help message
    --version, -v       Show version

  Examples
    json-cli "please run tests"
    json-cli "run tests and build"
    json-cli "run tests and build" --yes
    json-cli "git add, commit with message 'fix: bug', push"
    json-cli "clone https://github.com/user/repo, install deps, run dev"
    json-cli "run tests and publish" --provider openai
    json-cli "run tests" --dry-run
    json-cli "run tests" --debug
    json-cli "run tests" --debug --dry-run
    json-cli "deploy to prod" --catalogs docker
    json-cli "list files in E:" --catalogs fs
    json-cli --resume
    json-cli --history

  Docs: https://github.com/ekaone/json-cli

---

Catalogs (Command Whitelists)

json-cli automatically detects which catalogs to use based on your project structure:

Catalog	Auto-detected when	Commands
package	package.json exists	npm, pnpm, yarn, bun
git	.git/ folder exists	git init, add, commit, push, pull...
docker	Dockerfile or docker-compose.yml exists	docker build, run, compose...
fs	Always included	mkdir, rm, cp, mv, touch, cat, ls, dir
shell	Always included	Any command (escape hatch)

Force specific catalogs

Use --catalogs to override auto-detection:

# Only use docker commands, even in a Node.js project
json-cli "deploy to prod" --catalogs docker

# Only filesystem commands
json-cli "list files in E:" --catalogs fs

# Multiple catalogs (comma-separated)
json-cli "build and deploy" --catalogs package,docker

This is useful when you want to:

• Exclude certain tools from the plan
• Ensure only specific command types are used
• Override auto-detection in CI/CD pipelines

---

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
docker	build, run, compose, push, pull, exec, logs, ps, stop, start, rm, rmi
fs	mkdir, rm, cp, mv, touch, cat, ls, dir
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

Pricing

Note: Pricing is based on the lastest rates from each provider. Write an issue if you find any outdated pricing.

Provider	Input Cost (per 1M tokens)	Output Cost (per 1M tokens)
Claude	$3.00	$15.00
OpenAI	$2.50	$10.00
Ollama	$0.00	$0.00

---

License

MIT © Eka Prasetia

Links

• npm Package
• GitHub Repository
• Issue Tracker

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