> For the complete documentation index, see [llms.txt](https://developer.celigo.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.celigo.com/cli/getting-started/configuration.md). # Configuration reference The CLI reads configuration from three sources, in priority order: 1. **Command-line flags** — `--token`, `--base-url`, `--profile`, `--format`, `--jq`, `--verbose` 2. **Environment variables** — see table below 3. **`~/.celigo/config.json`** — per-profile defaults An earlier source overrides a later one. `--token` on the command line wins over the env var, which wins over the config file. ## Config file schema ```json { "active_profile": "prod", "profiles": { "": { "api_token": "", "base_url": "", "default_format": "json" | "table", "mode": "read" | "operate" | "full", "account_alias": "", "list_fields": "all" | "default" } }, "settings": { "auto_update": "true" | "false", "skills_auto_install": "true" | "false", "skills_auto_install_exclude": "", "specs_auto_update": "true" | "false" } } ``` File mode is `0600` on Unix. Unknown fields are preserved across writes but not surfaced. ### Per-profile keys Each profile targets one account and environment, so these keys are set per profile. | Field | Type | Default | Notes | | ---------------- | ------ | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `api_token` | string | — | Bearer token. Required for anything but `config`/`profile` commands. | | `base_url` | string | `https://api.integrator.io` | Use your region's API host. See [Profiles & regions](/cli/getting-started/profiles.md#regions). | | `default_format` | enum | `json` | `json` for scripts, `table` for terminals. | | `mode` | enum | `full` | Permission mode. See [Profiles & regions](/cli/getting-started/profiles.md). | | `account_alias` | string | — | This account's MCP alias — the path segment in `/mcp//`. No API endpoint returns it, so set it here when you manage MCP connections. With it set, the CLI matches an MCP connection on the full server key rather than the relative URI alone. | | `list_fields` | enum | `default` | Default field scope for `list` commands. `default` keeps the built-in projection; `all` returns complete documents. Only these two values are valid — a profile-wide field list would apply one set of fields to every resource type. A `--fields` flag on the command always wins. See [Global flags](/cli/getting-started/global-flags.md). | ### Machine-wide settings One CLI installation serves every profile, so these four settings live in a top-level `settings` object rather than inside a profile. Setting one from any profile changes it for all of them, and `config set` rejects `--profile` for them. | Field | Type | Default | Notes | | ----------------------------- | ------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `auto_update` | enum | `true` | `false` downgrades the background self-update to a notification only. | | `skills_auto_install` | enum | `true` | `false` disables the background skills install. See [AI assistant skills](/cli/using-the-cli/skills.md). | | `skills_auto_install_exclude` | string | — | Comma-separated skill names the background install must never install. Use the names `celigo skills list` reports. The CLI checks the shape, not whether the skill exists, so a typo is accepted and excludes nothing. Set it to an empty string to clear the list. While the list is non-empty, the background install requests every other skill by name. An explicit `celigo skills install` ignores this setting. See [AI assistant skills](/cli/using-the-cli/skills.md). | | `specs_auto_update` | enum | `true` | `false` disables the once-a-day background refresh of the `celigo lint` schema pack from the `@celigo/api-specs` package on npm. The pack bundled with the release keeps working. See [Lint and resolve](/cli/local-tree/lint-and-resolve.md). Added in celigo-cli 2026.9.1. | ## Environment variables | Variable | Maps to | Notes | | ---------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `CELIGO_API_TOKEN` | `--token` | Most common form of auth in CI. | | `CELIGO_BASE_URL` | `--base-url` | Overrides profile and default. | | `CELIGO_PROFILE` | `--profile` | Select a profile for the session (a shell, an agent session, a CI job). Overrides the machine-wide active profile; `--profile` overrides it. A name that does not exist fails the command before any request. Added in celigo-cli 2026.9.1. | | `CELIGO_FORMAT` | `--format` | `json` or `table`. | | `CELIGO_MODE` | profile `mode` | `read`, `operate`, or `full`. Overrides the profile's mode for the session; a refusal then says `Current mode: read (from CELIGO_MODE)` and points at the variable, because `config set mode` changes nothing while it is exported. | | `CELIGO_ACCOUNT_ALIAS` | profile `account_alias` | Overrides the profile value for one shell session. | | `CELIGO_CONCURRENCY` | `--concurrency` | Requests in flight at once for `pull`, `diff`, `push`, and `promote` (1–16; default 8). The command's `--concurrency ` overrides it. Added in celigo-cli 2026.9.1. | | `CELIGO_TARGET_API_TOKEN` | — | The TARGET's API token for `celigo promote --to ` and `celigo diff --target ` on a machine with no profile of that name (a CI job). `CELIGO_API_TOKEN` is the source session's and never reaches the target. See [Promote](/cli/local-tree/promote.md). Added in celigo-cli 2026.9.1. | | `CELIGO_TARGET_BASE_URL` | — | The TARGET's API base URL for the same two commands (default `https://api.integrator.io`). `CELIGO_BASE_URL` does not apply to the target. Added in celigo-cli 2026.9.1. | | `CELIGO_NO_UPDATE` | — | Set to any value to suppress the auto-update check. | | `CELIGO_NO_SKILLS_INSTALL` | — | Set to any value to suppress the background skills install for one run. | | `CELIGO_NO_SPEC_UPDATE` | — | Set to any value to disable the once-a-day background refresh of the `celigo lint` schema pack. See [Lint and resolve](/cli/local-tree/lint-and-resolve.md). Added in celigo-cli 2026.9.1. | | `CELIGO_INDEX_STALE_MINUTES` | — | Account-index staleness threshold in minutes (default 15). | | `HTTPS_PROXY`/`HTTP_PROXY` | — | Standard proxy env vars, honored by the HTTP client. | There is no environment variable for `list_fields`. Set it per profile, or pass `--fields` on the command. The CLI detects CI automatically (any of `CI`, `CONTINUOUS_INTEGRATION`, `GITHUB_ACTIONS`, `JENKINS_URL`, `GITLAB_CI`, `CIRCLECI`, `BUILDKITE` set) and skips all three background tasks — the update check, the skills install, and the schema-pack refresh — without any of the `CELIGO_NO_*` variables. ## `celigo config` commands ```bash celigo config show # selected profile's config plus machine-wide settings celigo config get api_token # single field celigo config set api_token "" # write a field to the selected profile celigo config set base_url https://api.eu.integrator.io celigo config set default_format table celigo config set mode operate celigo config set account_alias acmecorp # this account's MCP alias celigo config set list_fields all # complete documents from every list command celigo config set auto_update false # machine-wide celigo config set skills_auto_install false # machine-wide celigo config set skills_auto_install_exclude writing-sql,writing-handlebars celigo config set specs_auto_update false # machine-wide: no daily lint schema-pack refresh ``` `celigo config` operates on the **selected profile** for per-profile keys — `--profile`, else `CELIGO_PROFILE`, else the active profile — and on the whole installation for the four machine-wide keys (which reject `--profile`). To target another profile, pass `--profile ` before the `config` subcommand. `config set … --profile ` is also how a profile that does not exist yet is created — the `config` commands are exempt from the check that fails every other command on an unknown profile name: ```bash celigo --profile ci config set default_format json celigo --profile new-account config set api_token "" # creates the profile ``` There is no `config unset`. Set the field to the default you want, or remove the profile entirely with `celigo profile delete ` and recreate it. ## Reset > ⚠️ **This permanently deletes all profiles and the account index.** `rm -rf ~/.celigo` cannot be undone — you must re-add every profile and re-authenticate afterward. ```bash rm -rf ~/.celigo # nuke everything (profiles + account index) celigo profile add default --api-token "" ```