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

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. Use -a <id-or-key> to filter by account ID or key, or --all to list all integrations ignoring default account.
• great integrations create <name>: Create a new integration on the Integreat server. Requires -a <account-id-or-key> flag. 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 on the server. If name is omitted, uses the current directory name.
• great clone <integration>: Clone an integration to a new folder. 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.
• great push: Push local changes to Integreat. Must be run from a folder with an integration.json file.

Deployment & Runtime

• great deploy [integration]: Create a version and start the integration. Specify an integration ID or key (with -a <account-id-or-key> flag) as the first argument, or run from a folder with integration.json. Use -n <name> to specify a custom version name.
• great run [integration]: Run a job or flow interactively. Specify an integration ID or key as the first argument, or run from a folder with integration.json. Use -a <account-id-or-key> flag when needed.
• great status [integration]: Show integration status and active version. Specify an integration ID or key (with -a <account-id-or-key> flag) as the first argument, or run from a folder with integration.json.
• great repl [integration]: Start a Node.js REPL session with access to integration dispatch functions. Use integration ID or key with -a <account-id-or-key> flag. Use help() in the REPL to see available functions.

Value Management

• great value list: List all value elements in an integration. Use -i <integration-id-or-key> flag or run from a folder with integration.json.
• great value get <element>: Get the value of a value element. The <element> can be either an element ID or key. When using an element key, provide integration context via -i <integration-id-or-key> flag or run from a folder with integration.json.
• great value set <element> <value>: Set the value of a value element. The <element> can be either an element ID or key. When using an element key, you must provide integration context via -i <integration-id-or-key> flag or run from a folder with integration.json. Use -a <account-id-or-key> flag when integration is specified by key (or rely on default account from config). The value will be automatically cast to the appropriate type (string, number, boolean, date, or secret) based on the element's type definition.

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). Note: value elements will have empty values in the output.
• great now: Prints the current Unix timestamp.

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 server: great push
4. Deploy: great deploy

For existing integrations:

• Clone to local: great clone <integration-id>
• 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

The following environment variables are useful for development and testing:

• INTEGREAT_APP_URL: Override the web app URL (default: https://app.integreat.io).
• INTEGREAT_API_URL: Override the API URL (default: https://api.integreat.io).
• GREAT_TOKEN: Manually provide a JWT token (bypasses stored token).

# Test with local app and API
INTEGREAT_APP_URL=http://localhost:3000 INTEGREAT_API_URL=http://localhost:3001 great login