Skip to main content

Synopsis

Description

capy project creates, deletes, and restores projects in the active organization. To list projects, use capy projects. 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

Creates the project and its first branch. It does not link the current folder. Run bare 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. 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. --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

For a protected first branch:

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

Deletes a project: it is hidden from the organization, and nothing is destroyed. An organization owner can bring it back with 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. --dry-run is a global option. capy project delete web --dry-run shows the project and its live deploy tokens, and deletes nothing.

Example

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

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

Error codes

See also

Last modified on November 10, 2026