> ## Documentation Index
> Fetch the complete documentation index at: https://capy.sc/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# capy project: Create, Delete, and Restore Projects

> Create a project and its first branch, delete a project, or restore a deleted one in your active organization. Works in a terminal and from agents and CI.

## Synopsis

```bash theme={null}
capy project create [name] [--branch <name>] [--protected yes|no]
capy project delete <name-or-id> [--force] [--yes]
capy project restore <name-or-id> [--yes]
```

## Description

`capy project` creates, deletes, and restores projects in the active organization. To list projects, use [`capy projects`](https://capy.sc/docs/cli/projects).

| Command | Who can run it | What it does |
| - | - | - |
| `capy project create` | Owners and admins | Creates a project and its first branch. |
| `capy project delete` | The organization owner | Hides a project. Nothing is destroyed, and an owner can restore it. |
| `capy project restore` | The organization owner | Brings a deleted project back. |

The active organization is the one in the folder's `keep.lock`. Outside a project folder, Capy uses your only organization. If you belong to several, a terminal asks which one. Without a terminal, `create`, `delete` and `restore` stop with `ORG_SELECTION_REQUIRED` and exit code `3`.

## capy project create

```bash theme={null}
capy project create [name] [--branch <name>] [--protected yes|no] [--json] [--non-tty]
```

Creates the project and its first branch. It does not link the current folder. Run bare [`capy`](https://capy.sc/docs/cli/capy) in a folder to link it.

A Capy branch works like a git branch. Capy branches can be used to set different variables for different environments. A project's first branch can be protected (invite-only) from the start. See [Protected branches](https://capy.sc/docs/using/branches/protected.md).

In a terminal, Capy asks for the project name, the first branch ("What should its first branch be called?"), and whether that branch is protected. Anything you pass as a flag or argument is not asked again.

Capy refuses a name that a live project in the organization already has (`PROJECT_NAME_EXISTS`), ignoring case. The name of a deleted project can be used again.

| Flag | Description |
| - | - |
| `--branch <name>` | The first branch. A terminal offers `development` by default. |
| `--protected <yes\|no>` | Whether the first branch is protected (invite-only). |
| `--non-tty` | Same as `--json`. |
| `--json` | Never ask, and answer in JSON. |

`--dry-run` is a global option. With all three values given, `capy project create web --branch development --protected no --dry-run` checks them and creates nothing.

### Names

* A project name uses letters, numbers, hyphens, and underscores. `_system` is reserved.
* A branch name starts with a letter or number, then uses letters, numbers, `.`, `_`, and `-`. It has at most 128 characters and no `..`.

### Example

```bash theme={null}
$ capy project create web --branch development --protected no
Created project web with branch development in Acme Corp.
```

For a protected first branch:

```bash theme={null}
capy project create billing --branch production --protected yes
```

### From an agent or CI

With `--json`, `--non-tty`, or no terminal, `capy project create` never prompts. If the name, `--branch`, or `--protected` is missing, it creates nothing and exits with code `3`. With `--json` or `--non-tty`, the JSON on standard output names what is missing in `code` and carries an `elicitation`: a question for the person, whose answer reruns the command with the values filled in. With neither flag and no terminal, Capy prints only a message on standard error, so agents always pass `--json`. See [Questions Capy asks agents](https://capy.sc/docs/using/agent-questions.md).

```bash theme={null}
capy project create --json
```

```json theme={null}
{
  "ok": false,
  "code": "PROJECT_NAME_REQUIRED",
  "error": "`capy project create` needs a project name. Pass it as an argument, or run it in a terminal.",
  "elicitation": {
    "kind": "form",
    "question": "What should the project and its first branch be called?",
    "details": { "org": { "id": "<org-id>", "name": "Acme Corp" } },
    "display": "|  |  |\n| --- | --- |\n| Org | Acme Corp |\n| Project | to choose |\n...",
    "fields": [
      { "name": "name", "type": "string", "pattern": "^[a-zA-Z0-9-_]+$", "question": "What should the project be called?", "default": "<folder-name>" },
      { "name": "branch", "type": "string", "pattern": "<branch-name-pattern>", "default": "development", "question": "What should its first branch be called?", "description": "A Capy branch works like a git branch. Capy branches can be used to set different variables for different environments." },
      { "name": "protected", "type": "string", "pattern": "^(yes|no)$", "question": "Make the first branch a protected branch? (invite-only)", "default": "no", "options": [{ "value": "yes", "label": "Yes" }, { "value": "no", "label": "No" }] }
    ],
    "answer": { "rerun": "capy project create <name> --branch <branch> --protected <protected> --json" }
  }
}
```

The form always has all three fields, with any value already given as the field's `default`. The name's `default` is the current folder's name, left out when that name is not allowed or a live project already has it. When the name was given, the form's `question` is "What should the first branch be called?" instead, and once the branch has a name the protected question names it: `Make "<branch>" a protected branch? (invite-only)`.

The agent shows the person `display`, asks each field, and runs `answer.rerun` with their answers. When all three values are given, the command creates the project and prints:

```json theme={null}
{
  "ok": true,
  "project": { "id": "<project-id>", "name": "web" },
  "branch": { "name": "development", "protected": false },
  "org": { "id": "<org-id>", "name": "Acme Corp" }
}
```

If the project is created but its first branch is not, the command exits with `BRANCH_CREATE_FAILED` and still returns the project, so you know it exists.

## capy project delete

```bash theme={null}
capy project delete <name-or-id> [--force] [--yes] [--json] [--non-tty]
```

Deletes a project: it is hidden from the organization, and nothing is destroyed. An organization owner can bring it back with [`capy project restore`](#capy-project-restore).

You can pass the project's name or its id. If several projects share the name, Capy asks which one and shows each with its variable count and how long ago it was created. The "created ... ago" part only appears when Capy has a creation date for the project. A name that matches nothing stops with `PROJECT_NOT_FOUND` before anything is asked.

Before it deletes anything, Capy shows what the project holds: its branches, the names of its variables (never their values), and its live deploy tokens. Then it asks `Delete project <name>?`, defaulting to no.

A project with live deploy tokens is not deleted unless you pass `--force`. Those deploys stop on their next restart. Without `--force`, the command stops with `PROJECT_HAS_LIVE_DEPLOY_TOKENS` and lists the tokens.

| Flag | Description |
| - | - |
| `--force` | Delete even if the project has live deploy tokens. |
| `--yes` | Skip the confirmation question. |
| `--non-tty` | Same as `--json`. |
| `--json` | Never ask, and answer in JSON. |

`--dry-run` is a global option. `capy project delete web --dry-run` shows the project and its live deploy tokens, and deletes nothing.

### Example

```bash theme={null}
$ capy project delete web
...
? Delete project web? (y/N) y
Deleted project web.
An owner can restore it with: capy project restore <project-id>
```

### From an agent or CI

With `--json`, `--non-tty`, or no terminal, Capy never prompts. Without `--yes`, `capy project delete` deletes nothing and exits with code `3`. With `--json` or `--non-tty`, the JSON carries `CONFIRMATION_REQUIRED` and a `confirm` elicitation that lists the branches, the variable names, and the live deploy tokens. With neither flag and no terminal, Capy prints only a message on standard error. The agent shows the table to the person and asks. Only on a yes does it run the command in `answer.yes`, which keeps `--force` if it was passed. An agent must never add `--yes` on its own.

Without `--force`, a project with live deploy tokens still gets the question first. The refusal with `PROJECT_HAS_LIVE_DEPLOY_TOKENS` comes when the delete is sent.

```bash theme={null}
capy project delete web --json
```

A name that several projects share stops with `PROJECT_AMBIGUOUS` and exit code `3`. Its elicitation has one `project` field, and its options are the matching projects. In a terminal, Capy asks which one instead. `--yes` never picks one for you. The answer reruns the delete without `--yes`, so the yes or no comes next.

## capy project restore

```bash theme={null}
capy project restore <name-or-id> [--yes] [--json] [--non-tty]
```

Brings a deleted project back. Only the organization owner can run it.

Capy asks `Restore project <name>?` unless you pass `--yes`.

`--dry-run` is a global option. `capy project restore web --dry-run` names the project that would come back, and restores nothing.

To see deleted projects and when they were deleted, run [`capy projects --deleted`](https://capy.sc/docs/cli/projects) (owners only).

### From an agent or CI

With `--json`, `--non-tty`, or no terminal, Capy never prompts. Without `--yes`, `capy project restore` restores nothing and exits with code `3`. With `--json` or `--non-tty`, the JSON carries `CONFIRMATION_REQUIRED` and a `confirm` elicitation. With neither flag and no terminal, Capy prints only a message on standard error. The elicitation's `details` hold the organization and the project (id, name, and when it was deleted), and `display` is a table with the rows Org, Project, and Deleted. The agent shows the table and asks the person. Only on a yes does it run the command in `answer.yes`:

```bash theme={null}
capy project restore <project-id> --yes --json
```

A name that several projects share stops first with `PROJECT_AMBIGUOUS`, as for delete. The answer reruns the restore with the same flags: without `--yes`, the yes or no comes next; if `--yes` was passed, the chosen project is restored.

## A folder whose project was deleted

If a folder's project is deleted, commands in it stop with `PROJECT_DELETED` and show the restore command with the project's id:

```bash theme={null}
capy project restore <project-id>
```

Capy does not offer to create a new project in its place and does not change `keep.lock`. In `capy info --json`, `project.state` is `"deleted"`.

## Exit codes

| Code | Meaning |
| - | - |
| `0` | Done, a dry run finished, or the person answered no. |
| `1` | Refused or failed. Branch on `code`, never on the message. |
| `3` | Capy needs an answer it cannot ask for. With `--json` or `--non-tty`, read the `elicitation` or `code`, ask the person, and rerun. |

## Error codes

| Code | Command | Exit | When |
| - | - | - | - |
| `PROJECT_NAME_REQUIRED` | create | `3` | No name, and nobody to ask. Carries an `elicitation`. |
| `BRANCH_NAME_REQUIRED` | create | `3` | No `--branch`, and nobody to ask. Carries an `elicitation`. |
| `BRANCH_PROTECTION_REQUIRED` | create | `3` | No `--protected`, and nobody to ask. Carries an `elicitation`. |
| `PROJECT_NAME_INVALID` | create | `1` | The name is empty or uses characters other than letters, numbers, hyphens, and underscores. |
| `PROJECT_NAME_RESERVED` | create | `1` | The name is `_system`. |
| `PROJECT_NAME_EXISTS` | create | `1` | A live project in the organization already has this name. |
| `BRANCH_NAME_INVALID` | create | `1` | `--branch` is not an allowed branch name. Nothing is created. |
| `BRANCH_PROTECTION_INVALID` | create | `1` | `--protected` is not `yes` or `no`. Nothing is created. |
| `BRANCH_CREATE_FAILED` | create | `1` | The project was created, but its first branch was not. |
| `QUOTA_EXCEEDED` | create | `1` | The account has reached its quota. |
| `DRY_RUN_UNSUPPORTED` | create | `1` | `--dry-run` in a terminal without all three values, because Capy would have to ask. |
| `CONFIRMATION_REQUIRED` | delete, restore | `3` | No `--yes` and nobody to ask. Carries a `confirm` elicitation. |
| `PROJECT_AMBIGUOUS` | delete, restore | `3` | Several projects share the name, and nobody to ask. Carries a pick-one elicitation. |
| `PROJECT_NOT_FOUND` | delete, restore | `1` | No project has that name. |
| `PROJECT_DELETE_OWNER_ONLY` | delete, restore | `1` | You are not the organization owner. |
| `PROJECT_HAS_LIVE_DEPLOY_TOKENS` | delete | `1` | The project has live deploy tokens. Pass `--force` to delete anyway. |
| `PROJECT_NOT_DELETED` | restore | `1` | The project is not deleted. |
| `SYSTEM_STORE_IMMUTABLE` | delete | `1` | The project is the organization's system store, which cannot be deleted. |
| `PERMISSION_DENIED` | create, delete, restore | `1` | Your role does not allow this, for example a member creating a project. |
| `RATE_LIMITED` | create, delete, restore | `1` | Too many requests. Try again later. |
| `SERVICE_ERROR` | create, delete, restore | `1` | Capy's service failed. |
| `ORG_SELECTION_REQUIRED` | create, delete, restore | `3` | No organization in the folder, you belong to several, and nobody can be asked. |
| `PROJECT_DELETED` | any command in the folder | `1` | The folder's project was deleted. See above. |

## See also

* [`capy projects`](https://capy.sc/docs/cli/projects) - list projects and their branches
* [`capy checkout`](https://capy.sc/docs/cli/checkout) - create more branches
* [Protected branches](https://capy.sc/docs/using/branches/protected.md)
* [Questions Capy asks agents](https://capy.sc/docs/using/agent-questions.md) - how agents ask the person


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.