The whole surface on one page, in the same five families. Keep it open
beside a terminal until you no longer need it. yell help
prints the same table, from the table the parser itself is built from.
Who is running, and how to make something run.
| Written | Does |
|---|---|
| list [@yantra] | Every yantra broadcasting a manifest, with its state, cpu, memory, uptime and pid. Reads files; dials nothing — which is why it can report one that has stopped answering. |
| spawn @yantra | Start it from the recipe in .yantras/<yantra>.toml, detached from this terminal. Refused, naming the pid, when that yantra is already up here. |
| reload [@yantra] | Close it, wait for the process to actually go, and launch it again from the same recipe. Bare, it re-execs yell itself onto a new build without losing the session. |
Not a word but a place on the line — always after the word, never before it. Resolved against live discovery every time, so it names something real or fails loudly.
| Form | Names |
|---|---|
| @forge | Every running forge on this machine. More than one, and the statement fans out to all of them. |
| @iron/forge | forge on the mettle iron — a machine, reached over ssh, named by its ~/.ssh/config alias. |
| @local/forge | Here. local is spelled out rather than implied. |
| @iron/ | Everything running on that mettle, whatever it is. |
| @* | Everything here. Useful, and worth a second thought. |
| @forge alone on a line | Asks that yantra its version. Anything written after it is refused rather than guessed at. |
No session target, no document header, nothing to inherit. Every tool but
version names the yantra it is spoken to, on its own line —
because the alternative is a line whose meaning depends on something
written somewhere else.
Look, and change nothing. These are exactly the tools that do not reach into the window.
| Written | Answers |
|---|---|
| version [@yantra] | What it is, which dialect it speaks and what it offers. Bare, with no address, yell's own version. |
| help [@yantra] | Addressed: the commands that yantra answers, in its own words. Bare: this card, in the terminal. |
| take_snapshot @yantra [verbose=true] | The element tree, indented, with a fingerprint for every node. This is where every fingerprint you will write comes from. |
| get_element @yantra <element> | One element in full: what it is, what it says, what it accepts, and where it sits this frame. |
| take_screenshot @yantra [<element>] [fullPage=true] | A png of the window, or of one element. Bind it with let and save it to a file. |
| wait_for @yantra <text>… [timeoutMs=8000] | Hold on until every one of those strings is on screen. Five seconds unless you say otherwise; running out is an error. |
| read_console @yantra [since=42] | What the yantra has said in its own voice, from a sequence number on. Every line carries its number, so the next read starts where this one stopped. |
The words that act. Seven reach into the window as real input; the eighth speaks to the app in its own vocabulary.
| Written | Does |
|---|---|
| click @yantra <element> [dblClick=true] | Press it. dblClick=true presses twice. |
| hover @yantra <element> | Put the pointer on it, and leave it there. |
| drag @yantra <from> <to> | Press on one element and release on another. |
| fill @yantra <element> <text> | Replace what that field holds. |
| type_text @yantra <text> [submitKey=enter] | Type into whatever holds focus, and optionally finish with a key. |
| press_key @yantra <key> | One stroke: enter, tab, escape, an arrow, a single character, with ctrl+, shift+, alt+ or super+ in front. |
| scroll_into_view @yantra <element> | Scroll until it is on screen. Nothing off screen can be pressed. |
| ux @yantra <command> [key=value]… | One of the app's own commands, mirrored from its message type — so the list can never drift from the compiled program. help @yantra is that list. |
&.
A trailing ampersand starts the statement and moves on, and its answer
prints when it lands, under the &1 it was given. Use it
for the one that takes a while — a bell that rings later, a screenshot of
a window mid-animation — and keep writing.
The session itself: hold an answer, write it down, listen, wait, leave.
| Written | Does |
|---|---|
| let $name = <tool> @yantra … | Run it and keep what it answered. Never takes a detached command — a binding needs the value. |
| $name | Put a kept answer back where an element or a phrase belongs: click @forge $anvil. |
| save $name <path> | Write it to a file — the raw bytes for an image, pretty json for a structured answer, the text otherwise. |
| report [path] | Every yantra on this machine in one json file: manifest, state, version, snapshot, screenshot and console. The thing to keep when something is wrong. |
| wait [@yantra] [millis] | Bare, a pause. Addressed, ask again until it answers — which is what belongs between spawn and the first order. |
| attach @yantra | Print that yantra's console here, as it speaks. |
| detach [@yantra] | Stop. Bare, stop listening to everything. |
| quit [@yantra] | Addressed, close that yantra. Bare, leave yell — as does Ctrl-D. |
Four kinds, told apart by how they are written.
| Written | Is |
|---|---|
| 0e9da92a…4a11df8d92 | An element: 64 hex digits, from take_snapshot. Never a coordinate — a fingerprint survives a window being moved or resized. |
| $name | The same thing, kept under a name by let. |
| "a maker's mark" | Text. Quotes when it has spaces; \", \\, \n, \r and \t inside them. |
| key=value | A setting. A flag takes true or false and nothing else; a setting the word does not know is refused by name, so a typo is never quietly ignored. |
Markdown in, execution out. Blocks run top to bottom in one session.
| Written | Means |
|---|---|
| ```yell | A block that runs. Three or more backticks, and yell as the first word of the info string. |
| ```text | Inert — the escape hatch for showing yell inside a yell runbook. |
| # comment | Skipped, inside a block. So is a blank line. |
| yell runbook.md | Run every block, in document order, in one session. The first refusal ends the run and names the line. |
| yell check runbook.md | Print what each line means, in yell's own spelling, and run nothing. |
| yell -c '…' | One statement, then leave. |
No frontmatter, no cell names, no attributes. What a line does is written on the line — which is what makes a runbook readable by someone who has never opened the file it lives beside.
yell knows more words than it accepts, so it can tell you what happened instead of shrugging.
| Written | Answers |
|---|---|
| if · for · while · fn · match · assert · watch … | Not yet. Held back so a runbook written today cannot be quietly re-read as something else the day one of them arrives. |
| refresh · sleep · ls · exit · console · ping · info | Retired, and the refusal names what took its place: reload, wait, list, quit, attach, version. |
| rpc · call · tools · tool | Retired into the shape that replaced them: write the tool's own name, or a bare @yantra. |