CLI

The fastest way to add /ai to your service. Converts OpenAPI specs, walks you through an interactive wizard, validates live endpoints, and generates framework-specific route handlers.

npm install -g @aiendpoint/cli
# or run directly:
npx @aiendpoint/cli init

Install

No install needed for one-off use:

npx @aiendpoint/cli init

Or install globally:

npm install -g @aiendpoint/cli

Generate from OpenAPI

If your service already has an OpenAPI/Swagger spec, the CLI converts it to /ai format automatically. No LLM, no server calls, runs entirely offline.

# From a URL
npx @aiendpoint/cli init --openapi https://petstore3.swagger.io/api/v3/openapi.json

# From a local file
npx @aiendpoint/cli init --openapi ./openapi.json

What it does:

1. Reads the OpenAPI spec (supports v2.x and v3.x)
2. Extracts up to 20 capabilities from the paths
3. Maps securitySchemes to the auth field
4. Maps tags to categories
5. Validates and scores the result (0-100)

Example output:

  Converted: 19 capabilities extracted

  Score: 75/100 (Good (AI-Ready))
  Capabilities: 19
  Token estimate: ~1462 tokens

  Framework: nextjs

  Files:
    + ai.json
    + app/ai/route.ts

Interactive wizard

No OpenAPI spec? The wizard walks you through each field:

npx @aiendpoint/cli init

  Service name: Acme Store
  Description (one sentence, for AI agents): Search and order products
  Categories: ecommerce
  Auth type: apikey

  Capability #1 id: search_products
    Description: Search products by keyword
    Endpoint: /api/search
    Method: GET
    Param name: q
      q description: string, required
    Returns: products[] {id, name, price}

  Add another capability? (y/N):

Validate

Check if a live /ai endpoint is valid and get a score:

npx @aiendpoint/cli validate https://api.aiendpoint.dev

  Found: https://api.aiendpoint.dev/ai (415ms)
  Score: 85/100 (Good (AI-Ready))
  Capabilities: 6
  Token estimate: ~832 tokens

The validator checks GET /ai and GET /.well-known/ai, uses the first that responds.

Returns exit code 0 on success, 1 if errors found. Use in CI:

npx @aiendpoint/cli validate https://yoursite.com || echo "Validation failed"

Code generation

The CLI auto-detects your framework and generates a route handler alongside ai.json.

Auto-detection: looks for next.config.* (Next.js) or fastify in package.json dependencies.

Manual override: --framework nextjs or --framework fastify

For more framework options (Express, Hono, NestJS), see @aiendpoint/serve.

Options reference

init

validate

npx @aiendpoint/cli validate <url>

No options. Checks /ai and /.well-known/ai, returns score and diagnostics.