Integreat CLI

A command line interface for Integreat.

Installation

Requires Node.js 22 or later.

Install with npm i great --global

Authentication

Before using most commands, you need to authenticate:

great login

This will open your browser to authenticate with GitHub or Google. The authentication token is stored locally and will be used for subsequent commands.

To log out:

great logout

Commands

Targeting an integration and account

Many commands act on a specific integration, and some on a specific account. They share the same rules for working out which one to use. The commands below note which of these they support.

• Integration — by default the current folder's integration (its integration.json and .great.json). To target another one, value commands take the -i <integration-id-or-key> flag, while others take it as a positional <integration> argument. An explicit integration overrides the folder.
• Account — needed only when an integration is addressed by key rather than id (a key is resolved within an account), or by commands that act on an account directly. Provide it with the -a <account-id-or-key> flag. When omitted, it falls back to the current folder's account (from .great.json), then the default account from config (great config set account <id>).

An integration or account passed explicitly that does not exist is an error — commands never silently fall back to the current folder in that case.

Authentication

• great login: Log in to Integreat via browser authentication.
• great logout: Log out and remove stored authentication token.
• great whoami: Displays your Integreat user.

Account Management

• great accounts or great accounts list: Display list of accounts (default action).
• great accounts create <name>: Create a new account.

Integration Management

• great integrations or great integrations list: Display list of integrations, with their type and account. Supports -a to filter by account, or --all to list all integrations ignoring the default account. Use -t <type> to only list integrations of a given type (integration, library, or template).
• great integrations create <name>: Create a new integration in Integreat. Requires -a. Returns integration ID to add to local integration.json for linking with workspace.

Local Workspace

• great init [name]: Initialize a new integration workspace locally. Creates integration.json and folder structure without creating anything in Integreat. If name is omitted, uses the current directory name. Use -a <account-id-or-key> to link the workspace to an account right away.
• great clone <integration>: Clone an integration to a new folder. <integration> can be an integration id or key; supports -a. Creates a new directory with the integration key (or id) and downloads all integration files.
• great pull: Pull remote changes to the current integration folder. Must be run from a folder with an integration.json file. Writes the integration config to integration.json and each element to its file under the matching folder, and updates .great.json with the remote links. Element files that no longer exist in Integreat are deleted, while local-only files are left alone. Will check for conflicts and abort.
• great push: Push local changes to Integreat. Must be run from a folder with an integration.json file; supports -a when creating a new integration, to create it in the right account. Will check for conflicts and abort. Use -y, --yes to answer yes to all prompts (sets values and detaches edited shadows). Template imports are registered in Integreat as well, and imports removed locally with great unimport are unregistered.
• great import <template>: Import a template, creating a local shadow file for each of its elements. <template> can be a template id or key; supports -a. A shadow file is an ordinary element file carrying a $shadow: true marker; it does not own its content (that lives in the source element) — the link to the source and the template import are recorded in .great.json. Integreat resolves all the imported templates together against the local elements, and the result is applied to the local files. Re-importing a template moves its shadows to the template's new version and removes the elements it no longer has (the next great push deletes them in Integreat too). Elements shared by several templates point at what the templates have in common. When templates share a service with different endpoint lists, the lists are merged into a local endpoint list that remembers every template it came from. Conflicts — such as a local element in the way of a template element, or templates disagreeing on an element — are reported by Integreat, and nothing is written. When the only conflict is that already imported templates pin a shared element at another version, the elements are listed and you are asked whether to move them to the version of the template being imported; answering yes leaves the other templates out of sync (which is reported) until they are re-imported. Use -y, --yes to answer yes to this without being asked. Must be run from a folder with an integration.json file (no push required first).
• great unimport <template>: Remove an imported template. <template> can be a template id or key; supports -a. Integreat resolves the remaining templates against the local elements, and the result is applied to the local files: elements only this template supplied are removed, shadows other templates also supply are kept with the template dropped from their provenance, and elements Integreat keeps as local elements lose their link to the templates. The template import is removed from .great.json. Nothing is changed in Integreat right away: the next great push deletes the removed elements and removes the template import there. Conflicts are reported and nothing is written. It is an error when the template is not imported. Must be run from a folder with an integration.json file.
• great include <element>: Include a single element from another integration as a shadow file. <element> is an element id, or "<folder>/<key>" (e.g. schemas/entry). With a key, -i, --integration is required and takes the id or key of the integration to include from. Use -a, --account to resolve an integration key (defaults to the folder's account, then the account in config). Use -p, --pinned-at <timestamp> to pin the shadow to the source as it stood at that ISO timestamp; omit it to follow the source's latest content. Including a service with an endpoint list, you're asked which endpoints to include with it as shadow elements. Leaving any out makes the endpoint list a local element with only the selected endpoints, detached from its source. Including an element that already exists replaces it with a shadow. You're asked first when local content would be overwritten. Must be run from a folder with an integration.json file.
• great rename <target> <new-key>: Rename an element or the account key, keeping the link to the remote element intact. <target> is "<folder>/<key>" for an element (e.g. schemas/entry), or the literal account. Use this instead of renaming an element file by hand — a plain rename is treated as deleting the old element and creating a new one. Already-pushed targets are renamed in Integreat too (requires login). Renaming a service also renames its endpoint list, and renaming an endpoint updates every service listing it. An endpoint list can't be renamed on its own. (To rename the integration itself, rename its folder — the folder name is the integration key.)
• great remove <target>: Remove an element file and its link in .great.json. <target> is "<folder>/<key>" (e.g. schemas/entry). Removing an endpoint also drops it from every service listing it. Nothing is changed in Integreat right away: the next great push deletes the removed elements there. Use this instead of deleting an element file by hand, which leaves a stale link behind for an element that hasn't been pushed. Must be run from a folder with an integration.json file.

Deployment & Runtime

• great deploy [integration]: Create a version and start the integration. Targets the [integration] argument or the current folder; supports -a. Use -n <name> to specify a custom version name. Only real integrations are started; library and template integrations get a new version but are not started.
• great run [integration]: Run a job or flow interactively. Targets the [integration] argument or the current folder; supports -a.
• great status [integration]: Show integration status and active version. Targets the [integration] argument or the current folder; supports -a.
• great repl [integration]: Start a Node.js REPL session with access to integration dispatch functions. Targets the [integration] argument or the current folder; supports -a. Use help() in the REPL to see available functions.

Value Management

Value commands read the latest values (the draft, when there is one, otherwise the active version), so they show what you're working on. Values are normally part of a version and take effect on the next great deploy. A value whose file has "isDynamic": true next to "type" is used by the running integration right away, outside of versions: setting or clearing it reloads the integration when it is running.

• great values or great values list: List all value elements in an integration. Supports -i and -a.
• great values get <element>: Get the value of a value element. The <element> can be either an element ID or key (a key needs integration context). Supports -i and -a.
• great values set <element> <value>: Set the value of a value element. The <element> can be either an element ID or key (a key needs integration context). Supports -i and -a. The value will be automatically cast to the appropriate type (string, number, boolean, date, or secret) based on the element's type definition. If the value starts with a dash (e.g. a PEM key like -----BEGIN PRIVATE KEY-----), put a bare -- before it so it isn't parsed as an option: great values set <element> -- '-----BEGIN ...'. Use $'...' quoting if you need \n sequences turned into real newlines.
• great values unset <element>: Clear the value of a value element, so it may fall back to an inherited value from a source element when present. The <element> can be either an element ID or key (a key needs integration context). Supports -i and -a.

Environments

• great env list: List configured environments. The built-in prod environment is always present, and the active one is marked.
• great env set <name> --api-url <url> --app-url <url>: Add or update a named environment. The name prod is reserved.
• great env use <name>: Switch the active environment. Use prod to reset to the default. When a non-prod environment is active, commands that contact the API print a warning.
• great env remove <name>: Remove a named environment.

Utilities

• great explode <file>: Convert legacy integration JSON to new file structure. Specify the path to a legacy JSON file as the first argument.
• great implode [folder]: Combine integration file structure into a single legacy JSON file. Specify the path to an integration folder as the first argument (defaults to current directory). Endpoint keys on services are resolved back to inline endpoint definitions. Note: value elements will have empty values in the output.
• great migrate: Migrate an existing workspace to the newest layout. Run it from the integration folder; it is safe to re-run. It does two things:
  • Moves sync bookkeeping stored inline as __id/__key/__timestamp props (the old layout) to a .great.json file (see Workspace files below).
  • Extracts inline endpoint definitions on services to endpoints/ files, leaving the endpoint keys on the service (see Services and endpoints below). Each key is the endpoint's id, or endpoint<N> by position, and is prefixed with the service key and a dash, unless --no-prefix is given. Keys are kept within 50 chars and made unique with a number suffix if needed. Run great push afterwards to create the endpoints in Integreat.
• great now: Prints the current Unix timestamp.

Workspace files

An integration folder contains:

• integration.json at the folder root. This holds the integration's own configuration: its name, description, status, type, and flags. The type is one of integration (the default), template, or library. The integration's key is the folder name, so renaming its folder to change the key (not yet implemented).
• Per-type folders (schemas/, services/, endpoints/, auths/, mutations/, dictionaries/, jobs/, values/, flows/, retryRules/) with one JSON file per element. These hold only configuration. Keys come from names, not stored fields: an element's key is its file name without the extension (e.g. schemas/entry.json has key entry). Rename an element with great rename (a plain file rename is treated as delete + recreate), and remove one with great remove.
• .great.json at the folder root. This holds the sync bookkeeping that links local files to their remote counterparts — the integration and element ids, the owning account, the last-synced timestamps and content hashes. It is managed by great pull and great push — commit it to git, and do not edit it by hand. Deleting it "forgets" all remote links, so the next great push recreates the remote elements; this is the clean way to regenerate a folder against a new environment.

Services and endpoints

A service is one file in services/, and each of its endpoints is a file of its own in endpoints/. The service refers to the endpoints it uses by key:

// services/crm.json
{
  "name": "CRM",
  "transporter": "http",
  "endpoints": ["crm-getEntries", "crm-setEntry"],
}

// endpoints/crm-getEntries.json
{
  "name": "Get entries",
  "match": { "action": "GET", "type": "entry" },
  "options": { "uri": "/entries" },
}

The order matters, as Integreat composes the endpoints in the order they are listed. Endpoints have a folder of their own because several services may list the same one, and their keys must be unique across the whole integration, so prefixing them with the service key is a good convention.

In Integreat the service consists of three element types: the service, one element per endpoint, and an endpoint list of ordered endpoint keys, tied to its service by having the same key. The endpoints array is that list, so one file gives you two elements in Integreat. The $shadow marker in this file says which of the two elements are shadows: true for both, "service" or "endpoints" for one of them.

Integreat still accepts an older "monolitic" endpoints format, where the endpoints are included directly in the endpoints array. This can't be mixed, so run great migrate to extract the inline endpoints to their own files before adding more endpoints.

Typical Workflow

For new integrations:

1. Initialize local workspace: great init "My Integration"
2. Create element files (schemas, services, etc.) in their respective folders
3. Push local files to Integreat: great push
4. Deploy: great deploy

For existing integrations:

• Clone to local: great clone <integration-id-or-key>
• Make local changes to element files
• Push changes: great push
• Deploy: great deploy

Setting values:

• From integration directory: great value set apiKey "my-secret-value"
• With integration flag: great value set apiKey "my-secret" -i my-integration
• By element ID: great value set val-123 "my-value"

Development and testing

To run against a non-prod setup (QA, local, etc.), configure a named environment once and switch to it:

great env set local --api-url http://localhost:3001 --app-url http://localhost:3000
great env use local
great login

Switch back to prod with great env use prod.