CLI Reference#
The command help below is captured from the installed Noema CLI entry point.
noema#
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#
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#
usage: noema ops list [-h] [--json]
options:
-h, --help show this help message and exit
--json Emit JSON
noema ops show#
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#
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#
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#
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#
usage: noema template list [-h] [--json]
options:
-h, --help show this help message and exit
--json Emit JSON
noema template show#
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#
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#
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#
usage: noema recipe validate [-h] path
positional arguments:
path
options:
-h, --help show this help message and exit
noema recipe lint#
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#
usage: noema recipe specs [-h] path
positional arguments:
path
options:
-h, --help show this help message and exit
noema recipe graph#
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#
usage: noema recipe expand-matrix [-h] path
positional arguments:
path
options:
-h, --help show this help message and exit
noema recipe run#
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#
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#
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#
usage: noema research catalog [-h]
options:
-h, --help show this help message and exit
noema research datasets#
usage: noema research datasets [-h]
options:
-h, --help show this help message and exit
noema research tasks#
usage: noema research tasks [-h]
options:
-h, --help show this help message and exit
noema research metrics#
usage: noema research metrics [-h]
options:
-h, --help show this help message and exit
noema research show#
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#
usage: noema research validate-recipe [-h] [--strict] path
positional arguments:
path
options:
-h, --help show this help message and exit
--strict
noema suite#
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#
usage: noema suite list [-h] [--json]
options:
-h, --help show this help message and exit
--json Emit JSON
noema suite show#
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#
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#
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#
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#
usage: noema benchmark show [-h] path
positional arguments:
path
options:
-h, --help show this help message and exit
noema benchmark validate#
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#
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#
usage: noema benchmark results [-h]
options:
-h, --help show this help message and exit
noema benchmark result#
usage: noema benchmark result [-h] result_id
positional arguments:
result_id
options:
-h, --help show this help message and exit
noema benchmark export#
usage: noema benchmark export [-h] result_id
positional arguments:
result_id
options:
-h, --help show this help message and exit
noema benchmark verify#
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#
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:<metric_id>.
--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#
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#
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#
usage: noema submission validate [-h] [--json] path
positional arguments:
path
options:
-h, --help show this help message and exit
--json Emit JSON
noema adapter#
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#
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#
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#
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#
usage: noema runs list [-h] [--json]
options:
-h, --help show this help message and exit
--json Emit JSON
noema runs show#
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#
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#
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#
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#
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#
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#
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#
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#
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#
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#
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#
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#
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#
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#
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