> 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/install.md).

# Install

## Requirements

* **Node.js 22.12 or newer.** Check with `node --version`. Since celigo-cli 2026.11.1 the floor is 22.12, the release the CLI's `commander` 15 dependency requires; it was 22. On an older Node 22 release, `npm install` warns `EBADENGINE`.
* **npm** (bundled with Node) or an equivalent registry client (pnpm, yarn).

## Global install (recommended)

```bash
npm install -g @celigo/celigo-cli
celigo --version
```

npm puts the `celigo` command in its global folder: `<prefix>/bin` on macOS and Linux (`/usr/local/bin` with the Node.js installer for macOS), and `%AppData%\npm` on Windows. That folder must be on your `PATH`. On Windows, the Node.js installer adds it for the account that runs the installer.

The CLI runs from any directory. It does not need a git repository or a project folder. Configuration is stored in `~/.celigo/`.

### Windows

1. Install Node.js 22.12 or later with the Windows installer from [nodejs.org](https://nodejs.org/en/download), keeping **Add to PATH** selected.
2. Close every terminal window and every app with a terminal inside it, such as VS Code, Cursor, or a coding agent. A program that was already running doesn't see the `PATH` the installer changed.
3. Open a new PowerShell window, install the CLI, and check it:

   ```powershell
   npm install -g @celigo/celigo-cli
   celigo --version
   ```

If PowerShell says that `npm.ps1` or `celigo.ps1` cannot be loaded, see [`running scripts is disabled on this system`](/cli/using-the-cli/troubleshooting.md#running-scripts-is-disabled-on-this-system). If `celigo` isn't recognized, see [`celigo: command not found`](/cli/using-the-cli/troubleshooting.md#celigo-command-not-found).

### npm install scripts and `--jq`

The CLI's install script downloads the jq binary `--jq` runs: jq 1.8.2, from [jq's own release](https://github.com/jqlang/jq/releases), kept in the package's `vendor/jq/` folder only when its SHA-256 matches the digest pinned in the script. npm 11 warns about the script on a global install. To let that one script run — which is also what `--strict-allow-scripts` requires — install with:

```bash
npm install -g @celigo/celigo-cli --allow-scripts=@celigo/celigo-cli
```

Since celigo-cli 2026.11.1 the script is the CLI's own. Earlier releases ran jq 1.7.1, which the `node-jq` dependency's install script downloaded, so they were allowed with `--allow-scripts=node-jq`. An `allow-scripts` entry that still names `node-jq` no longer covers the download, and under `--strict-allow-scripts` the install fails until the entry names `@celigo/celigo-cli`.

The script never fails an install. Offline, behind a policy that blocks it, on a platform jq publishes no binary for, or with `--ignore-scripts`, the install succeeds without the binary. `--jq` then runs the jq that `JQ_PATH` names, or a `jq` on `PATH`, and says how to get one when there is neither (since celigo-cli 2026.10.1). A `JQ_PATH` set at install time skips the download. The download goes through `HTTPS_PROXY` or `HTTP_PROXY`, in either case, like every other request, else through npm's own `https-proxy` or `proxy` setting. A proxy the script cannot use is reported, never bypassed.

An upgrade downloads the binary again. Where github.com is unreachable, the upgraded CLI has no jq of its own until the script runs again with access:

```bash
npm rebuild -g @celigo/celigo-cli    # a global install
npm rebuild @celigo/celigo-cli       # a project install
```

See [Which jq runs](/cli/getting-started/global-flags.md#which-jq-runs).

## One-off invocation without install

```bash
npx --yes @celigo/celigo-cli --version
```

Useful in CI when you want to pin a specific version in a workflow file.

## Upgrading

```bash
npm install -g @celigo/celigo-cli@latest
```

The CLI checks npm for a newer version every four hours on startup and auto-installs it unless suppressed. Skip the check with `CELIGO_NO_UPDATE=1`. CI environments are detected (`CI`, `GITHUB_ACTIONS`, `GITLAB_CI`, `JENKINS_URL`, `CIRCLECI`, `BUILDKITE`, …) and the check is skipped automatically. `celigo config set auto_update false` keeps the check but only prints the command to run.

When a newer version exists, the CLI says so on stderr and installs it in the background; the update applies from your next command:

```
celigo: updating 2026.9.6 → 2026.10.1 in the background (same as: npm install -g @celigo/celigo-cli@2026.10.1); it should apply to your next command. Opt out with CELIGO_NO_UPDATE=1 or 'celigo config set auto_update false'.
```

When the CLI cannot update itself, it says so instead of staying on the old version silently. If the installed package directory is not writable by your user, it prints the `sudo` command to run instead; if a background install failed, the next check says that the update did not apply and retries.

Since celigo-cli 2026.10.1:

* **The update replaces the copy you run.** When your `celigo` sits under a prefix npm is not configured for — a second install earlier on `PATH`, or a `prefix` setting changed since — the background install and every command the CLI prints add `--prefix <dir>` (`npm install -g --prefix /opt/tools @celigo/celigo-cli@2026.10.1`). A plain `npm install -g` would update the other copy. Nothing changes where the two prefixes agree.
* **The update check works on Windows.** The check, the install, and the background skills install start npm's `.cmd` shims through the shell with one quoted command line. Until this release the check never reached npm on Windows, so no update was found there.
* **npm and npx run from your home directory, without the CLI's API tokens.** The update check and install, and the background skills install, start npm and npx from your home directory — never the directory you ran `celigo` in, whose project `.npmrc` could otherwise choose the registry — and without `CELIGO_API_TOKEN` or `CELIGO_TARGET_API_TOKEN` in their environment.
* **A home directory the CLI cannot write** (a full disk, a read-only sandbox) no longer slows every command: the check records its throttle first, and skips itself when it cannot.

## Uninstalling

> ⚠️ **`rm -rf ~/.celigo` is irreversible.** It permanently deletes your saved profiles, tokens, config, and the account index. Omit it if you plan to reinstall the CLI later.

```bash
npm uninstall -g @celigo/celigo-cli
rm -rf ~/.celigo     # removes profiles, config, and the account index
```

## Verifying the install

```bash
$ celigo --version
2026.6.1

$ celigo --help
Usage: celigo [options] [command]

Celigo CLI — manage your integrator.io resources from the terminal.

Options:
  --token <token>                           API bearer token (prefer CELIGO_API_TOKEN env var to avoid exposing in process list).
  --base-url <url>                          API base URL.
  --format <format>                         Output format (json or table). Defaults to config or json.
  --jq <expr>                               Transform JSON output with a jq expression (e.g. --jq '.[] | {id: ._id, name}').
  --verbose                                 Show HTTP requests.
  --profile <name>                          Run against a named config profile (must exist — see 'celigo profile list'). Overrides CELIGO_PROFILE, which in turn overrides the machine-wide active profile.
  -h, --help                                display help for command

Commands:
  config                                    Manage CLI configuration.
  profile                                   Manage named config profiles (multiple accounts/environments).
  login [options]                           Sign in with OAuth (authorization code + PKCE). …
  logout                                    Revoke the OAuth session for a profile and forget stored tokens. …
  skills                                    Install and update agent skills from the public celigo/ai repository.
  …

Version: 'celigo --version' (or 'celigo -v') prints the CLI's version — as the first argument
only, so that a subcommand's own --version (connections create, http-connectors catalog and
endpoint-detail) reaches the subcommand.
…
```

`-v`/`--version` is read only as the first argument since celigo-cli 2026.10.1, so it is no longer listed under `Options`.

If `celigo` isn't found after install, follow the steps for your system in [`celigo: command not found`](/cli/using-the-cli/troubleshooting.md#celigo-command-not-found).

## Releases & versioning

The CLI uses calendar versioning (e.g. `2026.6.1` = 2026-06, patch 1). Release notes and tarballs live on the [npm package page](https://www.npmjs.com/package/@celigo/celigo-cli).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developer.celigo.com/cli/getting-started/install.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
