Documentation

Install

Sembl is a Python command-line tool. You need Python 3.10 or newer. The stable package is live on PyPI:

pip install sembl

That gives you the sembl command. Confirm it is there:

sembl --version

If you prefer an isolated CLI install, use uv:

uv tool install sembl

For real repositories, install the graph extra too. It pulls in Graphify and code-review-graph, which give Sembl a structural map of your code:

pip install "sembl[graph-pipeline]"

pip install sembl gives you the latest stable release (0.1.9). For commits not yet released, install from GitHub: uv pip install "sembl[graph-pipeline] @ git+https://github.com/speedvibecode/sembl.git".

Set an API key

Sembl asks a language model to write the Work Order, so it needs one API key from a provider you have access to. You set the key once as an environment variable and Sembl reads it automatically - you never paste it into a command.

Pick whichever provider you already have a key for:

Provider	Environment variable	--provider	Default model
OpenAI	`OPENAI_API_KEY`	`openai`	gpt-4o
Anthropic	`ANTHROPIC_API_KEY`	`anthropic`	claude-sonnet-4-6
Google Gemini	`GEMINI_API_KEY`	`gemini`	gemini-2.5-flash
NVIDIA NIM	`NVIDIA_API_KEY`	`nvidia`	mistral-medium-3.5
OpenRouter	`OPENROUTER_API_KEY`	`openrouter`	moonshotai/kimi-k2
Ollama (local)	none - `OLLAMA_HOST` optional	`ollama`	qwen2.5-coder:7b

Set the variable in your terminal using the block that matches your shell.

Windows - PowerShell

# just this terminal
$env:OPENAI_API_KEY = "sk-your-key"

# or save it for every future terminal
setx OPENAI_API_KEY "sk-your-key"

After setx, open a new terminal - it doesn't change the one you're in.

macOS / Linux - bash or zsh

# just this terminal
export OPENAI_API_KEY="sk-your-key"

# or save it permanently
echo 'export OPENAI_API_KEY="sk-your-key"' >> ~/.zshrc

Never commit your key or paste it into a shared repo. Sembl only ever reads it from the environment.

Your first Work Order

Open a terminal inside a repo and describe the task in plain words - a rough one-liner is fine:

sembl generate --task "add a dark mode toggle to settings" --provider openai

Or point at any repo and choose your provider:

sembl generate --repo C:\path\to\repo --task "fix the login redirect bug" --provider nvidia

Sembl reads the repo, gathers context, asks the model to write the Work Order, then checks every file path against your real code before saving. You'll get a short summary and the folder where everything was written.

Read the output

Everything lands in a folder inside the repo:

.sembl/work-orders/wo-<project>-<timestamp>-<slug>/
  work-order.md       # read this first
  executor-prompt.md  # paste into your agent
  validation-plan.md  # run after the agent finishes
  work-order.json     # machine-readable
  graph-impact.md     # only when graph context was used

Three commands to browse them:

sembl list                        # every Work Order in this repo
sembl show                        # the latest one
sembl show --file executor-prompt  # the agent-ready prompt

Hand executor-prompt.md to Claude Code, Cursor, Aider, or Codex. It carries the goal, the files the agent may touch, what it must not, and how to prove the work is done.

Choosing a provider

All six work the same way from your side - you only change --provider and the matching key. A few notes:

OpenAI and Anthropic are the most reliable at producing clean, structured Work Orders.
Gemini is fast and inexpensive for everyday tasks.
NVIDIA NIM gives access to open models; pick a strong instruction-follower for best JSON discipline.
OpenRouter is OpenAI-compatible and routes to its full model catalog - handy when you want one key for many models. Pass the catalog id with --model, e.g. moonshotai/kimi-k2.
Ollama runs a model locally - no API key, no rate limits, fully offline. Install Ollama, pull a model (ollama pull qwen2.5-coder:7b), then --provider ollama. Point at a remote host with OLLAMA_HOST. Expect slower generation on CPU-only machines.

Want a specific model? Override the default with --model:

sembl generate --task "..." --provider anthropic --model claude-sonnet-4-6

To try a key without setting an environment variable, pass --api-key for a single run.

Diagnose with `sembl doctor`

Before you lean on graph context, run sembl doctor. It tells you exactly what is installed, what is built, and the one command to fix each gap - no guessing.

sembl doctor --repo C:\path\to\repo

It reports your Sembl version and Python, which provider key is set, whether the repo is a real project root, whether Graphify and code-review-graph are installed, and whether their graphs are actually built for this repo. For anything missing, it prints the exact repair command.

Pass --fix to install missing graph tools - it only runs when you opt in, and never touches your environment otherwise. Add --json for machine-readable output your own tooling can read.

Graph pipeline

Sembl works on its own, but the sharpest Work Orders come from graph context - a structural map of your repo built by Graphify and code-review-graph. Build the graphs once, then generate against them:

uv pip install "sembl[graph-pipeline] @ git+https://github.com/speedvibecode/sembl.git"

# 1. Graphify - broad understanding of the project
graphify update C:\path\to\repo --no-cluster

# 2. code-review-graph - structural blast radius
code-review-graph build --repo C:\path\to\repo --data-dir C:\path\to\repo-crg-data --skip-flows

# 3. point Sembl at the graph data and require it
$env:CRG_DATA_DIR = "C:\path\to\repo-crg-data"
sembl generate --repo C:\path\to\repo --task "fix the failing login redirect test" --provider nvidia --graph-mode required

Graph modes

Control how generation treats graph context with --graph-mode:

auto (default) - use graph context if it is available; otherwise explain what is missing and fall back to direct repo probing.
required - fail before any LLM call if graph context is unavailable, so you never spend tokens on a weak run. (--require-graph-context is a backward-compatible alias.)
off - skip Graphify and code-review-graph entirely.

Add --refresh-graph to rebuild both graphs before generating, so you are always working from fresh context.

When graph context is available, Sembl runs a short extra LLM pass that turns the raw structural output into a plain-language impact analysis - likely edit targets, hidden coupling, and files to leave alone. It's saved as graph-impact.md. Skip it with --no-graph-enrichment.

Configuration

Command flags

Flag	What it does
`--task, -t`	The task to scope. Required.
`--repo, -r`	Repository path. Defaults to the current directory.
`--provider, -p`	`openai`, `anthropic`, `gemini`, `nvidia`, `openrouter`, or `ollama`.
`--model, -m`	Override the provider's default model.
`--api-key`	Use this key for one run instead of the env var.
`--graph-mode`	`auto` (use graph if available, else fall back), `required` (fail before any LLM call if unavailable), or `off` (skip graph tools).
`--refresh-graph`	Rebuild Graphify + code-review-graph before generating.
`--require-graph-context`	Backward-compatible alias for `--graph-mode required`.
`--no-graphify`	Skip Graphify even if it's installed.
`--no-crg`	Skip code-review-graph even if it's installed.
`--no-graph-enrichment`	Skip the LLM graph-impact pass.

Environment variables

Variable	Purpose
`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GEMINI_API_KEY`, `NVIDIA_API_KEY`, `OPENROUTER_API_KEY`	Your provider key. Set the one you use.
`OLLAMA_HOST`	Ollama server URL for `--provider ollama`. Defaults to `http://localhost:11434`.
`CRG_DATA_DIR`	Where code-review-graph stores its graph for a repo.
`SEMBL_CRG_DATA_DIR`	Force a specific graph folder for Sembl, overriding the above.

If CRG_DATA_DIR looks like it belongs to a different repo, Sembl quietly derives a repo-specific folder instead - so a stale value won't poison your results.

How Sembl works

Between your task and the finished packet, Sembl runs a short, predictable pipeline:

Probe - reads language, framework, branch, dirty state, the README, and any project rules (AGENTS.md, CLAUDE.md, and the like).
Graph context (optional) - asks Graphify what the task likely touches and pulls code-review-graph's structural blast radius.
Impact synthesis (optional) - an LLM turns that structural output into a focused read: likely edits, hidden coupling, and read-only zones.
Generate - the model writes the eight-lock Work Order as structured JSON, grounded in everything above.
Ground - Sembl checks every path against your real repo, drops files the model invented, and adds real files surfaced by the graph. Validation commands pointing at missing files are removed.
Write - the Work Order, executor prompt, validation plan, JSON, and graph-impact analysis are saved under .sembl/.

That grounding step is what makes the output safe to hand an agent: it never receives a path that doesn't exist or a test command for a file that isn't there.

The eight locks

Every Work Order pins down eight things before a line of code changes:

`Intent`	The real goal and the outcome a user would see.
`Boundary`	Non-goals and areas that must stay untouched.
`Scope`	Editable paths, kept separate from read-only context.
`Context`	Files to read first, plus the rules that apply.
`Success`	Acceptance criteria and what must not regress.
`Proof`	The exact commands that prove it works.
`Safety`	When the agent must stop and ask a human.
`Executor`	An agent-ready prompt that carries all of the above.

Troubleshooting

"No API key found"

Sembl couldn't read a key for your provider. Set the matching environment variable (see Set an API key). On Windows, if you used setx, open a new terminal first.

"OpenAI quota is exhausted" / insufficient_quota

The request reached OpenAI but the account has no credit or hit a spend limit. API billing is separate from a ChatGPT subscription - add credits or raise the limit, then rerun the same command.

"OpenAI rejected the API key" (401)

The key is wrong, expired, or for a different project. Set a valid OPENAI_API_KEY and try again.

"Model not found" or no access (403 / 404)

Your key can't use that model. Check the model name, or pass a model you have access to with --model.

"Rate limit reached"

You're sending requests too fast. Wait a moment, reduce concurrency, or switch to a lighter model.

Gemini or NVIDIA errors

Same shape as above: check the key, the model name, and your quota. If NVIDIA returns "invalid JSON", retry once or pick a stronger instruction-following model - some open models are less disciplined about structured output.

"Graph context required but unavailable"

You used --graph-mode required (or its alias --require-graph-context) but no graph context was available, so Sembl stopped before spending any tokens. Run sembl doctor to see exactly what is missing, build the graphs (see Graph pipeline), or switch to --graph-mode auto to allow the direct-probe fallback.

"graphify / code-review-graph not found"

The graph tools are not installed. Add the graph extra: pip install "sembl[graph-pipeline]".

It used the wrong repo's graph

Sembl derives a repo-specific graph folder to avoid this, but you can be explicit by setting SEMBL_CRG_DATA_DIR to the right path before generating.

Getting started with Sembl

Install

Set an API key

Windows - PowerShell

macOS / Linux - bash or zsh

Your first Work Order

Read the output

Choosing a provider

Diagnose with sembl doctor

Graph pipeline

Graph modes

Configuration

Command flags

Environment variables

How Sembl works

The eight locks

Troubleshooting

"No API key found"

"OpenAI quota is exhausted" / insufficient_quota

"OpenAI rejected the API key" (401)

"Model not found" or no access (403 / 404)

"Rate limit reached"

Gemini or NVIDIA errors

"Graph context required but unavailable"

"graphify / code-review-graph not found"

It used the wrong repo's graph

Diagnose with `sembl doctor`