workflows

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

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:

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 skill.

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.

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.

# 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.

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

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.

# 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.

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).

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:

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

Identify users by email with --with. The CLI resolves each email to a user ID, so a typo fails loudly rather than sharing with the wrong person.

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

# Share with a specific user by email
carto workflows share <id> --with [e-mail]

# Repeat or comma-separate to reach several people at once
carto workflows share <id> --with [e-mail] --with [e-mail]
carto workflows share <id> --with [e-mail],[e-mail]

# Also grant edit access, and see who has access today
carto workflows share <id> --with [e-mail] --can-edit
carto workflows share <id> --list

# Remove one person's access, or revert to private
carto workflows unshare <id> --with [e-mail]
carto workflows unshare <id>

Options:

Option	Description
--org	Share with the entire organization (unshare drops org-wide sharing).
--with <email>	Share with a user by email. Repeatable, or comma-separated.
--can-edit	Grant edit access as well as read (share only).
--list	Show the current sharing state without changing it (share only).

--user-id and --user-email were removed in v0.10.0. Use --with <email>.

carto workflows mcp

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

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 guide for the publishing flow end-to-end.

carto workflows schedule

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

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.

# 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 workflows extensions install

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

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

# 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