projects

Manage CARTO projects — the containers that group maps and workflows. A project is a top-level folder; it can hold subfolders, native maps and workflows, and shortcuts to maps or workflows that live elsewhere.

# Read
carto projects list [options]                      # Top-level projects
carto projects get <id|name>                       # Project details + full contents tree

# Top-level CRUD
carto projects create --name <name>                # New top-level project
carto projects rename <path> --to <name>           # Rename a folder
carto projects delete <path>                       # Delete a folder or shortcut

# Asset placement
carto projects add <path> --folder <name>          # Create a subfolder inside a project
carto projects add <path> --map <map-id>           # Add an existing map (creates a shortcut)
carto projects add <path> --workflow <wf-id>       # Add an existing workflow (creates a shortcut)
carto projects move <path> --to <path>             # Move a folder or shortcut to a new parent

# Local-sync workflow
carto projects init <name>                         # New project + scaffold a local working dir
carto projects clone <id|name>                     # Materialize an existing project to disk
carto projects status                              # Show local-vs-clone diff (run inside a checkout)

Identifier resolution

Project arguments accept either the UUID (e.g. 62c90ed4-eeec-46d0-bda9-c7ea173e26f0) or the project name. Names are resolved via the entries search; ambiguous matches error out and ask for the UUID.

Nested locations use slash paths: Q2 Analytics/Maps/Drafts. The first segment must be a top-level project (or its UUID); subsequent segments walk the tree by title-match within each parent folder.

Adding maps and workflows: shortcuts under the hood

The CARTO platform doesn't currently expose a way to move an existing map or workflow into a folder — assets live at the account root. The mechanism for making one appear inside a project is to create a shortcut (an alias entry pointing at the underlying asset). carto projects add <path> --map <id> creates that shortcut for you. The map itself is not moved; deleting the shortcut later only removes the alias, not the map.

Local-sync workflow

Treat a CARTO project as a working directory you can clone, edit, and sync:

# Start a brand-new project — creates server-side and scaffolds a local dir
carto projects init "Q2 Analytics" --color "#3478f6"
cd q2-analytics
$EDITOR AGENTS.md                # capture project context for an agent

# Or check out an existing project
carto projects clone "Q2 Analytics"
cd q2-analytics
ls -R                            # AGENTS.md, README.md, *.map.json, *.workflow.json

# See what's changed locally vs the clone
carto projects status

# Optionally check whether anything moved on the server since you cloned
carto projects status --server

The clone lays down:

• .carto/project.json — manifest with project ID, content hashes, server timestamps, and the recursive entry tree.

• AGENTS.md, README.md — tracked scaffold docs (their hashes go in the manifest, so edits show up in status).

• .gitignore — meta, untracked.

• For each entry: a directory (folders) or a *.map.json / *.workflow.json bundle.

Pushing edits back uses the existing per-resource verbs:

$EDITOR my-map.map.json
carto maps update <map-id> < my-map.map.json

Common flags

projects list — --in <id|name>, --search <query>, --owner <me|others>, --mine, --order-by <field> (updatedAt / title), --order-direction <ASC|DESC>, --page, --page-size.

projects get — --depth <n> (0 = unbounded, 1 = top level only), --budget <n> (folder-lookup cap, default 500), --no-entries (metadata only).

projects create — --name <name>, --color <hex>, --file <path> (read full create payload from JSON).

projects add — exactly one of --folder <name>, --map <map-id>, --workflow <id>, plus --color <hex> for new subfolders.

projects rename — --to <new-name>.

projects move — --to <path>. Top-level → top-level is not supported by the API today.

projects delete — --yes to skip the confirmation prompt.

projects init / projects clone — --path <dir> (default: ./<slug-of-name>/), --force (write into a non-empty dir / overwrite scaffold). clone adds --shallow (skip bundle fetches, just structure) and --budget <n>.

projects status — --path <dir> (project root, defaults to walking up from CWD), --server (also check for changes on the CARTO server since clone).

Examples

# Browse
carto projects list --mine
carto projects list --search analytics
carto projects get "Q2 Analytics"
carto projects get "Q2 Analytics/Maps"

# Build out a project
carto projects create --name "Q2 Analytics" --color "#3478f6"
carto projects add "Q2 Analytics" --folder "Maps"
carto projects add "Q2 Analytics/Maps" --map 62c90ed4-eeec-46d0-bda9-c7ea173e26f0
carto projects add "Q2 Analytics" --workflow b32f9fff-4303-4f75-bf7a-1f661c60b53a

# Reorganize
carto projects rename "Q2 Analytics/Maps" --to "Production maps"
carto projects move  "Q2 Analytics/Production maps" --to "Q1 Archive"

# Clean up
carto projects delete "Q2 Analytics" --yes