Getting Started

<!-- TIER:1 -->

Getting Started with Celigo Integrations

Core Concepts

Celigo integrations move data between external systems through a small set of resource types:

• Connection -- credentials and configuration that authenticate to an external system (Salesforce, NetSuite, HTTP API, database, FTP, etc.)
• Export -- data source step that fetches records from a connected system (or receives them via webhook)
• Import -- data destination step that writes records to a connected system
• Flow -- pipeline that connects exports to imports, with optional branching, transformation, and scripting
• Integration -- named container that groups related flows, connections, and resources
• Script -- JavaScript hook that runs at specific points in the data pipeline (preSavePage, preMap, postMap, postSubmit, postResponseMap)
• API -- custom HTTP endpoint that exposes integration logic for synchronous external consumption
• Tool -- reusable building block (input schema -> routers with lookups/imports -> output contract) callable from flows, APIs, AI agents, MCP servers, and other tools
• AI agent -- LLM-powered pipeline step (stored as an import) that classifies, extracts, summarizes, or generates data mid-pipeline
• Guardrail -- safety/compliance check (PII, moderation, AI evaluation) that flags records; the parent pipeline decides what happens to flagged records
• Lookup cache -- account-level key-value store for fast in-memory reference lookups (cross-reference IDs, large translation tables, dedup markers)

How each surface is invoked

The three pipeline-carrying resources differ mainly in what starts them:

"Every night at 2 AM" or "when a webhook fires" always points at a flow. "Reachable from outside Celigo over HTTP" points at an API. "Reusable from multiple places inside Celigo" points at a tool (and a recipe needed both inside and outside is a tool exposed behind an API).

Build Order

Always build bottom-up. Resources reference each other, so dependencies must exist first:

1. Connection     (credentials for each system)
2. Export + Import (data source and destination steps, each referencing a connection)
3. Flow           (pipeline wiring exports to imports)

Never start by creating a flow -- its exports and imports must exist first, and those require connections.

At each layer, match the connector to the target application -- raw HTTP is the fallback, not the default. Use the application-specific adaptor when one exists (NetSuite, Salesforce, databases, FTP/S3); otherwise check for a pre-built HTTP connector (550+ apps: celigo http-connectors list); hand-write HTTP config only when neither covers the target. See configuring-connections and the adaptor decision matrices in configuring-exports / configuring-imports.

For APIs and tools, the same principle applies: build the connections, exports, and imports that the API/tool will use, then wire them into the API/tool definition.

<!-- TIER:2 -->

First Steps

0. Pick your surface: CLI or MCP

Skills in this pack show celigo ... CLI commands, but there are two equivalent ways to execute most operations:

• The Celigo CLI -- what the command blocks in these skills show.
• The Celigo Platform MCP server -- if your agent is connected to it, the same operations are MCP tools. Translate CLI blocks directly: list_<type> / upsert_<type> replace celigo <type> list|get|create|update, delete_resource replaces celigo <type> delete, and run_flow, cancel_job, list_jobs, list_flow_errors, list_execution_logs, deploy_template, and get_schema cover running, monitoring, deploying, and schema lookups. The MCP server also has tools with no CLI equivalent, such as search_knowledge_base and triage_flow_errors.

A few operations are CLI-only (no MCP tool): the local account index (celigo account snapshot|search|dependencies|lint), API-token management (celigo accesstokens ...), stacks, on-premise agents, and user management. For those, use the CLI, the integrator.io REST API, or the UI.

1. Configure the CLI

celigo config set api_token <your-token>       # Set your API bearer token
celigo config set base_url <url>               # Optional: override base URL for sandbox/EU
celigo config show                             # Verify configuration

The CLI accepts either token kind from Resources > API tokens as its bearer token: a personal access token (any user can generate one; inherits your own permissions; expires after 90 days by default) or an account API token (owner/admin-created, scopeable, long-lived -- prefer it for CI). See managing-api-tokens.

Which account the CLI targets. The CLI keeps one profile per account or environment (celigo profile list; each holds its own token). Every command resolves its profile as --profile > CELIGO_PROFILE > the machine-wide active profile that celigo profile use <name> selects. A person switching with profile use moves every session that did NOT pin a profile -- a session still passing --profile <name> keeps hitting <name>. An agent once carried a stale --profile for a day and wrote flows into another customer's account while the person believed their switch had moved it. Rules:

1. Confirm the target before the first write of a session -- run celigo profile whoami, and read the celigo: profile '<name>' → <host> line every write prints on stderr. If it names a profile other than the one the user means, stop and ask.
2. Do not pass `--profile` unless the user asked for that specific profile in this request. Work on the active profile. If a session must stay on one account, bind it once with export CELIGO_PROFILE=<name> rather than repeating the flag -- a repeated flag is how a stale value survives a switch.
3. `(pinned with --profile; the active profile is '<other>')` on a stderr line is a stop sign (CLI 2026.9.2 and later, printed on reads too): the person switched profiles and your pin did not follow. Ask which account they mean before the next command. Under profile_pin_policy = strict the CLI refuses such a command outright -- do not run celigo profile use, change profile_pin_policy, or edit ~/.celigo/config.json to get past it; which account a machine targets is the person's decision, never the agent's.
4. Never run `config set api_token` or `profile use` in response to an error. Profile 'x' does not exist means the NAME is wrong, not the token; celigo profile list shows what exists -- pick from it, never guess a name.

2. Build the Account Index

The account index is a local snapshot of all resources in your Celigo account. It enables fast search, dependency analysis, and linting without repeated API calls.

celigo account snapshot                        # Fetch all resources, build dependency graph
celigo account search <keyword>                # Find resources by name or keyword
celigo account dependencies <type> <id>        # Show what a resource uses and what uses it
celigo account lint                            # Find orphaned resources, offline connections, untriggered flows