> For the complete documentation index, see [llms.txt](https://developer.celigo.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.celigo.com/cli/commands/tools.md).

# 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](https://developer.celigo.com/api/api-reference/tools)

```
celigo tools <subcommand> [args] [flags]
```

Supports all [global flags](/cli/getting-started/global-flags.md).

***

## Subcommands

| Subcommand                                              | Purpose                                                                                                                     |
| ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `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).                                                                                 |
| `graph [ref]`                                           | Render the tool's Flow Builder graph from the local tree, offline — as JSON, Mermaid, or DOT. Added in celigo-cli 2026.9.1. |
| `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**

```bash
celigo tools list
```

**Example**

```bash
celigo tools list
```

**Corresponds to**: [`GET /v1/tools`](https://developer.celigo.com/api/api-reference/tools#get-v1-tools)

***

## `celigo tools get`

Fetch one tool by ID.

**Signature**

```bash
celigo tools get <id>
```

**Arguments**

| Argument | Type   | Required | Description |
| -------- | ------ | -------- | ----------- |
| `<id>`   | string | Yes      | Tool ID.    |

**Example**

```bash
celigo tools get 5f8d43a1b9e5a80011a35f2c
```

**Corresponds to**: [`GET /v1/tools/{_id}`](https://developer.celigo.com/api/api-reference/tools#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**

```bash
celigo tools create --file <path>
celigo tools create < tool.json     # or pipe on stdin
```

**Flags**

| Flag                | Type   | Default | Description                                                                                                  |
| ------------------- | ------ | ------- | ------------------------------------------------------------------------------------------------------------ |
| `-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**

```bash
celigo tools create --file ./tool.json
```

**Corresponds to**: [`POST /v1/tools`](https://developer.celigo.com/api/api-reference/tools#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.

> ⚠️ **`update` replaces the entire tool.** `PUT` erases any field you omit — routers, branches, page processors, hooks. `GET` the tool first, edit it, then send the complete object back, or use `set` for targeted edits.

**Signature**

```bash
celigo tools update <id> --file <path>
celigo tools update <id> < tool.json     # or pipe on stdin
```

**Arguments**

| Argument | Type   | Required | Description |
| -------- | ------ | -------- | ----------- |
| `<id>`   | string | Yes      | Tool ID.    |

**Flags**

| Flag                | Type    | Default | Description                                                                                                  |
| ------------------- | ------- | ------- | ------------------------------------------------------------------------------------------------------------ |
| `-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**

```bash
celigo tools get 5f8d43a1b9e5a80011a35f2c | jq '.name = "Renamed tool"' | celigo tools update 5f8d43a1b9e5a80011a35f2c
```

**Corresponds to**: [`PUT /v1/tools/{_id}`](https://developer.celigo.com/api/api-reference/tools#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**

```bash
celigo tools set <id> <key=value> [key=value ...]
```

**Arguments**

| Argument      | Type   | Required | Description                                                                                                                                                                                                   |
| ------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `<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**

```bash
celigo tools set 5f8d43a1b9e5a80011a35f2c name="Customer lookup" disabled=false
```

**Corresponds to**: [`GET /v1/tools/{_id}`](https://developer.celigo.com/api/api-reference/tools#get-v1-tools-_id) then [`PUT /v1/tools/{_id}`](https://developer.celigo.com/api/api-reference/tools#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**

```bash
celigo tools delete <id> [flags]
```

**Arguments**

| Argument | Type   | Required | Description |
| -------- | ------ | -------- | ----------- |
| `<id>`   | string | Yes      | Tool ID.    |

**Flags**

| Flag        | Type    | Default | Description                   |
| ----------- | ------- | ------- | ----------------------------- |
| `-y, --yes` | boolean | `false` | Skip the confirmation prompt. |

**Example**

```bash
celigo tools delete 5f8d43a1b9e5a80011a35f2c -y
```

**Corresponds to**: [`DELETE /v1/tools/{_id}`](https://developer.celigo.com/api/api-reference/tools#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**

```bash
celigo tools dependencies <id>
```

**Arguments**

| Argument | Type   | Required | Description |
| -------- | ------ | -------- | ----------- |
| `<id>`   | string | Yes      | Tool ID.    |

**Example**

```bash
celigo tools dependencies 5f8d43a1b9e5a80011a35f2c
```

**Corresponds to**: [`GET /v1/tools/{_id}/dependencies`](https://developer.celigo.com/api/api-reference/tools) (operationId: `listToolDependencies`)

***

## `celigo tools audit`

Show the audit log (change history) for one tool.

**Signature**

```bash
celigo tools audit <id>
```

**Arguments**

| Argument | Type   | Required | Description |
| -------- | ------ | -------- | ----------- |
| `<id>`   | string | Yes      | Tool ID.    |

**Example**

```bash
celigo tools audit 5f8d43a1b9e5a80011a35f2c
```

**Corresponds to**: [`GET /v1/tools/{_id}/audit`](https://developer.celigo.com/api/api-reference/tools)

***

## `celigo tools graph`

Render a tool's Flow Builder graph from the local tree, offline — the tool's input as the one source, the steps and branchings, and its output as the terminal, as the canvas draws them. Each step carries its name, category, application, and step components (filters, mappings, hooks, response mapping, error handling), resolved through the tree that `celigo pull` wrote. See [The local tree](/cli/local-tree.md). Added in celigo-cli 2026.9.1.

The graph is rendered from the documents on disk, so no profile or token is needed and the command is never mode-gated. `[ref]` is a tree path, a link, a resource folder, `type:id`, or a bare id. Any `tool.json` on disk works through `--file` (`-` for stdin), but its references stay unresolved unless the file sits in a pulled tree. A `flow:`, `api:`, or `tool:` ref renders with its own builder's shape from any of the three groups, and a `--file` document whose shape names no builder renders as a tool. The JSON output is the graph the Celigo VS Code extension's Flow Canvas consumes ([VS Code extension](/cli/vscode-extension.md)); `--as mermaid` renders natively in GitHub pull requests, and `--as dot` is Graphviz input. The full contract is the same as [`flows graph`](/cli/commands/flows.md#celigo-flows-graph).

**Signature**

```bash
celigo tools graph [ref] [--dir <path>] [--as json|mermaid|dot] [--file <path>] [--status] [--no-components]
```

**Arguments**

| Argument | Type   | Required | Description                                                                                                                                                                                                                                                            |
| -------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `[ref]`  | string | No       | The tool to render: a tree path, a link, a resource folder, `tool:<id>` (or `flow:`/`api:`), or a bare id. Required unless `--file` is given; with neither, the command exits `1` with `Provide a ref (a tree path, type:id, or id) or --file <path> ('-' for stdin).` |

**Flags**

| Flag              | Type                         | Default | Description                                                                                                                                                                                    |
| ----------------- | ---------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--dir <path>`    | string                       | `.`     | Tree root directory.                                                                                                                                                                           |
| `--as <format>`   | `json` \| `mermaid` \| `dot` | `json`  | Output format. `json` is the graph the VS Code canvas consumes; `mermaid` renders natively in GitHub pull requests; `dot` is for Graphviz.                                                     |
| `--file <path>`   | string                       | —       | Read the document from a file instead of the tree (`-` for stdin). References render unresolved unless the file sits in a pulled tree.                                                         |
| `--status`        | boolean                      | `false` | Add the tree's `celigo status` state (`clean`, `modified`, `missing`, or `untracked`) for the document and each step's resource. In `mermaid`/`dot` output the states appear as comment lines. |
| `--no-components` | boolean                      | `false` | Leave the step component chips out of `mermaid`/`dot` output.                                                                                                                                  |

**Example**

```bash
# From inside a pulled tree
celigo tools graph tool:5f8d43a1b9e5a80011a35f2c

# Graphviz, with the tree's status for the tool and each step
celigo tools graph "integrations/Order to Cash/tools/Ranking Tool/tool.json" --as dot --status
```

**Corresponds to**: no API call — the graph is built from the local tree.

***

## `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**

```bash
celigo tools add-processor <id> <exportOrImportId> [flags]
```

**Arguments**

| Argument             | Type   | Required | Description                                        |
| -------------------- | ------ | -------- | -------------------------------------------------- |
| `<id>`               | string | Yes      | Tool ID.                                           |
| `<exportOrImportId>` | string | Yes      | Export or import ID to attach as a page processor. |

**Flags**

| Flag                    | Type    | Default | Description                       |
| ----------------------- | ------- | ------- | --------------------------------- |
| `--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**

```bash
celigo tools add-processor 5f8d43a1b9e5a80011a35f2c 62abc123... --router r1 -y
```

**Corresponds to**: [`GET /v1/tools/{_id}`](https://developer.celigo.com/api/api-reference/tools#get-v1-tools-_id) then [`PUT /v1/tools/{_id}`](https://developer.celigo.com/api/api-reference/tools#put-v1-tools-_id)

***

## `celigo tools remove-processor`

Remove a page processor from a tool by its export or import ID.

**Signature**

```bash
celigo tools remove-processor <id> <exportOrImportId> [flags]
```

**Arguments**

| Argument             | Type   | Required | Description                                     |
| -------------------- | ------ | -------- | ----------------------------------------------- |
| `<id>`               | string | Yes      | Tool ID.                                        |
| `<exportOrImportId>` | string | Yes      | Export or import ID of the processor to remove. |

**Flags**

| Flag                    | Type    | Default | Description                       |
| ----------------------- | ------- | ------- | --------------------------------- |
| `--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**

```bash
celigo tools remove-processor 5f8d43a1b9e5a80011a35f2c 62abc123... -y
```

**Corresponds to**: [`GET /v1/tools/{_id}`](https://developer.celigo.com/api/api-reference/tools#get-v1-tools-_id) then [`PUT /v1/tools/{_id}`](https://developer.celigo.com/api/api-reference/tools#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**

```bash
celigo tools test-run <id>
```

**Arguments**

| Argument | Type   | Required | Description |
| -------- | ------ | -------- | ----------- |
| `<id>`   | string | Yes      | Tool ID.    |

**Flags**

| Flag                  | Type   | Default | Description                                                                                    |
| --------------------- | ------ | ------- | ---------------------------------------------------------------------------------------------- |
| `--export <exportId>` | string | —       | Export ID (page generator). Not required for tools; accepted for parity with `flows test-run`. |

**Example**

```bash
celigo tools test-run 5f8d43a1b9e5a80011a35f2c
```

**Corresponds to**: [`POST /v1/tools/{_id}/test/run`](https://developer.celigo.com/api/api-reference/tools)

***

## `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**

```bash
celigo tools test-run-step-results <id> <runId> <exportOrImportId>
```

**Arguments**

| Argument             | Type   | Required | Description                                 |
| -------------------- | ------ | -------- | ------------------------------------------- |
| `<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**

```bash
celigo tools test-run-step-results 5f8d43a1b9e5a80011a35f2c run_abc123 62abc123...
```

**Corresponds to**: [`GET /v1/tools/{_id}/test/run/{runId}/{exportOrImportId}`](https://developer.celigo.com/api/api-reference/tools)

***

## `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**

```bash
celigo tools test-run-step-logs <id> <runId> <exportOrImportId>
```

**Arguments**

| Argument             | Type   | Required | Description                         |
| -------------------- | ------ | -------- | ----------------------------------- |
| `<id>`               | string | Yes      | Tool ID.                            |
| `<runId>`            | string | Yes      | Test run ID.                        |
| `<exportOrImportId>` | string | Yes      | Step ID with an HTTP-issuing stage. |

**Example**

```bash
celigo tools test-run-step-logs 5f8d43a1b9e5a80011a35f2c run_abc123 62abc123...
```

**Corresponds to**: [`GET /v1/tools/{_id}/test/run/{runId}/{exportOrImportId}/logs/requestAndResponse`](https://developer.celigo.com/api/api-reference/tools)

***

## `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**

```bash
celigo tools debug-requests <id> <exportOrImportId> [flags]
```

**Arguments**

| Argument             | Type   | Required | Description                     |
| -------------------- | ------ | -------- | ------------------------------- |
| `<id>`               | string | Yes      | Tool ID.                        |
| `<exportOrImportId>` | string | Yes      | Export or import ID to inspect. |

**Flags**

| Flag                | Type   | Default | Description                            |
| ------------------- | ------ | ------- | -------------------------------------- |
| `--since <minutes>` | number | `60`    | Show requests from the last N minutes. |

**Example**

```bash
celigo tools debug-requests 5f8d43a1b9e5a80011a35f2c 62abc123... --since 15
```

**Corresponds to**: [`GET /v1/tools/{_id}/{exportOrImportId}/requests?time_gt=<ms>`](https://developer.celigo.com/api/api-reference/tools)

***

## `celigo tools debug-request-detail`

Get full request/response detail for a single debug log entry.

**Signature**

```bash
celigo tools debug-request-detail <id> <exportOrImportId> <key>
```

**Arguments**

| Argument             | Type   | Required | Description                          |
| -------------------- | ------ | -------- | ------------------------------------ |
| `<id>`               | string | Yes      | Tool ID.                             |
| `<exportOrImportId>` | string | Yes      | Export or import ID.                 |
| `<key>`              | string | Yes      | Log entry key from `debug-requests`. |

**Example**

```bash
celigo tools debug-request-detail 5f8d43a1b9e5a80011a35f2c 62abc123... <key>
```

**Corresponds to**: [`GET /v1/tools/{_id}/{exportOrImportId}/requests/{key}`](https://developer.celigo.com/api/api-reference/tools) (operationId: `getToolStepRequest`)

***

## `celigo tools connections`

List the connections used by a tool — every connection referenced by the tool's exports and imports.

**Signature**

```bash
celigo tools connections <id>
```

**Arguments**

| Argument | Type   | Required | Description |
| -------- | ------ | -------- | ----------- |
| `<id>`   | string | Yes      | Tool ID.    |

**Example**

```bash
celigo tools connections 5f8d43a1b9e5a80011a35f2c
```

**Corresponds to**: [`GET /v1/tools/{_id}/connections`](https://developer.celigo.com/api/api-reference/tools) (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**

```bash
celigo tools download <id> [-o <path>]
```

**Arguments**

| Argument | Type   | Required | Description |
| -------- | ------ | -------- | ----------- |
| `<id>`   | string | Yes      | Tool ID.    |

**Flags**

| Flag                  | Type   | Default           | Description                                                                                                               |
| --------------------- | ------ | ----------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `-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**

```bash
celigo tools download 5f8d43a1b9e5a80011a35f2c

# A stable path for a git-tracked export
celigo tools download 5f8d43a1b9e5a80011a35f2c -o ./templates/address-lookup.zip
```

**Corresponds to**: [`GET /v1/tools/{_id}/template`](https://developer.celigo.com/api/api-reference/tools), 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**

```bash
celigo tools clone <id> --integration <integrationId> [--name <name>] [-f <path>]
```

**Arguments**

| Argument | Type   | Required | Description     |
| -------- | ------ | -------- | --------------- |
| `<id>`   | string | Yes      | Source tool ID. |

**Flags**

| Flag                            | Type   | Default        | Description                                                                               |
| ------------------------------- | ------ | -------------- | ----------------------------------------------------------------------------------------- |
| `--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**

```bash
# A tool with one connection, cloned within the same environment
echo '{"connectionMap":{"5f8d43a1b9e5a80011a35f2e":"5f8d43a1b9e5a80011a35f2e"}}' \
  | celigo tools clone 5f8d43a1b9e5a80011a35f2c --integration 60a1b2c3d4e5f6a7b8c9d0e1 --name "Customer lookup (staging)"
```

**Corresponds to**: [`POST /v1/tools/{_id}/clone`](https://developer.celigo.com/api/api-reference/tools)

***

## `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**

```bash
celigo tools invoke <id> [--file <path>] [--log-mode <mode>]
```

**Arguments**

| Argument | Type   | Required | Description |
| -------- | ------ | -------- | ----------- |
| `<id>`   | string | Yes      | Tool ID.    |

**Flags**

| Flag                | Type                                     | Default | Description                                                                                                                                                                                                                                                                                                                                                                          |
| ------------------- | ---------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `-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**

```bash
echo '{"input": {"customerId": "C-1042"}, "overrides": {"connections": [{"_abstractId": "5f8d43a1b9e5a80011a35f2e", "_id": "5f8d43a1b9e5a80011a35f2e"}]}}' \
  | celigo tools invoke 5f8d43a1b9e5a80011a35f2c --log-mode debug
```

**Corresponds to**: [`POST /v1/tools/{_id}/invoke`](https://developer.celigo.com/api/api-reference/tools)

***

## Gotchas

* **`invoke` is the synchronous call; `test-run` is the development harness.** `invoke` runs the saved tool with a real input and prints its mapped output; `test-run` returns 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.)
* **`invoke` needs connection overrides.** Any step that references a connection requires `overrides.connections` in the body, even mapping each connection to itself. Log mode is chosen per invoke — the tool resource stores no logging setting, and only `debug` records a direct invoke.
* **`clone` requires a connection map when steps reference connections.** The server rejects such clones without one, even same-env — map each connection to itself.
* **`input` and `output` are JSON Schemas.** Every tool must declare an input schema and an output schema; callers are validated against them.
* **`PUT` replaces the whole tool.** Use `set` for targeted edits; `update` will erase any field you omit.
* **`add-processor` auto-creates a router.** If the tool has no routers, the first `add-processor` call creates a default router and a single branch. Use `--router` / `--branch` once you have more than one.
* **Debug logs require `debugUntil` on the referenced export/import**, not on the tool itself.

## Related

* [apis](/cli/commands/apis.md) — wrap a tool in an authenticated HTTP endpoint for synchronous callers.
* [mcp-servers](/cli/commands/mcp-servers.md) — expose a tool to MCP clients.
* [ai-agents](/cli/commands/ai-agents.md) — AI agents can call tools as part of their reasoning loop.
* [flows](/cli/commands/flows.md) — reference a tool as a step inside a flow.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developer.celigo.com/cli/commands/tools.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.