CLI Usage

Every command that talks to the network needs a resolvable API key — via .appilotsrc, APPILOTS_API_KEY, or --api-key. See Configuration for how the CLI resolves config and the precedence between flags, environment variables, and the config file.

appilots init

Interactive setup. Validates your API key, confirms it against the server, and writes a .appilotsrc file.

Flag	Description
--api-key <key>	Your Appilots API key (ak_... format)
--server <url>	Server URL. Falls back to the environment, then http://localhost:4000 if neither is set — pass --server https://api.appilots.com explicitly for production use

What it does:

1. Validates the key format (must start with ak_).
2. Calls the server's health check and status endpoint to confirm the key works and to fetch your project name/id.
3. Writes .appilotsrc to the current directory.
4. Appends .appilotsrc to .gitignore if one exists and doesn't already ignore it — and warns loudly if there's no .gitignore at all, since the file holds your API key in plaintext.

appilots init --api-key ak_xxxxxxxxxxxx... --server https://api.appilots.com

appilots sync

Analyzes the project and uploads the MCP document. This is the command you'll run most often, locally and in CI.

Flag	Description
--verbose	Extra logging, plus a details table of screens/forms/actions/checksums at the end
--force	Upload even if the local checksum matches the last run
--api-key <key>	Override the API key for this run only (highest precedence)
--project-id <id>	Override the project id for this run only
--server <url>	Override the server URL for this run only
--json	Machine-readable JSON result on stdout instead of the human-readable log. Implies --quiet
--quiet	Suppress the banner/info logs, keep only success/error
--strict-metadata	Exit non-zero if any mutating action is missing effect/riskLevel metadata — see Metadata quality

Behavior: sync analyzes the project and compares the new checksum against the previous run's, stored in <outputDir>/.appilots-checksum. If nothing changed locally and the server confirms it already has an active document, the upload is skipped — pass --force to upload anyway. Otherwise it uploads via POST /cli/sync (API-key authed; see API Reference for API basics) and prints the document id, checksum, and a dashboard link when a projectId is known.

appilots sync --verbose
appilots sync --json          # for scripting/CI

appilots watch

Runs an initial sync, then watches the project directory recursively and re-syncs on change.

Flag	Description
--verbose	Extra logging

watch loads .appilotsrc and fails if none is found — unlike sync and status, environment-only config is not supported for watch. File changes are debounced before triggering re-analysis, and dotfiles, node_modules, and the output directory are ignored. Press Ctrl+C to stop the watcher cleanly.

appilots watch

appilots generate

Analyzes the project and writes the MCP document to disk, without uploading anywhere. Useful for CI dry-runs, diffing output between branches, or feeding the document into a custom pipeline — see Programmatic API if you'd rather script this instead of shelling out.

Flag	Description
-o, --output <path>	Output directory. Default .appilots
-f, --format <format>	Output format. Only json is currently supported — any other value errors out
--strict-metadata	Same as sync — see Metadata quality

appilots generate --output .appilots

See Output format for the shape of the file this command writes.

appilots status

Prints local config plus the server's project info and active MCP document summary. A good smoke test for "is my API key/project set up correctly."

Flag	Description
--json	Machine-readable JSON output
--quiet	Suppress banner/info logs, keep only success/error

Prints: server URL, project id, output dir, and autoActivate from local config, plus the server's project info and active MCP document summary (screens/forms/actions counts, version, document id) via GET /cli/status (API-key authed).

appilots status