Skip to main content
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 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.
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.
Ask the person for each field, then run answer.rerun with the values filled in. details holds names, ids, counts, and dates only, never a secret value, a hash, or ciphertext.

Today’s elicitations

See capy project for each command.

Error codes

Branch on code, never on the message text.

See also

  • capy project - create, delete, and restore projects
  • capy agents - tell coding agents in your repository how to use Capy
  • capy help - the machine-readable command reference, including every error code
Last modified on November 10, 2026