toha 0.2.0

Generate projects and files from templates through one interview for people, scripts, agents, and Rust callers.
Documentation

Toha

Generate projects and files from templates.

CI Latest release

Toha terminal demo

Toha is a project scaffolding tool and Rust crate. A template contains an interview and files to render with Jinja. Toha plans the output before it writes, so you can inspect a dry run and handle conflicts.

The same interview engine serves terminal users, scripts, agents, and Rust callers. Scripts and agents can answer one JSON Schema batch at a time and resume a staged interview in another process.

  • One interview for people, scripts, agents, and Rust callers
  • Resumable async interviews and headless answers files
  • Typed Jinja values and rendered file paths
  • each file generation and static files
  • Template hooks gated by trust
  • Git template sources, short names, and aliases
  • Embedded agent skills through toha skills

Read the Toha documentation for guides and the full contract.

Install

Homebrew:

brew install wyrd-company/tools/toha

APT:

sudo install -d -m 0755 /etc/apt/keyrings
curl -fsSL https://repo.wyrd.foo/pubkey.asc |
  sudo tee /etc/apt/keyrings/wyrd-company.asc >/dev/null
echo "deb [signed-by=/etc/apt/keyrings/wyrd-company.asc] \
https://repo.wyrd.foo/apt stable main" |
  sudo tee /etc/apt/sources.list.d/wyrd-company.list >/dev/null
sudo apt update
sudo apt install toha

RPM:

sudo curl -fsSL https://repo.wyrd.foo/wyrd.repo -o /etc/yum.repos.d/wyrd.repo
sudo dnf install toha

Arch Linux (AUR):

paru -S toha-bin

GitHub Releases also provides Linux and macOS tarballs, Windows zip archives, and SHA256SUMS for direct installation.

First run

Toha ships a small demo template inside the binary. From any directory, offline, with nothing installed:

toha apply toha-demo ./notes

Answer Note title and Topic. To inspect the file plan without writing it, use toha apply toha-demo ./preview --dry-run.

toha-demo is a reserved fallback name. If you install or alias a template as toha-demo, that template resolves instead.

Using Toha from Rust

Add the library without the CLI dependencies:

cargo add toha --no-default-features

From this repository checkout, drive the same interview with an identity-bearing answers document. The document names the template it answers, which Toha compares by exact string equality with the formal name the caller has established before it evaluates any answer:

use std::path::Path;
use toha::{Interview, Seed, Template};
use toha::context::{EnvironmentSnapshot, ExecutionFacts, HostFacts, InvocationContext, SelectedTemplate};
use toha::protocol::{self, DocumentStep};
use toha::staging::canonical_target;
let template_root = Path::new("docs/examples/demo").canonicalize().unwrap();
let template = Template::load(&template_root).unwrap();
let expected = template_root.to_str().unwrap();
let target = canonical_target(Path::new("./notes")).unwrap();
let seed = Seed {
    now: "2026-01-01T00:00:00Z[UTC]".parse().unwrap(),
    defaults: Default::default(),
    context: InvocationContext::new(
        target,
        SelectedTemplate::new(expected.into(), template.name.clone(), Vec::new(), None),
        HostFacts::capture(),
        ExecutionFacts::new(false, false),
        EnvironmentSnapshot::Unavailable,
    ).unwrap(),
};
let Interview::Asking(pending) = Interview::start(&template, seed).unwrap() else { panic!("expected questions") };
// The document must name the formal template it answers.
let text = serde_json::json!({
    "template": expected,
    "answers": {"title": "Sample note", "topic": "Research"},
}).to_string();
let DocumentStep::Accepted { interview, .. } =
    protocol::answer_document_once(expected, pending, &text).unwrap()
else { panic!("the document was rejected") };
let Interview::Complete(done) = interview else { panic!("expected complete interview") };
assert_eq!(done.answers.len(), 2);

In-memory callers that build answers directly still use Pending::answer with RawAnswers and the raw headless walk; the envelope is only for external JSON.

See CONTRIBUTING.md for development and changes.