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

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

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

```bash
$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

```bash
# 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
```


---

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