> For the complete documentation index, see [llms.txt](https://docs.carto.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.carto.com/carto-for-agents/cli/command-reference/workflows.md).

# workflows

Manage CARTO Workflows — list, inspect, create, update, copy, validate, verify-remote, run, share, publish, schedule, enable 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 (same-tenant, or cross-tenant with --dest-profile)
carto workflows schema [section]                     # JSON Schema reference for agents
carto workflows validate [--file <bundle.json>]      # Structure + components against the connection's live catalog
carto workflows verify-remote [--file <bundle.json>] # Deep validation of a bundle against the 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> --connection <c> # Poll an async-submitted run
carto workflows share <id> [--org | --with <email> | --group <name>]  # Share workflow
carto workflows unshare <id>                         # Revert to private
carto workflows publish <id>                         # Publish the current version to everyone it's shared with
carto workflows mcp enable|disable|describe|list     # MCP tool lifecycle
carto workflows schedule create|update|delete <id>   # Warehouse schedule 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). Save it to a file for `workflows create --file` / `workflows update --file`, or pipe it straight back in through stdin:

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

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. Without `--file`, pipe the bundle through stdin.                      |
| `--connection <name\|uuid>`    | Override `bundle.connectionId` for the pre-flight check against the connection's component catalog. |
| `--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`**: checks the bundle's structure, then checks its component names and parameters against the connection's live component catalog (native components, extensions and stored procedures). It needs a connection, taken from the bundle's `connectionId` or from `--connection`. `create` and `update` run the same check before writing. Use it to iterate on a bundle before writing; for the deeper warehouse-side checks 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
# Structure and component check (uses the bundle's connectionId)
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>` | Override `bundle.connectionId`. Required when the bundle has no `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
```

API credentials in the output are placeholders, so the SQL is for review and can't be run as is.

| Option                      | Description                                                                     |
| --------------------------- | ------------------------------------------------------------------------------- |
| `--file <path>`             | Bundle JSON path (or pipe via stdin).                                           |
| `--connection <name\|uuid>` | Override `bundle.connectionId`. Required when the bundle has no `connectionId`. |
| `--dry-run`                 | Emit an empty-table SQL skeleton instead of the full SQL.                       |
| `--no-cache`                | Compile without the engine cache.                                               |

## `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> --connection <name>  # Poll the async job
carto workflows run output <id> <node-id>         # Fetch a specific node's output rows
```

A run is recorded on the workflow, as it is when you run it from Builder, so a workflow you run from the CLI can be [scheduled](#carto-workflows-schedule) right after. If the run can't be recorded, the CLI prints a warning, and `--json` lists it under `warnings`.

| Option                 | Description                                                                                        |
| ---------------------- | -------------------------------------------------------------------------------------------------- |
| `--async`              | Return a job ID right away instead of waiting for the run to finish. Poll it with `run status`.    |
| `--no-cache`           | Bypass the execution cache.                                                                        |
| `--timeout <ms>`       | Maximum time to wait for the run, in milliseconds (default: 600000, minimum: 10000).               |
| `--poll-interval <ms>` | How often to check the run, in milliseconds (default: 1000, minimum: 500).                         |
| `--limit <n>`          | (`run output`) Maximum rows to return (default: 100).                                              |
| `--connection <name>`  | (Required for `run status`) The workflow's connection. Job status is read through that connection. |

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

Identify users by email with `--with`, and groups by name or id with `--group`. The CLI resolves each email and group name before sharing, so a typo fails loudly rather than sharing with the wrong people. Group names match exactly, ignoring case.

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

# Share with a specific user by email
carto workflows share <id> --with someone@example.com

# Repeat or comma-separate to reach several people at once
carto workflows share <id> --with a@example.com --with b@example.com
carto workflows share <id> --with a@example.com,b@example.com

# Share with groups by name or id
carto workflows share <id> --group Analysts
carto workflows share <id> --group Analysts,Marketing

# Also grant edit access, and see who has access today
carto workflows share <id> --with someone@example.com --can-edit
carto workflows share <id> --list

# Remove one person's or one group's access, or revert to private
carto workflows unshare <id> --with someone@example.com
carto workflows unshare <id> --group Analysts
carto workflows unshare <id>
```

**Options:**

| Option           | Description                                                                                                |
| ---------------- | ---------------------------------------------------------------------------------------------------------- |
| `--org`          | Share with the entire organization (`unshare` drops org-wide sharing and keeps specific users and groups). |
| `--with <email>` | Share with a user by email. Repeatable, or comma-separated.                                                |
| `--group <name>` | Share with a group by its name or id. Repeatable, or comma-separated. An unknown name fails the command.   |
| `--can-edit`     | Grant edit access as well as read (`share` only).                                                          |
| `--list`         | Show the current sharing state without changing it (`share` only).                                         |

{% hint style="info" %}
`--user-id` and `--user-email` were removed in v0.10.0. Use `--with <email>`.
{% endhint %}

## `carto workflows publish`

Publish a workflow's current version to everyone it's shared with, like **Publish updates** in the Workflows editor. Until you publish, the people it's shared with keep seeing the previously published version.

```bash
carto workflows publish <id>
```

The command refuses a workflow that nobody else can access, counting access inherited from its folder, so share it first with `carto workflows share`. Publishing doesn't enable the workflow as an MCP tool: use [`carto workflows mcp enable`](#carto-workflows-mcp) for that.

## `carto workflows mcp`

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

```bash
carto workflows mcp enable <id> [options]       # Enable this workflow as an MCP tool
carto workflows mcp disable <id>                # Disable the MCP tool
carto workflows mcp describe <id>               # Show the current MCP tool config
carto workflows mcp list                        # List all workflows enabled as MCP tools
```

Enabling works as it does in Builder: the CLI compiles the workflow and creates or replaces its stored procedure in the warehouse, so it runs SQL on the workflow's connection. The workflow needs at least one variable scoped to the MCP tool and an MCP Tool Output component. Workflows on PostgreSQL and Databricks cluster connections can't be enabled, because Builder doesn't offer MCP tools on them either.

| Option                               | Description                                                                                                                                                                                                                                                                                          |
| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--name <name>`                      | (`enable`) Tool name. Default: a slug of the workflow title.                                                                                                                                                                                                                                         |
| `--description <text>`               | (`enable`) Tool description that agents read.                                                                                                                                                                                                                                                        |
| `--output-description <text>`        | (`enable`) Description of the tool's output.                                                                                                                                                                                                                                                         |
| `--input-description <input>=<text>` | (`enable`) Description of one input, at most 500 characters, which is all an agent learns about that parameter. Repeat it per input, e.g. `--input-description "city=City to filter by"`. A name that isn't an input is refused, and the command warns about every input left without a description. |

{% hint style="info" %}
`mcp publish` and `mcp unpublish` were renamed to `mcp enable` and `mcp disable` in v0.14.0, and `--draft-only`, `--file` and `--from-file` were removed. The old names exit with an error that names the new command.
{% endhint %}

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

## `carto workflows schedule`

Create, change or delete the warehouse schedule that runs a workflow:

```bash
carto workflows schedule create <id> --expression "every day 08:00"
carto workflows schedule update <id> --expression "every monday 09:00"
carto workflows schedule delete <id>
```

The format of `--expression` depends on the workflow's connection:

| Connection                                             | Format           | Examples                                                       |
| ------------------------------------------------------ | ---------------- | -------------------------------------------------------------- |
| BigQuery and CARTO Data Warehouse                      | Natural language | `"every day 08:00"`, `"every monday 09:00"`, `"every 2 hours"` |
| Snowflake, PostgreSQL, Oracle and Databricks Warehouse | Standard cron    | `"0 8 * * *"`, `"0 9 * * 1"`, `"0 */2 * * *"`                  |
| Databricks clusters                                    | Quartz cron      | `"0 0 8 * * ?"`, `"0 0 9 ? * MON"`                             |

`schedule create` refuses what the Builder scheduler refuses: a workflow that has never run, Redshift connections, BigQuery OAuth connections without BigQuery Data Transfer, and connections whose warehouse permissions don't allow scheduled queries. Existing schedules can still be updated and deleted.

{% hint style="info" %}
`schedule add` and `schedule remove` were renamed to `schedule create` and `schedule delete` in v0.14.0. The old names exit with an error that names the new command.
{% endhint %}

## `carto workflows copy`

Duplicate a workflow. Without `--dest-profile`, the copy is created in the same organization on the same connection, and starts private and untagged. With `--dest-profile`, the workflow is copied to that profile's organization: the CLI uses the destination connection that has the same name as the source connection, or the one you name with `--connection`, and checks that it can read the workflow's source tables before creating the copy.

```bash
# Same-organization duplicate with a new title
carto workflows copy abc123 --title "Copy of my pipeline"

# Another organization, auto-map the connection 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>`    | Destination profile name. Omit it for a same-organization duplicate.                |
| `--source-profile <name>`  | (With `--dest-profile`) Source profile (default: current).                          |
| `--connection <name>`      | (With `--dest-profile`) Destination connection name (auto-maps by name if omitted). |
| `--title <title>`          | Override the workflow title on the copy.                                            |
| `--skip-source-validation` | (With `--dest-profile`) Skip validating source table accessibility.                 |

For the full walkthrough including connection-mapping scenarios, see [Examples → Copying maps and workflows between organizations](https://docs.carto.com/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

# 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

# Enable as an MCP tool so agents can call it
carto workflows mcp enable abc123
```


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
