Expand description
§Toha
Generate projects and files from templates.

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
eachfile 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/tohaAPT:
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 tohaRPM:
sudo curl -fsSL https://repo.wyrd.foo/wyrd.repo -o /etc/yum.repos.d/wyrd.repo
sudo dnf install tohaArch Linux (AUR):
paru -S toha-binGitHub 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 ./notesAnswer 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-featuresFrom 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.
Re-exports§
pub use apply::Applied;pub use apply::ApplyError;pub use apply::ApplyOptions;pub use apply::HookReport;pub use inject::Anchor;pub use inject::EditReport;pub use inject::EditResolution;pub use inject::JsonEditError;pub use inject::JsonFormat;pub use inject::JsonPath;pub use inject::JsonPathSegment;pub use inject::MarkerStyle;pub use inject::Occurrence;pub use inject::PlannedEdit;pub use inject::PlannedJsonEdit;pub use inject::PlannedRegionEdit;pub use inject::RegionError;pub use inject::RegionKey;pub use inject::json_value_to_cst_input;pub use inject::report_json_edit;pub use inject::report_region_edit;pub use inject::resolve_json_edit;pub use inject::resolve_region_edit;pub use interview::Answer;pub use interview::AnswerError;pub use interview::Answers;pub use interview::Batch;pub use interview::CheckError;pub use interview::Completed;pub use interview::Disposition;pub use interview::EndKind;pub use interview::Ended;pub use interview::EvalError;pub use interview::Interview;pub use interview::Item;pub use interview::Pending;pub use interview::Prompt;pub use interview::PromptKind;pub use interview::RawAnswer;pub use interview::RawAnswers;pub use interview::Rejection;pub use interview::RejectionKind;pub use interview::Rejections;pub use interview::Seed;pub use interview::Step;pub use plan::Content;pub use plan::Deferred;pub use plan::FileMutation;pub use plan::Plan;pub use plan::PlanError;pub use plan::Planned;pub use plan::PlannedFile;pub use plan::PlannedHook;pub use plan::PlannedProgram;pub use plan::TargetPath;pub use requirement::MissingRequirements;pub use requirement::Requirement;pub use review::HookSurface;pub use review::HookSurfaceDiff;pub use review::HookView;pub use review::ReviewDigest;pub use review::ReviewError;pub use review::ScriptDigest;pub use review::Trust;pub use review::evaluate_trust;pub use template::FlowAction;pub use template::FlowNode;pub use template::Id;pub use template::LoadError;pub use template::Node;pub use template::Problem;pub use template::Question;pub use template::QuestionKind;pub use template::SkipScope;pub use template::Template;
Modules§
- apply
- config
- Layered configuration for template lookup.
- context
- Toha’s immutable, typed invocation context.
- git_
target - Initializes an apply target as a git repository for a template’s
gitquestion, with an optionaloriginremote. - hook
- inject
- Content injection: bounded mutation of an existing target file.
- interview
- plan
- protocol
- The interview protocol boundary: the external answers envelope, the identity gate, and the result documents.
- registry
- Validated registry layers, discovery, and name resolution.
- requirement
- The programs a template declares in
requires, confirmed onPATHbefore an interview starts so that a caller does not answer questions for an apply whose hooks cannot run. - review
- The reviewable executable surface of a template and the single trust rule.
- snapshot
- Git-based project snapshots and template updates.
- source
- Template addresses and immutable Git fetches.
- staging
- template