Gene Lifecycle Commands
rotifer init
Section titled “rotifer init”Initialize a new Rotifer Agent workspace with Genesis genes and Arena preview.
rotifer init [workspace-name]Arguments:
| Argument | Required | Description |
|---|---|---|
workspace-name | No | Agent workspace directory name (defaults to my-agent) |
Options:
| Flag | Description |
|---|---|
--domain <domain> | Default gene domain (default: general) |
--fidelity <level> | Example gene fidelity: Wrapped | Hybrid | Native (default: Wrapped) |
--no-genesis | Skip genesis genes installation |
What it creates:
my-agent/├── rotifer.json # Agent workspace configuration├── genes/ # Gene source directory│ ├── genesis-web-search/│ ├── genesis-web-search-lite/│ ├── genesis-file-read/│ ├── genesis-code-format/│ └── genesis-l0-constraint/└── .rotifer/ └── playground.db # Local Arena databaseExample:
$ rotifer init my-agent# Creates ./my-agent with Genesis genes and local Arena state
$ cd my-agent && rotifer arena list# Shows Genesis genes pre-ranked in the local Arenarotifer scan
Section titled “rotifer scan”Scan source files for candidate functions that can be wrapped as genes.
rotifer scan [path]Arguments:
| Argument | Required | Description |
|---|---|---|
path | No | Path to scan (defaults to .) |
Options:
| Flag | Description |
|---|---|
--skills | Scan for SKILL.md files instead of source functions |
--skills-path <dir> | When using --skills, directory to scan (default: [path] or .cursor/skills) |
Supported languages: TypeScript (.ts, .js), Rust (.rs)
Detection patterns:
export function name()export async function name()export const name =pub fn name()/pub async fn name()
Example:
$ rotifer scan src/tools/ Scanning src/tools/search.ts...
Found 3 candidate functions: ┌────┬──────────────┬──────────────────────┬──────┐ │ # │ Name │ File │ Line │ ├────┼──────────────┼──────────────────────┼──────┤ │ 1 │ webSearch │ src/tools/search.ts │ 12 │ │ 2 │ fileRead │ src/tools/file.ts │ 8 │ │ 3 │ codeFormat │ src/tools/format.ts │ 5 │ └────┴──────────────┴──────────────────────┴──────┘rotifer wrap
Section titled “rotifer wrap”Wrap a function as a Rotifer gene, generating a Phenotype and shim code.
rotifer wrap <gene-name> --domain <domain> [options]Arguments:
| Argument | Required | Description |
|---|---|---|
name | Yes | Gene name |
Options:
| Flag | Description |
|---|---|
-d, --domain <domain> | Functional domain (e.g., search.web, file.read) |
--fidelity <level> | Fidelity level (default: Wrapped) |
--from-skill <path> | Create gene from a SKILL.md file (path to SKILL.md or its directory) |
--from-clawhub <slug> | Create gene from a ClawHub skill (downloads and converts automatically) |
Generated files:
genes/<name>/├── phenotype.json # Gene metadata (domain, schemas, fidelity)├── index.ts # Express function wrapper└── shim.ts # Compatibility shimExample:
$ rotifer wrap my-search --domain search.web ✓ Gene 'my-search' wrapped successfully
Domain: search.web Fidelity: Wrapped Version: 0.1.0rotifer test
Section titled “rotifer test”Execute sandbox tests against a gene, validating schemas and behavior.
rotifer test <gene-name> [options]Arguments:
| Argument | Required | Description |
|---|---|---|
name | Yes | Gene name to test |
Options:
| Flag | Description |
|---|---|
--verbose | Show detailed input/output for each test case |
--compliance | Run structural compliance checks (sandbox, L0, fuel metering, IR integrity) |
--scaffold | Write a starting testsuite.json from the phenotype and stop, without running any test. Refuses to overwrite an existing testsuite.json |
--json | Also print the T1 results as JSON: requirements, gatePassed and the result of each case. Printed only when the gene has a testsuite.json; the rest of the report still prints as text |
--allow-credentials <list> | Let external genes use these credentials from your environment, each only at its host: KEY@api.example.com,KEY2@other.example.com. Without it, an external gene that declares a credential makes the command ask once at a terminal (default no), or exit 1 with credentials_not_granted elsewhere |
Test cases run automatically:
- Schema validation — Phenotype conforms to Gene Standard
- Express function —
express()is exported and callable - Input/Output conformance — Output matches
outputSchema - Error handling — Graceful failure on invalid input
- Null check —
express()returns non-null data - Sandbox execution — Compiled genes execute through WASM sandbox; uncompiled genes fall back to Node.js with a warning
- IR verification — WASM module contains all required custom sections
With --compliance, 6 additional structural checks run:
- C1: Sandbox execution verification (sandbox_type == “wasm”)
- C2: Fuel consumption verification (fuel_consumed > 0)
- C3: L0Gate pre-execution check pass
- C4: Phenotype field completeness (Gene Standard)
- C5: F(g) computability (all input metrics available)
- C6: IR segment integrity (custom WASM sections)
T1 test suite: if the gene’s folder has a testsuite.json (spec §47.5), rotifer test also runs it as T1, the same check rotifer publish runs. Without one, it warns that the publishing gate was not evaluated. A failing case makes the command exit with code 1. rotifer test <gene> --scaffold writes a starting suite.
- Async
express(0.37.0 and later): T1 waits for an asyncexpressand judges the value it resolves to. Before, it judged the Promise object, so a suite that passed on the Promise may now fail, and one that failed on it may now pass. - A call that never finishes: if a gene’s Promise never settles, the call fails with exit code 1 and the message says the gene never finished. Before 0.37.0 the command stopped partway with exit code 0.
rotifer runandrotifer agent runbehave the same way. - External genes without IR (0.38.0 and later): a gene installed from Cloud or wrapped from ClawHub that has no compiled IR is not run on Node.js. T1 fails and tells you to run
rotifer compile <gene>first; once compiled, the suite runs in the sandbox. Genes you wrote in this workspace still run their suite on Node.js.
Example:
$ rotifer test my-search Running tests for 'my-search'...
✓ Phenotype schema is valid ✓ express() returned successfully ✓ Output conforms to outputSchema ✓ Error handling works correctly
All 4 tests passed ✓ Fitness: F(g) = 0.8234 V(g) = 0.9100rotifer run
Section titled “rotifer run”Execute a single gene directly, checking its input and output against the gene’s schema.
rotifer run <gene-name> [options]Arguments:
| Argument | Required | Description |
|---|---|---|
gene-name | Yes | Gene name to execute |
Options:
| Flag | Description |
|---|---|
--input <json> | Input JSON string (default: {"name":"world"}) |
--verbose | Show detailed execution output |
--no-sandbox | Run without the WASM sandbox (Node.js only) |
--trust-unsigned | Allow Node.js execution for Cloud-installed or ClawHub-wrapped genes |
--no-validate | Skip checking the input and output against the gene’s inputSchema / outputSchema |
--allow-credentials <list> | Let external genes use these credentials, each only at its host: KEY@api.example.com,KEY2@other.example.com |
External genes:
- A gene installed from Cloud or wrapped from ClawHub runs in the WASM sandbox when it has been compiled (
gene.ir.wasm). If it would have to run from source on Node.js,runrefuses it and exits 1 unless you pass--trust-unsigned, or compile it first withrotifer compile <gene>. - If an external gene that runs in the sandbox declares a credential from your environment,
runasks once at a terminal before running it (default no). Elsewhere it exits 1 withcredentials_not_granted;--allow-credentials KEY@hostallows that credential for this one command, sent only to that host. With--trust-unsignedthe gene runs on Node.js instead:rundoes not ask, and the gene can read every environment variable you have.
Example:
rotifer run my-search --input '{"query":"rotifer"}'rotifer compile
Section titled “rotifer compile”Compile a gene to Rotifer IR (WASM with custom sections).
rotifer compile [gene-name] [options]Arguments:
| Argument | Required | Description |
|---|---|---|
gene-name | No | Gene name (auto-detects if omitted) |
Options:
| Flag | Description |
|---|---|
--check | Validate only, don’t produce artifacts |
--wasm <path> | Path to pre-compiled .wasm file to wrap as IR |
--lang <ts|wasm> | Force compilation mode (auto-detected by default) |
Compilation pipeline:
TypeScript source ↓ esbuild (bundle + minify)WASI-compatible JavaScript ↓ IR compiler (QuickJS → WASM)Raw WASM module ↓ Rotifer IR Injectorgene.ir.wasm (with custom sections)Custom sections injected:
rotifer.version— Protocol versionrotifer.phenotype— Serialized phenotyperotifer.constraints— L0 constraint metadatarotifer.metering— Fuel/resource limits
Example:
$ rotifer compile my-search Compiling 'my-search'...
Pipeline: TypeScript → esbuild → IR compiler → IR ✓ Compiled successfully
IR Hash: a3f2b1...c4d5 Size: 142.3 KB Sections: version, phenotype, constraints, meteringOutput: genes/<name>/gene.ir.wasm
rotifer doctor
Section titled “rotifer doctor”Check the toolchain that rotifer compile needs to turn TypeScript into WASM: esbuild and Javy.
rotifer doctorIt takes no arguments. It looks for esbuild on your PATH (then npx --no-install esbuild) and for javy on your PATH (then npx --no-install javy-cli and javy), and prints which npx and node are active. It does not download anything.
Example:
$ rotifer doctor Rotifer Doctor — TS→WASM toolchain ──────────────────────────────────── esbuild: ok (esbuild) javy: ok (javy) active npx: /usr/local/bin/npx node: /usr/local/bin/node
✓ Toolchain ready — `rotifer compile` can build Native WASM Genes.When something is missing, it lists what it tried and prints the fix: npm i -g esbuild javy-cli (the javy-cli package installs a binary named javy), then make sure the Node prefix that owns rotifer comes first in your PATH. It exits with code 1 in that case, so it can gate a CI step.