FAQ

Home > FAQs > Write your own blank

How do I write my own blank?

A blank is a folder with a BLANK.md inside ~/.cues/blanks/<name>/. Declare what triggers it and what computes it, and your own _ command is live in every host within seconds.

Trigger and binding

The trigger is blankKeywords (or a blankShapes grammar that keywords desugar into); the blank claims a _ when its trigger leads the sentence the _ ends, so prose that merely mentions the word never fires it. The binding is one of three: blankScript (a sibling shell script), impl (a runtime class, or a sandboxed ./blank.js), or stepValues (a static list to cycle).

The hello-world

The shipped example blank is the template: time _ calling a small script that prints the local time. Copy the folder, change the keywords and the script, and you have a live system control. A script that both reads and writes (like the shipped volume blank) makes cycling step the real state.

Safety is structural

Third-party JavaScript blanks run capability-restricted: no filesystem, no process, hostname-exact network allow-lists, namespaced storage. Scripts you write yourself can opt into an OS-level sandbox with sandbox: strict. Details: the security model.

Related: What is a blank? · Control your system from text · The gh-issues blank · Blank shapes · What is BLANKS.md? · GitHub repo