api-to-cli 0.1.1 → 0.1.2

package/README.md

@@ -21,27 +21,49 @@ This means anyone can create a CLI layer for an API, even if the API owner never
   - JSON error envelope
   - Env-var auth injection (`header` or `query`)
 
-## Project Setup
-Clone this repository to any local folder and run commands from the repo root.
+## Install and Run
+
+### Option A: Run with npx (no global install)
+
+```bash
+npx api-to-cli --help
+```
+
+### Option B: Install globally with npm
+
+```bash
+npm install -g api-to-cli
+api-to-cli --help
+```
 
 ## Core Commands
 
+Use either `npx api-to-cli` or `api-to-cli` (if globally installed).
+
 ```bash
 # 1) Validate config only
-node ./bin/api-to-cli.js validate \
+npx api-to-cli validate \
   --config ./examples/trello/api-to-cli.config.js
 
 # 2) Generate only the CLI project
-node ./bin/api-to-cli.js generate \
+npx api-to-cli generate \
   --config ./examples/trello/api-to-cli.config.js \
   --output ./examples/trello/trelloapi-cli
 
 # 3) Generate a full agent bundle (CLI + skill + manifest)
-node ./bin/api-to-cli.js scaffold \
+npx api-to-cli scaffold \
   --config ./examples/trello/api-to-cli.config.js \
   --output ./examples/trello/trelloapi-agent
 ```
 
+## Local Development
+
+If you cloned this repo and want to run from source:
+
+```bash
+node ./bin/api-to-cli.js --help
+```
+
 ## Scaffold Output Layout
 
 ```text

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "api-to-cli",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Generate AI-agent-friendly CLIs, skills, and manifests from API configs",
   "license": "MIT",
   "type": "commonjs",
@@ -12,9 +12,7 @@
     "src",
     "examples",
     "README.md",
-    "LICENSE",
-    "PROJECT_BRIEF.md",
-    "SPEC.md"
+    "LICENSE"
   ],
   "engines": {
     "node": ">=18"

package/PROJECT_BRIEF.md

@@ -1,65 +0,0 @@
-# API-to-CLI Project Brief
-
-## Working Name
-- Recommended: `AgentBridge`
-- NPM package (generator): `api-to-cli`
-- Why this split: product name can be brandable, while npm name stays literal and searchable.
-
-Other viable names:
-- `APIBridge`
-- `CLIForge`
-- `Toolwire`
-
-## Problem
-Most APIs are not directly usable by AI agents. We want a generator that turns a REST API definition into:
-1. an AI-agent-friendly CLI (JSON-first output), and
-2. an MCP server exposing equivalent tools.
-
-## What We Are Building (MVP)
-- Input:
-  - `api-to-cli.config.js` custom config (first)
-  - OpenAPI support later
-- Output:
-  - Installable Node CLI
-  - MCP server
-- Core behavior:
-  - JSON output by default
-  - Consistent JSON error envelope
-  - Shared auth handling (API key + bearer first)
-  - Safe-by-default confirmations for destructive methods
-
-## Explicit Non-Goals (MVP)
-- Full OAuth/device flow in v1
-- Every OpenAPI edge case in v1
-- Multi-language generators in v1
-
-## Demo API Choice (Free + Popular, No First-Party CLI)
-Recommended demo target: **Trello REST API**
-- Popular real product used by millions
-- Free plan available
-- Official REST API docs and auth flow
-- No first-party Trello CLI from Atlassian (there are community CLIs, which is fine and reinforces the need)
-
-Key references:
-- API reference landing: https://developer.atlassian.com/cloud/trello/rest/
-- API introduction (first calls, key + token): https://developer.atlassian.com/cloud/trello/guides/rest-api/api-introduction/
-- Authorization details: https://developer.atlassian.com/cloud/trello/guides/rest-api/authorization/
-- Pricing (Free plan): https://trello.com/pricing
-
-## MVP Command Set for Trello Demo
-- `trelloapi me`
-- `trelloapi list-boards`
-- `trelloapi list-cards --board-id <id>`
-- `trelloapi create-card --list-id <id> --name <title> --yes`
-
-## Build Sequence
-1. Generator from custom config -> CLI output (GET-only)
-2. Add POST/PUT/PATCH/DELETE with `--yes` guard
-3. Generate MCP server from same config
-4. Add OpenAPI parsing layer
-
-## Immediate Next Step (Before Coding)
-Finalize:
-1. Product name (`AgentBridge` vs alternatives)
-2. Package names (`api-to-cli`, `@randyventures/api-to-cli`, or other)
-3. Trello as first official example API

package/SPEC.md

@@ -1,99 +0,0 @@
-# AgentBridge MVP Spec
-
-## Location
-- Project folder: repository root (where this project is cloned)
-- This project is standalone and not nested inside another repo
-
-## Product Identity
-- Product name: `AgentBridge`
-- Generator package name: `api-to-cli`
-
-## Goal
-Given a config file describing API endpoints, generate:
-1. a JSON-first CLI, and
-2. an MCP server exposing matching tools.
-
-## Demo API (First Example)
-- Trello REST API
-- Why: popular, free tier, official docs, no first-party Trello CLI from Atlassian
-
-## MVP Scope (Current)
-- Input:
-  - `api-to-cli.config.js`
-- Generator commands:
-  - `validate`
-  - `generate`
-- Output:
-  - generated CLI project
-- Endpoint support:
-  - GET only
-- Auth support:
-  - env-var credentials injected into header or query
-
-## CLI Behavior Requirements
-- Every command prints valid JSON to stdout on success.
-- Every failure prints JSON in this shape:
-```json
-{
-  "error": true,
-  "code": "REQUEST_FAILED",
-  "message": "...",
-  "details": {}
-}
-```
-- Exit code:
-  - `0` on success
-  - non-zero on error
-
-## Security Requirements
-- Credentials must come from environment variables only.
-- Generated code must not write credentials to files.
-- Error output must not include auth headers, tokens, or full request URLs.
-
-## Generated Project Structure (MVP)
-```text
-<name>-cli/
-  package.json
-  bin/<name>
-  commands/*.js
-  lib/client.js
-  lib/output.js
-```
-
-## Config Shape (MVP)
-```js
-module.exports = {
-  name: "trelloapi",
-  version: "1.0.0",
-  apiBase: "https://api.trello.com/1",
-  auth: {
-    credentials: [
-      { envVar: "TRELLO_KEY", in: "query", name: "key" },
-      { envVar: "TRELLO_TOKEN", in: "query", name: "token" }
-    ]
-  },
-  commands: [
-    {
-      name: "get-board",
-      description: "Get a board by ID",
-      method: "GET",
-      path: "/boards/{boardId}",
-      params: {
-        boardId: { type: "string", required: true }
-      }
-    }
-  ]
-};
-```
-
-## Out of Scope for MVP
-- OpenAPI parsing
-- MCP generation
-- POST/PUT/PATCH/DELETE
-- confirmation prompts (`--yes`)
-- OAuth flow
-
-## Success Criteria
-- `api-to-cli validate --config <file>` validates and returns summary JSON.
-- `api-to-cli generate --config <file> --output <dir>` creates runnable CLI.
-- Generated CLI executes GET commands and emits valid JSON success/error output.