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)
carto projects push # Push local changes back to CARTOIdentifier 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:
The clone lays down:
.carto/project.json— manifest with project ID, content hashes, server timestamps, and the recursive entry tree..gitignore— meta, untracked.For each entry: a directory (folders) or a
*.map.json/*.workflow.jsonbundle.
Push local edits back with carto projects push. It sends every modified *.map.json / *.workflow.json bundle, then records the new hashes in the manifest so status stops reporting them. CARTO validates each map and workflow bundle before saving it, so an invalid file is rejected instead of being saved broken.
Deleting a local file does not delete anything on CARTO, and bundles skipped by a --shallow clone are never pushed.
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). init also takes --name <name> (instead of the positional name) and --color <hex>. 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).
projects push: --path <dir> (project root, defaults to walking up from CWD), --dry-run (print the planned actions without calling the API).
Examples
Last updated
Was this helpful?
