# Commands

Every command, flag and exit code, as `evoke --help` prints them and with what each one does. The three groups
are use, tune and install; the SDK has its own [reference](../sdk/getting-started.md).

```text
evoke 0.21.0 · you invoke a function; you evoke a reflex

use
  evoke "<input>"                         decide, gate, run
  evoke                                   the REPL; a piped line is one input
  evoke try "<input>"                     decide only, and show every judgment
    --json                                one JSON line per input, for a filter
    --tag <tag>                           only the reflexes carrying the tag
    --save <file>                         the plan as a file, for run
    --                                    the rest is input, even a command word
  evoke why                               the last sentence, explained
  evoke run <call>                        by name, without the classifier
  evoke run <file>                        a saved plan, run as it stands
    --json                                one JSON line: the call and its result
    <call> is <name> [<arg>=<value> | <flag>]…

install
  evoke add <ref>… [--as <name>]          fetch, lint, lock, install
  evoke remove <name>
  evoke update [<name>]                   each remote reflex to its newest tag
  evoke update --accept <name>            a moved contract or effect, accepted
  evoke sync                              the lock realised on this machine
  evoke trust                             this project, trusted at its content

tune
  evoke show [<name>]                     the installed reflexes, or one as used
  evoke teach ["<utterance>"] <call>      the utterance means this call
  evoke teach ["<utterance>"] not <name>  the utterance is not this reflex
    --forget <name>                       the overlay's line for it, removed
    ["<utterance>"] omitted means the last input
  evoke vocab <name>                      the words and their meanings
  evoke vocab <name> add <word> "<meaning>" [--value <v>]
  evoke vocab <name> remove <word>
  evoke config <name> <key> <value>       a setting; a secret as --env <VAR>
  evoke test [<name>]                     every example and test, judged
  evoke calibrate [<name>]                the confidence measured on the records
    --repeat <k>                          each input decided k times: the spread
    --json                                one JSON object, for a script

author
  evoke new <name>                        a working reflex from the template
    --playbook                            a playbook instead: a plan of steps
  evoke check                             lint, types, contract against its tag

exit    0 ran · 1 failed · 2 declined · 3 needs a human · 4 adapter failed
manual  https://evoke.build/manual/
```

## Grammar

- The first argument selects a command only when it is exactly a command word. Otherwise every argument is the
  input, bare words joined by one space. `--` forces input. Lines from stdin are always input.
- `--help`, `-h` or `help`, and `--version` or `-V`, are flags in the first place. They print to stdout and exit
  0. `--help` or `-h` right after a command word prints the help too.
- A command word after a flag, `evoke --json try "…"`, is refused with the way to write it. It is never decided.
- What you asked to see goes to stdout: a reflex's result, the `--json` line, and the answer of `show`, `vocab`,
  `why`, `try`, `test` and `check`. What `evoke` says about a run goes to stderr: the call and its confidence,
  prompts, the line of a write, the ranking after an abstain, and every diagnostic.
- Commands validate every argument before acting. Arguments that spell no command end in `evoke --help`. The
  reserved words `edit`, `search`, `publish` and `adapter` are refused by name until they exist.
- A **call** is `name arg=value…`. A value is bare or a JSON string, like `duration="10 minutes"`. A flag is its
  bare name. `run` and `teach` take a call as one argument or as separate words. An argument to `run` whose first
  word is no reflex name, `month.plan.json` or `~/month.plan.json`, is a plan file.

## Use

| Command                | Does                                                                                          | Exit |
| :--------------------- | :-------------------------------------------------------------------------------------------- | :--- |
| `evoke "<input>"`      | Decides, gates, runs. Prints the call and confidence on stderr, and the result on stdout. Logged | 0 · 2 · 3 · 1 · 4 |
| `evoke`                | On a terminal, the REPL: `> `, line editing, history. Piped, a filter: one input per line, and the first non-zero exit is kept | as each line |
| `evoke try "<input>"`  | Decides only, and prints the sentence as it was read: how it was read as a whole, then each step with which reflex, each value with what it stands on, the call and what would become of it, and why; a sentence of several steps shows the plan first. Last, how much the adapter was asked. Never logged: [Outcomes](../use/outcomes.md#try-decide-and-show-the-work) | 0 · 3 · 4 |
| `evoke try --save <file> "<input>"` | The plan's lines, then the plan written as a file for `run <file>`: the sentence, the classifier's answers and the pins it was decided under, in clear. A plan that asks is refused with the step's question, exit 3; one that refuses, exit 2; nothing written either way. Never logged: [Weaving](../use/weaving.md#saving-a-plan-and-running-it-for-someone-else) | 0 · 2 · 3 · 4 |
| `evoke why`            | The last logged sentence, shown as `try` would show it, and what became of each step: `ran`, `ran at your yes`, `declined`, `asked`, `refused`, `failed`, `cancelled`, `skipped`, `unanswered`; `from <file>` where a plan ran from one; a playbook's own block first where one wrote the plan | 0 · 3 |
| `evoke run <call>`     | Runs the call by name. No classifier. The effect policy is kept, so a destructive call confirms with `[y]es [n]o`. A reflex that takes an earlier step's result is refused: only a sentence of several steps hands one. So is a playbook: a sentence reaches it. `--json` prints the call and its result as one line. Not logged | 0 · 2 · 3 · 1 |
| `evoke run <file>`     | Runs a plan `try --save` wrote, exactly: a file, since its first word is no reflex name. A pin that moved refuses it with the line that names it and the command that mends it; so does a file that does not read the same as its answers. The plan prints, one yes over it is asked whatever its verdict, then each step at its turn as a sentence's is. Every step's line names the file. Logged | 0 · 1 · 2 · 3 · 4 |

| Flag            | With            | Does                                                                     |
| :-------------- | :-------------- | :----------------------------------------------------------------------- |
| `--json`        | input, `try`, `run` | One JSON line per input, per step of a weave, or per call; `try` prints a weave's plan whole: [The JSON line](json.md) |
| `--tag <tag>`   | input, `try`    | Only reflexes carrying the tag; repeatable                                |
| `--save <file>` | `try`           | The plan written as a file for `run <file>`; one input, never stdin       |
| `--`            | input           | The rest is input                                                        |

## Install

| Command                                | Does                                                                                  |
| :------------------------------------- | :------------------------------------------------------------------------------------ |
| `evoke add <ref>… [--as <name>]`       | Fetches each ref at its pin or newest tag, once per repository; reads a local ref, `./dir`, where it is. Lints, tests for stolen phrases, writes `evoke.toml`, the lock and `evoke.d.ts`, and records the runtime; for a playbook, decides each step over the set it joins and prints what it reaches, and any reflex reached that lacks the playbook's tag. `--as` names a single ref |
| `evoke remove <name>`                  | Drops the reflex from `evoke.toml` and the lock. Keeps your overlay, vocabularies, settings and the store's copy |
| `evoke update [<name>]`                | Moves each unpinned remote reflex, or one, to its newest tag. A pinned one moves to its pin. Reports, or prints `up to date`. Never prompts or rewrites your files |
| `evoke update --accept <name>`         | Takes on an effect upstream loosened, or a declaration it widened, at the current tag |
| `evoke sync`                           | Places every locked reflex in the store at its locked tag, and records the runtime, or prints `up to date`. Never changes the lock |
| `evoke trust`                          | Trusts the project here, at the content of its four owned paths                       |

A ref is `owner/repo[/dir][@tag]` on GitHub, `<git url>[#dir][@tag]` over `https` or `ssh`, or `./dir` for a
local reflex: [Installing reflexes](../use/installing.md#refs).

## Tune

| Command                                                   | Does                                                                        |
| :-------------------------------------------------------- | :-------------------------------------------------------------------------- |
| `evoke show`                                              | Every installed reflex: name, ref and tag or `./dir`, effect, what it runs or `a plan of 7 steps`. Then the inactive lines |
| `evoke show <name>`                                       | The effective manifest as TOML, with `+` in the gutter of every line that is yours; for a reflex that takes whole results, which installed reflexes return each; for a playbook, its steps after `confirm`, numbered, a step that may not run ending in its `when`. Then its inactive lines |
| `evoke teach "<utterance>" <call>`                        | Writes the example to `overlays/<name>.toml`, with only what the call asserts |
| `evoke teach "<utterance>" not <name>`                    | Writes `"<utterance>" = false` to the reflex's overlay                       |
| `evoke teach --forget "<utterance>" <name>`               | Removes the utterance's line from the reflex's overlay, an example or a test |
| `evoke teach <call>` · `evoke teach not <name>`           | The same, for the last input the log holds; of a weave, the step the lesson's reflex decided. A first word is the utterance when a call follows it, unless it names an installed reflex |
| `evoke vocab <name>`                                      | Lists the words. Empty exits 3, with the add line                            |
| `evoke vocab <name> add <word> "<meaning>" [--value <v>]` | Adds or replaces a word                                                     |
| `evoke vocab <name> remove <word>`                        | Removes one. A word that is not there is refused                            |
| `evoke config <name> <key> <value>`                       | Sets a declared setting under `[config.<name>]`                             |
| `evoke config <name> <key> --env <VAR>`                   | Names the variable a setting is read from. The only way to set a secret     |
| `evoke test [<name>]`                                     | Decides every example and test of every active reflex, or of one, without the cache; a playbook's steps too, each filled from a record, `7 steps route` or the step that reaches nothing, or reaches a reflex that yields no field a branch waits on. A case that passes while its call would wait for a yes, holding less than its words, is named under its reflex and fails nothing. Exits 1 when a case failed; nothing to test says so |
| `evoke calibrate [<name>] [--repeat <k>] [--json]`        | Decides every record once more, each distinct input once or `k` times, and reports what the confidence meant: the whole call right by bins with their counts and intervals, the wrong calls at or over each bar per thousand, the spread over repeats, the log's lines apart. `--json` prints one object. Exits 1 on a call wrong at or over its bar, or a bin of a hundred calls over-confident: [Calibrating](../use/calibrating.md) |

None of these needs the classifier's key but `test` and `calibrate`, which ask it, or a recording.

## Author

| Command            | Does                                                                                                       |
| :----------------- | :--------------------------------------------------------------------------------------------------------- |
| `evoke new <name>` | Writes `./<name>/reflex.toml`, `<name>.mts` and `reflex.d.ts` from the template. Refuses a directory that exists |
| `evoke new --playbook <name>` | Writes `./<name>/reflex.toml` alone, a playbook of three steps from the template |
| `evoke check`      | In a reflex directory: the manifest's lines to fix, the body found and loaded, lint, `reflex.d.ts` rewritten when it changed, and the contract diffed against the repository's newest tag |

## Exit codes

| Code | Meaning                                                                                  |
| :--- | :--------------------------------------------------------------------------------------- |
| 0    | Ran, or the command did what it said                                                     |
| 1    | A body or the machine failed. Also `evoke test` with a failing case, and `evoke calibrate` with a call wrong at or over its bar |
| 2    | Abstained, or declined at a prompt                                                       |
| 3    | Needs a human: a missing key, nothing installed, an untrusted project, a prompt without a terminal, a line to fix |
| 4    | The adapter failed                                                                       |