An automation is a KATA script bound to a trigger, plus a policy that grants the script its privileges. The two move together: a script that gains a privileged command stops working until the policy allows it.
\ncerb-docs contains the Cerb documentation for KATA syntax and annotations, automation commands, triggers, events, policies, record types, search queries, toolbars, workflows, and guides. Consult it before writing anything you're unsure of — especially @cerb-docs/references/docs/automations.md, @cerb-docs/references/docs/kata.md, and @cerb-docs/references/docs/records/types.md.
Search cerb-docs for the exact command, trigger, event, field, or filter you need rather than inventing syntax. Cite what you relied on when it clarifies your change.
Read a command's own page before you write that command -- every time, including commands you are confident you already know. Recall is reliable about which command to reach for and unreliable about what to type inside it: parameter names, which inputs are required, what the output dictionary contains. A wrong input name is accepted when the automation is saved and fails when it runs, so there is nothing to catch it in between. One read is cheaper than that.
name is an IDENTIFIER, not a title. It's how the automation is addressed everywhere else — uri: cerb:automation:example.math.sum in function:, toolbars, timers, and data queries. Human-friendly wording belongs in description:, not in the name._), and dots (.) — the same set Cerb requires for plugin and extension IDs (@cerb-docs/references/docs/plugins.md). No spaces, dashes, or slashes.<namespace>.<area>.<thing> -- e.g. example.math.sum, example.translate.function, example.automationTimer.createDailyTasks, wgm.example.openai.cerb. for Cerb itself and example. for documentation samples.name:example.mail.*) is how people find them in worklists.cerb:automation: URI pointing at it, so call out affected call sites when you propose a rename.set/a:, await/step:), which allow only letters, numbers, and underscores — no dots.These are the automation-specific ones. The language itself — indentation, quoting, comments, annotations, unique sibling keys — is the kata skill, and its indentation rule bites here constantly: a bare key: with indented lines under it is an OBJECT, so any multi-line or prose value needs @text: on its key.
each: to resolve to an ARRAY, and a bare each: {{...}} does not -- a placeholder renders to TEXT. Annotate the key: each@key: results.data when the array is already in a placeholder (@key reads the dictionary value and keeps its type, so there's no round-trip through text), otherwise @csv / @json / @list, or native KATA children. A non-array -- or absent -- each: is NOT an error: repeat: runs ZERO iterations and moves on, so the symptom is a loop body that silently never executes.if:, and the same bare-key-renders-TEXT problem inverts here. Any text that isn't false/0/no/n/off/empty is TRUE, so if: fed a rendered string is true forever and the loop only stops at the policy time limit. if: and if@bool: are equivalent (both end at the same toBool), so what matters is that the expression renders to 1/empty -- write a comparison, not a value. Unlike repeat:, a missing if: IS a hard error.script@raw:, event_kata@raw:, and policy_kata@raw: are where this comes up. Use the normal annotations inside them (if@bool:, set:); if@raw,bool: {{...}} makes the condition never match.|json_encode for @json; prefer native KATA (0:, 1:, …) for static arrays of objects.icons skill covers the set and its naming conventions.output: and inputs:Action commands do NOT take their parameters directly. Each takes an output: (the placeholder that receives the result — name one whenever you need the result) plus an inputs: block holding every documented parameter, with the handlers on_simulate:/on_success:/on_error: as siblings of those keys:
start:\n record.create/newTask:\n output: new_task\n inputs:\n record_type: task\n fields:\n title: This is a new task\n status: open\n on_success:\n return:\n task_id: {{new_task.id}}\nWrong — parameters hung directly off the command. record_type:/fields: are not recognized there, so the command gets no inputs and fails:
record.create:\n record_type: task\n fields:\n title: This is a new task\nThis shape applies to record./records.update:, http.request:, data.query:, function:, storage., file., kata.parse:, llm.chat:/llm.agent:/llm.embed:/llm.router:, queue., metric.increment:, email.parse:, encrypt.pgp:/decrypt.pgp:, api.command:, and var.set:/var.push:/var.unset:/var.expand:.
\nThe exceptions are the state and flow keywords, which take their parameters directly and have no output:/inputs: — return:, error:, await:, tool.return:, set:, decision:/outcome:, repeat:, while:, and log:/log.warn:/log.error:/log.alert:.
\nlog: is the sharpest exception: unlike every other action it takes a SINGLE STRING as its value and nothing else -- no inputs:, no output:, no on_success:/on_error:.
log: Ticket {{ticket_id}} was routed to {{group_name}}\nGive it a block instead and the value is empty, which log: treats as nothing to log -- it writes no entry and reports no error. The four severities (log: debug, log.warn:, log.error:, log.alert:) all take the same bare string.
Results read off the output placeholder after the call ({{new_task.id}}), and an error reads off that same placeholder inside on_error: ({{new_task.error}}) — no separate output key is needed for errors. Look up a command's exact input table on its own page (below) instead of guessing parameter names.
\nThis list is an INDEX, not syntax. It says a command exists and what it is for; it does not tell you what to type. Pick the command from here, then read its page and write from that.
Each command has its own page at @cerb-docs/references/docs/automations/commands/<command>.md -- read it directly for full syntax, parameters, and examples. Go straight there rather than searching: a name like set or return appears in every corner of the docs, and the search costs turns to land where one read would have. Five have no page of their own -- start, tool.return, and the log.warn/log.error/log.alert variants (covered by log.md); for those, and for the overview, read @cerb-docs/references/docs/automations.md.
State: return: (success), error: (fail), await: (pause/continuation), tool.return: (answer a tool call -- only valid inside an llm.agent: on_tool: branch)
Flow: decision:/outcome: (first-match branching), repeat: (iterate array), while: (loop)
Variables: set:, var.set: (key path), var.push: (append), var.unset: (remove), var.expand: (lazy-load)
Records: record.create:, record.get:, record.search:, record.update:, record.upsert:, record.delete:, records.update: (one call updating many records by id -- reach for it instead of wrapping record.update: in a repeat:)
HTTP: http.request: (GET/POST/PUT/PATCH/DELETE, streaming, auth)
Data: data.query: (worklist queries, custom formats)
Functions: function: (call another automation)
Storage: storage.get:, storage.set:, storage.delete: (key/value, optional TTL)
Files: file.read: (attachments/resources), file.write: (automation resources)
KATA: kata.parse: (parse KATA with placeholders)
LLM: llm.chat: (single-turn), llm.agent: (conversational + tools), llm.embed: (vectors), llm.router: (resolve a model from requirements instead of naming one)
Queues: queue.push:, queue.pop: (message queues)
Metrics: metric.increment: (time-series samples)
Email: email.parse: (MIME → ticket)
Encryption: encrypt.pgp:, decrypt.pgp:
API: api.command: (internal Cerb commands)
Logging: log:, log.warn:, log.error:, log.alert:
Simulation: simulate.success:, simulate.error: (mock outputs in on_simulate:)
all: / deny: yes catch-all at the end -- it grants nothing, denies nothing already permitted, and reads as though the rules above it were open-ended.return:, error:, await:, tool.return:, set:, decision:/outcome:, repeat:, while:, and log:/log.warn:/log.error:/log.alert: -- run with no rule at all, and so do var.set:/var.push:/var.unset:/var.expand: and kata.parse: despite taking output:/inputs:. Entries for those are noise; leave them out.records.update: is gated separately from record.update: -- allowing one does not allow the other.allow@bool: yes. Do NOT try a positive allow/...@bool with a ternary on inputs.record_type — it does not work.The deny-first idiom:
\ndeny/type@bool: {{inputs.record_type is not record type ('task')}}\nallow@bool: yes\nkata skill for the language's own conventions.kata — the language this is written in: the indentation rule, quoting, comments, annotations.scripting — the Twig inside a {{...}} placeholder or a script@raw: value.search-queries — writing a record_query: for record.search: / data.query:.records — confirming a record type's alias, its writable fields, and its search filters.data-queries — the data.query: command's own query language.