The evoke manual

Software, by reflex. evoke turns a sentence into a call of a small program. That program is a reflex: a recipe anyone can write, share and improve. A classifier chooses it. A confidence gate decides whether it runs. A sentence can choose a program. It can never invent a value. The classifier is Jev, TypeSafe AI's System One model, reached through either of two built-in adapters. The design is bound to none.

$ evoke "kill the lights in the den"
  lights room="den" state="off"  0.92
den lights off

One tool does three jobs. A CLI where you type what you want. A package manager that installs reflexes from git. A TypeScript SDK that puts the same decisions inside your app. You invoke a function; you evoke a reflex.

Where to start

You want to…	Read
Type what you want and see it happen	Install, then The first ten minutes
Learn the words this manual uses	Concepts
Write a reflex of your own	Your first reflex
Decide and run reflexes inside your application	The SDK
Look something up	Reference

The manual

Start

Page	Read it when
Install	Putting `evoke` and its SDK on a machine
The first ten minutes	Your first key, your first reflexes, your first lesson
Concepts	The words, and the three steps of a decision

Use: the CLI

Page	Read it when
Typing a request	Bare input, the REPL, a pipe, `--json`, `--tag`, exit codes
Languages	English, German, French and Spanish: how `evoke` tells, what stays as typed, what `why` says
Outcomes	Run, confirm, ask and abstain; `try`, `why`, `run`
Weaving	Several things in one sentence: the plan, what a step takes from another
Installing reflexes	`add`, `remove`, `update`, `sync`, `trust`; refs, the lock, the store
Tuning	`teach`, overlays, vocabularies, `config`, `show`, `test`
Calibrating	`calibrate`: what the confidence meant on your records, and over repeats
Projects	Your home project, an app's project, `evoke.toml`, trust

Author: writing reflexes

Page	Read it when
Your first reflex	`new`, `check`, a try, a run: a reflex in ten minutes
The manifest	`reflex.toml`, key by key
Arguments	Options, vocabularies, picks and flags; ranges; renames
The body	File bodies and argv bodies; context, results, the deadline
Playbooks	A reflex whose body is a plan: steps with slots, one yes over the whole
Examples and tests	Records, assertions, `evoke test`, lint
The rules	How a reflex, a playbook and a set are written, and the checklists
Publishing	Tags, versions, the contract diff, collections, the Hub

SDK: `@evoke-build/evoke`

Page	Read it when
Getting started	The first hour: one file, one reflex, one decision
Projects in code	`load()`, roots, reflexes as code, `with()`, generated types
Decisions	The `Decision` union, `fill`, `run`, `handle`; `steps` and `weave`
Adapters	`jev()`, `openjev()` and `clef()`, thresholds, and writing an adapter of your own
Testing	`replay()`: offline, deterministic tests over a recording
Errors	The three errors, and what each asks of you

Reference

Page	Holds
Commands	Every command, flag and exit code
Files	`evoke.toml`, `evoke.lock`, overlays, vocabularies, the types
The JSON line	What `--json` prints, field by field
Environment	Variables `evoke` reads and the paths it writes
Diagnostics	Every line that ends in a fix, and what the fix does
Glossary	The words, in one place

Around the tool

Page	Holds
The collection	The first-party reflexes: what a Mac does at a word
Security	What runs as you, what is guaranteed, and what is not

Conventions

A line beginning $ is a command you type. The lines under it are what the terminal shows.
What you asked to see goes to stdout: a reflex's result, or the answer of show, try, why and test. What evoke says about a run goes to stderr, indented two spaces.
Every line that needs something from you ends with the command that does it: → evoke trust.
macOS and Linux; Windows through WSL. The collection's programs are for macOS.

evoke is Apache-2.0; the collection is MIT. The name and the logo are trademarks: except for displaying the licence details and identifying us as the origin of the software, you have no right under the licence to use them.

Keyboard shortcuts