cerb/cerb-release/kata

KATA

KATA is Cerb's configuration language: keys, values, and indentation. It looks like YAML and is not YAML. Everything below applies everywhere Cerb uses KATA -- automation scripts and policies, toolbars, sheets, charts, workflows, interaction elements, agent config, the schema file -- not just automations.

Full reference: /cerb-docs/references/docs/kata.md.

The indentation rule -- read this one twice

A bare `key:` with anything indented under it is an OBJECT. Always. There is no exception and no heuristic.

To put a multi-line VALUE under a key, the key must carry an annotation. @text: is the generic one, but any annotation works -- @int:, @bool:, @json: all accept a value indented on the following lines.

message@text:
  Subject: Order 123
  Status: open

→ the string "Subject: Order 123\nStatus: open".

Drop the annotation and the same lines mean something completely different:

message:
  Subject: Order 123
  Status: open

→ the object {"message": {"Subject": "Order 123", "Status": "open"}}.

That second one does not error. It parses cleanly into the wrong shape, and the failure surfaces much later as an empty placeholder or a command that received an object where it wanted a string. Prose is especially prone to it, because a colon anywhere in a sentence is enough -- Subject:, Note:, a time like 9:00.

You are only warned when the indented text can't be read as keys:

note:
  See https://cerb.ai/docs/ for more

→ Unexpected syntax (line 2). Same mistake, but this one is loud. Don't rely on it.

So: any value that spans lines, or that contains prose, needs an annotation on its key. When in doubt, @text:.

Strings are never quoted

Values are literal text from the colon to the end of the line. Quotes are not syntax -- they become part of the value.

name: Jeff          →  "Jeff"
name: "Jeff"        →  "\"Jeff\""      ← the quotes are IN the string
name: 'Jeff'        →  "'Jeff'"

Never wrap a value in quotes to "make it a string". It already is one. Quote only when the quotes are genuinely part of the text you want.

Comments must be on their own line

A # only starts a comment at the beginning of a line (after indentation). There are no trailing comments.

# This is a comment.
name: Jeff

name: Jeff # this is NOT a comment

→ the value is "Jeff # this is NOT a comment".

Note that this cuts the other way inside an annotated text block: there, a # line is content, because the whole block is a literal value.

Types come from annotations

All values are text by default. Convert explicitly:

@bool @int @float @csv @json @list @date @key @text @raw @optional

Annotations combine with a comma (@optional,text:). @optional is honored by whatever CONSUMES the KATA rather than by the parser, so what it does depends on the command -- check that command's documentation rather than assuming it drops empty values.

Never stack `@raw` inside an already-raw block. Inside script@raw: / event_kata@raw: / policy_kata@raw:, use the normal annotations (if@bool:, set:). Writing if@raw,bool: {{...}} makes the condition never match.

Keys must be unique among siblings

A repeated key silently clobbers the earlier one. Where you need the same command twice under one parent, give each an alias with /:

set/init:
set/increment:
await/step:

The part before the / is what Cerb dispatches on; the part after is yours, and it may contain only letters, numbers, and underscores -- no dots.

References

&name: defines a reusable block; @ref uses it. Useful for a long value you'd otherwise repeat, and for keeping a big text block out of the middle of a script.

House style

Two-space indentation, spaces not tabs. Annotate types rather than relying on a reader to infer them.