Mentu

Quickstart

Quickstart

This page takes you from nothing to a recipe that runs inside a declared boundary and leaves a record you can read afterwards. The first run uses the shell backend, so no API key and no network access are involved.

Requirements: macOS 13 or later, git, and Homebrew.

1. Install the runner

curl -fsSL https://get.mentu.ai | sh

Apple Silicon and Intel. It checks the download against the checksums published with the release, installs into ~/.local/bin, and never asks for your password. Homebrew and the signed installer package are on the Install page.

Other install paths, including the signed installer package, are on the Install page.

Run the binary with no arguments to see the command surface:

mentu-recipes
Mentu Recipes
 
New here? Run `mentu-recipes setup`: it shows what is on this Mac, places an
example recipe in the workspace, runs it, and shows you the record.
 
Usage:
  mentu-recipes setup [--yes] [--json] [--no-run]
  mentu-recipes init
  mentu-recipes check <recipe-or-path>
  mentu-recipes run <recipe-or-path> [--workspace PATH] [--backend NAME] [--model MODEL] [--cloud] [--max-parallel N] [--var KEY=VALUE]
  mentu-recipes resume <run-id> [--workspace PATH]
  mentu-recipes retry-step <run-id> <step-label> [--workspace PATH]
  mentu-recipes report <run-id> [--format markdown|json|csv]
  mentu-recipes doctor <recipe-or-path> [--format markdown|json|csv] [--strict]
  mentu-recipes analyze-runs [--workspace PATH] [--format markdown|json|csv] [--export-jsonl PATH]
  mentu-recipes adapters [--json|--explain NAME]
  mentu-recipes vault <set|get|list|delete> ...
  mentu-recipes scan [path] [--artifact PATH]
  mentu-recipes --version

2. Create a workspace

The runner commits the artifacts a step declares, so give it its own git repository rather than an existing project.

mkdir ~/recipe-demo && cd ~/recipe-demo
git init
printf '# demo\n' > README.md
git add -A && git commit -m "init"

3. Run the first-run wizard

mentu-recipes setup
Mentu Recipes 0.5.0 · first run
 
Workspace  /Users/you/recipe-demo
 
Backends on this Mac
  ✓ shell              available  (shell)
  · openai             not found  (llm-http)
  · openai-chat        not found  (llm-http)
  · deepseek           not found  (llm-http)
  ✓ ollama             available  (llm-http)
  ✓ claude             available  (agent-cli)
  ✓ codex              available  (agent-cli)
 
Keychain   no provider keys stored; add one later with `mentu-recipes vault set <name>`
 
Example    /Users/you/recipe-demo/.mentu/recipes/hello-justifiable.json
           Two shell steps. The first writes examples/.work/hello.md inside its declared boundary;
           the second proves the file says what the first claimed. No credentials needed.
 
Run it now? [Y/n]

The backend list reflects what is on your PATH, so yours may differ. The wizard does four things. It lists the backends found on this Mac and the provider keys already in the Keychain. It places one example recipe in .mentu/recipes and never overwrites a file that is already there. It runs that example with the shell backend. It prints the record path and the commands to try next.

Answer Y (or pass --yes) and the run follows:

✓ hello-justifiable · 2 step(s) · ok
Record     /Users/you/recipe-demo/.mentu/runs/run_20260902181808_1300AA16/run.json
 
Next
  mentu-recipes run hello-justifiable
  mentu-recipes run hello-justifiable --backend claude
  mentu-recipes doctor hello-justifiable
 
Docs       https://docs.mentu.ai/quick-start

The --backend claude line appears only when an agent CLI was found on this Mac. Flags: --no-run stops after scaffolding; --json prints one machine-readable report with the same fields and makes no interactive decisions.

setup also writes .mentu/.gitignore with runs/ and cache/, so run records stay out of git status while your recipes and prompts stay tracked. mentu-recipes list shows what a workspace can run.

4. Read the example

Open .mentu/recipes/hello-justifiable.json. It is the recipe you would have written by hand:

{
  "name": "hello-justifiable",
  "description": "Two steps: one produces an artifact under a declared path, one proves the artifact says what it claims.",
  "type": "sequence",
  "steps": [
    {
      "label": "produce",
      "backend": "shell",
      "prompt": "mkdir -p examples/.work && printf 'status: ok\\nreviewed: yes\\n' > examples/.work/hello.md && echo PRODUCE_COMPLETE",
      "completion_keyword": "PRODUCE_COMPLETE",
      "expected_changes": ["examples/.work/hello.md"],
      "timeout": 30
    },
    {
      "label": "prove",
      "backend": "shell",
      "depends_on": ["produce"],
      "prompt": "echo PROVE_COMPLETE",
      "completion_keyword": "PROVE_COMPLETE",
      "verify": {
        "grep_present": [
          {
            "file": "examples/.work/hello.md",
            "pattern": "status: ok",
            "min": 1,
            "description": "hello.md must record the status the produce step claimed to write"
          }
        ]
      },
      "timeout": 30
    }
  ]
}

Three fields carry the contract. expected_changes is the write boundary: the step may only change the paths it declares, and the runner commits exactly those. completion_keyword is how a step says it is done. verify is a check the runner performs itself after the step, on the files, not on the step's word. An unmet grep_present marks the step warn_bookkeeping and the run continues; a check that must stop the run belongs in verify.commands.

The runner made one commit for the declared artifact:

git log --oneline
29b47c8 chore: mentu-recipes step produce (run_20260902181808_1300AA16)
87504c7 init

5. Read the record

find .mentu/runs -maxdepth 2 -type f
.mentu/runs/run_20260902181808_1300AA16/baseline.json
.mentu/runs/run_20260902181808_1300AA16/events.jsonl
.mentu/runs/run_20260902181808_1300AA16/produce.stderr
.mentu/runs/run_20260902181808_1300AA16/produce.stdout
.mentu/runs/run_20260902181808_1300AA16/prove.stderr
.mentu/runs/run_20260902181808_1300AA16/prove.stdout
.mentu/runs/run_20260902181808_1300AA16/run.json
.mentu/runs/run_20260902181808_1300AA16/state.json

baseline.json is the git state before the run, events.jsonl is every event in order, state.json is per-step state updated as the run goes, and run.json is the summary. These are plain JSON files: they are not chained, and nothing in the runner verifies them after the fact. The full layout is in the CLI reference.

6. Use a real backend

If the wizard found claude or codex on your PATH:

mentu-recipes run hello-justifiable --backend claude

Same recipe, same boundary, same record. The only difference is who does the work. The claude and codex backends use the CLI's own login and need no key in the Keychain. The openai and deepseek backends need an API key, read from the environment (OPENAI_API_KEY, DEEPSEEK_API_KEY) or from the Keychain. The vault set command reads the secret from stdin:

printf '%s' "$OPENAI_API_KEY" | mentu-recipes vault set openai-api-key

Credential resolution is covered in Credentials.

7. Write your own

Copy the example, change the prompts and the declared paths, and validate it:

mentu-recipes check my-recipe
mentu-recipes doctor my-recipe

check loads the recipe, validates it against the schema, and prints the step count and the resolved path:

✓ hello-justifiable · 2 step(s) · /Users/you/recipe-demo/.mentu/recipes/hello-justifiable.json

doctor scores the recipe out of 100 and names what is missing: steps that write without declaring a boundary, non-shell steps with no completion signal, unknown backends, unsupported per-backend options, and shell commands that look destructive. --strict makes warnings fail, which is what you want in CI. The example scores clean:

# Mentu Recipes Doctor
 
- Recipe: `hello-justifiable`
- Score: 100
 
No findings.

The full contract is in Recipe schema.

8. Give Claude Code the skills

If you use Claude Code, two commands teach it this contract:

claude plugin marketplace add mentu-ai/mentu-recipes
claude plugin install mentu-recipes@mentu

It then writes recipes that pass doctor and reads the run record afterwards instead of taking a step at its word. Details on the Install page.

PreviousWhat is Mentu Recipes?NextInstall
© 2026 Mentu.