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

# Questions Capy Asks Agents: Elicitations

> How a Capy command hands a question to the AI agent that ran it, so the agent can ask you. Fields, kinds, and exit code 3.

Some commands need an answer that only a person can give: a project name, or a yes before a delete. In a terminal, Capy asks. With no terminal - an AI agent, a CI job, `--json`, `--non-tty` - Capy cannot ask, so it stops, changes nothing, and exits with code `3`.

With `--json`, that stop carries an **elicitation** next to its `code`: a question for the person, never for the agent. The agent asks the person, then runs the command that answers it.

## `--json` and `--non-tty`

Agents and CI pass `--json`. It means: never ask, and answer with one JSON object on standard output. Messages for people go to standard error.

`--non-tty` means the same as `--json` on the commands that ask these questions (`capy project create`, `delete`, and `restore`). With neither flag and no terminal, those commands still never ask, but they print only a message on standard error, with no elicitation.

## What the agent does

1. Write the `display` table in your reply exactly as given. Do not shorten or reorder it, and do not put it inside the question.
2. Ask the short `question` with your question tool: one question per field, using the field's own `question` followed by its `description` when it has them, and its `options` or `default` as the choices. If you have no question tool, end your reply with the `question` and let the person answer in chat.

   A field without `options` is typed in. With a `default`, offer exactly two choices, the `default` and "Cancel"; the person types any other answer in the question tool's own free-text answer. With no `default`, leave it out of the question tool: after the other questions, ask its `question` in chat and let the person type the answer. On "Cancel", stop.
3. Run the answer command with what the person chose.

Never answer an elicitation yourself, and never add `--yes` on your own.

[`capy agents`](https://capy.sc/docs/cli/agents) writes the same instructions into `AGENTS.md` and `CLAUDE.md`, so an agent working in your repository has them.

## The two kinds

### `confirm`

A yes or no.

```json theme={null}
{
  "kind": "confirm",
  "question": "Delete project web?",
  "details": {
    "org": { "id": "<org-id>", "name": "Acme Corp" },
    "project": { "id": "<project-id>", "name": "web" },
    "branches": ["development", "production"],
    "variables": [{ "name": "DATABASE_URL", "branches": ["development", "production"] }],
    "live_deploy_tokens": []
  },
  "display": "|  |  |\n| --- | --- |\n...",
  "answer": { "yes": "capy project delete <project-id> --yes --json" }
}
```

On yes, run the command in `answer.yes`. It keeps any flag the person already chose, such as `--force`. On no, stop.

### `form`

One or more values.

```json theme={null}
{
  "kind": "form",
  "question": "What should the first branch be called?",
  "details": { "org": { "id": "<org-id>", "name": "Acme Corp" } },
  "display": "|  |  |\n| --- | --- |\n...",
  "fields": [
    { "name": "name", "type": "string", "pattern": "<regular expression>", "default": "web", "question": "What should the project be called?" },
    { "name": "branch", "type": "string", "pattern": "<regular expression>", "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)$", "default": "no", "question": "Make the first branch a protected branch? (invite-only)", "options": [{ "value": "yes", "label": "Yes" }, { "value": "no", "label": "No" }] }
  ],
  "answer": { "rerun": "capy project create <name> --branch <branch> --protected <protected> --json" }
}
```

Ask the person for each field, then run `answer.rerun` with the values filled in.

| Field | Meaning |
| - | - |
| `name` | The value's name, and the place it goes in `answer.rerun`. |
| `type` | Always `string`. |
| `pattern` | A regular expression the value must match. |
| `default` | A value the person can accept as is. Absent when there is none. |
| `question` | What to ask for this field. |
| `description` | What the field is. Absent when the name says it all. |
| `options` | When present, the answer must be one of these. The person picks a `label`, and you fill in its `value`. |

`details` holds names, ids, counts, and dates only, never a secret value, a hash, or ciphertext.

## Today's elicitations

| Command | Code | Exit | Kind | Asks |
| - | - | - | - | - |
| `capy project create` | `PROJECT_NAME_REQUIRED`, `BRANCH_NAME_REQUIRED`, or `BRANCH_PROTECTION_REQUIRED` | `3` | `form` | The name, the first branch, and whether it is protected (`yes` or `no`). |
| `capy project delete` | `CONFIRMATION_REQUIRED` | `3` | `confirm` | Whether to delete, with the branches, variable names, and live deploy tokens. |
| `capy project restore` | `CONFIRMATION_REQUIRED` | `3` | `confirm` | Whether to restore, with the organization, the project, and when it was deleted. |
| `capy project delete`, `capy project restore` | `PROJECT_AMBIGUOUS` | `3` | `form` | Which project, when several share the name. One `project` field whose options are the projects. The answer reruns the command with the same flags: for a delete it never has `--yes`, so the yes or no comes next; a restore keeps `--yes` only if it was passed. The "created ... ago" part of an option only appears when Capy has a creation date for the project. |

See [`capy project`](https://capy.sc/docs/cli/project) for each command.

## Error codes

Branch on `code`, never on the message text.

| Code | When | Exit |
| - | - | - |
| `PROJECT_NAME_REQUIRED` | `capy project create` has no name and nobody to ask. | `3` |
| `BRANCH_NAME_REQUIRED` | `capy project create` has no `--branch` and nobody to ask. | `3` |
| `BRANCH_PROTECTION_REQUIRED` | `capy project create` has no `--protected` and nobody to ask. | `3` |
| `CONFIRMATION_REQUIRED` | A delete or restore needs a yes, nobody can be asked, and there is no `--yes`. | `3` |
| `PROJECT_AMBIGUOUS` | A name matches several projects and nobody can be asked. | `3` |
| `ORG_SELECTION_REQUIRED` | The folder names no organization, you belong to several, and nobody can be asked. | `3` |
| `PROJECT_NAME_INVALID`, `PROJECT_NAME_RESERVED`, `PROJECT_NAME_EXISTS` | The project name cannot be used. | `1` |
| `BRANCH_NAME_INVALID`, `BRANCH_PROTECTION_INVALID` | `--branch` or `--protected` is not allowed. | `1` |
| `BRANCH_CREATE_FAILED` | The project was created, but not its first branch. | `1` |
| `PROJECT_NOT_FOUND`, `PROJECT_NOT_DELETED` | No project has that name, or the project is not deleted. | `1` |
| `PROJECT_DELETE_OWNER_ONLY` | Only the organization owner can delete or restore a project. | `1` |
| `PROJECT_HAS_LIVE_DEPLOY_TOKENS` | A delete needs `--force` because deploy tokens are live. | `1` |
| `PROJECT_DELETED` | The folder's project was deleted. Stop and tell the person. | `1` |
| `QUOTA_EXCEEDED` | The account has reached its quota. | `1` |
| `DRY_RUN_UNSUPPORTED` | `--dry-run` would need an answer from the person. | `1` |
| `SYSTEM_STORE_IMMUTABLE` | The project is the organization's system store, which cannot be deleted. | `1` |
| `PERMISSION_DENIED` | Your role does not allow this. | `1` |
| `RATE_LIMITED`, `SERVICE_ERROR` | Too many requests, or Capy's service failed. | `1` |

## See also

* [`capy project`](https://capy.sc/docs/cli/project) - create, delete, and restore projects
* [`capy agents`](https://capy.sc/docs/cli/agents) - tell coding agents in your repository how to use Capy
* [`capy help`](https://capy.sc/docs/cli/help) - the machine-readable command reference, including every error code


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