UL
Words: prompting
Namespace: durian.cloud/cyanprint/prompting
How the CLI gets a template's answers - the question loop between the CLI and one template container, interactive or headless. The CLI holds every answer; the container holds none.
| Word | Meaning |
|---|---|
| Question | One thing a template script asks - text, password, select, checkbox, confirm or date - with a question id, a message and optional extras. |
| Question id | The string a question's answer is stored under - in the answer map, the answers file, the state file and the node cache. |
| Answer | The value for one question id - a String, a StringArray or a Bool - written { type, value } in files and { type, answer } on the wire. |
| Answer map | Every answer known so far in one run, keyed by question id; the CLI sends the whole map on every init call. |
| Stateless replay | Asking a template's questions by running its script from the top on every call, with every answer so far, until it stops at an unanswered one. |
| Init call | One POST to a template's /api/template/init with the answer map and the deterministic state; it returns a question reply or a final reply. |
| Validate call | One POST to a template's /api/template/validate; the template replays to its first unanswered question and runs its validator on a candidate. |
| Question reply | An init call's answer when the script stopped at an unanswered question - type: questionnaire, the question, and the deterministic state so far. |
| Final reply | An init call's answer when every question was answered - type: final and the Cyan, with no deterministic state. |
| Checkpoint exception | The exception an SDK's inquirer throws when the script asks a question whose id is not in the answer map; the SDK turns it into a question reply. |
| Deterministic state | The map of values a template made with d.get (a UUID, a date) that the CLI passes back on every init call, so one run sees one value. |
| Prompt outcome | How one template's question loop ends - Complete (Cyan and answers), NeedInput (headless, a question), or Err (a message). |
| Headless mode | Running create, update or try with --headless - answers from a file or stdin, no prompts, one JSON envelope on stdout, exit 0/2/1. |
| Answers file | The headless input - one JSON object of question id to { type, value }, read from --answers <path> or piped stdin. |
| Envelope | The one JSON object a headless run prints on stdout - {status: done}, {status: need_input, question} or {status: error, message}. |
| Need input | The headless outcome when a replay reaches a question with no supplied answer - the run stops before any file is written. |
| Answer validation | Checking an answer before it is used - the template's own validator through a validate call for text, password and date, local shape checks for the rest. |
| Discovery walk | The first of two headless walks - feed supplied answers one question at a time so each reached answer is validated. |
| Outcome walk | The second headless walk - send the full supplied map from empty state and stop at need input, the final reply, or an error. |
| Revealed answers | The supplied answers whose question the discovery walk actually reached; the engine returns these, not the whole answers file. |
| Secret redaction | Keeping supplied answer values out of headless error messages and password defaults out of the envelope. |
| Skip | Pressing Esc at an interactive prompt - removes the asked question's answer (normally absent) so the next replay asks it again. |
Question
One thing a template script asks - text, password, select, checkbox, confirm or date - with a question id, a message and optional extras.
- In code:
Question (cyanprompt),QuestionRes,QuestionWire,TextQ and SelectQ etc. (SDKs) - See: Question id, Answer, Question reply
Six kinds, fixed. Each kind has its own extra fields (default, initial, options, min/max date, confirmation, error message). A question exists only while a replay is stopped at it: the template sends it in a question reply; it is never stored. Only text, password and date questions carry a validator (a function in the template, never sent over the wire).
Example: web:5 asks name (text), port (text, default "3000", validator) and features (checkbox: docker, storybook).
Not to be confused with:
- prompt: the terminal widget (inquire) the CLI builds from a question
- need input: the headless outcome that carries a question
Question id
The string a question's answer is stored under - in the answer map, the answers file, the state file and the node cache.
- Do not say: key, question name
- See: Answer
Chosen by the template author. The only link between a question and its answer: kinds are never compared on the way in.
Two questions with one id share one answer. In a composition with more than one executable node, a question surfaced
in need input is prefixed <version id>/ (answer namespacing).
Example: name in web:5; surfaced headless as e5d07b3a-2f1e-4d3c-9b8a-7f6e5d4c3b2a/name because web:5's tree has four executable nodes.
Not to be confused with:
- deterministic state key: the key of a d.get value, a separate map
- version id: the GUID of a template version
Answer
The value for one question id - a String, a StringArray or a Bool - written { type, value } in files and { type, answer } on the wire.
- Do not say: response, input
- In code:
Answer,AnswerReq,AnswerRes - See: Question id
Three spellings of one value: state file, answers file and node cache use {type: String|StringArray|Bool, value};
the HTTP calls to a template use {type: string|str_array|boolean, answer}; preset answers in cyan.yaml are plain YAML.
Text, password, select and date give a String (date as YYYY-MM-DD); checkbox gives a StringArray; confirm gives a Bool.
Example: name: { type: String, value: shop }, features: { type: StringArray, value: [docker] }.
Answer map
Every answer known so far in one run, keyed by question id; the CLI sends the whole map on every init call.
- In code:
answers (TemplateEngine),TemplateAnswerInput.answers - See: Stateless replay
Starts from saved answers, preset answers and answers carried from earlier nodes; grows by one per question reply. Answers are looked up, never consumed, so extra keys are harmless to the template and are sent along.
Example: Before web:5 asks name: { node_version: 22, module_type: esm }.
Stateless replay
Asking a template's questions by running its script from the top on every call, with every answer so far, until it stops at an unanswered one.
- Also called: client-state prompting
- Do not say: session, conversation, wizard
- In code:
TemplateEngine::start_with,TemplateService.template - See: Question reply, Final reply, Checkpoint exception
The CLI keeps the answer map and the deterministic state; the template keeps nothing between calls. A script with N questions runs N+1 times (plus one replay per validation). Code before a question runs again on every call.
Example: web:5 (3 questions) gets four init calls; d.get("instance-id") runs in all four.
Init call
One POST to a template's /api/template/init with the answer map and the deterministic state; it returns a question reply or a final reply.
- In code:
CyanClient::prompt_template,TemplateAnswerReq - See: Validate call
Sent through the coordinator's proxy route /proxy/template/<version id>/api/template/init. Request field deterministicStates (plural).
Example: {"answers":{"name":{"type":"string","answer":"shop"}},"deterministicStates":{}}
Validate call
One POST to a template's /api/template/validate; the template replays to its first unanswered question and runs its validator on a candidate.
- In code:
CyanClient::validate_template,TemplateValidateReq - See: Answer validation
Carries no question id: the answer map must stop the replay at the right question. Reply { "valid": null } means accepted,
{ "valid": "<reason>" } means refused. A JSON body with no valid key (a coordinator error, a Python {"error": ...}) also
decodes as accepted (bug).
Example: Checking port 80 for web:5: answers {node_version, module_type, name}, validate: "80" → { "valid": "Use a port from 1024 to 65535" }.
Question reply
An init call's answer when the script stopped at an unanswered question - type: questionnaire, the question, and the deterministic state so far.
- In code:
TemplateQnARes,TemplateOutput::QnA - See: Final reply
Made when the script throws the checkpoint exception. Field deterministicState (singular). HTTP 200, never an error status.
Example: { "type": "questionnaire", "question": { "type": "text", "id": "port", ... }, "deterministicState": { "instance-id": "4f9c2e71-aaaa" } }
Final reply
An init call's answer when every question was answered - type: final and the Cyan, with no deterministic state.
- In code:
TemplateFinalRes,TemplateOutput::Final - See: Deterministic state
Values the script made with d.get after its last question, and the whole map, go nowhere: the reply has no field for them.
Example: { "type": "final", "cyan": { "processors": [ ... ], "plugins": [] } }
Checkpoint exception
The exception an SDK's inquirer throws when the script asks a question whose id is not in the answer map; the SDK turns it into a question reply.
- Do not say: interrupt, pause
- In code:
OutOfAnswerException - See: Question reply
Named OutOfAnswerException in all three SDKs. It unwinds the author's script mid-run, so the script never waits for a person. Any other exception is a real error and is not caught by the template service.
Example: web:5's script reaches i.text(... 'port' ...) with no port answer: OutOfAnswerException carries the port question.
Deterministic state
The map of values a template made with d.get (a UUID, a date) that the CLI passes back on every init call, so one run sees one value.
- Do not say: pin, seed, cache
- In code:
deterministicStates (request),deterministicState (reply),state_data,deterministic_states (history entry) - See: Stateless replay
Key to string. Made in the template, carried by the CLI between calls of one template's Q&A only. Lost at four places:
the final reply has none, the Complete prompt outcome has none, the state writer saves {}, and a headless walk starts from {}.
Example: web:5 makes instance-id: 4f9c2e71-aaaa on its first init call; calls two to four send it back.
Not to be confused with:
- determinism helper: the SDK function d.get that reads and writes this map (authoring)
- state file: the project's saved record; its deterministic_states field is always {}
- try's deterministic states count: a map of the String answers, printed as a number; not d.get values
Prompt outcome
How one template's question loop ends - Complete (Cyan and answers), NeedInput (headless, a question), or Err (a message).
- Do not say: template state, result
- In code:
TemplateState (cyanprompt) - See: Need input
A fourth value, QnA, means "still asking" and never leaves the loop. Code name TemplateState in cyanprompt, which is also the name of a state file type in cyancoordinator: say "prompt outcome" or "template record".
Example: web:5 interactive: Complete with the Cyan and {node_version, module_type, name, port, features}.
Not to be confused with:
- template record: the state file entry, also called TemplateState in code
Headless mode
Running create, update or try with --headless - answers from a file or stdin, no prompts, one JSON envelope on stdout, exit 0/2/1.
- Do not say: batch mode, CI mode
- In code:
start_headless,finish_headless,HeadlessEnvelope - See: Answers file, Envelope, Need input
The caller loops: run, read the envelope, add the asked answer, run again. Each run is a fresh replay of the whole batch.
--headless and --interactive cannot be combined on update.
Example: cyanprint create atomi/web:5 ./shop --headless --answers answers.json exits 2 with the node_version question first.
Answers file
The headless input - one JSON object of question id to { type, value }, read from --answers <path> or piped stdin.
- Do not say: answer file, input file
- In code:
parse_answers,read_answers_from - See: Headless mode
Same answer spelling as the state file. Empty or blank input means no answers. No flat shorthand, no YAML, no deterministic state.
--answers - is a file named -, not stdin.
Example: { "name": { "type": "String", "value": "shop" } }
Envelope
The one JSON object a headless run prints on stdout - {status: done}, {status: need_input, question} or {status: error, message}.
- Also called: headless envelope
- Do not say: response, output
- In code:
HeadlessEnvelope,QuestionWire,emit_to - See: Need input
Exit codes 0, 2 and 1. done carries nothing else, never the answers. Today a create or update with the node cache on prints
a cache line on stdout before it.
Example: {"status":"need_input","question":{"type":"text","id":"e5d0…/name",...}} then exit 2.
Need input
The headless outcome when a replay reaches a question with no supplied answer - the run stops before any file is written.
- Do not say: missing answer, prompt
- In code:
TemplateState::NeedInput,CompositionState.need_input - See: Envelope
Envelope need_input, exit 2. The rest of the batch is not run; a target folder this run created is removed; sessions are released.
Example: First headless create of web:5 with an empty answers file: need input for docker:7's node_version.
Answer validation
Checking an answer before it is used - the template's own validator through a validate call for text, password and date, local shape checks for the rest.
- In code:
add_template_validator,validate_answer,validateable_value - See: Discovery walk, Validate call
Interactive: inquire runs the validator when the user presses Enter; answers already in the map at the start are never validated. Headless: a discovery walk validates every supplied answer the replay reaches, before the outcome walk. The validator's sibling map is the whole map interactively, but only the answers this node revealed so far in headless (bug).
Example: Typing 80 for web:5's port shows Use a port from 1024 to 65535 and the prompt stays open.
Discovery walk
The first of two headless walks - feed supplied answers one question at a time so each reached answer is validated.
- In code:
validate_supplied_answers - See: Outcome walk
Starts from an empty map and empty state, adds an answer only when its question is asked. Stops at the first question with no supplied answer, or at the final reply. Returns the revealed answers; the engine hands only those back as the node's answers, but the batch run then saves the whole supplied map (bug, see headless mode).
Example: Answers for docker:7 {node_version: 22}: call 1 asks node_version (checked: 22 is an option), call 2 is final.
Outcome walk
The second headless walk - send the full supplied map from empty state and stop at need input, the final reply, or an error.
- In code:
start_headless - See: Discovery walk
With the SDKs' first-unanswered behaviour this is usually one init call. Deterministic state from discovery is not passed on.
Example: docker:7 with {node_version: 22}: one init call returns the final reply.
Revealed answers
The supplied answers whose question the discovery walk actually reached; the engine returns these, not the whole answers file.
- In code:
revealed (start_headless)
Over-supplied ids and answers for branches not taken are dropped from what the engine returns. The batch run then saves the whole supplied map anyway, so a stale value still lands in the state file (bug).
Example: Supplying {node_version: 22, colour: blue} to docker:7: the engine returns node_version only; the run still saves colour.
Secret redaction
Keeping supplied answer values out of headless error messages and password defaults out of the envelope.
- Do not say: masking, encryption
- In code:
redact_coordinator_message,InFlightAnswers,value_echoed - See: Answer validation
Covers three paths only: answers-file parse errors, validation refusals, and init call errors during a headless walk.
Example: A refused password npm_token gives invalid answer for question 'npm_token' with the template's reason dropped.
Skip
Pressing Esc at an interactive prompt - removes the asked question's answer (normally absent) so the next replay asks it again.
- Do not say: go back, undo
- In code:
prompt_skippable,last_question_id
It does not go back to the previous question. With an empty answer map it ends the CLI at once with exit code 0; with a non-empty map (every node after the first) it never ends the run.
Example: Esc at web:5's port: port is not in the map, nothing changes, port is asked again.