Terminal

The agent terminal

Your terminal tool runs ONE command line per call -- verb, arguments, and flags together, exactly as you would type them at a prompt. Everything below is a COMMAND, not a tool of its own: there is no separate search tool, only search ... typed into the terminal.

It is NOT a Unix shell. It has only the documented commands -- ls, find, search, read, write, append, edit, copy, rm -- plus a trailing | pipeline. A few Unix names work as aliases -- cat (read), grep (search), dir (ls), cp (copy) -- and everything else errors, echo and awk included.

search needs a fulltext index, which only a mounted volume has. With nothing but /tmp you do not have it -- filter /tmp with a pipeline instead.

Paths

Write every path in full. cd exists, but assume it does not stick: your terminal call starts at / every time, so a cd is gone by your next call. Use an absolute path (/cerb-docs/references/docs/kata.md) or the @<filesystem>/path shorthand (@cerb-docs/references/docs/kata.md). A mount is read-only unless its overview says otherwise; /tmp is always read-write.

Searching the mounted filesystems

The search command matches file CONTENTS with AND, not OR -- every word in the query must appear in the same file. Piling on keywords narrows to zero hits fast, and zero hits is NOT evidence the topic is undocumented.

• Start with the one or two most distinctive terms, then narrow with --path or --ext instead of adding more words.
• --terms is the OR view, and it is how you find the right word. It counts how many files contain EACH word, ranked, instead of searching for all of them: search --terms school college academic university tuition. One call, any number of synonyms, no reading. Take the highest count, require it with +, and throw the next set of words at it: search --terms +college tuition fees pricing. Repeat until the word list is good, THEN run the real search.
• A wildcard or stem term lists the words it covers, inline on one indented line beneath it: auto* reports automations (476) automation (374) automatically (228) .... That is how you learn the vocabulary this corpus actually uses instead of guessing at it; a trailing ... means the list was capped.
• A + term is echoed as a heading above the counts; every count below it is within the files that contain it, so numbers collapse fast. That collapse is the signal -- keep the words that survive it.
• A miss falls back to this view automatically, and keeps any + you already had, so a failed AND search still tells you which words exist alongside it.
• A - instead of a count means the index skips that word as too common (the, not, can, com, www, ...) -- it was never searched for, which is not the same as finding nothing.
• Run separate searches for alternatives; there is no OR.
• A search returns the 25 most relevant files, not every match. --top <n> raises or lowers that cap and --top 0 returns every match unranked, so a full list is one flag away. Don't report a capped list as the whole answer.
• Use find to match names and search to match contents. Add --lines only after you've picked a file worth reading in context.
• find also carries every Markdown file's frontmatter, so you can select on metadata without opening anything. Each row has its keys under meta, and --fields title,description prints chosen ones as columns: find *.md --fields name | files|filter(f => f.meta.name starts with "cerb"). Listing never opens a file, so this costs nothing.
• Prefer search/find to locate a file, then read only the part you need (--offset/--limit).

/tmp -- a compute surface, not an overflow buffer

/tmp is a read-write scratch area. Reach for it whenever you'd otherwise scan a long piece of text by hand, or need to hold intermediate work across steps.

• Write an arbitrary string to a file (write /tmp/scratch.txt), then read it back through a trailing Twig filter chain to count, filter, reshape, or diff it -- for example staging alternate drafts, or reducing a large document to just the lines that matter, before committing a final version anywhere.
• It is per-session, and it is NOT indexed by search. Filter it with a pipeline rather than searching it.
• A command whose output is too large to return is saved there and referenced by path.

The | pipeline

Pipe ANY command through Twig filters with a trailing | (lines, filter, map, length, column, ...). The pipeline runs on the FULL output before any truncation, so it is how you reduce a big result to just what you need instead of paying for the whole thing in context.

read /tmp/scratch.txt | lines|filter(l => "field" in l)
search widgets | results|map(r => r.meta.title ?? r.path)
ls /docs | files|filter(f => not f.is_dir)|column("name")

lines preserves original line indices as keys. Each command sets its own row variable -- lines, results, files above -- and that is what makes a pipe iterate ROWS rather than text. For a longer transform than fits on one line, put a Twig template in script instead of a trailing |.

This is Cerb scripting, not a pipeline language of its own -- the same Twig, the same filters, functions and operators you would write anywhere else in Cerb. Read @cerb-agents/skills/scripting/SKILL.md for what is available rather than guessing at a filter name here.

cerb -- the command line into this installation

Some agents also have cerb, a command line into THIS Cerb install rather than into files. It reports what this installation actually has, custom record types and fieldsets included, which the documentation cannot. Run cerb help to see what it answers, and cerb <topic> help for one topic's usage. Its rows pipe like any other command's.