Programmatic API

Advanced. This page is about scripting the CLI's behavior from a custom build script — for example, generating an MCP document as part of a larger tool, or checking its contents before deciding whether to sync.

@appilots/cli is not set up as an importable library

@appilots/cli's package.json only declares a bin entry (appilots → dist/cli/index.js); it does not declare a main, module, or exports field. That means there is no supported entry point for import { ... } from '@appilots/cli' — even though the package internally builds a library bundle from src/index.ts (exporting things like MCPGenerator and AppilotsAPIClient), nothing in the published package manifest points a consumer at it.

Don't import @appilots/cli as a library. Treat the appilots binary as the only supported integration surface, and script around it instead.

Supported approach: shell out to the CLI

Run appilots generate or appilots sync from your own script (Node, using execa or child_process; or any other language), the same way you'd invoke any other CLI tool:

import { execa } from 'execa';

// Analyze only — writes the MCP document to disk, no upload.
await execa('appilots', ['generate', '--output', '.appilots']);

generate writes the document to <outputDir>/mcp-document.json (see Output format for its shape) — read that file back in your script to inspect the result. Use --json on sync/status if you need a machine-readable result on stdout instead of parsing log output — see CLI usage.

How sync / status work under the hood

For context — not as a documented public API — sync, status, and init all use an internal HTTP client (AppilotsAPIClient) that is not exported from the package's public entry point either. It sends requests authenticated with Authorization: Bearer <apiKey> to two endpoints:

• sync(content, version, appVersion?) — used by appilots sync
• status() — used by appilots status

Both are API-key-authed. The full request/response contract for these routes lives in the API Reference section — this page only exists to explain what sync/status are doing internally, not to document them as a library you can import.

Summary

Want to...	Do this
Generate an MCP document from a script	Shell out to appilots generate --output <dir> and read the resulting JSON file
Upload from a script/CI pipeline	Shell out to appilots sync --json (see CI integration)
Import MCPGenerator/AppilotsAPIClient directly	Not supported — the package doesn't expose a library entry point