Feature proposal: @json-render/cli package

[lucianfialho]

Summary

Proposing a @json-render/cli package to improve developer experience for common deterministic tasks that don't require an AI agent in the loop.

Motivation

The project already has @json-render/mcp for AI agent integration, but there's a gap for human developers working directly in the terminal, CI/CD pipelines, and automation scripts. A CLI would lower the barrier to entry and complement the existing MCP package.

CLI vs MCP — complementary, not competing

Use case	CLI	MCP
Deterministic tasks (validate, scaffold)	✅ Direct execution, no AI overhead	Overkill — adds LLM roundtrip for deterministic work
CI/CD pipelines	✅ Trivial integration	Requires MCP client setup
Unix composability	✅ json-render validate --json | jq .errors	Not scriptable
Onboarding	✅ npx @json-render/cli init — universal	Requires MCP client already configured
AI-driven generation	Not the right tool	✅ Structured schema, persistent connection

MCP is better for AI agents

For AI agent workflows, MCP is more performant than shelling out to a CLI: persistent connections, typed schemas, structured JSON output, and no process spawn overhead per call. The CLI is not a replacement for MCP — it targets a different audience.

Proposed commands

json-render init

Interactive scaffolding: select framework (React, Vue, Svelte, Solid), generates catalog, registry, and renderer boilerplate.

json-render validate <spec.json>

Validates a UI spec JSON against a catalog definition. Useful for CI/CD checks and debugging. Exit code 1 on validation errors.

json-render add <component>

Similar to shadcn add — adds pre-built components from the shadcn catalog to the project.

json-render inspect <spec.json>

Pretty-prints the component tree from a spec, showing hierarchy, props, and actions for debugging.

Implementation approach

• New packages/cli using a lightweight CLI framework (e.g., citty or commander)
• Leverages existing @json-render/core for validation and catalog parsing
• TypeScript, follows existing monorepo conventions (tsup, vitest)

Open questions

• Are there other commands that would be valuable?
• Any preference on CLI framework?
• Should init support generating from existing shadcn catalogs?

Would love to hear if this aligns with the project's direction before starting implementation.