> 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/global-flags.md). # Global flags Flags available on every `celigo` command. These override config-file and env-var values. | Flag | Purpose | | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--token ` | API bearer token. Overrides `CELIGO_API_TOKEN` and the profile's credential (its API token or its `celigo login` session). Prefer the env var to avoid exposing the token in the process list. | | `--base-url ` | API base URL. Overrides `CELIGO_BASE_URL` and profile. A profile signed in with `celigo login` refuses a `--base-url` on another host, because its session is sent only to the host it was issued for (since celigo-cli 2026.10.1; see [Authenticate](/cli/getting-started/authenticate.md)). | | `--profile ` | Use a specific profile for this command only. The profile must exist — an unknown name is an error before any request (`celigo profile list` shows what exists). Overrides `CELIGO_PROFILE`, which overrides the machine-wide active profile. A value that differs from the active profile is announced on stderr by every command that targets it — `celigo: profile 'acme-sandbox' → api.integrator.io (pinned with --profile; the active profile is 'acme-prod')` — or refused before any request under `profile_pin_policy = strict` (since celigo-cli 2026.9.5; see [Profiles & regions](/cli/getting-started/profiles.md#refusing-a-pinned-profile)). An empty value is refused before any command runs (since celigo-cli 2026.10.1; see [Combine](#combine)). | | `--format ` | Output format. Default `json`. | | `--jq ` | Transform JSON output through a jq expression. | | `--verbose` | Print each HTTP request's method and URL, and every retry, on stderr. | | `-v, --version` | Print CLI version and exit. Read only as the first argument (`celigo --version`) since celigo-cli 2026.10.1. | | `-h, --help` | Show help for the current command. | ## `--format` Default is `json`. Override per invocation, per profile, or via env var: ```bash celigo flows list --format table # one command export CELIGO_FORMAT=table # shell session celigo config set default_format table # active profile (persistent) ``` With `--format table`, a list prints as a table, a single document as one line per field, and a value with no rows — a count, a string, a list of names — as JSON. See [Output formats](/cli/using-the-cli/output-formats.md). ## `--jq` Applies a jq expression to the JSON response. Useful for one-liners without piping: ```bash celigo integrations list --jq '.[] | {_id, name}' celigo flows get 5f83a9b2c7d3e8f1a2b3c4d5 --jq '{name, disabled, schedule}' ``` A result that is one string prints raw, without quotes. Several strings or numbers — `.[] | ._id` — print as one JSON array; to get one value per line, join them: `--jq '[.[] | ._id] | join("\n")'`. Several objects — `.[] | {_id, name}` — print as jq prints them, one indented object after another; wrap the expression in `[ ]` to get one JSON array. Under `--format table` the expression runs first. An array of objects prints as a table, and since celigo-cli 2026.10.1 a result that is not rows — a count, a list of names — prints as JSON instead of a header over blank rows. A single string and a stream of objects print as they do without `--format table`. ### Which jq runs `--jq` needs no separate jq install. Since celigo-cli 2026.10.1 it runs the first of these that exists: 1. `JQ_PATH`, when it is set — a path, or a name looked up on `PATH`. The CLI runs it with `--version` first and refuses it when it does not answer as jq. 2. The jq binary the CLI's `node-jq` dependency downloads when the CLI is installed. 3. A `jq` on `PATH` — for an install that skipped install scripts (`npm install -g --ignore-scripts`, or an install-script policy). With none of them, `--jq` says how to get one: ``` jq: no jq to run. The CLI's own jq is downloaded by node-jq's install script, which was skipped or blocked (npm install --ignore-scripts, or an install-script policy), and there is no jq on PATH. Install jq (https://jqlang.org/download/), set JQ_PATH to a jq binary, or reinstall the CLI letting that script run: npm install -g @celigo/celigo-cli --allow-scripts=node-jq (without --ignore-scripts). ``` See [Install](/cli/getting-started/install.md). ### When `--jq` fails after a write A bad expression never hides the result of a write that succeeded. Since celigo-cli 2026.10.1, when `--jq` cannot transform the response of a `create`, `update`, `set`, `clone`, or another command that changed the account, stderr says that the request succeeded — with the response's `_id` when it has one — and then prints the untransformed response as JSON. The command exits `1`. ``` The request succeeded (created _id 5f83a9b2c7d3e8f1a2b3c4d5), but --jq could not transform the response: jq: error (at :0): Cannot index string with "name" ``` ## `--verbose` Prints the method and full URL of each HTTP request to stderr before it is sent, and one line for every retry with its cause. It prints no headers, no token, and no request or response body. ```bash $ celigo flows get 5f83a9b2c7d3e8f1a2b3c4d5 --verbose GET https://api.integrator.io/v1/flows/5f83a9b2c7d3e8f1a2b3c4d5 ``` A retried request adds a line such as `Retry 1/3 after 1000ms (HTTP 503)...` before each new attempt. ## Combine All global flags except `-v`/`--version` can be mixed freely and placed before or after the subcommand: ```bash celigo --profile eu --format json flows list celigo flows list --profile eu --format json ``` `-v`/`--version` prints the CLI version only as the first argument: `celigo --version` or `celigo -v`. After a subcommand, `--version` belongs to that subcommand — its own option where it has one (`connections create --connector --version v2`, `http-connectors catalog --version `), an unknown-option error where it has none. Since celigo-cli 2026.10.1; earlier releases printed the CLI version for a subcommand's `--version` and sent nothing. To bind a whole shell or agent session to one profile instead of repeating `--profile`, set `CELIGO_PROFILE=`; see [Profiles & regions](/cli/getting-started/profiles.md#selecting-a-profile). Either pin keeps the session on that profile when `celigo profile use` moves the machine's active profile elsewhere — which is why a pin that differs from the active profile is announced on every command (reads included), and refused outright once `celigo config set profile_pin_policy strict` is set on the machine. Pass `--profile` only when that profile is the one you mean for this command. An empty `--profile ""` — usually a shell variable that was never set — is refused before any command runs, instead of running the command against the active profile (since celigo-cli 2026.10.1): ``` The --profile value is empty. Provide a profile name (this usually means a shell variable was unset), or drop --profile to use the active profile. ``` ## Field projection on `list` commands `--fields` and `--limit` are not global flags. They appear on `list` verbs, and they control how much data a listing returns. This section documents them here because the projection default affects almost every `list` command. ### The default A `list` command asks the API for a trimmed row rather than the complete resource document. Each row carries `_id`, `name`, and the fields the command's table columns need. This is the default because full collections are large: on one production account, `celigo exports list` returned 12.9 MB of JSON, and the projected listing returns 183 KB — 98.6% smaller. `celigo flows list` is 7.5 times smaller. The lean shape is what most work needs. You list to find a resource, then `get` it by ID. `get` is never projected and always returns the complete document. ### `--fields` | Value | Result | | --------- | ------------------------------------------------------------------------------------------------------- | | omitted | The command's built-in projection: `_id`, `name`, and the table columns. | | `default` | The same built-in projection, stated explicitly. | | `all` | Complete documents, as the API returns them. | | `a,b,c` | `_id`, `name`, and the named fields. Dot notation selects nested paths, for example `http.relativeURI`. | ```bash # The default projection celigo flows list --format table # Complete flow documents celigo flows list --fields all # Just the schedule, plus the identity fields that always travel celigo flows list --fields schedule,disabled ``` An explicit field list is a floor, not an exact shape. `_id` and `name` are always requested, and so is any field the command reads off each row internally. `celigo ai-agents list --fields lastModified` requests `lastModified` and `adaptorType`, because the command filters on `adaptorType` client-side. Dropping that field would break the command, not just the display. Expect at least the fields you named — never fewer. With `--format table`, an explicit field list also sets the table's columns: `_id`, `name`, then the fields you named. This holds on every group's `list` and on `http-connectors list`, `notifications list`, `stacks list`, and `templates marketplace`. Since celigo-cli 2026.10.1; earlier releases drew the default columns, blank where the projection had dropped a field, and left out the fields you asked for. ```bash # Columns: _id, name, schedule, disabled celigo flows list --fields schedule,disabled --format table ``` ### `--limit` `--limit ` caps the number of rows and fetches a single page. It exists only on the standard `list` verb. It takes a whole number from 1 up (see [Whole-number flags](#whole-number-flags)). The platform serves at most 1000 rows per page and refuses a larger `--limit`; since celigo-cli 2026.10.1 the CLI adds the reason under the error: ``` Hint: The platform serves at most 1000 rows per page: use a --limit of 1000 or less (without --limit a list verb pages through every row; audit list returns one page, so narrow it with filters). ``` Seven listings are built differently and accept `--fields` without `--limit`: * `ai-agents list` * `guardrails list` * `notifications list` * `stacks list` * `http-connectors list` * `trading-partner-connectors list` * `templates marketplace` To cap output from those, filter with `--jq`. ### Precedence Four inputs can decide the projection. They resolve in this order: 1. `--fields` on the command 2. `--jq` on the command, which requests complete documents 3. The profile's `list_fields` setting — see [Configuration reference](/cli/getting-started/configuration.md) 4. The command's built-in default projection `--jq` implies complete documents only when `--fields` is absent. A jq expression addresses the full document, so projecting underneath it would return `null` instead of an error. Combining `--jq` with an explicit `--fields` projects the rows first, and the expression then reads whatever the projection kept: ```bash # Complete documents, so the expression sees every field celigo exports list --jq '.[] | select(.adaptorType == "RESTExport") | .name' # Projected first: fields outside the list resolve to null celigo exports list --fields name --jq '.[] | {name, adaptorType}' ``` ### What is never projected * `get` on any resource, and every other single-resource read. * `account snapshot`, which builds the local index from complete documents. * `jobs`, `sync-jobs`, and `recycle-bin` listings. * `storage list` and `storage search`. * `audit` listings and the flow error listings. ### Endpoints that ignore the request The CLI requests a projection through the API's `include` query parameter. A few endpoints do not recognize it and return complete rows regardless. The CLI trims those rows locally, so the printed output matches the documented shape either way. Only the transfer size is unaffected. ## Whole-number flags Since celigo-cli 2026.10.1, `--limit`, `--since`, `--offset`, `--timeout`, and `--page` take only a positive whole number on every command that has them (`--offset` also takes `0`). A value such as `--timeout 5m`, `--limit 1e3`, or `--limit 2.5` is refused. Earlier releases read those three as 5 seconds, 1 row, and 2 rows.