Configuration

The CLI reads its configuration from three places, in this order of precedence:

CLI flags > environment variables > .appilotsrc file

sync and status work with only environment variables set — no .appilotsrc needed at all — which is what makes CI-only setups possible (see CI integration). watch is the one exception: it currently requires an actual .appilotsrc file to exist; environment-only config is not supported for watch.

.appilotsrc

A JSON file, one per project, written by appilots init and read by every other command.

Field	Type	Required	Description
apiKey	string	Yes	Appilots API key. Must start with ak_
serverUrl	string	Yes (defaults to http://localhost:4000 if omitted)	See production URL below
projectId	string	No	Informational — the API key alone identifies the project server-side. Used for the dashboard link sync prints
outputDir	string	No	Where generate/sync/watch write the local MCP document and checksum cache. Default .appilots
include	string[]	No	Glob patterns for source files included in analysis
exclude	string[]	No	Glob patterns for source files excluded from analysis
autoActivate	boolean	No	Whether the uploaded document is automatically made active. Default true
strictScreens	boolean	No	When true, only files matching screenPatterns (or containing a registerScreen() call) are treated as screens. Default true
screenPatterns	string[]	No	Glob patterns used with strictScreens. Default ['**/*Screen.{ts,tsx}', '**/screens/**/*.{ts,tsx}']
navigationInclude	string[]	No	Additional glob patterns for navigation-file discovery. Added to the defaults, not a replacement
navigationExclude	string[]	No	Glob patterns excluded from navigation-file discovery

Example

{
  "apiKey": "ak_xxxxxxxxxxxx...",
  "projectId": "proj_xxxxxxxx",
  "serverUrl": "https://api.appilots.com",
  "outputDir": ".appilots",
  "autoActivate": true,
  "strictScreens": true
}

Discovery

appilots looks for .appilotsrc by walking up from the current working directory to the filesystem root, the same way .npmrc lookup works. That means you can run appilots sync from any subdirectory of a project and it will find the config at the project root.

Environment variables

Variable	Overrides
APPILOTS_API_KEY	apiKey
APPILOTS_PROJECT_ID	projectId
APPILOTS_SERVER_URL	serverUrl

Blank or whitespace-only values are treated as unset.

Production server URL

The CLI's built-in default for serverUrl is http://localhost:4000 — a dev-oriented default for running against a self-hosted server locally. If neither serverUrl in .appilotsrc, APPILOTS_SERVER_URL, nor --server is set, this is what the CLI will silently use. Always set serverUrl explicitly to https://api.appilots.com for anything other than local development — don't let the raw default end up in a production CI pipeline.

Security

.appilotsrc holds your API key in plaintext.

• appilots init automatically appends .appilotsrc to .gitignore when one exists, and warns loudly if it can't (no .gitignore present).
• Verify it's actually ignored before committing anything in that directory — never commit .appilotsrc.
• For CI, prefer environment variables / your CI provider's secret store over a committed config file — see CI integration. APPILOTS_API_KEY is part of the CLI's own public config surface (it's meant to be set, just like .appilotsrc's apiKey field), but its value should be handled like any other credential.