Scripts Reference

Every bun run <script> in the root package.json, grouped by what you are trying to do. Most scripts print their own --help; the linked guide is the long form.

Run Marina

Script	What it does
start / dev	Start the server (src/main.ts). On the local profile it prints a ready-to-use OPENAI_BASE_URL / OPENAI_API_KEY line; the key part is a $(cat '<path>') that reads the 0600 key file, never the key itself.
init	Interactive first-run setup: writes .env (provider keys, profile, world). See Getting Started.
code [dir]	Folder-scoped Marina in agentic Code Mode for that directory — “Claude/Codex in any folder”. See Coding.
clean	Delete the local database and scratch files. Irreversible; stop the server first.
prune-agent-users	Remove users rows left behind by agents that were removed or scaled down.
build	Bundle the server, the memory importer and the browser memory SDK into dist/.
dashboard:dev / dashboard:build	Vite dev server / production build for the dashboard.
usecase-ui:dev / usecase-ui:build	The example use-case UI (examples/usecase-ui).
setup:cli	Put marina on your PATH: links it into ~/.bun/bin or ~/.local/bin, whichever is already on PATH; with neither, links into ~/.bun/bin and prints the line for your shell (--force replaces another link).
build:native	Compile the marina dispatcher into a standalone dist/marina executable. See Compatibility.
build:sdk	Build the @marina/agent-sdk package into src/sdk/dist.
pack:sdk	Build the SDK and write an installable tarball to dist/sdk/ (install it with bun add <path>.tgz; no registry needed).
create:agent <new-dir>	Scaffold a minimal SDK agent project in a new directory (never overwrites files).
monitor	Outside health monitor: checks /health, alerts once per outage (--desktop, webhook), pings a heartbeat URL while healthy, installs nothing on the host. See Operations.
recovery create|restore|unlock	Create or restore a private recovery bundle, or release the lease of a stopped database. See Recovery.

The terminal client is bun run scripts/connect.ts <name> (-c "<command>" for one-shot, --port 3400 or --url ws://host:3400 for another instance). See Connecting.

Ask, forecast, compete

Script	What it does
forecast "<question>"	Forecast any question with no server running: a probability or a number, with sources, verified figures, each analyst’s answer and the cost. See Forecasting.
arena <sub>	Social Simulation Arena operator CLI: keygen, registration, status, rounds, show, submit, backtest, evaluate, research, shadow run|list|score, discover, signals. See Arena.
forecastbench fetch|estimate|run|write|upload|resolve|select|baseline|learn|status	ForecastBench: forecast a round’s 500 questions (resumable) with statistical priors for dataset questions, write the set file, choose up to 3 configurations by backtest, score the model-free priors (baseline), learn from backtest answers (learn); upload needs FORECASTBENCH_GCS_FOLDER and --yes. See ForecastBench.
deepresearch select|run|check|score|summary|compare|file|export	DeepResearch Bench I and II: cited research reports for each task (resumable, --max-usd hard stop), the optional cross-model fact pass, local scoring with the official evaluators behind a capped judge proxy, ledger and lessons; never sends anything. See DeepResearch Bench.
metaculus select|pass|forecast|resolve|status|timer	Metaculus tournament bot: choose a configuration by held-out backtest, forecast open questions with a reasoning comment (--dry-run posts nothing), learn from resolved ones, write the 20-minute systemd units (never enabled). Needs METACULUS_TOKEN. See Metaculus.
learned export|import|distill|archive|entitle|verify|diff|keygen	Signed marina.learned.v1 bundles of lessons, defaults, ledger aggregates, adopted roles and ratified conventions: export (allow-list, scans, proprietary unless --open), verify against pinned keys, diff two versions, distill (read a world database read-only into a bundle, unsigned and labelled so without a key; --archive then archives the database), archive (move a stopped world’s database into a cold archive directory beside it; never deletes), import (MARINA_UPSTREAM=on; unset imports only open bundles signed by a pinned key; trust imported, served below local lessons per MARINA_IMPORTED_LESSONS; paid slices need --entitlement, your own private pack --own), entitle (sign an entitlement token). See Learned bundles.
mind2web2 run|cache|judge|score|record	Mind2Web 2: answer live-web research tasks with the research agent (--cap-usd required), export the pages it read in the judge’s cache layout, run the official judge locally under a spend cap, score, and record to the ledger and lessons. Never submits. See Mind2Web 2.
repro doctor|list|<setup>	Reproduce a published benchmark setup (hle-verified, swebench-verified, tau2, futurex-backtest, arena-backtest): prerequisite checks with fixes, --dry-run plans with estimated spend, replicated arms, a pooled comparison from the ledger. See Reproduce.
leaderboards	Print a markdown snapshot of the public-competition record — external submissions, arena filings, and the benchmark ledger — from the append-only tables. See Leaderboards.
futurex fetch|run|backtest|watch|schedule|learn|status	FutureX weekly prediction benchmark: download a batch, forecast every row and write the submission file, backtest resolved rows, learn from resolved weeks; watch --answer late answers each row once near its cutoff, and schedule prints (never installs) a systemd timer for it. Never submits. See FutureX.
swebench export|subset|run|score|file	SWE-bench through the one-shot coding entry point: seeded subsets, runs per arm and replicate, scoring with the official harness, filing to the benchmark ledger. See SWE-bench.
browsecomp-plus run|compare	BrowseComp-Plus over a local corpus: runs formations with a hard --max-usd stop, judges answers, and compares two arms. See BrowseComp-Plus.
tau2 summary|convert	Summarize τ²-bench result files and convert them into a harness-shaped file for benchmark:import (--require-clean refuses runs with infrastructure errors). See τ²-bench.
longmemeval summary|convert	Summarize LongMemEval-V2 run folders and convert them into a ledger file. See LongMemEval.
arena:research capture|run|score	Checkpointed arena research qualification on frozen inputs. Never signs or submits. See Arena.
arena:portfolio	Shadow comparison of arena formations on a disposable database. No signing, submission or route writes. See Arena.
corpus build|list|search|get|embed|vectors	Build and inspect offline BM25 corpora that agents search with web search engines:corpus:<name>; optional dense vectors. See Search.
benchmark:import	Import harness result files into a world’s benchmark ledger; also regroups, invalidates or revalidates runs (DB_PATH).
outcomes:settle	Settle measured results onto the outcome path: ledger runs without an outcome, plus optional FutureX, arena and Metaculus resolutions. Files nothing.
lessons backfill|rank|replay|backfill-work	Operator tools for the judged lesson pool: teach unlessoned ledger runs, rank and replay lessons, backfill lessons from recorded work (DB_PATH).

Memory service

Script	What it does
memory <sub>	Standalone memory service admin: init, serve, revoke, backup, restore, rotate-backups, compact-receipts, transfers. See Memory Service.
memory:mcp	Memory as a stdio MCP server for coding clients. See Memory extensions.
build:memory	Build the browser memory SDK (dist/memory.js).
build:codex-plugin	Build a local Codex plugin marketplace with memory tools, skills and optional world access. See Codex plugin.
memory:compatibility status|upgrade <db>	Report schema version, pending migrations and numeric-memory integrity without changing the database (status), or apply pending migrations (upgrade). See Compatibility.

Develop and test

Script	What it does
test	Full backend suite, four workers, progress heartbeat and a 15-minute process deadline.
test:ui	Full dashboard suite on Node/Vitest, with four JSDOM workers.
test:browser	Build the dashboard and run every Playwright spec in dashboard/e2e/*.spec.ts.
test:explorer	Build the documentation site and verify API explorer search, schemas, deep links and mobile layout in Chromium.
test:properties	Run shrinking, seeded cache invalidation, command scheduling/cancellation and context security properties (FC_SEED, FC_RUNS, FC_PATH).
docs:api [--check]	Generate builtin commands, live MCP tool schemas, published SDK declarations, HTTP dispatch references and API explorer data, or check them for drift.
docs:env [--check]	Regenerate docs/reference/environment.md from config/environment.reference alone (docs:api also does this).
schema:check	Check that the generated fresh-database schema baseline is current.
test:mutation	Stryker mutation tests over the cache and admission contracts. See Testing.
check:model	Model-check the bounded MCP session specification with TLC (needs Java 21). See Testing.
check:a11y / test:a11y	Dashboard accessibility lint contract; test:a11y adds a dashboard build and axe-core browser checks. See Dashboard accessibility.
check:context-performance --baseline <dir>	Compare context-retrieval p99 latency against a base checkout. See Testing.
test:serial	The same suite in one process (for order-dependent debugging).
test:fast	Engine-free subset, ~10 s — the pre-commit loop (--check reports drift).
test:shard I N	Time-balanced shard I of N (CI runs 3). See Testing.
test:coverage / check:coverage	Suite with coverage, then the per-directory line floor (--strict gates).
test:canvas:browser	Build the dashboard and run the Playwright canvas suite.
typecheck / lint / format	tsc --noEmit, Biome check, Biome auto-format.
check:versions / check:overrides	Every package.json matches the root version; audit root overrides.
plugin:sync [--check]	Regenerate the Claude Code plugin’s copied skills and version (plugins/claude-code) from their sources, or report drift.
prepack	Dashboard and memory SDK build before packing.

Evaluate and qualify

These make claims measurable. Provider-backed ones spend money; each says so and most take a budget flag. Write their reports outside the public checkout.

Script	What it does
playbook	Marina’s use cases as executable steps (scripts/playbook/catalog.ts): each command a person would type, whether it must succeed or be refused, the words its reply must carry, and time and cost ceilings. Boots one isolated server per world (local profile, own port and database, daily cap --cap, default $10; only the --env-file you name is read) and writes report.md / report.json to --out (default ~/.marina/playbook/<timestamp>). --free needs no keys; --long adds scheduled runs, model comparison and analyst teams; --only <ids> picks use cases. The model-free slice also runs in test/playbook.test.ts. See Testing.
bench / bench:ui	Academic benchmark harness; web UI on port 3303. See Benchmarks.
bench:compare <a> <b>	Paired comparison of two harness result files or tier-0 directories: Wilson intervals, McNemar test, paired bootstrap, reported cost.
eval:transfer --spec <file>	Transfer report: a candidate configuration counts only when it improves on at least two independent suites (paired bootstrap + exact sign test, held-out items) with no significant regression. Ingests existing result files and benchmark ledgers (read-only); --run executes suite commands; --inventory <root…> lists the per-item results under the given roots (with each variant’s commit) and the pairs they offer. Every suite must compare one clean commit (results record theirs): mixed, unstamped or dirty sources are reported and not counted; a spec’s versions: {baseline, candidate} declares a deliberate release comparison, and --allow-unversioned ingests old unstamped files with a warning label. Writes markdown and JSON. See Benchmarks.
eval:triage --futurex <rows.json>	Offline intake-triage evaluation (deterministic, no model call, no cost): the class mix of FutureX rows at several horizons, and each class’s mean score and loss share over ledger runs (--ledger), FutureX run directories (--results) and ForecastBench result files (--forecastbench). Writes markdown and JSON. Library: benchmarks/triage/eval.ts.
bench:tier0	A small fixed hard slice (HLE verified gold, GPQA, FRAMES) for crew and formation sweeps against any endpoint.
bench:native	Native world tasks: print a seeded task, or run and score it against a live server.
bench:dream -- --db <path>	Replay every recorded memory dream offline, with no model calls: probes rebuilt from the live records (intact / drifted / gone) and run today, merge/link/decay ops re-checked, and the held-out effect over every owner (--limit, --json). See Memory.
bench:participation-context	Measure automatic-context retrieval latency on seeded records. See Testing.
qualify:tasks --input <file> --output <file>	Score a frozen task-completion suite from saved, audited evidence (no agents, no provider calls); exits 1 unless every planned run and phase passes. See Testing.
qualify:coding	Live Code Mode qualification on small fixture projects (--directory, --budget-usd). See Testing.
qualify:agents:handoff	Live, bounded resident handoff qualification (needs OPENAI_API_KEY, --directory). See Execution evidence.
qualify:sdk	Build, pack and install the SDK into a temporary consumer project and check its exports.
qualify:server	Build the server bundle and boot it from a temporary instance directory (assets, settings, SDK command, shutdown). See Release qualification.
qualify:native	Build dist/marina and test it outside the checkout with only Git on PATH. See Release qualification.
qualify:investigations [dir]	Key-free qualification of the investigation service on a disposable database: content and admission limits, recovery and erasure. Never calls a provider.
qualify:investigations:live	Bounded live investigation qualification (--model, --budget-usd); a dry run prints the plan, --live permits paid work. Never opens an existing database.
qualify:investigations:replay <report>	Replay the attempts saved by a live run in the browser, dashboard, chat, CLI and terminal workspace. Needs dashboard:build and Chromium.
qualify:image <image>	Check a packaged server container image (CONTAINER_RUNTIME, default docker). See Compatibility.
qualify:participation:load --directory PATH [--participants 16 --records 64 --operations 30]	Real local MCP HTTP concurrency, private automatic context, FULL SQLite durability, bounded overflow and recovery; emits report.json without model calls.
bench:context	Offline old/new term-statistics comparison on 1,000 canonical records; verifies equal results and reports median/p95, without caching retrieved memory.
eval-prompt / qualify:prompt	Fast 15-item prompt A/B against a running model endpoint; qualify:prompt gates the answerer at ≥ 13. In-world: benchmark run smoke. See Prompt architecture.
qualify:decisions	Compare decision backends on labeled gate and route cases. In-world (the world’s own backend): decision qualify. See decisions.
qualify:autonomy / qualify:evolution	Autonomy and native-evolution qualification from readiness evidence. In-world views: readiness autonomy, evolve qualify. See Autonomous quality loops.
trial:evolution / trial:evolution:local	Run an evolution trial against a server, or against a disposable local one. See Native evolution.
qualify:flywheel	Live Flywheel sandbox qualification. See Flywheel live qualification.
inventory:capabilities <out.json> / qualify:capabilities	Write an inventory of registered commands, room handlers, tick work and environment reads, then exercise it on a fresh world (--inventory, --directory, --extended; --live with --model and --budget-usd spends). See Release qualification.
qualify:release	The whole local release gate: SBOM, versions, typecheck, lint, tests, dashboard, browser, site, audit. See Release qualification.
sbom [path]	Generate and check the CycloneDX repository dependency inventory with pinned Syft. See Supply-chain verification.
qualify:memory	Black-box memory service proof over public HTTP and scoped keys.
qualify:memory:benchmark	Memory-delta benchmark (offline stub by default).
qualify:paraphrase	Paraphrase retrieval gate (hit@3 across lexical variants).
qualify:memory:reliability / :storage / :sustained / :load	Restart and fault recovery; real ENOSPC and read-only faults in a private mount; elapsed-time resident continuity; concurrent tenants with cancellation and retry.
qualify:memory:assistance / :resident / :workflow / :task-workflows / :utility / :scale / :clients	Research qualifications for memory assistance, residents, workflows, utility, synthetic scale, and installed coding clients. See Memory assistance.

Research probes and audits without a package.json alias run directly with bun run scripts/research/<name>.ts. They use synthetic identities and disposable databases; the ones marked live need an output directory outside the public checkout.

Script	What it does
memory-api-baseline	Records observed memory API behavior (a probe, not a conformance test).
memory-surface-audit	Wider-surface audit over real authenticated route handlers; lists unresolved boundaries.
memory-long-horizon-audit	Long-horizon functional audit with simulated time, real handlers and compactor; no models.
memory-retrieval-bench	Reproducible local retrieval microbenchmark with result checks; no models.
memory-embedding-review	Boundary diagnostic for local embeddings; optional model-cache path, never downloads.
bridge-translation-audit	Functional observations of the Anthropic ↔ OpenAI translator; no provider calls.
memory-extension-qualification	Live: extension sockets, persistent restart and paired fresh agents.
memory-handoff-qualification	Live: agent-to-agent memory handoff (--directory, --budget-usd).
memory-transfer-qualification <dir>	Live: transfer between two memory servers.

The shell launchers under benchmarks/ (build.sh, run.sh, launch-stack.sh, launch-providers.sh, launch-synthesis.sh, launch-translators.sh, sweep.sh, run-sweep.sh, sweep-translators.sh) start the self-referential provider stack and sweep the harness across substrates; each documents its usage in its header.

Load and soak

Script	What it does
soak	Flood: N concurrent WebSocket connections sending commands (--connections --duration --rate).
soak:churn / soak:churn:local	Bounded reconnect soak with rotating session tokens, against a server or a disposable local one.