tools
Builder-mode tools are reusable building blocks that encapsulate lookups, imports, transforms, and conditional routing behind input/output contracts. They're callable from flows, APIs, AI agents, MCP servers, and other tools.
REST API: Tools
celigo tools <subcommand> [args] [flags]Supports all global flags.
Subcommands
list
List all tools.
get <id>
Fetch one tool by ID.
create
Create a tool from a JSON body (--file <path> or stdin).
update <id>
Full replace from a JSON body (--file <path> or stdin); destructive PUT.
set <id> key=value …
Safe field edit (GET → modify → PUT). Supports key=file://<path>.
delete <id>
Delete a tool.
dependencies <id> (alias used-by)
List resources that depend on this tool.
audit <id>
Show the tool's audit log (change history).
add-processor <id> <exportOrImportId>
Add a page processor (export or import) to the tool.
remove-processor <id> <exportOrImportId>
Remove a page processor by its export/import ID.
test-run <id>
Start a test run and return stage-by-stage results.
test-run-step-results <id> <runId> <exportOrImportId>
Get stage-by-stage results for a test run step.
test-run-step-logs <id> <runId> <exportOrImportId>
List HTTP request/response logs for a test run step.
debug-requests <id> <exportOrImportId>
List debug request log entries for a step.
debug-request-detail <id> <exportOrImportId> <key>
Get full request/response detail for one log entry.
connections <id>
List the connections used by a tool.
download <id>
Download the tool as a template ZIP.
clone <id>
Clone a tool into a target integration.
invoke <id>
Invoke the saved tool synchronously and print its mapped output.
celigo tools list
List all tools in the account.
Signature
Example
Corresponds to: GET /v1/tools
celigo tools get
Fetch one tool by ID.
Signature
Arguments
<id>
string
Yes
Tool ID.
Example
Corresponds to: GET /v1/tools/{_id}
celigo tools create
Create a tool from a JSON body. Read the body from a file with -f, --file (recommended), or pipe it on stdin.
Signature
Flags
-f, --file <path>
string
—
Read the JSON body from a file instead of stdin (--file - also means stdin). Added in celigo-cli 2026.6.1.
Request body
A JSON object matching the POST /v1/tools request schema (input/output schemas, routers, branches, page processors, lookups, hooks).
Example
Corresponds to: POST /v1/tools
celigo tools update
Full replace of a tool from a JSON body (--file <path> or stdin). PUT is destructive — any field omitted from the payload is erased. Prefer set for targeted edits.
⚠️
updatereplaces the entire tool.PUTerases any field you omit — routers, branches, page processors, hooks.GETthe tool first, edit it, then send the complete object back, or usesetfor targeted edits.
Signature
Arguments
<id>
string
Yes
Tool ID.
Flags
-f, --file <path>
string
—
Read the JSON body from a file instead of stdin (--file - also means stdin). Added in celigo-cli 2026.6.1.
--force
boolean
false
Submit even if the body contains masked credential values (***) copied from a GET.
Request body
The complete tool document, matching the PUT /v1/tools/{_id} request schema.
Example
Corresponds to: PUT /v1/tools/{_id}
celigo tools set
Edit one or more fields on a tool without rewriting the whole document. Performs GET → apply assignments → PUT. A key=file://<path> value loads that field's value from a file instead of the command line; a leading ~ and paths relative to the current directory are supported. Added in celigo-cli 2026.6.1.
Signature
Arguments
<id>
string
Yes
Tool ID.
<key=value>
string
Yes (≥1)
Field assignment(s). Dot + bracket notation supported (e.g. routers[0].branches[0].name=Primary). Values auto-parse as JSON; null removes the field. Use key=file://<path> to load a value from a file.
Example
Corresponds to: GET /v1/tools/{_id} then PUT /v1/tools/{_id}
celigo tools delete
Delete a tool by ID. Prompts for confirmation unless -y is passed.
⚠️ Deleting a tool cannot be undone. Flows, APIs, MCP servers, and AI agents that reference this tool will fail. Run
celigo tools dependencies <id>first to confirm nothing depends on it.
Signature
Arguments
<id>
string
Yes
Tool ID.
Flags
-y, --yes
boolean
false
Skip the confirmation prompt.
Example
Corresponds to: DELETE /v1/tools/{_id} (operationId: deleteTool)
celigo tools dependencies
List resources that depend on this tool (alias: used-by). Use it to check whether a tool is safe to delete — an empty result means nothing references it.
Signature
Arguments
<id>
string
Yes
Tool ID.
Example
Corresponds to: GET /v1/tools/{_id}/dependencies (operationId: listToolDependencies)
celigo tools audit
Show the audit log (change history) for one tool.
Signature
Arguments
<id>
string
Yes
Tool ID.
Example
Corresponds to: GET /v1/tools/{_id}/audit
celigo tools add-processor
Add a page processor (export or import) to a tool. Auto-detects whether the target ID is an export or an import. If the tool has no routers yet, a default router + branch is created.
Signature
Arguments
<id>
string
Yes
Tool ID.
<exportOrImportId>
string
Yes
Export or import ID to attach as a page processor.
Flags
--router <routerId>
string
—
Target a specific router by ID.
--branch <branchName>
string
—
Target a specific branch by name.
-y, --yes
boolean
false
Skip the confirmation prompt.
Example
Corresponds to: GET /v1/tools/{_id} then PUT /v1/tools/{_id}
celigo tools remove-processor
Remove a page processor from a tool by its export or import ID.
Signature
Arguments
<id>
string
Yes
Tool ID.
<exportOrImportId>
string
Yes
Export or import ID of the processor to remove.
Flags
--router <routerId>
string
—
Target a specific router by ID.
--branch <branchName>
string
—
Target a specific branch by name.
-y, --yes
boolean
false
Skip the confirmation prompt.
Example
Corresponds to: GET /v1/tools/{_id} then PUT /v1/tools/{_id}
celigo tools test-run
Start a test run of a tool and return stage-by-stage results. Returns metadata (stages per step), flowJob, and childJobs. The CLI sends triggeredAt automatically.
Signature
Arguments
<id>
string
Yes
Tool ID.
Flags
--export <exportId>
string
—
Export ID (page generator). Not required for tools; accepted for parity with flows test-run.
Example
Corresponds to: POST /v1/tools/{_id}/test/run
celigo tools test-run-step-results
Get stage-by-stage results for a single step within a test run. Step IDs and runId come from the test-run response. Base64-encoded responses are decoded automatically.
Signature
Arguments
<id>
string
Yes
Tool ID.
<runId>
string
Yes
Test run ID returned by test-run.
<exportOrImportId>
string
Yes
Step ID (export or import) within the tool.
Example
Corresponds to: GET /v1/tools/{_id}/test/run/{runId}/{exportOrImportId}
celigo tools test-run-step-logs
List HTTP request/response logs for a step in a test run. Logs are only recorded for steps that issued outbound HTTP calls (exports, imports, lookups). Routers and stages that didn't make HTTP requests return 404 Not Found by design.
Signature
Arguments
<id>
string
Yes
Tool ID.
<runId>
string
Yes
Test run ID.
<exportOrImportId>
string
Yes
Step ID with an HTTP-issuing stage.
Example
celigo tools debug-requests
List debug request log entries for an export or import referenced by a tool. Requires debugUntil to be set on the export or import (use exports enable-debug / imports enable-debug).
Signature
Arguments
<id>
string
Yes
Tool ID.
<exportOrImportId>
string
Yes
Export or import ID to inspect.
Flags
--since <minutes>
number
60
Show requests from the last N minutes.
Example
Corresponds to: GET /v1/tools/{_id}/{exportOrImportId}/requests?time_gt=<ms>
celigo tools debug-request-detail
Get full request/response detail for a single debug log entry.
Signature
Arguments
<id>
string
Yes
Tool ID.
<exportOrImportId>
string
Yes
Export or import ID.
<key>
string
Yes
Log entry key from debug-requests.
Example
Corresponds to: GET /v1/tools/{_id}/{exportOrImportId}/requests/{key} (operationId: getToolStepRequest)
celigo tools connections
List the connections used by a tool — every connection referenced by the tool's exports and imports.
Signature
Arguments
<id>
string
Yes
Tool ID.
Example
Corresponds to: GET /v1/tools/{_id}/connections (operationId: listToolConnections)
celigo tools download
Download a tool as a template ZIP file. Use it to version a tool in git, or to move one between accounts.
The CLI requests the template, follows the signed URL, and writes the file locally.
Signature
Arguments
<id>
string
Yes
Tool ID.
Flags
-o, --output <path>
string
<tool-name>.zip
Output file path. Without it, the CLI writes <tool-name>.zip in the current directory, falling back to tool-<id>.zip.
Example
Corresponds to: GET /v1/tools/{_id}/template, which returns a short-lived signed URL. The CLI then downloads the archive from that URL.
celigo tools clone
Clone a tool into a target integration. Returns a manifest of every created resource as [{model, _id}] tuples. Requires full mode, like every other clone.
Connection-less tools clone with no body. Tools whose steps reference connections require a connection map, piped via stdin or --file — the server rejects such clones without one, even within the same environment:
Same-env clone — map each connection to itself:
{"connectionMap":{"connId":"connId"}}Cross-env clone — map source to target:
{"connectionMap":{"sourceConnId":"targetConnId"}}
Signature
Arguments
<id>
string
Yes
Source tool ID.
Flags
--integration <integrationId>
string
—
Required. Target integration for the clone.
--name <name>
string
server default
Name for the cloned tool.
-f, --file <path>
string
—
Read the connectionMap body from a file instead of stdin (--file - also means stdin).
Example
Corresponds to: POST /v1/tools/{_id}/clone
celigo tools invoke
Invoke a saved tool synchronously and print its mapped output. Requires operate mode.
The body is {"input": {...}, "overrides": {...}} from stdin or --file — a bare object is wrapped as the input automatically. Any tool step that references a connection requires overrides.connections: [{"_abstractId": "<connId>", "_id": "<connId>"}] (mapping a connection to itself is accepted).
Signature
Arguments
<id>
string
Yes
Tool ID.
Flags
-f, --file <path>
string
—
Read the body from a file instead of stdin (--file - also means stdin).
--log-mode <mode>
debug | basic | standard | detailed
—
Record this run in the tool's execution logs (sent as the x-log-mode header). Only debug takes effect for a direct invoke like this one — basic, standard, and detailed are accepted but the server only honors them when an AI agent or MCP server invokes the tool. Recorded runs surface in the platform's request-history feature when it is available on the account.
Example
Corresponds to: POST /v1/tools/{_id}/invoke
Gotchas
invokeis the synchronous call;test-runis the development harness.invokeruns the saved tool with a real input and prints its mapped output;test-runreturns stage-by-stage results for debugging. (Before celigo-cli 2026.8.7 there was no direct invocation — you had to expose the tool through an API or MCP server.)invokeneeds connection overrides. Any step that references a connection requiresoverrides.connectionsin the body, even mapping each connection to itself. Log mode is chosen per invoke — the tool resource stores no logging setting, and onlydebugrecords a direct invoke.clonerequires a connection map when steps reference connections. The server rejects such clones without one, even same-env — map each connection to itself.inputandoutputare JSON Schemas. Every tool must declare an input schema and an output schema; callers are validated against them.PUTreplaces the whole tool. Usesetfor targeted edits;updatewill erase any field you omit.add-processorauto-creates a router. If the tool has no routers, the firstadd-processorcall creates a default router and a single branch. Use--router/--branchonce you have more than one.Debug logs require
debugUntilon the referenced export/import, not on the tool itself.
Related
apis — wrap a tool in an authenticated HTTP endpoint for synchronous callers.
mcp-servers — expose a tool to MCP clients.
ai-agents — AI agents can call tools as part of their reasoning loop.
flows — reference a tool as a step inside a flow.
Last updated
Was this helpful?