> 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, and each profile's one credential An earlier source overrides a later one. `--token` on the command line wins over the env var, which wins over the config file. The config file's credential is the selected profile's one credential: its OAuth session from `celigo login`, or its `api_token`. A signed-in profile's session goes only to its own host, so a `--base-url` or `CELIGO_BASE_URL` naming another host is refused for it before any request. ## Config file schema ```json { "active_profile": "prod", "profiles": { "": { "api_token": "", "oauth": { "access_token": "", "refresh_token": "", "expires_at": "", "client_id": "", "issuer": "", "scope": "", "resource": "", "id_token": "", "identity_verified": true | false, "token_type": "", "token_endpoint": "" }, "identity": "@", "base_url": "", "default_format": "json" | "table", "mode": "read" | "operate" | "full", "account_alias": "", "list_fields": "all" | "default" } }, "identities": { "@": { "base_url": "", "user_id": "", "account_id": "", "company": "", "environment_id": "", "environment": "" } }, "settings": { "auto_update": "true" | "false", "profile_pin_policy": "allow" | "strict", "skills_auto_install": "true" | "false", "skills_auto_install_exclude": "", "specs_auto_update": "true" | "false" } } ``` A profile holds `api_token` or `oauth`, never both. `oauth`, `identity`, and the `identities` map are new in celigo-cli 2026.10.1: * **`oauth`** is the session `celigo login` stores, in the same write as the profile's `base_url` and `identity`, once the sign-in has succeeded; `celigo logout` removes it. `token_endpoint` appears only for a device sign-in redeemed at another token endpoint than the issuer's metadata advertises, and the session renews there. * **`identity`** is the key of the environment the profile is bound to: the environment's user (`user_id`) at its API host. `celigo login` and a `profile add` without a name record it; `logout` keeps it. * **`identities`** holds each environment once, with the account, company, and environment as labels, so several profiles can reference one. Neither `oauth` nor `identity` is a `config set` key. Every command that prints a profile — `config show`, `config get`, `profile show`, `profile list` — redacts each value whose key names a token, secret, or password to its first and last four characters; `token_type` and `token_endpoint`, which only name a token, print as they are. ### How the file is written Since celigo-cli 2026.10.1, every write of `config.json` — `config set` and `unset`, `profile use`, `add`, `delete`, and `rename`, the machine-wide settings, a sign-in, a session renewal, and `logout` — is one read-modify-write under a lock, `~/.celigo/config.lock`, so commands running in parallel never lose each other's changes. A command waits up to 10 seconds for another command's write, and a lock a crashed process left behind is reclaimed. The file is written through `config.json.tmp`, which is created owner-only, so no moment of a write leaves the tokens readable by other users. File mode is `0600` on Unix. A `config.json` that does not parse is never written over. Every command warns once and runs with defaults (`Warning: Could not parse the config file . Using defaults for this command; fix the file by hand before changing the configuration (a write never replaces it).`), and every write refuses until you fix the file or move it away (`Cannot change the configuration: cannot be read as JSON (). Fix the file by hand, or move it away to start over; nothing was written.`). Until celigo-cli 2026.10.1 the next write replaced such a file, erasing every other profile in it. Unknown fields are preserved across writes but not surfaced. ### The managed policy file Since celigo-cli 2026.9.5 the CLI reads a second file, which it never writes: the **managed policy file**, `/etc/celigo/policy.json` on macOS and Linux and `%ProgramData%\Celigo\policy.json` on Windows (the default `C:\ProgramData\Celigo\policy.json` is tried as well). It holds one key and exists so that an administrator can force `profile_pin_policy` from a place the account running the CLI cannot write: ```json {"profile_pin_policy": "strict"} ``` The file is tighten-only. `strict` there forces `strict` and locks the user-level key (`config set` and `config unset` refuse; `config get` and `config show` report `managed by /etc/celigo/policy.json`); `allow`, an absent key, or no file leaves the `settings` value in `~/.celigo/config.json` in charge. A file that cannot be read or parsed is reported once per invocation on stderr and ignored. See [The managed policy file](/cli/getting-started/profiles.md#the-managed-policy-file) in the profiles guide. ### Per-profile keys Each profile targets one account and environment, so these keys are set per profile. | Field | Type | Default | Notes | | ---------------- | ------ | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `api_token` | string | — | API token: the profile's credential when it is not signed in with OAuth. A command that calls the API needs a credential; `config` and `profile` commands do not, `profile whoami` aside. Refused on a signed-in profile — a profile holds one credential: `celigo logout` first, or keep the token in a profile of its own. | | `oauth` | object | — | The OAuth session `celigo login` stores. Not a `config set` key; `celigo logout` removes it, and `config get oauth` prints it as redacted JSON. Added in celigo-cli 2026.10.1. | | `identity` | string | — | The `identities` key of the environment the profile is bound to. Recorded by `celigo login` and a `profile add` without a name, kept across `logout`. Not a `config set` key. Added in celigo-cli 2026.10.1. | | `base_url` | string | `https://api.integrator.io` | Use your region's API host. See [Profiles & regions](/cli/getting-started/profiles.md#regions). On a signed-in profile, `config set base_url` — and `config unset base_url`, which moves the profile to the default host — is refused for any host but the session's. | | `default_format` | enum | `json` | `json` for scripts, `table` for terminals. Since celigo-cli 2026.10.1 any other value is refused (`Invalid format 'xml' for default_format. Use json or table.`); it used to be stored and then read as `json`. | | `mode` | enum | `full` | Permission mode. Since celigo-cli 2026.10.1, raising it — `read` to `operate` or `full`, `operate` to `full` — needs a person at a terminal, and a stored value that is not a mode runs the profile in `read`. See [Permission modes](/cli/getting-started/profiles.md#permission-modes). | | `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 five 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` and `config unset` reject `--profile` for them. | Field | Type | Default | Notes | | ----------------------------- | ------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `auto_update` | enum | `true` | `false` downgrades the background self-update to a notification only. | | `profile_pin_policy` | enum | `allow` | What a `--profile` or `CELIGO_PROFILE` value that differs from the machine-wide active profile gets. `allow` runs the command and announces the divergence on stderr (`celigo: profile 'acme-sandbox' → api.integrator.io (pinned with --profile; the active profile is 'acme-prod')`). `strict` refuses it before any request (exit 1), so `celigo profile use` is the only way an account gets selected on this machine. Since celigo-cli 2026.10.1 the refusal also covers `config get`/`set`/`unset`/`show`, `profile show`/`add`/`delete`/`rename`, `login`, and `logout`; `profile use` itself needs a terminal, and `promote --to` a profile that is not the active one asks a person to type the profile's name back. `profile whoami --profile `, `profile list`, `skills`, and the offline tree verbs are unaffected. Loosening `strict` back to `allow`, with `config set` or `config unset`, needs a person at a terminal typing `allow` — it is refused off a TTY — and the managed policy file (above) can force `strict` from outside the user's account. See [Refusing a pinned profile](/cli/getting-started/profiles.md#refusing-a-pinned-profile) in the profiles guide. Added in celigo-cli 2026.9.5. | | `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. Clear the list with `celigo config unset skills_auto_install_exclude`: `config set` refuses an empty value, and a value of commas alone is refused with `No skill names in ','. To clear skills_auto_install_exclude, run: celigo config unset skills_auto_install_exclude`. 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. Wins over the selected profile's credential, an OAuth sign-in included. | | `CELIGO_BASE_URL` | `--base-url` | Overrides profile and default. For a profile signed in with OAuth, a host other than the session's is refused before any request, since celigo-cli 2026.10.1. | | `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. A value that differs from the active profile is announced on stderr by every command that targets it (`… (pinned with CELIGO_PROFILE; the active profile is 'x')`), or refused under `profile_pin_policy = strict` — a `celigo profile use` in another terminal does not redirect a session bound this way. See [Selecting a profile](/cli/getting-started/profiles.md#selecting-a-profile). It is also the profile `celigo login` signs in to when `--profile` is not given. | | `CELIGO_FORMAT` | `--format` | `json` or `table`. | | `CELIGO_MODE` | profile `mode` | `read`, `operate`, or `full`. Since celigo-cli 2026.10.1 it only tightens: the session runs in the stricter of the profile's stored mode and the variable (a profile with no stored mode, or no profile at all, has the `full` default), and it tightens a `promote --to` target's mode the same way. A refusal the variable caused says `Current mode: read (from CELIGO_MODE)` and names the variable, because `config set mode` changes nothing while a stricter one is exported. A value that is not a mode counts as `read`, with a warning; set but empty, it refuses every command. See [Permission modes](/cli/getting-started/profiles.md#permission-modes). | | `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. For a target profile signed in with OAuth, a host other than the session's is refused. | | `CELIGO_AUTH_ISSUER` | — | The OAuth issuer `celigo login` signs in with, instead of the one derived from the API base URL. HTTPS, or HTTP on localhost only. Added in celigo-cli 2026.10.1. | | `CELIGO_OAUTH_CLIENT_ID` | — | Replaces the CLI's built-in public OAuth client id, `celigo-cli`, for sign-ins. Added in celigo-cli 2026.10.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). | | `JQ_PATH` | — | The jq binary `--jq` runs — a path, or a name looked up on `PATH`. Since celigo-cli 2026.10.1, `--jq` runs `JQ_PATH` when it is set, else the jq the CLI downloads at install time, else a `jq` on `PATH`, so an install with `--ignore-scripts` still works; a `JQ_PATH` that does not run like jq is refused. | | `HTTPS_PROXY`/`HTTP_PROXY` | — | Standard proxy env vars, in either case, honored by every request — sign-ins and signed-URL transfers included. | | `ProgramData` | — | Windows only: the folder whose `Celigo\policy.json` is read as the [managed policy file](#the-managed-policy-file), beside the fixed `C:\ProgramData\Celigo\policy.json`. | 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. In CI, `celigo login` also uses the device grant. ## `celigo config` commands ```bash celigo config show # selected profile's config plus machine-wide settings celigo config get api_token # single field celigo config get oauth # a sign-in's session, as redacted JSON 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 set profile_pin_policy strict # machine-wide: refuse a --profile/CELIGO_PROFILE that differs from the active profile celigo config unset default_format # remove a field so its default applies again celigo config unset skills_auto_install_exclude # machine-wide: clear the exclusion list ``` `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 five 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 ``` `config set` refuses an empty value — usually an unset shell variable — with `The argument is empty. Provide a non-empty value (this usually means a shell variable was unset). To clear a key, run: celigo config unset .` Since celigo-cli 2026.10.1, `celigo config unset ` is the one way to clear a key, per-profile or machine-wide. It is held to the same rules as `config set` and never creates a profile. See the [`config` command reference](/cli/commands/config.md#celigo-config-unset). ## 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. Sign each signed-in profile out first (`celigo logout --profile `): deleting the file revokes nothing, and a session's tokens stay valid on the server until they expire. ```bash rm -rf ~/.celigo # nuke everything (profiles + account index) celigo login # sign in again, or: celigo profile add default --api-token "" ```