Install evoke and run your first command.

Change the example →

1. What you need before you start

   • macOS or Linuxevoke runs on both. The collection, fifteen ready-made reflexes this route adds, is for a Mac. On Linux, install evoke in step 2, skip the collection, and start with a command you already run. Wrapping it takes one short file, with no code and no Node.
   • Node 24 or newerThirteen of the fifteen run a JavaScript file, so install Node before you add them. The other two run a command the Mac already has, and need no Node. Neither does a reflex you write around a command.
   • gitevoke add fetches reflexes from a git repository. Your own git settings and credentials apply.
   • Node 24.5 or newerYour project also needs ES modules: "type": "module" in package.json, or .mts files.
   • git, for reflexes from a repositoryOnly when you install reflexes from a git repository into your app's folder. The file in step 2 defines its reflex in code, so it needs no git.
   • A classifier keyA classifier reads each sentence you type: Jev, TypeSafe AI's model. It answers which reflex you mean and which value fills each input, with a probability for each. It needs an API key from TypeSafe AI, set as TYPESAFE_API_KEY. TypeSafe AI says Jev is most accurate in English.

   Get a key from TypeSafe AI, at typesafe.ai. A TypeSafe AI key you already hold works here. Copy it: the next step puts it in your shell.

   evoke is free and open source. Each time evoke decides what a sentence asks for, it sends one request to the classifier. The classifier's provider bills that request to the account your key belongs to. In the terminal, a sentence you repeat is answered from a local cache, with no request. evoke never contacts evoke.build, and there is no evoke account. What a decision costs →

   Get a key at typesafe.ai All requirements, in the manual →

2. Set your key and install evoke

   Set the key. Put your key in place of <value>. evoke reads it only when it sends a sentence to the classifier, and never writes it to a file. The line lasts until you close this terminal. To keep it, add it to your shell's startup file, such as ~/.zshrc.

   export TYPESAFE_API_KEY=<value>Copy

   Install the CLI. The script fetches the release built for your machine, checks it against the release's checksums, and puts evoke in ~/.local/bin. If that folder is not on your PATH, the script's last lines print the command that adds it.

   curl -fsSL https://evoke.build/install.sh | shCopy

   Add the collection. This line fetches fifteen reflexes for a Mac from git, and pins each one to its version. Install Node first, because evoke add records where it is.

   evoke add evoke-build/reflexesCopy

   It prints one row per reflex. note, open and visit stay inactive until you give them a notes file, a folder and a site. Until then, no sentence reaches them. A line under the rows names the command that gives each one what it needs. The other ten work at once. A reflex runs as you, held by the kernel to what its manifest declares, so read what you add: every file of the collection is public.

   On Linux, skip this line. The collection is for a Mac. Wrap a command you already run instead, then use steps 3 and 4 with a sentence that asks for it. A reflex around a command, in the manual →

   Set the key. Put your key in place of <value>. The SDK reads it from the environment only when it sends a sentence to the classifier. The line lasts until you close this terminal.

   export TYPESAFE_API_KEY=<value>Copy

   Install the SDK. It carries evoke's core as WebAssembly, so it has no build step and no dependencies.

   npm install @evoke-build/evokeCopy

   Write one file. It defines a reflex in code, so no reflex files are needed. One call then decides, asks, confirms and runs.

   app.ts

   import { load, reflex } from "@evoke-build/evoke"
   import { jev } from "@evoke-build/evoke/jev"
   
   const timer = reflex({
     description: "Start a countdown timer.",
     effect: "write",
     confirm: "Start a {duration} timer?",
     args: { duration: { ask: "How long?", pick: "duration" } },
     examples: { "timer for 10 minutes": { duration: "10 minutes" } },
   }, async ({ duration }) => {                       // duration: number, in seconds
     setTimeout(() => console.log("ring"), duration * 1000)
     return `ringing in ${duration} s`
   })
   
   const project = await load({ reflexes: { timer }, adapter: jev() })
   const handled = await project.handle(process.argv[2] ?? "", {
     confirm: async d => { console.log(d.prompt.template); return true },
     ask: async d => ({ duration: "10 minutes" }),
   })
   console.log(handled.outcome === "ran" ? handled.result.text : handled.outcome)

   To stay short, this file answers evoke's questions itself. Your app would ask the person using it.

3. See the decision before anything runs

   evoke try decides and runs nothing. It prints the classifier's answers: which reflex, each input, and what would happen.

   evoke try "kill the wifi"Copy

   evoke try

     which reflex            wifi 0.95   (none of them 0.03 · power 0.01)
     state                   off 0.86   (on 0.10 · not said 0.04)
     → waits for a yes: wifi state="off" · write · weakest: state 0.86
       a write runs at 0.90 or more

   Turning Wi-Fi off changes something, so wifi is a write reflex. A write runs without a question only when evoke is at least 0.9 sure of every answer. That is its bar. Here the least sure answer is 0.86, so this sentence would ask you first. Try a sentence of your own the same way. Nothing runs.

   evoke printed these lines in one of its own tests, from answers written for it, after note and open were set up. The numbers the classifier gives you will differ.

   decide() makes a decision and runs nothing. It is the first thing handle() does. To see one on its own, add these lines to app.ts after load(). The result is a typed union: narrow it by outcome, then by reflex. When the decision is to run, these lines print the call and how sure evoke is.

   decide only

   const d = await project.decide("timer for 10 minutes")
   if (d.outcome === "run") console.log(d.call, d.confidence)

4. Run your first command

   Type what you want, in quotes after evoke. It prints the call it chose and how sure it is. Then the reflex prints what it did.

   evoke "set the volume to 40 percent"Copy

   evoke

     volume level="40 percent"  0.96
   volume 40%

   In this test run, 0.96 cleared the bar of 0.9, so it ran without asking. The last line, volume 40%, is your first result. Your number may differ. Under 0.9, evoke asks first, with [y]es [n]o [t]each. Typing t saves your sentence as an example in your own file, then runs it.

   Run the file with a sentence. handle() decides, asks for anything missing, confirms, and runs. The file prints what the timer returned, and the timer rings ten minutes later. The program stays open until then, so press Ctrl-C to end it sooner.

   node app.ts "timer for 10 minutes"Copy

5. Choose your next step

   Each card stands alone. Pick the one that fits what you want next.

   Teach it a phrase of yours

   This line saves «go dark» as a way to ask for Wi-Fi off. It goes in your overlay, the file that holds your own wording for a reflex. Your next sentence uses it, and no update of the reflex touches it.

   evoke teach "go dark" wifi state=offCopy

   Teaching, in the manual →

   Name a folder of yours

   open, note and visit need something only you can supply: a folder, a notes file or a site. This line names your desktop folder. Put your own path in place of ~/Desktop. Then evoke "open my desktop folder" opens it.

   evoke vocab places add desktop "The desktop." --value "~/Desktop"Copy

   Your own word lists, in the manual →

   Write your first reflex

   evoke new writes three files that already work: a manifest, a program and its types. The manifest says what the reflex does and which inputs it takes. Put your own code in the program. To wrap a command you already run, the manifest alone is enough.

   evoke new helloCopy

   Your first reflex, in the manual → A reflex around a command, in the manual →

   Ask for two things in one sentence

   Join two requests with «and» or «then». evoke shows the plan first, one numbered line per step. Then each step runs when it clears its own bar, or asks you first. A no at one step skips the steps after it. A sentence with several steps makes one request to find the steps, then at least one for each step.

   Several steps in one sentence, in the manual →

   Load reflexes from files

   In your app's folder, evoke add writes evoke.toml, its lock file evoke.lock, and evoke.d.ts, with a type for each reflex. load() reads them. This needs the evoke CLI from the terminal route.

   Reflexes from files, in the SDK manual →

   Test offline, after one recording

   replay() answers from a recording. Record once with your key. Every run after that is offline, with the same answers.

   Offline tests, in the SDK manual →

   Plan several steps from one sentence

   steps() returns the plan and runs nothing. weave() runs it, and your handlers answer each step's questions.

   Several steps from one sentence, in the SDK manual →

6. Set up your example

   Open the example's setup

$ evoke "lock the screen"
  jev needs TYPESAFE_API_KEY, a key from typesafe.ai  →  export TYPESAFE_API_KEY=<value>
[3]