← back home

cli quickstart

Five minutes from a clean checkout to a green run. Every command on this page maps to a real click subcommand registered in bernstein.cli.main. If a flag shows up here, it ships in the wheel on PyPI.

1. install Bernstein

The fastest install is pipx. It pins Bernstein in its own venv and exposes the bernstein and bernstein-worker entry points on $PATH. uv tool install and a plain pip install also work.

pipx install bernstein
bernstein init
bernstein run -g "fix the failing test in tests/test_foo.py"

Bernstein requires Python 3.12 or newer. The wheel is published to PyPI under bernstein, Apache 2.0. If you need an offline install, the air-gap wheelhouse path is documented in the canonical reference linked at the bottom of this page.

2. initialise the workspace

Change into the repository you want Bernstein to work on and run bernstein init. The command is idempotent and safe to run a second time:

cd /path/to/your/project
bernstein init

On a fresh checkout, init creates four things:

  • .sdd/: runtime directory for state, backlog, metrics, traces. .sdd/runtime/ is added to .gitignore automatically.
  • bernstein.yaml: project config. The starter file ships with one agent and a placeholder goal.
  • templates/: copied from the wheel. Contains the role prompts (manager, backend, qa, security, devops, and a dozen more). Edit them per project if you want a different voice.
  • .sdd/config.yaml: server port, worker cap, default model, default effort.

3. configure agents in bernstein.yaml

Open bernstein.yaml and edit the agents block. Each entry binds a name (free-form), an adapter (one of the 44 CLI adapters listed in the project README), a role, and a model. A minimal three-agent config looks like this:

# bernstein.yaml
goal: "Add JWT auth to the /login endpoint"

agents:
  - name: backend-claude
    adapter: claude
    role: backend
    model: sonnet
  - name: tests-codex
    adapter: codex
    role: qa
    model: gpt-5.4-mini
  - name: review-gemini
    adapter: gemini
    role: reviewer
    model: gemini-2.5-pro

budget:
  max_cost_usd: 5.00

Adapter names map one-to-one to files in src/bernstein/adapters/. If the CLI binary for an adapter is not installed on the host, the scheduler skips that agent and logs a warning. The budget block is optional but recommended on first run.

4. run a goal

With bernstein.yaml saved, kick the crew off:

bernstein run -g "Add JWT auth to the /login endpoint"

Useful flags on the run command:

  • --dry-run: print the scheduling plan (which agent and model gets which task) without spawning anything. Zero token spend.
  • --plan-only: emit the decomposed task plan as markdown and exit. Use this when you want a human review before any agent runs.
  • --auto-approve: skip the interactive merge prompt at the end of the run. Pair with --max-cost-usd for unattended runs.
  • --profile airgap: deny outbound network by default. Combine with --allow-network to allow-list specific hosts.
  • --audit: enable the HMAC-chained audit log for every task lifecycle event, with a Merkle seal on shutdown.

The orchestrator decomposes the goal into tasks, spawns one agent per task inside a fresh git worktree under .worktrees/, runs lint, types, tests, and the cross-model review gate against each branch, and merges only the work that passes every gate.

5. inspect status and results

While a run is in flight, open a second terminal and check progress:

bernstein status        # one-shot text summary
bernstein dashboard     # live TUI: agents, tasks, costs, traces
bernstein stop          # graceful shutdown of the running orchestra

After the run, the artefacts live in three places. The HMAC-signed audit log is at .sdd/runtime/audit.log; you can verify the chain with bernstein lineage verify <run_id>. Per-task traces (JSONL) are under .sdd/traces/. The merged code is in your working tree, ready for git diff.

For the full reference, including every adapter, every quality gate, and the YAML workflow schema, see the why Bernstein decision FAQ, the cost calculator, and the llms-full.txt dump (consumed by other LLMs the same way as this page).

faq

Five common operator questions about the install path, picked from real GitHub issues and discussion threads. Mirror of the FAQPage structured data on this page.

What does bernstein init create in 2026?

bernstein init creates four artefacts in the current directory. .sdd/ is the runtime directory where backlog, traces, metrics, and audit logs live; .sdd/runtime/ is auto-appended to .gitignore so process state never leaks into commits. bernstein.yaml is the project config; the starter file ships with one agent and a placeholder goal. templates/ holds the role prompt overrides (manager, backend, qa, security, devops) copied from the wheel, edit them per project if you want a different voice. .sdd/config.yaml holds the server port, worker cap, default model, and default effort. The init command is idempotent: running it on an initialised project preserves existing files and refreshes only the templates.

Which CLI agents are auto-discovered?

Bernstein discovers every CLI agent whose binary is on $PATH at run time. The current adapter set covers Claude Code, Codex, Gemini CLI, Aider, Cursor, Copilot, Goose, OpenHands, OpenCode, Plandex, Charm Crush, Continue, Cline, Kilo, Forge, Hermes, Junie, Letta Code, Pi, Q Developer, Qwen, Ralphex, Rovo, Mistral Vibe, Auggie, AIChat, Amp, Autohand, Codebuff, Cody, Composio Orchestrator, Devin Terminal, Droid, gptme, Kimi, Kiro, OpenAI Agents SDK, Ollama (any OpenAI-compatible local LLM), and a generic adapter for arbitrary CLI tools. If you list an adapter whose binary is missing, the scheduler skips that agent and logs a warning rather than failing the run.

Can I do a dry-run before spending tokens?

Yes. bernstein run --dry-run prints the scheduling plan (which agent and which model would be assigned to which task) and exits with zero token spend. bernstein run --plan-only emits the decomposed task plan as markdown and exits before any agent spawns. Either flag is the recommended first pass when you are checking that the goal decomposition matches what you want. The dry-run flag also surfaces missing-binary warnings up-front so you find them before the first paid token leaves your terminal.

How do I run an air-gapped install in 2026?

Pair bernstein run --profile airgap with the wheelhouse-bundle install path. The airgap profile denies outbound network by default; combine with --allow-network <host> to allow-list specific hosts (your local model server, for example). For the install side, bernstein ships a wheelhouse build helper that bundles every dependency as a verifiable archive so you can transport bernstein and its tree onto a disconnected machine. The runtime configuration lives in .sdd/config.yaml under the offline.allow_hosts field.

Where does the audit log live and how do I verify it?

The HMAC-chained audit log is at .sdd/runtime/audit.log. Each line is one JSON record carrying the previous line's HMAC as a chain link, so modifying any earlier line breaks the chain at the next verification. Run bernstein lineage verify <run_id> to walk the chain end-to-end; the command exits zero on a clean chain and prints the first divergent line on tamper. Per-task transcripts under .sdd/traces/ are referenced from the audit log by run_id so a reviewer can cross-check what a specific agent saw and produced against the chain entry that records the gate outcome.