@gridfox/api-skill

@gridfox/api-skill is a self-contained CLI for Gridfox schema inspection, seed-plan execution, and local session-based auth proxying.

The model still does the smart work:

• inspect the live schema
• infer the domain story
• design realistic demo data
• write the seed plan JSON

The CLI does the repetitive work:

• expose a local auth proxy so the agent never needs the raw API key
• return built-in agent workflow guidance
• call the Gridfox API
• resolve $ref links between records
• create records in dependency order
• run post-create updates
• handle Gridfox API quirks consistently

Shortest Agent Flow

Start the local proxy:

npx @gridfox/api-skill proxy

Load a named session in the proxy terminal:

proxy> add client-a
Session ID: client-a
Gridfox API key (hidden):

Then the agent only needs to run:

npx @gridfox/api-skill bootstrap --session client-a

bootstrap returns:

• live schema summary
• built-in workflow instructions
• execution guardrails
• data-quality rules
• ready-to-run command templates

That means the human prompt can be very short:

Use npx @gridfox/api-skill bootstrap --session client-a and follow its instructions to add realistic demo data to this Gridfox project.

Usage

Agent-safe proxy usage:

npx @gridfox/api-skill proxy
npx @gridfox/api-skill bootstrap --session client-a
npx @gridfox/api-skill validate --session client-a --plan ./seed-plan.json
npx @gridfox/api-skill apply --session client-a --plan ./seed-plan.json

Direct API key usage is still available:

npx @gridfox/api-skill bootstrap --api-key YOUR_GRIDFOX_API_KEY
npx @gridfox/api-skill inspect --api-key YOUR_GRIDFOX_API_KEY --summary
npx @gridfox/api-skill validate --plan ./seed-plan.json --api-key YOUR_GRIDFOX_API_KEY
npx @gridfox/api-skill apply --plan ./seed-plan.json --api-key YOUR_GRIDFOX_API_KEY

You can also use GRIDFOX_API_KEY:

GRIDFOX_API_KEY=YOUR_GRIDFOX_API_KEY npx @gridfox/api-skill apply --plan ./seed-plan.json

Commands

bootstrap

Return built-in agent instructions plus the live schema summary.

npx @gridfox/api-skill bootstrap --session client-a
npx @gridfox/api-skill bootstrap --session client-a --full-schema

Use --full-schema when the agent needs the complete raw /tables response instead of the summarized view.

inspect

Fetch the live Gridfox schema.

npx @gridfox/api-skill inspect --session client-a --summary
npx @gridfox/api-skill inspect --api-key YOUR_GRIDFOX_API_KEY --summary

validate

Validate a seed plan and, when a direct key, session, or custom base URL is provided, validate the plan against the live schema.

npx @gridfox/api-skill validate --plan ./seed-plan.json --session client-a

apply

Apply a seed plan to Gridfox.

npx @gridfox/api-skill apply --plan ./seed-plan.json --session client-a

Useful flags:

• --dry-run: show execution order without writing records
• --clear-existing: delete existing records from the plan's tables before applying
• --session <id>: route through the local auth proxy on 127.0.0.1:4319
• --base-url <url>: override the endpoint root directly
• --port <number>: choose the proxy port when --session or proxy is used

proxy

Start the local auth proxy on 127.0.0.1:4319.

npx @gridfox/api-skill proxy

The proxy keeps named sessions in memory only. Each session maps to one Gridfox API key, so one localhost proxy can safely serve multiple projects without a hidden global current key.

Proxy terminal commands:

• add <session-id>: load or replace a session and paste the key in the terminal
• list: show loaded sessions and their local session URLs
• remove <session-id>: remove a session from memory
• help: show command help
• exit: stop the proxy

Proxy HTTP endpoints:

• GET /health
• GET /sessions
• GET /sessions/{id}
• GET /sessions/{id}/ready
• GET|POST|PUT|DELETE /sessions/{id}/... forwarded to https://api.gridfox.com/... with the session key injected

Seed Plan Contract

The model should author a JSON file that follows seed-plan.schema.json.

Key ideas:

• tables[] groups records by Gridfox table name
• each record can have a stable key
• later records can refer to earlier records with { "$ref": "some_key" }
• action can be create or update
• ref is required for update

Included Examples

• examples/medical-mdr-plan.json
• examples/jewellery-ops-test-plan.json
• examples/education-hub-test-plan.json

Notes From Live Use

This CLI already handles several Gridfox-specific behaviors observed in live projects:

• parent refs to auto-counter tables need numeric values
• update payloads need the reference field in both URL and body
• newly created records can need a short delay before update
• single-link many-to-many updates can require a scalar ref payload rather than a one-item array
• local proxy sessions keep API keys out of agent prompts and avoid cross-project writes by requiring explicit session IDs

For higher-level usage guidance, see SKILL.md. The package no longer depends on that hosted guidance to operate correctly.