# workflows

Manage CARTO Workflows — list, inspect, create, update, copy, validate, verify-remote, run, share, schedule, publish as MCP tools, and install extensions.

```bash
carto workflows list [options]                       # List workflows
carto workflows get <id>                             # Pretty details; --json = round-trippable bundle
carto workflows create [--file <bundle.json>]        # Create from a bundle
carto workflows update <id> [--file <bundle.json>]   # Update (partial bundles OK)
carto workflows delete <id>                          # Delete workflow
carto workflows copy <id> --dest-profile <name>      # Duplicate (cross-tenant or same-tenant)
carto workflows schema [section]                     # JSON Schema reference for agents
carto workflows validate [--file <bundle.json>]      # Tier-0 offline (Zod-only) bundle check
carto workflows verify-remote <id|--file …> --connection <c>  # Tier-0 + Tier-2 deep validation against a warehouse
carto workflows to-sql [--file <bundle.json>]        # Compile bundle → SQL preview (what `run` would submit)
carto workflows components list                      # Agent-facing component catalog
carto workflows components get <names>               # Full input/output signature for components
carto workflows run <id>                             # Execute workflow; returns per-node outputs
carto workflows run output <id> <node-id>            # Fetch a node's output rows
carto workflows run status <job-id>                  # Poll an async-submitted run
carto workflows share <id> [--org | --with <email>]  # Share workflow
carto workflows unshare <id>                         # Revert to private
carto workflows mcp publish|unpublish|describe|list  # MCP tool lifecycle
carto workflows schedule add|update|remove <id>      # Warehouse cron lifecycle
carto workflows extensions install --file <ext.zip> --connection <name>  # Install an extension zip
```

## The bundle model

`workflows get <id> --json` returns a **round-trippable bundle** (title and description lifted, server fields stripped, privacy synthesised). Pipe straight back into `workflows create --file` or `workflows update --file`:

```bash
carto workflows get abc123 --json > /tmp/wf.json
jq '.title = "New title"' /tmp/wf.json | carto workflows update abc123 --file -
```

Structural validation runs on Zod schemas under `src/schemas/workflows/`. For the full bundle recipe, see the [`carto-create-workflow`](https://github.com/CartoDB/agent-skills/tree/master/skills/carto-create-workflow) skill.

{% hint style="info" %}
**GeoJSON inputs**: `native.tablefromgeojson` and `native.drawcustomgeographies` accept both a stringified `FeatureCollection` and a `FeatureCollection` object on the input `value` field, so workflows that ingest GeoJSON can be authored from the CLI.
{% endhint %}

## `carto workflows list`

| Option                           | Description                                                                            |
| -------------------------------- | -------------------------------------------------------------------------------------- |
| `--page <n>` / `--page-size <n>` | Pagination.                                                                            |
| `--order-by <field>`             | `updated_at` (default), `created_at`, `title`. Aliases `updated` / `created` accepted. |
| `--order-direction <dir>`        | `ASC` or `DESC`.                                                                       |
| `--search <term>`                | Search filter.                                                                         |
| `--privacy <level>`              | Filter by privacy: `public` or `shared`.                                               |
| `--tags <json>`                  | Filter by tags (JSON array).                                                           |
| `--all`                          | Fetch all pages automatically.                                                         |

## `carto workflows create` / `carto workflows update`

| Option                         | Description                                                                   |
| ------------------------------ | ----------------------------------------------------------------------------- |
| `--file <path>`                | Read bundle JSON from a file (or stdin via `-`).                              |
| `--verify`                     | Run Tier-2 checks (sources region + SQL dry-run + engine compile) post-write. |
| `--verify sources,sql,compile` | Subset — each can also be used alone.                                         |

```bash
# Create from a bundle
carto workflows create --file my-pipeline.json

# Update + verify post-write
carto workflows update abc123 --file pipeline.json --verify
```

## `carto workflows validate` / `carto workflows verify-remote`

* **`validate`** — **Zod-only**, offline, no network. Use it to iterate on a bundle locally before writing. The `--connection` and `--no-engine` flags are removed; for warehouse-aware validation use `verify-remote`.
* **`verify-remote`** — Standalone command, hard-errors without a connection. Runs the full Tier-0/1/2 stack (structural + engine compile + schema trace + sources + customsql) without writing the workflow. Useful before opening a PR that ships a new bundle. Advisory warnings appear in the output but no longer fail the exit code; pass `--strict` to restore the previous behaviour, where any warning fails the run.

```bash
# Offline structural check
carto workflows validate --file bundle.json

# Full warehouse-side check
carto workflows verify-remote --file bundle.json --connection carto_dw

# Same, but fail on advisory warnings (CI gates)
carto workflows verify-remote --file bundle.json --connection carto_dw --strict
```

| Option                      | Description                                                                            |
| --------------------------- | -------------------------------------------------------------------------------------- |
| `--file <path>`             | Bundle JSON path (or pipe via stdin).                                                  |
| `--connection <name\|uuid>` | (Required for `verify-remote`) Override `bundle.connectionId`.                         |
| `--mode <create\|update>`   | (`validate` only) Validation mode (default: `update`).                                 |
| `--strict`                  | (`verify-remote` only) Fail the exit code on any advisory warning, not just on errors. |

## `carto workflows to-sql`

Compile a bundle to the SQL that `run` would submit, without executing:

```bash
carto workflows to-sql --file bundle.json
```

## `carto workflows components`

Agent-facing component catalog. Use `list` to discover components, `get` to fetch their full input/output signatures.

```bash
# Browse native components
carto workflows components list --connection carto_dw --group Joins

# Full signatures (for agent composition)
carto workflows components get native.customsql,native.joinv2 --connection carto_dw --json

# Include input-format reference entries
carto workflows components get native.customsql --connection carto_dw --input-formats
```

| Option                      | Description                                                                                                                                |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `--connection <name\|uuid>` | (Required) Catalog is fetched per-connection so extensions and stored procedures appear alongside native components. Provider is inferred. |
| `--group <name>`            | Filter `list` to a specific group (e.g. `Joins`).                                                                                          |
| `--search <term>`           | Substring match across name / title / description.                                                                                         |
| `--starred`                 | Only starred components.                                                                                                                   |
| `--include-deprecated`      | Include deprecated components (hidden by default).                                                                                         |
| `--input-formats`           | (`get` only) Include deduped format reference entries for all input/output types.                                                          |

{% hint style="warning" %}
**Breaking in 0.7:** `components list` and `components get` now require `--connection`. The previous `--provider` flag was removed; the provider is now inferred from the connection so extensions and stored procedures appear in the catalog. Extension and stored-procedure load failures surface as warnings (in JSON output under a `warnings` array; in text as `Warning: …` lines).
{% endhint %}

For `Selection`-typed inputs (e.g. `native.isolines.mode`) the JSON output includes both `options` (the wire values the engine accepts, e.g. `"walk"`) and `optionsText` (the matching human-readable labels, e.g. `"Walk"`). Use `options` when populating the bundle.

## `carto workflows run`

Execute a workflow and fetch results:

```bash
carto workflows run <id>                          # Run synchronously; returns per-node outputs
carto workflows run <id> --async                  # Return immediately with a job ID
carto workflows run status <job-id>               # Poll the async job
carto workflows run output <id> <node-id>         # Fetch a specific node's output rows
```

## `carto workflows share` / `carto workflows unshare`

```bash
# Share with the whole organization
carto workflows share <id> --org

# Share with a specific user (email → user-id lookup is automatic)
carto workflows share <id> --with someone@example.com

# Revert to private
carto workflows unshare <id>
```

## `carto workflows mcp`

Publish a workflow as an MCP tool so it shows up in the CARTO MCP Server:

```bash
carto workflows mcp publish <id> [options]      # Expose this workflow as an MCP tool
carto workflows mcp unpublish <id>              # Remove from MCP catalog
carto workflows mcp describe <id>               # Show current MCP tool registration
carto workflows mcp list                        # List all workflows published as MCP tools
```

See the [Workflows as MCP Tools](/carto-user-manual/workflows/workflows-as-mcp-tools.md) guide for the publishing flow end-to-end.

## `carto workflows schedule`

Warehouse-side cron lifecycle for the workflow's run schedule:

```bash
carto workflows schedule add <id> --cron "0 6 * * *"
carto workflows schedule update <id> --cron "0 6 * * 1-5"
carto workflows schedule remove <id>
```

## `carto workflows copy`

Duplicate a workflow between profiles. Connection mapping behaves like `maps copy`.

```bash
# Auto-map by name
carto workflows copy abc123 --dest-profile production

# Explicit connection
carto workflows copy abc123 \
  --source-profile staging \
  --dest-profile production \
  --connection prod-bigquery
```

| Option                       | Description                                                 |
| ---------------------------- | ----------------------------------------------------------- |
| `--dest-profile <name>`      | (Required) Destination profile name.                        |
| `--source-profile <name>`    | Source profile (default: current).                          |
| `--connection <name>`        | Destination connection name (auto-maps by name if omitted). |
| `--connection-mapping <map>` | Per-source map: `"src1=dst1,src2=dst2"`.                    |
| `--title <title>`            | Override workflow title in the destination.                 |
| `--skip-source-validation`   | Skip validating source table accessibility.                 |

For the full walkthrough including connection-mapping scenarios, see [Examples → Copying maps and workflows between organizations](/carto-for-agents/cli/examples.md#copying-maps-and-workflows-between-organizations).

## `carto workflows extensions install`

Install a CARTO Workflows extension zip (bundles `metadata.json` + provider-specific SQL) into a warehouse connection.

```bash
carto workflows extensions install --file my-extension.zip --connection carto_dw
```

| Option                | Description                                                               |
| --------------------- | ------------------------------------------------------------------------- |
| `--file <path>`       | (Required) Path to the extension `.zip`.                                  |
| `--connection <name>` | (Required) Connection to install into. Provider must match the extension. |

## Examples

```bash
# List ETL workflows, recently updated first
carto workflows list --search "ETL" --order-by updated_at

# Round-trip get → edit → update
carto workflows get abc123 --json > /tmp/w.json
jq '.title = "New title"' /tmp/w.json | carto workflows update abc123 --file -

# Local validation before write
carto workflows validate --file bundle.json

# Full warehouse-side verification before merging a bundle PR
carto workflows verify-remote --file bundle.json --connection carto_dw

# Preview the SQL `run` would submit
carto workflows to-sql --file bundle.json

# Publish as MCP tool so agents can call it
carto workflows mcp publish abc123
```


---

# Agent Instructions: 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:

```
GET https://docs.carto.com/carto-for-agents/cli/command-reference/workflows.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.