@squaredup/cli

CLI tool for validating and deploying plugins to the SquaredUp platform.

Installation

npm install -g @squaredup/cli
# or
pnpm add -g @squaredup/cli

Requires Node.js 22.19 or later

Authentication

There are two ways to authenticate: a browser sign-in (OAuth) for interactive use, and an API key for CI / headless environments.

Browser sign-in (default)

squaredup login

This starts the OAuth device flow: the CLI prints a verification URL and user code, then best-effort opens your browser. It then asks which organization to use (skipped if you only belong to one). Pass --region to skip the region prompt:

squaredup login --region eu

Your sign-in is stored as a short-lived token and refreshed automatically while the stored credentials remain valid. Run squaredup logout to clear them.

API key (CI / headless)

Browser sign-in needs a browser, so CI and headless shells should use an API key. Generate one at app.squaredup.com → Settings → Advanced → API, then:

squaredup login --apiKey <your-api-key> --region eu

| Option | Values | Default | Description | | ---------- | ---------- | -------------- | ------------------------------------------------------ | | --apiKey | string | — | Authenticate with an API key instead of the browser | | --region | us, eu | prompt, else us | Target region |

Status & logout

Check your current authentication (tenant, region, and whether you're using OAuth or an API key):

squaredup status

Log out and clear stored credentials:

squaredup logout

Commands

| Command | Status | Description | | ------------------ | --------- | --------------------------------------------------------------------------- | | login | Available | Authenticate with the SquaredUp platform | | logout | Available | Clear stored credentials | | status | Available | Show current authentication status | | validate | Available | Validate a plugin package or folder | | deploy | Available | Deploy a plugin to the platform | | list | Available | List deployed plugins for your tenant | | delete | Available | Delete a deployed plugin by ID | | test | Available | Run a data stream against a deployed data source and show the shaped data | | objects | Available | List the objects a scoped data stream can be tested against | | datasources | Available | List the deployed plugin's data sources | | index | Available | Re-index a data source's objects and wait for it to finish | | index-status | Available | Report a data source's re-index status | | edges | Available | List the edges on a data source's objects, as produced by correlation rules | | correlate | Available | Re-run the plugin's correlation rules and wait for them to finish | | correlate-status | Available | Report the correlation status of the plugin's rules |

Run squaredup <command> --help for the full flag list and examples for any command.

Global flags

| Flag | Description | | ----------- | --------------------------- | | --silent | Suppress all output | | --debug | Enable verbose debug output | | --version | Print CLI version | | --help | Show help |

Support log file

Every command run appends a timestamped record to a rolling squaredup-cli.log file in your OS's standard log directory (shown by squaredup status, and printed as Full log: <path> when a command fails). It's redacted so it's safe to attach to a support request. The file rotates at 5MB, keeping 3 generations; if a write fails, logging is silently disabled for that process without affecting the command. Set SQUAREDUP_LOG_FILE=0 to disable it, or SQUAREDUP_LOG_FILE=/custom/path to redirect it.

Corporate proxies and TLS inspection

Some corporate networks inspect HTTPS traffic with a product such as Zscaler, Netskope, or Palo Alto. The product re-signs each connection with its own root certificate. Your operating system trusts that root, but Node.js does not, because Node.js trusts only its bundled Mozilla root list by default. Each request then fails, and the CLI shows the reason under the error:

✖ fetch failed
  Caused by: [UNABLE_TO_GET_ISSUER_CERT_LOCALLY] unable to get local issuer certificate
  Hint: Node.js does not trust the server certificate. This happens behind TLS inspection ...

To prevent this, the CLI adds the certificates in your OS trust store to the Node.js default list at the start of each run. This has the same effect as the Node.js --use-system-ca flag. Set SQUAREDUP_USE_SYSTEM_CA=0 to turn it off.

If the CLI still cannot connect:

• Make sure that the root certificate of the inspection product is in your OS trust store. Your IT team can supply it.

• If you cannot add it to the OS trust store, give Node.js the certificate directly. Export it as a Base-64 encoded X.509 file (.cer or .pem) and set NODE_EXTRA_CA_CERTS to its path:

  export NODE_EXTRA_CA_CERTS=/path/to/inspection-root.pem

  On Windows, setx NODE_EXTRA_CA_CERTS C:\path\to\inspection-root.cer makes the setting permanent.

Development

Prerequisites: Node.js ≥22.19, pnpm

git clone <repo>
cd plugin-cli
pnpm install

| Script | Command | Description | | ------ | ------------ | ------------------------------------ | | Build | pnpm build | Compile TypeScript to dist/ | | Dev | pnpm dev | Watch mode — rebuild on file changes | | Lint | pnpm lint | Run ESLint | | Test | pnpm test | Run tests with Vitest |

After building, you can run the CLI locally:

node dist/index.js --help

To use the squaredup command globally from your local checkout, link the package after building:

pnpm build
pnpm link --global

The squaredup command will now resolve to your local dist/index.js. To unlink when you're done:

pnpm unlink --global @squaredup/cli

Credential storage

Credentials — an API key, or OAuth tokens (id token + refresh token) plus the chosen tenant, along with region and tenant name — are stored in the OS-specific user config directory managed by the conf package under the project name squaredup-cli. The config file is written with 0o600 permissions (owner read/write only).