Give your scripts and your app a way to be asked.

Start with a command or a function you already have.

A command you already run needs only a manifest, and no code. A function needs the same manifest and a file whose default export is your function.

reflex = 1

description = """
Scale a service to a number of replicas.
One deployment in one environment; the number is set, never added to."""
not_for = [
  "restarting or rolling back a service",
  "resizing a database or a disk",
  "autoscaling rules",
]
tags    = ["ops"]
effect  = "write"
confirm = "Scale {service} in {env} to {replicas}?"
run     = [
  "kubectl", "-n", "{env}", "scale", "deployment", "{service}",
  "--replicas", "{replicas}",
]

[args.service]
ask   = "Which service?"
vocab = "services"

[args.env]
ask   = "Which environment?"
vocab = "envs"

[args.replicas]
ask   = "How many replicas?"
pick  = "number"
range = [1, 20]

[examples]
"scale checkout to 6 in staging"   = { replicas = "6" }
"run 3 replicas of search in prod" = { replicas = "3" }
"take payments down to 1 replica"  = { replicas = "1" }

[tests]
"bring checkout up to 12 in prod" = { replicas = "12" }
"scale checkout"                  = { replicas = false }
"restart checkout"                = false

import type { Reflex } from "./reflex.d.ts"

export default (async ({ who }) => `Hello, ${who}!`) satisfies Reflex

$ evoke new hello
+ hello/reflex.toml
+ hello/hello.mts
+ hello/reflex.d.ts
$ cd hello && evoke check
  hello  read  runs hello.mts
$ evoke run hello who=Ada
  hello who="Ada"
Hello, Ada!

The first tab is the scale reflex of the kubectl example, where a team asks for it by its own service names. In the second, evoke new writes a reflex that already works, and the program is your function: before evoke run, add it with evoke add ./hello, from the directory that holds hello. How evoke runs a command, without a shell →

Describe what it does, and where it stops.

A classifier reads each sentence against your manifest. The classifier is Jev, TypeSafe AI's model. It answers closed questions, such as which reflex and which value, and gives each answer a probability.

reflex = 1

description = """
Turn the lights in one room on, off, or dim them.
Ceiling and lamp lights only."""
not_for = ["colour scenes and schedules", "asking whether a light is on"]
tags    = ["home", "lighting"]
effect  = "write"
confirm = "Set the {room} lights {state}?"
run     = "lights.mts"

[config]
bridge = "Hue bridge address"
token  = { about = "Hue API key", secret = true }

[args.room]
ask   = "Which room?"
vocab = "rooms"

[args.state]
ask = "What should the lights do?"
options.on  = "Switch on."
options.off = "Switch off."
options.dim = "Lower the brightness without switching off."

[args.brightness]
ask      = "How bright, in percent?"
pick     = "number"
range    = [1, 100]
optional = true

[yields]
level = "number"

[examples]
"turn on the kitchen lights"   = { state = "on" }
"dim the office to 30 percent" = { state = "dim", brightness = "30 percent" }

[tests]
"make it darker in here" = { state = "dim" }
"light a candle"         = false

lights is an illustration from evoke's own tests, not a reflex you can install. It shows every top-level key a manifest may carry.

The reflex.toml format and its JSON Schema → The rules for writing one →

Put decisions inside your app.

A decision is a typed value your code holds before anything runs. Inspect it, show it, fill in what is missing, ask for approval, then run it. Or let handle() run the whole loop.

import { load } from "@evoke-build/evoke"
import type { Reflexes } from "./evoke.d.ts"

const project = await load<Reflexes>({ root: import.meta.dirname })
const d = await project.decide("kill the lights in the den")

switch (d.outcome) {
  case "run":     await project.run(d); break
  case "confirm": if (await ui.confirm(d.prompt.template))
                    await project.run(d, { confirmed: true }); break
  case "ask":     project.fill(d, await ui.pick(d.missing)); break
  case "abstain": ui.say(d.contenders); break
}

// typed by evoke.d.ts once the reflex is known
if (d.outcome === "run" && d.reflex === "lights") {
  d.values.room    // string
  d.values.state   // "on" | "off" | "dim"
}

Two examples build on this. In the triage example, what is sure runs and the rest waits in a queue for a person. In the maker-checker approval example, one person types a payment and a second person confirms it.

Use the SDK → The decision types, key by key → Approval set by risk: read, write, destructive →

Run several steps, planned by evoke or by your loop.

One sentence can ask for several reflexes, and evoke shows the plan before anything runs. Or a program names the next request, and your own loop sends it.

const plan = await project.steps("look up dana's address and email them")
plan.steps       // [{ n: 1, text, decision, reflex: "contact", effect: "read", ... }, { n: 2, ... }]
plan.binds       // [{ from: 1, to: 2, arg: "to", field: "email", kind: "email", via: "fill" }]
plan.verdict     // { outcome: "run" | "ask" | "confirm" | "refuse", because?: [...] }

const woven = await project.weave(input, {
  ask: (d, turn) => ui.pick(d.missing, turn.step),     // before anything runs
  confirm: (d, turn) => ui.confirm(d.prompt.template),   // at the step's turn
})
woven.status     // the worst step's: "ran", "failed", "declined", "refused", "unanswered"

contact in this plan is a stand-in from evoke's own tests. In the collection, download and screenshot yield the path they saved to, and note takes it. A sentence with several steps makes one request to find the steps, then at least one for each step.

Pass a result to the next step → The loop, in the runbook example. How one sentence becomes a plan →

Keep each team's names apart from the program.

Your data supplies the words people type, such as room or service names. The program underneath never changes. A server for many teams loads the reflexes once. It gives each team its own words with one synchronous call, with({ vocab }).

const tenant = project.with({ vocab: { rooms: await db.rooms(user) } })
const d = await tenant.decide(input)
if (d.outcome === "run") await tenant.run(d)

den    = "The TV room downstairs; also 'the snug'."
office = { what = "The upstairs study.", value = "group-7" }

Test how sentences are read, and what the program does.

Three tests, each for a different thing. One checks the wording over everything installed. One runs your app's control flow offline. One calls the program as a plain function.

$ evoke test
  lights  3 passed · 1 failed
    "make it darker in here"  state: expected "dim", read "off"
  timer   8 passed
  1 of 12 cases failed  →  evoke test
[1]

const record = process.env.RECORD ? jev() : undefined
const project = await load({
  reflexes: { timer },
  adapter: replay("answers.toml", { record }),
})
const d = await project.decide("timer for 10 minutes")
assert.equal(d.outcome, "run")

import note from "../note/note.mts"

const context = {
  input: "",
  config: { file: "notes/today.txt" },
  signal: new AbortController().signal,
}
assert.equal(await note({ text: "buy milk" }, context),
  'noted "buy milk" in ~/notes/today.txt')

Write examples and tests → Testing in the SDK →

Share a reflex with a git tag.

Publishing is a git tag, with no account, no registry and no build step. Others install from your repository, pinned by tag, commit and content.

$ evoke add radhi/home/lights radhi/timer
+ lights  radhi/home/lights 1.2.0  write  runs lights.mts
+ timer   radhi/timer 1.0.1        write  runs timer.mts
  inactive  lights: vocabulary "rooms" is empty  →  evoke vocab rooms add <word> "<meaning>"
  inactive  lights: config "bridge" is not set   →  evoke config lights bridge <value>
  inactive  lights: config "token" is not set    →  evoke config lights token --env <VAR>

  lights  write  runs lights.mts
+ reflex.d.ts
  1.2.0 → 2.0.0  major
    args.state  renamed power

evoke's own collection, fifteen reflexes for macOS, installs the same way: evoke add evoke-build/reflexes.

Publish a reflex → What you trust when you install a reflex →

How evoke relates to what you already use.

evoke turns a typed sentence into a call of a program you installed. It asks when something is missing or unclear, and runs nothing when nothing fits. Here is how that job sits beside what you already have.

How the classifier reads a sentence →

Start with what you already have.

Wrap one command in your terminal today, or put decisions inside a Node app.

evoke is free and open source. Each decision is one request to the classifier, billed by its provider to your own key. At the terminal, a sentence you repeat is answered from a local cache. Nothing goes to evoke.build.

What leaves your machine → Questions before you install →