CLI Integration Standard (API Passthrough)

Standard for exposing reliable CLI access to a web app without duplicating business logic.

Core rule

API/server is the single source of truth for domain logic.
CLI is a client of that API.
CLI must not call the database directly.

If behavior is missing for CLI, add endpoint/service logic in API first, then call it from CLI.

Required project structure

project-root/
├── src/app/api/...            # API routes
├── src/lib/server/...         # business/domain logic
├── scripts/
│   ├── lib/
│   │   └── api_client.sh      # shared transport helper
│   ├── <resource>.sh          # task/project/sprint style command groups
│   ├── <wrapper>.sh           # optional umbrella script
│   ├── README.md              # command docs
│   └── tests/
│       ├── *.test.ts          # unit tests for shared logic
│       └── *.sh               # mocked CLI contract tests
└── README.md

CLI responsibilities

Parse args and flags.
Resolve user-friendly names to IDs (via API calls).
Call API endpoints.
Format output and errors.

Do not implement:

status/sprint/date/business transition logic
server-side validation rules
persistence logic
auth policy logic

Configuration

Preferred runtime variables:

API_URL (for example http://localhost:3000/api)
GANTT_COOKIE_FILE (or equivalent session cookie path)

Do not require service-role DB keys in CLI scripts.

Testing requirements

Every CLI-enabled project must include:

API/domain unit tests
API route/integration tests
CLI contract tests with mocked transport

CLI contract mock pattern

For shell CLIs:

mock curl via PATH override
log METHOD URL PAYLOAD
return fixture JSON + HTTP codes
fail on unhandled endpoint calls
assert expected endpoint calls were made

Also assert no direct DB references remain in scripts/ (for example rest/v1, service keys).

Verification checklist

CLI scripts only call API
No direct DB credentials/queries in CLI
Missing CLI behavior added to API first
Tests added/updated (unit + mocked contract)
Refactor suite runs in CI
scripts/README.md and root README.md are updated

Migration guide (direct DB CLI -> API passthrough CLI)

Inventory commands and duplicated logic.
Implement needed behavior in API/server modules.
Replace CLI DB calls with api_call helper.
Add mocked contract tests that cover all command families.
Remove old DB code and env vars from scripts.
Update docs and CI gates.

2.6 KiB Raw Blame History