getting-started

name	getting-started
description	Orientation for Celigo integrations -- core concepts, build order, account discovery, planning discipline, sandbox awareness, and which skill to use for each task. Start here when the task is unclear or the user is new to Celigo.

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 operation (export + import pair) callable from flows, APIs, AI agents, and MCP servers

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.

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.

First Steps

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

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)

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

Task	Skill	Key sections
Set up credentials for an external system	configuring-connections	Connection Type Decision Matrix, iClients
Fetch data from a system (export)	configuring-exports	Adaptor Decision Matrix, Export Execution Pipeline
Write data to a system (import)	configuring-imports	Adaptor Decision Matrix, Import Execution Pipeline
Wire exports to imports in a pipeline	building-flows	Flow Topologies, How to Build a Flow
Build a synchronous HTTP endpoint	building-apis	Builder vs Script mode, API Execution Pipeline
Build a reusable operation	building-tools	Tool Concepts, Tool Execution Pipeline
Map fields between source and destination	writing-mappings	Mapper 2.0 Workflow, Transformation 2.0
Write dynamic expressions in configs	writing-handlebars	Helper Catalog, Expression Patterns
Write JavaScript hooks	writing-scripts	Hook Point Decision Matrix
Set up EDI/B2B trading partner integrations	building-b2b	EDI Standards, Trading Partner Onboarding
Debug a failing flow	troubleshooting-flows	Error Diagnosis Framework, Diagnostic Workflow
Configure filters on exports or imports	configuring-filters	Expression Syntax, Filter Placement
Set up AI-powered import processing	configuring-ai-agents	Provider Decision Matrix
Configure lookup caches	configuring-lookup-caches	How to Build a Lookup Cache
Expose tools via MCP for AI agents	building-mcp-servers	How to Build an MCP Server
Manage account users and access	managing-users	Access Strategy Decision Matrix