Headless mode
create, update and try without a terminal - the answers file, the two walks, the JSON envelope, exit codes 0/2/1, cleanup, and the stdout contract.
The problem. CI jobs, scripts and other programs need to create and update projects, but the CLI asks its questions in a terminal. A program cannot answer a prompt, and it cannot hold a run open while it works out the next answer.
The idea. Turn the question loop inside out, like stateless replay does for templates: the caller supplies every answer it has, the CLI replays from scratch, and either finishes or prints the one question it is missing and exits. The caller adds that answer and runs the same command again. Each run is a complete, fresh replay.
The flow below is one headless invocation, from the answers file to the exit code.
flowchart TD
A["--answers file, or piped stdin, or nothing"] --> P{"parse id → {type, value}"}
P -->|bad JSON| E1["error envelope, exit 1"]
P --> B["batch run: every template spec, every node"]
B --> D["per node: discovery walk<br/>validate each reached supplied answer"]
D -->|refused| ER["Err → error envelope, exit 1"]
D --> O["outcome walk: full map, state {}"]
O -->|unsupplied question| NI["NeedInput: stop the batch,<br/>no write, remove created folder"]
O -->|final reply| BUILD["build phase, next node"]
BUILD --> B
B -->|all nodes done| W["merge, write, save state, commands"]
NI --> C["release sessions"]
W --> C2["release sessions"]
C --> NE["need_input envelope, exit 2"]
C2 --> DONE["done envelope, exit 0"]The answers file
- Flags:
--headlessturns it on;--answers <path>names the answers file. Both exist oncreate,update,try templateandtry group.updaterefuses--headlesswith--interactive. - Source:
--answers <path>if given; else stdin if stdin is not a terminal; else no answers.--answers -is a file called-. - Format: one JSON object, question id to an answer in file spelling. Empty or blank input means "no answers yet".
{"7a90c2d4-1e3f-4b5a-8c6d-9e0f1a2b3c4d/node_version": { "type": "String", "value": "22" },"e5d07b3a-2f1e-4d3c-9b8a-7f6e5d4c3b2a/name": { "type": "String", "value": "shop" },"e5d07b3a-2f1e-4d3c-9b8a-7f6e5d4c3b2a/port": { "type": "String", "value": "3000" },"e5d07b3a-2f1e-4d3c-9b8a-7f6e5d4c3b2a/features": { "type": "StringArray", "value": ["docker"] }}
- Not accepted: flat values (
{"name": "shop"}), YAML, an{answers: …}wrapper, deterministic state. - A parse error names only the category and position, for example
failed to parse answers JSON: answers JSON does not match the expected {id: {type, value}} shape (line 2, column 61); never the value. - Where answers go: only into the template this command adds, upgrades or reruns (create), or the upgraded templates (update). Other stacked templates replay with their saved answers only.
- Ids: use the id exactly as a
need_inputenvelope gave it. In a tree with more than one template with an image, that is<version id>/<id>(answer namespacing); a raw id also works but reaches every node that asks it.
The two walks, per node
Each template node runs two walks in start_headless. Details of the checks are in answer validation.
- Discovery walk. Start with an empty map and empty state. Each time the template asks a question the caller supplied, check and validate that answer, add it, carry the reply's state, call again. Stop at the first unsupplied question or the final reply. Result: the revealed answers.
- Outcome walk. Start again from empty state and send the whole supplied map. On a final reply, return
Completewith the revealed answers. On a supplied question (a template that asks in a different order), validate and go on. On an unsupplied question, returnNeedInput. With the SDKs' first-unanswered replay this is usually one call. - Each walk stops with an error after 1000 calls. Any init call error is redacted before it becomes the message.
The envelope and exit codes
The envelope is one JSON object and a newline on stdout. The table is complete.
| Status | Shape | Exit | Meaning |
|---|---|---|---|
done | {"status":"done"} | 0 | files written, state saved, commands run |
need_input | {"status":"need_input","question":{…}} | 2 | add this answer and run again |
error | {"status":"error","message":"…"} | 1 | stopped; message names ids, not values |
donenever echoes answers or files.- The
questionuses snake_case fields and no password default (question). - A prompting error's
messageis the Rust debug print of aProblemDetails(title: "🚨 Template Prompting Error", …,data: … "error": "invalid answer for question 'port': …"), not a short sentence. - If writing the envelope fails (closed pipe), the exit code is 1.
Cleanup and what a stopped run leaves
- Nothing is written before
done. Aneed_inputstops the batch run before layering, merge, write, state save and commands. - A folder this run created is removed on
need_inputor error, down to the shallowest new parent (created folder cleanup). A folder that already existed is untouched. - Sessions are released at the command boundary, best effort.
- Not undone: containers warmed, images pulled, node cache entries stored for nodes that completed, and anything after the write (a failed post-template command gives
errorwith the files already on disk).
Here is the real code from ingestion to exit code.
- lines 121-138Source order: --answers file, else stdin when piped, else empty.
cyanprint/src/headless.rs:121-138rust pub fn read_answers_from(answers_path: Option<&str>,read_stdin: bool,stdin: impl Read,) -> Result<HashMap<String, Answer>, Box<dyn Error + Send>> {if let Some(path) = answers_path {let content = fs::read_to_string(path).map_err(|e| {Box::new(std::io::Error::other(format!("failed to read answers file '{path}': {e}"))) as Box<dyn Error + Send>})?;return parse_answers(&content);}if read_stdin {return read_answers_reader(stdin);}Ok(HashMap::new())} - lines 74-78Blank input is a valid empty map; anything else must map ids to typed answers.
cyanprint/src/headless.rs:74-78rust pub fn parse_answers(raw: &str) -> Result<HashMap<String, Answer>, Box<dyn Error + Send>> {let trimmed = raw.trim();if trimmed.is_empty() {return Ok(HashMap::new());} - sulfone.iridium/cyanprompt/src/domain/services/template/engine.rs:140-145Discovery first; then the outcome walk starts again from empty state.
cyanprompt/src/domain/services/template/engine.rs:140-145rust let revealed = match self.validate_supplied_answers(&answers) {Ok(revealed) => revealed,Err(msg) => return TemplateState::Err(msg),};let mut state_data: HashMap<String, String> = HashMap::new(); - sulfone.iridium/cyanprompt/src/domain/services/template/engine.rs:176-188Outcome walk: final → Complete with the revealed answers only.
cyanprompt/src/domain/services/template/engine.rs:176-188rust match self.client.prompt_template(input) {Ok(TemplateOutput::Final(c)) => {// Persist ONLY the answers the coordinator actually revealed and// accepted during the discovery walk — not the full caller-supplied// map. `revealed` excludes over-supplied / untaken-branch answers// (and their secrets), so a stale value for a question that was never// prompted cannot leak into persisted state and be silently reused on// a later run where the branch changes.return TemplateState::Complete(c.cyan, revealed);}Ok(TemplateOutput::QnA(q)) => {let question_id = q.question.id();if let Some(answer) = answers.get(&question_id) { - sulfone.iridium/cyanprompt/src/domain/services/template/engine.rs:226-236A supplied question advances; an unsupplied one is NeedInput.
cyanprompt/src/domain/services/template/engine.rs:226-236rust walked.insert(question_id, answer.clone());state_data = q.deterministic_state;}Err(msg) => {return TemplateState::Err(msg);}}} else {// First unanswered question — emit and stop.return TemplateState::NeedInput(q.question, q.deterministic_state);} - sulfone.iridium/cyanprint/src/run.rs:829-843need_input returns before any write; the folder guard removes what this run created.
cyanprint/src/run.rs:829-843rust // Headless: a question is pending. Do NOT persist state, write files, or run// post-commands — surface the question and stop (stateless replay). The still-armed// `dir_guard` drops on this return and removes the directory tree THIS invocation// created (the walk stopped before PHASE 4, so the tree is empty and removal is safe),// leaving the filesystem exactly as found; a pre-existing target is untouched.if let Some(question) = need_input {return Ok(CyanRunResult {session_ids,need_input: Some(question),});}// Past the `need_input` check the run is committed to producing output (`done`):// disarm the directory guard so the created tree is kept from here on.dir_guard.disarm(); - lines 211-234One boundary: release sessions, build the envelope, print it.
cyanprint/src/headless.rs:211-234rust pub fn finish_headless<W, F>(r: Result<CyanRunResult, Box<dyn Error + Send>>,writer: &mut W,clean_sessions: F,) -> Result<(), Box<dyn Error + Send>>whereW: std::io::Write,F: FnOnce(&[String]),{use cyanprompt::domain::models::headless::{HeadlessEnvelope, QuestionWire};let env = match r {Ok(result) => {clean_sessions(&result.session_ids);match result.need_input {Some(question) => HeadlessEnvelope::NeedInput {question: QuestionWire::from(&question),},None => HeadlessEnvelope::Done,}}Err(e) => HeadlessEnvelope::error(e.to_string()),};emit_to(writer, &env).map_err(|e| Box::new(e) as Box<dyn Error + Send>)} - lines 159-174One JSON line; done → Ok, need_input → 2, error → 1; a write failure → 1.
cyanprint/src/headless.rs:159-174rust pub fn emit_to<W: std::io::Write>(writer: &mut W,envelope: &HeadlessEnvelope,) -> Result<(), HeadlessExit> {// One JSON object + trailing newline. A write failure (e.g. a closed pipe) is// treated as a non-zero exit so a caller observing the exit code does not mistake// a truncated stream for success.let json = envelope.to_json();if writeln!(writer, "{json}").is_err() {return Err(HeadlessExit(1));}match envelope.exit_code() {0 => Ok(()),code => Err(HeadlessExit(code)),}} - sulfone.iridium/cyanprint/src/main.rs:46-58main turns the code into the process exit status without printing again.
cyanprint/src/main.rs:46-58rust match run() {Ok(()) => ExitCode::SUCCESS,Err(e) => {// Headless commands signal their exit code via HeadlessExit; the JSON// envelope has already been printed to stdout, so do not print an// "Error:" line — just propagate the code (need_input → 2, error → 1).if let Some(headless_exit) = e.downcast_ref::<crate::headless::HeadlessExit>() {return ExitCode::from(headless_exit.0);}eprintln!("Error: {e}");ExitCode::FAILURE}}
Worked example: a script creates ./shop
A CI job runs cyanprint create atomi/web:5 ./shop --headless --answers answers.json on a fresh machine, adding one answer per round. Step through the three rounds.
- Run 1: empty answers
docker:7 runs first. Its discovery walk has nothing to check; its outcome walk stops at node_version. lint:2, node-base:3 and web:5 never run.
answers.json {}stdout need_input, id 7a90c2d4-…/node_version, select [20, 22]exit 2./shop created, then removed - Run 2: node_version added
docker:7 validates 22 against its options and completes (built and cached). lint:2 completes; node-base:3 completes with its preset module_type. web:5 stops at name.
answers.json node_versionstdout need_input, id e5d07b3a-…/name, textexit 2./shop created, then removed - Run 3: all answers
docker:7, lint:2 and node-base:3 are served from the node cache (no questions, no validation). web:5's discovery walk validates name and port with two validate calls and checks features against its options; the outcome walk completes in one init call.
answers.json node_version, name, port, featuresstdout line 1 ♻️ Cache: 3/4 nodes served from cachestdout line 2 {"status":"done"}exit 0 - instance-id in run 3
Discovery made a value X in its first call and carried it; the outcome walk started from {} and made a new value Y. The files hold Y, and the state file saves {}.
discovery Xoutcome walk Yapp.config.json instanceId Y
Why it is built this way
Hard cases
- stdout is not always one line. Create and update print the cache summary (
♻️ Cache: …) on stdout before adoneenvelope whenever the cache is on, which is the default.trysuppresses it. With cache debug on, per-nodecache HIT/MISSlines also go to stdout. - Exit 2 is not only need_input. A bad flag (including
--headless --interactiveon update) is a clap usage error: it prints to stderr, no envelope, and clap exits with 2. - Over-supplied answers are still saved. The engine returns only revealed answers, but the composition state starts from the whole supplied map, and that map is what the state file saves. An answer for a branch not taken lands in
.cyan_state.yaml. - Two walks, two random values. Discovery and outcome each start from
{}, so d.get values differ between them, and a template that branches on one can be validated on one path and built on another. - Cache hits skip validation. A node served from the cache runs no walk at all, so its supplied answers are not checked.
- Saved answers are re-validated. In an update, the upgraded template's saved answers are in the supplied map, so discovery validates them against the new version's validators. So are the saved answers of every other re-executed template that is not served from the cache: each node runs both walks over its whole map (
executor.rs:208-211), so a stricter validator there can fail the run even when the caller supplies nothing. Found while reading; not run. - Validators see fewer siblings than in a terminal. The discovery walk's sibling map holds only the answers this node revealed, not carried or preset ones (answer validation).
- A failed validate call passes. A JSON error body from the coordinator or a Python SDK decodes as "accepted", so the walk goes on (question protocol).
- Work is repeated each round. Every round re-runs every node before the missing question, including warm and build; only the cache saves time.
- An answer for a non-target template cannot be given. Supplied answers reach only the added or upgraded template; if another stacked template's replay ever stops at a question, no answers file can satisfy it.
- A headless rerun can get stuck on a cache miss. In the shop's step 6 (
cyanprint create atomi/ci:2 ./shopagain)manager.resetclears the answers of every stacked template, web:5 included (run.rs:763), but supplied answers go only to the rerun target ci:2 (run.rs:785-801). With the node cache on, web:5 is a hit with answers{}and nothing is asked. With the cache off, or after a miss, web:5 asksnameagain, the run stops withneed_input, and adding the answer changes nothing because it never reaches web:5: every round returns the same question. Found while reading; not run.
Questions for the designer
- Why exit code 2 for need_input, given clap also uses 2 for usage errors?
- Should the envelope carry the deterministic state, so the next round can pass it back?
- Should supplied answers be able to reach every stacked template, scoped by template?
- Should
donereport anything (files written, conflicts) for the caller? - Should a headless rerun reuse the saved answers of the templates it does not target, instead of clearing them, so it can finish on a cache miss?