# CLI Reference The command help below is captured from the installed Noema CLI entry point. ## `noema` ```text usage: noema [-h] [--version] [--workspace WORKSPACE] [--adapter ADAPTER] {ops,data,recipe,template,research,suite,benchmark,submission,adapter,runs,differentiable,dataset-capture,agentic,ui} ... Run learned-communication experiment contracts and inspect protocol-to-plot evidence. positional arguments: {ops,data,recipe,template,research,suite,benchmark,submission,adapter,runs,differentiable,dataset-capture,agentic,ui} ops Inspect operation contracts data Fetch or inspect sample datasets recipe Validate, graph, or run recipes template Inspect or instantiate cataloged recipe starters research Inspect research datasets, tasks, and metrics suite Inspect benchmark suites benchmark Inspect or run benchmark packs submission Validate benchmark submission bundles adapter Create and validate external adapter SDK manifests runs Inspect run records differentiable Inspect replacement-to-loss training paths and export training contracts dataset-capture Generate dataset-capture shards from researcher- selected recipe taps agentic Validate, run, replay, or verify agentic supervisory experiments ui Run the dashboard server options: -h, --help show this help message and exit --version show program's version number and exit --workspace WORKSPACE Workspace for datasets, artifacts, and run records. Defaults to .noema. --adapter ADAPTER External adapter manifest or directory to register. May be repeated. NOEMA_ADAPTER_PATHS is also honored. ``` ## `noema ops` ```text usage: noema ops [-h] {list,show} ... positional arguments: {list,show} list List registered operations show Show one operation contract options: -h, --help show this help message and exit ``` ## `noema ops list` ```text usage: noema ops list [-h] [--json] options: -h, --help show this help message and exit --json Emit JSON ``` ## `noema ops show` ```text usage: noema ops show [-h] [--json] operation_id positional arguments: operation_id options: -h, --help show this help message and exit --json Emit JSON ``` ## `noema data` ```text usage: noema data [-h] {fetch} ... positional arguments: {fetch} fetch Download a sample dataset options: -h, --help show this help message and exit ``` ## `noema data fetch` ```text usage: noema data fetch [-h] [--limit LIMIT] [--directory DIRECTORY] [--json] {kodak} positional arguments: {kodak} options: -h, --help show this help message and exit --limit LIMIT --directory DIRECTORY --json Emit JSON ``` ## `noema template` ```text usage: noema template [-h] {list,show,instantiate} ... positional arguments: {list,show,instantiate} list List validated recipe starters show Show one recipe starter contract instantiate Instantiate a standalone recipe from a stable template ID options: -h, --help show this help message and exit ``` ## `noema template list` ```text usage: noema template list [-h] [--json] options: -h, --help show this help message and exit --json Emit JSON ``` ## `noema template show` ```text usage: noema template show [-h] [--json] template_id positional arguments: template_id options: -h, --help show this help message and exit --json Emit JSON ``` ## `noema template instantiate` ```text usage: noema template instantiate [-h] [--name NAME] [--description DESCRIPTION] [--set STEP.PARAM=JSON] [--json] template_id positional arguments: template_id options: -h, --help show this help message and exit --name NAME --description DESCRIPTION --set STEP.PARAM=JSON Apply a typed step parameter override; may be repeated. --json Emit the recipe and provenance as JSON instead of recipe YAML. ``` ## `noema recipe` ```text usage: noema recipe [-h] {validate,lint,specs,graph,expand-matrix,run,run-matrix} ... positional arguments: {validate,lint,specs,graph,expand-matrix,run,run-matrix} validate Validate a recipe lint Run strict shared-platform recipe invariant checks specs Show normalized dataset/task/benchmark specs for a recipe graph Show recipe graph expand-matrix Expand a recipe metadata.matrix into concrete recipe JSON documents run Run a recipe locally run-matrix Validate and run every concrete metadata.matrix variant in order options: -h, --help show this help message and exit ``` ## `noema recipe validate` ```text usage: noema recipe validate [-h] path positional arguments: path options: -h, --help show this help message and exit ``` ## `noema recipe lint` ```text usage: noema recipe lint [-h] [--json] [--relaxed] path positional arguments: path options: -h, --help show this help message and exit --json Emit JSON --relaxed Keep catalog status warnings as warnings instead of strict errors. ``` ## `noema recipe specs` ```text usage: noema recipe specs [-h] path positional arguments: path options: -h, --help show this help message and exit ``` ## `noema recipe graph` ```text usage: noema recipe graph [-h] [--format {text,json,dot}] path positional arguments: path options: -h, --help show this help message and exit --format {text,json,dot} ``` ## `noema recipe expand-matrix` ```text usage: noema recipe expand-matrix [-h] path positional arguments: path options: -h, --help show this help message and exit ``` ## `noema recipe run` ```text usage: noema recipe run [-h] [--strict-lint] [--backend BACKEND] [--implementation IMPLEMENTATION] [--parallel-workers N] [--no-plan-cache] path positional arguments: path options: -h, --help show this help message and exit --strict-lint Run strict shared-platform lint checks before execution. --backend BACKEND Require this materialization backend for every recipe step. --implementation IMPLEMENTATION Require this materialization implementation for every recipe step. --parallel-workers N Execute independent DAG branches with up to N workers (1-32, default: 1). --no-plan-cache Bypass execution-plan caching for this run. ``` ## `noema recipe run-matrix` ```text usage: noema recipe run-matrix [-h] [--strict-lint] [--continue-on-error] [--backend BACKEND] [--implementation IMPLEMENTATION] [--parallel-workers N] [--no-plan-cache] path positional arguments: path options: -h, --help show this help message and exit --strict-lint Run strict shared-platform lint checks on every concrete variant. --continue-on-error Continue running remaining variants after a variant fails. --backend BACKEND Require this materialization backend for every recipe step. --implementation IMPLEMENTATION Require this materialization implementation for every recipe step. --parallel-workers N Execute independent DAG branches with up to N workers per variant (1-32, default: 1). --no-plan-cache Bypass execution-plan caching for every matrix variant. ``` ## `noema research` ```text usage: noema research [-h] {catalog,datasets,tasks,metrics,show,validate-recipe} ... positional arguments: {catalog,datasets,tasks,metrics,show,validate-recipe} catalog Show the full research catalog datasets List cataloged datasets tasks List cataloged tasks metrics List cataloged metrics show Show one catalog entry validate-recipe Validate a recipe against the research catalog options: -h, --help show this help message and exit ``` ## `noema research catalog` ```text usage: noema research catalog [-h] options: -h, --help show this help message and exit ``` ## `noema research datasets` ```text usage: noema research datasets [-h] options: -h, --help show this help message and exit ``` ## `noema research tasks` ```text usage: noema research tasks [-h] options: -h, --help show this help message and exit ``` ## `noema research metrics` ```text usage: noema research metrics [-h] options: -h, --help show this help message and exit ``` ## `noema research show` ```text usage: noema research show [-h] {dataset,task,metric} id positional arguments: {dataset,task,metric} id options: -h, --help show this help message and exit ``` ## `noema research validate-recipe` ```text usage: noema research validate-recipe [-h] [--strict] path positional arguments: path options: -h, --help show this help message and exit --strict ``` ## `noema suite` ```text usage: noema suite [-h] {list,show,benchmarks} ... positional arguments: {list,show,benchmarks} list List benchmark suites show Show one benchmark suite benchmarks List benchmark packs in one suite options: -h, --help show this help message and exit ``` ## `noema suite list` ```text usage: noema suite list [-h] [--json] options: -h, --help show this help message and exit --json Emit JSON ``` ## `noema suite show` ```text usage: noema suite show [-h] [--json] suite_id positional arguments: suite_id options: -h, --help show this help message and exit --json Emit JSON ``` ## `noema suite benchmarks` ```text usage: noema suite benchmarks [-h] [--json] suite_id positional arguments: suite_id options: -h, --help show this help message and exit --json Emit JSON ``` ## `noema benchmark` ```text usage: noema benchmark [-h] {list,show,validate,run,results,result,export,publish,verify,plot} ... positional arguments: {list,show,validate,run,results,result,export,publish,verify,plot} list List benchmark packs grouped by suite show Show one benchmark pack validate Validate one benchmark pack run Run every recipe in a benchmark pack results List benchmark result bundles result Show one benchmark result bundle export Regenerate CSV and Markdown reports for a benchmark result publish Publish a verified benchmark result as a deterministic static demo verify Verify one benchmark result bundle plot Export a paper-ready figure from a benchmark result options: -h, --help show this help message and exit ``` ## `noema benchmark list` ```text usage: noema benchmark list [-h] [--directory DIRECTORY] [--json] options: -h, --help show this help message and exit --directory DIRECTORY --json Emit JSON ``` ## `noema benchmark show` ```text usage: noema benchmark show [-h] path positional arguments: path options: -h, --help show this help message and exit ``` ## `noema benchmark validate` ```text usage: noema benchmark validate [-h] [--summary] path positional arguments: path options: -h, --help show this help message and exit --summary Print a compact human-readable validation summary instead of the full JSON report. ``` ## `noema benchmark run` ```text usage: noema benchmark run [-h] [--strict-lint] [--backend BACKEND] [--implementation IMPLEMENTATION] [--parallel-workers N] [--no-plan-cache] [--resume FAILED_RESULT_ID] [--retain-backing-runs] [--json] path positional arguments: path options: -h, --help show this help message and exit --strict-lint Require every benchmark recipe to pass strict shared- platform lint. --backend BACKEND Require this materialization backend for every benchmark recipe step. --implementation IMPLEMENTATION Require this materialization implementation for every benchmark recipe step. --parallel-workers N Execute independent DAG branches with up to N workers per recipe (1-32, default: 1). --no-plan-cache Bypass execution-plan caching for every benchmark recipe. --resume FAILED_RESULT_ID Explicitly resume a failed terminal result. Validated completed recipe evidence is reused; the failed row and remaining rows run with identical pack and execution settings. --retain-backing-runs Keep redundant .noema/runs backing directories after their result-local evidence snapshots are verified. By default they are pruned to control benchmark disk usage. --json Emit JSON ``` ## `noema benchmark results` ```text usage: noema benchmark results [-h] options: -h, --help show this help message and exit ``` ## `noema benchmark result` ```text usage: noema benchmark result [-h] result_id positional arguments: result_id options: -h, --help show this help message and exit ``` ## `noema benchmark export` ```text usage: noema benchmark export [-h] result_id positional arguments: result_id options: -h, --help show this help message and exit ``` ## `noema benchmark verify` ```text usage: noema benchmark verify [-h] [--json] result_id positional arguments: result_id options: -h, --help show this help message and exit --json Emit JSON ``` ## `noema benchmark plot` ```text usage: noema benchmark plot [-h] --plot {graceful-degradation,packet-success,channel-uses} --out OUT [--y-metric Y_METRIC] [--x X_METRIC] [--y Y_METRIC_EXPLICIT] [--group GROUP] [--method-order METHOD_ORDER] [--style {noema,paper,compact}] [--style-config STYLE_CONFIG] [--packet-success-panel] [--outage-markers] [--no-outage-markers] [--json] result_id positional arguments: result_id options: -h, --help show this help message and exit --plot {graceful-degradation,packet-success,channel-uses} Plot type to export. --out OUT Output image path. Relative paths are written inside the result bundle. --y-metric Y_METRIC Optional metric id for the y-axis, for example quality.psnr_db or task.accuracy. --x X_METRIC Metric id for the x-axis, for example channel.snr_db. --y Y_METRIC_EXPLICIT Metric id for the y-axis, for example quality.psnr_db. --group GROUP Grouping key for curves. Use method, recipe, role, or metric:. --method-order METHOD_ORDER Comma-separated method/series order for the legend and curves. --style {noema,paper,compact} Built-in plot style preset. --style-config STYLE_CONFIG Optional JSON/YAML style override file. --packet-success-panel For graceful-degradation plots, add a secondary packet-success panel when the metric exists. --outage-markers Mark outage points on digital cliff plots. --no-outage-markers Disable outage markers. --json Emit JSON ``` ## `noema benchmark publish` ```text usage: noema benchmark publish [-h] --slug SLUG --out OUT [--force] [--allow-warnings] [--json] result_id positional arguments: result_id options: -h, --help show this help message and exit --slug SLUG Stable demo slug; must match metadata.demo.slug when declared. --out OUT Output directory for the static demo publication. --force Replace an existing publication directory. --allow-warnings Publish verifier warnings visibly; invalid or incomplete bundles are always rejected. --json Emit JSON ``` ## `noema submission` ```text usage: noema submission [-h] {validate} ... positional arguments: {validate} validate Validate a submission JSON/YAML file options: -h, --help show this help message and exit ``` ## `noema submission validate` ```text usage: noema submission validate [-h] [--json] path positional arguments: path options: -h, --help show this help message and exit --json Emit JSON ``` ## `noema adapter` ```text usage: noema adapter [-h] {validate,scaffold} ... positional arguments: {validate,scaffold} validate Validate an external adapter manifest scaffold Create a starter adapter manifest and Python module options: -h, --help show this help message and exit ``` ## `noema adapter validate` ```text usage: noema adapter validate [-h] [--json] [--no-import] path positional arguments: path options: -h, --help show this help message and exit --json Emit JSON --no-import Validate manifest structure without importing adapter callables. ``` ## `noema adapter scaffold` ```text usage: noema adapter scaffold [-h] [--name NAME] [--kind {bits,indices,latents,deepjscc_symbols,classification_dataset,classification_metric}] [--force] [--json] directory positional arguments: directory options: -h, --help show this help message and exit --name NAME --kind {bits,indices,latents,deepjscc_symbols,classification_dataset,classification_metric} --force --json Emit JSON ``` ## `noema runs` ```text usage: noema runs [-h] {list,show,manifest,verify} ... positional arguments: {list,show,manifest,verify} list List runs show Show one run summary manifest Show one run manifest verify Verify one run/result bundle options: -h, --help show this help message and exit ``` ## `noema runs list` ```text usage: noema runs list [-h] [--json] options: -h, --help show this help message and exit --json Emit JSON ``` ## `noema runs show` ```text usage: noema runs show [-h] [--json] run_id positional arguments: run_id options: -h, --help show this help message and exit --json Emit JSON ``` ## `noema runs manifest` ```text usage: noema runs manifest [-h] [--json] run_id positional arguments: run_id options: -h, --help show this help message and exit --json Emit JSON ``` ## `noema runs verify` ```text usage: noema runs verify [-h] [--json] run_id positional arguments: run_id options: -h, --help show this help message and exit --json Emit JSON ``` ## `noema differentiable` ```text usage: noema differentiable [-h] {inspect,export} ... positional arguments: {inspect,export} inspect Inspect replacement targets, downstream gradient support, or capture-only training export Export an architecture-neutral training contract from a recipe options: -h, --help show this help message and exit ``` ## `noema differentiable inspect` ```text usage: noema differentiable inspect [-h] [--replacement STEP_IDS] [--loss LOSS] [--training-plan TRAINING_PLAN] [--json] path positional arguments: path options: -h, --help show this help message and exit --replacement STEP_IDS, --optimizable STEP_IDS Optional comma-separated replacement step ids to inspect against the selected loss. --optimizable is retained as a compatibility alias. --loss LOSS Optional loss/evaluation step id. Defaults to metrics/evaluation steps or terminal steps. --training-plan TRAINING_PLAN Optional separate training-plan YAML/JSON overlay; the source recipe remains unchanged. --json Emit JSON ``` ## `noema differentiable export` ```text usage: noema differentiable export [-h] [--training-plan TRAINING_PLAN] [--replacement STEP_IDS] [--route-loss ROUTE_LOSS] [--framework {torch-sionna,torch}] --out OUT [--force] [--json] path positional arguments: path options: -h, --help show this help message and exit --training-plan TRAINING_PLAN Optional separate training-plan YAML/JSON overlay; the source recipe remains unchanged. --replacement STEP_IDS, --optimizable STEP_IDS Comma-separated replacement-target step ids, for example sender,receiver. May instead be supplied as selected_steps in --training-plan; --optimizable is a compatibility alias. --route-loss ROUTE_LOSS Optional comma-separated recipe loss/evaluation step ids that define the live downstream support DAG. May instead come from training-plan loss_steps. --framework {torch-sionna,torch} Framework requested for support blocks; may instead come from --training-plan. --out OUT Output directory for generated differentiable-export files. --force Overwrite generated files in an existing directory. --json Emit JSON ``` ## `noema dataset-capture` ```text usage: noema dataset-capture [-h] {run} ... positional arguments: {run} run Run a recipe and write dataset-capture tap outputs options: -h, --help show this help message and exit ``` ## `noema dataset-capture run` ```text usage: noema dataset-capture run [-h] [--training-plan TRAINING_PLAN] --out OUT [--force] [--json] [--progress | --no-progress] path positional arguments: path options: -h, --help show this help message and exit --training-plan TRAINING_PLAN Separate training-plan YAML/JSON containing the capture taps and split settings. --out OUT Output dataset-capture bundle directory --force Overwrite files in an existing dataset-capture directory --json Emit final JSON and suppress live progress unless --progress is set. --progress Show capture progress on stderr even when it is not a terminal. --no-progress Disable capture progress. ``` ## `noema agentic` ```text usage: noema agentic [-h] {validate,run,verify,replay} ... positional arguments: {validate,run,verify,replay} validate Validate an agentic supervisory experiment contract run Run an agent and its declared paired comparators verify Verify a completed agentic campaign and its evidence bindings replay Replay recorded effective actions without calling the model options: -h, --help show this help message and exit ``` ## `noema agentic validate` ```text usage: noema agentic validate [-h] [--json] path positional arguments: path options: -h, --help show this help message and exit --json Emit JSON ``` ## `noema agentic run` ```text usage: noema agentic run [-h] [--provider PROVIDER] [--model MODEL] [--model-revision MODEL_REVISION] [--endpoint ENDPOINT] [--base-url BASE_URL] [--api-key-env API_KEY_ENV] [--prompt PROMPT] [--device DEVICE] [--out OUT] [--json] path positional arguments: path options: -h, --help show this help message and exit --provider PROVIDER Override the configured decision provider for this recorded campaign --model MODEL Override the model identifier --model-revision MODEL_REVISION Override the immutable local-model revision --endpoint ENDPOINT Override the Ollama or compatible HTTP endpoint --base-url BASE_URL Alias for --endpoint for OpenAI-compatible providers --api-key-env API_KEY_ENV Dedicated NOEMA_AGENT_* environment variable containing the API key --prompt PROMPT Override the recorded prompt file --device DEVICE Override the local Transformers device, for example cpu --out OUT Campaign output directory; defaults below WORKSPACE/agentic --json Emit JSON ``` ## `noema agentic verify` ```text usage: noema agentic verify [-h] [--json] campaign positional arguments: campaign options: -h, --help show this help message and exit --json Emit JSON ``` ## `noema agentic replay` ```text usage: noema agentic replay [-h] [--out OUT] [--json] campaign positional arguments: campaign options: -h, --help show this help message and exit --out OUT Replay output directory; defaults below WORKSPACE/agentic --json Emit JSON ``` ## `noema ui` ```text usage: noema ui [-h] {serve} ... positional arguments: {serve} serve Serve the local dashboard options: -h, --help show this help message and exit ``` ## `noema ui serve` ```text usage: noema ui serve [-h] [--host HOST] [--port PORT] [--project-root PROJECT_ROOT] options: -h, --help show this help message and exit --host HOST --port PORT --project-root PROJECT_ROOT ```