UL
Words: prompting
Namespace: durian.cloud/cyanprint/prompting
How the CLI gets a template's answers - the question loop between the CLI and a template container
| Word | Meaning |
|---|---|
| Question | One prompt a template asks - text, password, select, checkbox, confirm or date - with an id and an optional validator. |
| Question id | The key a question's answer is stored under - in the replay, in headless answers, and in the state file. |
| Answer | A value for one question - a string, a list of strings, or a boolean - stored as type and value. |
| Stateless replay | Each step the CLI sends every answer so far and the template script runs again from the top until it meets an unanswered question. |
| Question reply | A template's reply naming the next unanswered question, with the deterministic state built so far. |
| Final reply | A template's reply when every question is answered - the Cyan, and no deterministic state. |
| Deterministic state | Values a template makes once with d.get (a UUID, a date) so they stay the same across the replays of one run. |
| Prompt outcome | How one prompt run ends - complete (answers and Cyan), need input (headless), or error. |
| Headless mode | Running without a terminal - answers from a file or stdin, one JSON envelope on stdout, exit 0 done, 2 need input, 1 error. |
| Need input | The headless outcome when the walk meets a question with no supplied answer; nothing is written. |
| Answer validation | Checking an answer with the template's own validator, by replaying to that question inside the template container. |
| Secret redaction | Dropping any headless error text that echoes a supplied answer value, so a password never reaches the JSON envelope. |
Question
One prompt a template asks - text, password, select, checkbox, confirm or date - with an id and an optional validator.
- See: Question id, Answer
Code: Question (cyanprompt/src/domain/models/question.rs); SDK: Question in sdks/node/src/domain/core/question.ts.
Example: await i.text('Project name?', 'name') asks a text question with id name.
Question id
The key a question's answer is stored under - in the replay, in headless answers, and in the state file.
- Do not say: key
Two templates that use one id share one answer in a composition, unless the caller scopes it (answer namespacing).
Example: id name answered shop is sent to every later template in the run.
Answer
A value for one question - a string, a list of strings, or a boolean - stored as type and value.
Code: Answer enum, serde tag type, content value (cyanprompt/src/domain/models/answer.rs:4-10).
Example: { type: Bool, value: true } for a confirm question.
Stateless replay
Each step the CLI sends every answer so far and the template script runs again from the top until it meets an unanswered question.
- Do not say: session, conversation, wizard
- See: Question reply, Final reply
Full walk-through: docs/domain/prompting/implementation/stateless-replay.md
Question reply
A template's reply naming the next unanswered question, with the deterministic state built so far.
Code: TemplateOutput::QnA / TemplateQnAOutput. The SDK sends it when the inquirer throws "out of answers".
Final reply
A template's reply when every question is answered - the Cyan, and no deterministic state.
- See: Cyan
Code: TemplateOutput::Final. The Cyan is defined in the authoring words.
Deterministic state
Values a template makes once with d.get (a UUID, a date) so they stay the same across the replays of one run.
- Do not say: pin, seed, determinism seed
A map of string to string. Returned with each question reply and sent back on the next step.
It is not in the final reply and is saved empty in the state file, so a new run makes new values.
Example: d.get('project-id', () => crypto.randomUUID()) gives the same UUID in steps 3 and 4 of one run.
Prompt outcome
How one prompt run ends - complete (answers and Cyan), need input (headless), or error.
- Do not say: template state
Code name TemplateState (cyanprompt/src/domain/services/template/states.rs:7-18); that name is also a state file type.
Headless mode
Running without a terminal - answers from a file or stdin, one JSON envelope on stdout, exit 0 done, 2 need input, 1 error.
- See: Need input
Flags --headless and --answers <file> on create, update, try template and try group.
Example: a need-input run prints the question as JSON and exits 2; the caller adds the answer and runs again.
Need input
The headless outcome when the walk meets a question with no supplied answer; nothing is written.
Code: TemplateState::NeedInput, envelope need_input.
Answer validation
Checking an answer with the template's own validator, by replaying to that question inside the template container.
Call: POST /api/template/validate. An error text is shown to the user and the answer is refused.
Secret redaction
Dropping any headless error text that echoes a supplied answer value, so a password never reaches the JSON envelope.