@axiomify/cli

The official CLI for the Axiomify framework — scaffold projects, run the dev server, build production bundles, inspect routes, generate OpenAPI specs, and audit production readiness.

Install

npm install -D @axiomify/cli
# or invoke without installing:
npx @axiomify/cli init my-api

Per-project install is recommended so the CLI version stays pinned to the same major as your @axiomify/* runtime packages.

Commands at a glance

| Command | Purpose | | --------------------------- | ------------------------------------------------------------------ | | axiomify init [directory] | Bootstrap a new project | | axiomify dev [entry] | Hot-reload dev server (esbuild watch) | | axiomify build [entry] | Compile a production bundle to dist/ | | axiomify routes [entry] | Inspect every HTTP + WebSocket route (+ snapshot/diff the surface) | | axiomify openapi [entry] | Generate the OpenAPI 3.1.0 spec (+ --validate) | | axiomify check [entry] | Static production-readiness audit | | axiomify studio [entry] | Launch Axiomify Studio visual dashboard | | axiomify doctor | Diagnose the host environment | | axiomify scaffold route | Generate a new route file under src/routes/ | | axiomify migrate | Codemod: migrate a v5 project to v6 | | axiomify db <subcommand> | Run the project's db workflow (migrate/seed/generate/status) | | axiomify sdk <subcommand> | Manage, generate, build, validate, and diff SDKs |

[entry] defaults to src/index.ts everywhere it's accepted.

For the full reference (flags, exit codes, CI examples), see ./docs/packages/cli.md.

axiomify init

axiomify init my-api

Interactive scaffolder. Prompts for project name (when no directory argument is given), description, package manager (npm / pnpm / yarn), optional ESLint + Prettier + EditorConfig, git initialisation, and whether to run install automatically.

The generated src/index.ts registers helmet, cors, security, rate-limit, fingerprint, and logger with sane defaults. Pass -f, --force to overwrite existing files.

axiomify dev / axiomify build

axiomify dev               # watches src/, restarts on change
axiomify build             # bundles to dist/index.js

Both use esbuild. dev sends SIGTERM first so your gracefulShutdown hooks can drain, with a SIGKILL fallback after 3 seconds.

dev also accepts --watch-sdk <langs...> to automatically regenerate type-safe SDKs (see axiomify sdk) for the given target languages whenever your source files change:

axiomify dev --watch-sdk typescript python

axiomify routes

Inspects the app without booting a listener. Prints a Unicode-bordered table with colour-coded HTTP methods, validation badges, OpenAPI tags + operationId, plugin count, timeout, and deprecation marker.

  🧭 Axiomify routes

┌─────────┬──────────────────────┬───────────────┬───────────────────────────────────────┐
│ METHOD  │ PATH                 │ VALIDATION    │ META                                  │
├─────────┼──────────────────────┼───────────────┼───────────────────────────────────────┤
│ WS      │ /chat                │ Message       │ —                                     │
│ GET     │ /health              │ —             │ —                                     │
│ POST    │ /users ⊘ DEPRECATED  │ Body,Response │ op:createUser #Users 5000ms +1 plugin │
│ GET     │ /users/:id           │ Params        │ op:getUser #Users                     │
│ DELETE  │ /users/:id           │ Params        │ —                                     │
└─────────┴──────────────────────┴───────────────┴───────────────────────────────────────┘

  ✓ 5 routes   DELETE 1 · GET 2 · POST 1 · WS 1
    └ 1 WebSocket route included

Flags: --json, --method GET,POST,WS, --filter "/api/v1/*", --sort path|method.

WebSocket routes (app.ws(...)) appear under the WS pseudo-method alongside HTTP routes — earlier CLI versions silently omitted them.

Route surface snapshot + diff

--json emits the machine-readable route surface: every route with a sha256 fingerprint of each validation schema part (body / query / params / response), computed over canonically-sorted JSON Schema output so hashes only change when a schema genuinely changes.

axiomify routes --snapshot                 # writes routes-baseline.json
axiomify routes --snapshot main.json       # custom file
# … later, e.g. on a feature branch …
axiomify routes --diff main.json           # exit 1 on breaking changes
axiomify routes --diff main.json --json    # machine-readable, for CI

Snapshot output is deterministic (byte-identical repeat runs), so baselines diff cleanly in git. --diff categorises every change:

| Change | Severity | | ------------------------------ | -------------------------------------------- | | Route added | info | | Route removed | BREAKING | | Method changed (same path) | BREAKING | | body/query/params schema | BREAKING | | response schema | warning (--strict-response → BREAKING) | | Newly deprecated | info |

Exit code 1 on any breaking change; --allow-breaking reports them but exits 0 (useful while a break is being intentionally shipped).

axiomify openapi

axiomify openapi                          # stdout, pretty JSON
axiomify openapi -o openapi.json
axiomify openapi --format yaml -o api.yml
axiomify openapi --minify > spec.min.json
axiomify openapi --title "My API" --spec-version "$(git describe)"

Generates the OpenAPI 3.1.0 spec from the app's registered routes. Useful in CI for client codegen pipelines (openapi-typescript, openapi-generator, oazapfts) without booting an HTTP listener.

Requires @axiomify/openapi to be installed; dynamic-imports it at runtime and prints a clean error if missing.

axiomify openapi --validate

axiomify openapi --validate                # human report
axiomify openapi --validate --json         # { valid, findings } for CI
axiomify openapi --validate -o spec.json   # also write the spec

Validates the generated document in two layers:

1. Official OAS 3.1 JSON Schema — the published spec.openapis.org/oas/3.1/schema/2022-10-07 schema, vendored into the CLI and compiled with Ajv's 2020-12 dialect support. (The generator emits openapi: "3.1.0" exclusively, so 3.1 is the only schema shipped; other versions are rejected explicitly.)
2. Semantic lints the schema can't express: responses missing description, duplicate parameter name+in pairs, operationId collisions, path template ↔ in: path parameter mismatches (both directions), and security requirements referencing schemes not declared in components.securitySchemes.

Each finding is { code, severity, location, message } with location a JSON pointer into the document. Exit code 1 on any error-severity finding — a hard CI gate.

axiomify check

axiomify check

Static production-readiness audit. Loads the app (no listener) and flags:

• ✓ pass — configuration is correct
• ⚠ warn — non-fatal smell
• ✗ fail — real defect that blocks ship

Checks include: enableRequestId() called, env vars referenced in source actually set, routes with body schemas declare response schemas, no deprecated meta: field usage, health check registered, OpenAPI docs protected, security plugins active.

Exit code 1 on any fail — wire into CI to gate deploys.

axiomify scaffold route

axiomify scaffold route GET /users/:id

Generates a new route file under src/routes/ from the method and path. Flags: --auth (include the requireAuth plugin + import), --rate-limit (include a default rate-limit plugin), --dir <dir> (target directory, default src/routes), --dry-run (print the source without writing), and --force (overwrite an existing file).

axiomify migrate

axiomify migrate                 # rewrites files under src/ in place
axiomify migrate --dry-run       # show the unified diff without writing
axiomify migrate --report-only   # print a migration report and exit
axiomify migrate --dir app       # scan a different directory (default: src)

v5 → v6 codemod: merges meta: fields into schema:, renames routePrefix → prefix, and applies other breaking-change fixups.

axiomify studio

axiomify studio [entry]

Launches Axiomify Studio — a premium visual developer dashboard that serves as a control center for your API. It inspects your application's:

• Route Inspector: Search, filter, and drill down into HTTP & WebSocket routes.
• Schema Inspector: Browse and inspect JSON schemas compiled from Zod validators.
• OpenAPI Spec Viewer: Render collapsible tree views of OpenAPI paths and operations.
• Lifecycle Hooks: Review registered hook handlers across request lifecycle phases.
• Health Dashboard: Inspect production-readiness finding audits (pass/warn/fail).
• Request Tester: Construct and send test requests directly against your in-memory Axiomify app instance, including cookies, Server-Sent Events, streams, and multipart file uploads.
• Session Recorder: Inspect or export request sessions as JSON or HAR. Authorization, cookies, passwords, tokens, and configured sensitive fields are redacted before recorder and replay history storage; body capture can be disabled in Studio.
• OTLP Metrics: Receive OTLP HTTP/JSON gauges, sums, histograms, exponential histograms, and summaries locally; inspect or clear them in Analytics—no hosted telemetry account required.

The dashboard uses Live Sync (WebSockets) powered by esbuild's watch context to automatically re-compile and refresh the browser interface in real time as you edit your project files.

Flags:

• -p, --port <number>: Port to start the Studio server on (default: 4399, falls back to a random port if busy).
• --no-open: Disable auto-opening the dashboard in the browser.

Studio security

Studio is a local developer tool and is hardened accordingly:

• Loopback only. The server binds to 127.0.0.1 and rejects any request whose Host header is not a loopback name (localhost, 127.0.0.1, ::1, 0.0.0.0) with 403. This is an anti-DNS-rebinding guard so a page you merely visit cannot drive Studio's endpoints.
• Bearer token. Every launch mints a random access token. The API, the Live Sync WebSocket, and the OTLP receiver endpoints (/__studio/otlp/*) all require it — the token is embedded in the URL Studio opens (?token=…) and printed to the console. It is also exposed to the loaded app via the AXIOMIFY_STUDIO_TOKEN environment variable (alongside AXIOMIFY_STUDIO=true and AXIOMIFY_STUDIO_PORT) so telemetry auto-export can authenticate to the receiver.
• Playground code execution is disabled by default. The Playground's "run snippet" endpoint writes user-supplied code to disk and executes it (node / python3 / dart) with the full privileges of the Studio process and no sandbox. It is therefore off by default and returns 403 unless you explicitly opt in with AXIOMIFY_STUDIO_ALLOW_EXEC=true. Only enable this on a trusted, single-user machine — never on a shared host — as it is effectively arbitrary code execution.

axiomify doctor

axiomify doctor

Diagnoses the host environment: Node version vs uWS prebuilt support, platform (Linux ✓ for SO_REUSEPORT clustering), @axiomify/* package alignment, uWS bindings load successfully, recent build artefact, port 3000 (or $PORT) availability.

Run on a fresh clone or new CI runner before chasing test failures that turn out to be Node-version mismatches.

axiomify db

axiomify db migrate            # run the manifest's migrate command
axiomify db seed --dry-run     # print what would run, execute nothing
axiomify db generate
axiomify db status             # which manifest + commands are configured

Runs the project's database workflow through a manifest at the project root — either axiomify.db.json (shell-string commands) or axiomify.db.mjs (may export function commands; requires @axiomify/db). Schema v1:

{
  "version": 1,
  "commands": {
    "migrate": "npx prisma migrate deploy",
    "seed": "node ./scripts/seed.mjs",
    "generate": "npx prisma generate"
  }
}

The CLI never runs anything not explicitly declared in the manifest. Shell commands are spawned with inherited stdio and their exit code is propagated; function commands (.mjs manifests) are awaited.

@axiomify/db is imported lazily: when it's installed its loadDbConfig loader is used; when it isn't, a built-in reader handles axiomify.db.json so the CLI stands alone (.mjs manifests without the package are a clear error).

axiomify db status with no manifest performs best-effort ORM detection (prisma/schema.prisma, drizzle.config.*, knexfile.*) and prints a suggested manifest for what it finds.

axiomify sdk

Subcommands for compiling type-safe client SDKs from specs:

# Generate SDKs for TS, Python, and Go:
axiomify sdk generate spec.json --target typescript python go -o ./sdks

# Validate a schema against the SDK compiler:
axiomify sdk validate spec.json

# Deep structural diff for breaking changes:
axiomify sdk diff old-spec.json new-spec.json

# Get client migration guidance:
axiomify sdk migrate old-spec.json new-spec.json

# Build a generated SDK:
axiomify sdk build

# Publish a generated SDK:
axiomify sdk publish

# Upgrade a generated SDK:
axiomify sdk upgrade

# Run generation hot-reloads on file change:
axiomify sdk watch spec.json --target typescript python

# Run local toolchain diagnostics:
axiomify sdk doctor

# Run compiler and emitter throughput benchmarks:
axiomify sdk benchmark

CI example

- run: npx axiomify doctor # environment sanity
- run: npx axiomify check # static readiness audit
- run: npx axiomify build
- run: npx axiomify openapi -o ./openapi.json --spec-version "$GITHUB_SHA"
- run: npx axiomify openapi --validate # official OAS 3.1 schema + lints
- run: npx axiomify routes --diff routes-baseline.json # exit 1 on breaking changes
- run: npx axiomify sdk validate ./openapi.json # schema verification
- run: npx axiomify sdk diff old-spec.json ./openapi.json # check breaking changes

Commit a routes-baseline.json (from axiomify routes --snapshot) and the --diff step blocks accidental breaking API changes before they reach production.