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
celigo account stats                           # Resource counts by type

The index auto-refreshes when stale (default: 4 hours, configurable via CELIGO_INDEX_STALE_HOURS). Commands that depend on the index refresh it automatically unless --no-refresh is passed.

3. Discover Before Building

Before creating new resources, always check what already exists:

• celigo account search "customer sync" -- find existing flows, exports, imports by keyword
• celigo account dependencies flow <id> -- see the full resource tree for an existing flow
• celigo account lint -- identify orphaned exports/imports you might reuse

Planning Discipline

Before writing any JSON or CLI commands, answer these questions:

What kind of operation is this?

• Modifying an existing resource's config (export settings, import mappings, scripts) -- work on the resource directly with celigo <type> set or celigo <type> get + edit + celigo <type> update. Don't rebuild the flow
• Modifying an existing flow's structure (add/remove steps, change schedule) -- GET the flow, modify the structure, PUT it back
• Building something new where every step is clear -- build directly, bottom-up
• Any ambiguity about what to build -- design first (see checklist below)

Design checklist (when ambiguity exists):

• What source systems? What destination systems?
• What data moves between them, in which direction?
• How often? (cron schedule, webhook trigger, on-demand)
• What happens when a step fails? (proceedOnFailure, error notifications)
• Do downstream steps need data from upstream responses? (response mapping)
• Is this a one-off or a reusable template? (abstract/instance flow)
• Sandbox or production? (never mix -- sandbox: true flows only use sandbox: true connections)

<!-- TIER:3 -->

Sandbox vs Production

Celigo enforces strict separation:

• A sandbox: true connection can only be used by sandbox: true flows
• A production (non-sandbox) connection can only be used by production flows
• Mixing sandbox and production resources will cause runtime errors

When testing, always create flows with disabled: true and verify before enabling.

Which Skill to Use

When No Skill Covers the Shape

The reference schemas shipped with these skills cover the high-stakes shapes where guessing corrupts data, not the whole API surface. When you need a field or resource no skill documents, use the live sources — in this order:

1. A real resource is ground truth. celigo <type> get <id> returns the exact wire shape; request bodies for create/update are exactly what GET returns. Copying a live resource beats any documentation.
2. The developer docs are agent-native and always current. Every API reference page is fetchable as markdown — append .md to any page URL (e.g. https://developer.celigo.com/api/api-reference/flows.md), start from the index at https://developer.celigo.com/llms.txt, or ask a direct question: GET https://developer.celigo.com/readme.md?ask=<question>.
3. Prefer a shipped schema when one exists — schemas under each skill's references/ are synced from the API specs and reviewed before shipping, and their x-celigo-ai-guidance notes carry hazards the raw docs don't.