CLI reference

Every mapi command with its --help, generated from the installed CLI by scripts/gen_docs_reference.py. The command-line guide shows them in use. Global options (--url, --token, --profile, --json) go before the command: mapi --json runs ls.

Command	What it does
mapi new	Scaffold a ModelSpec YAML from a template (geo-mmm, forecast, tabular, glm).
mapi check	Statically validate a spec (exit status 1 when it has errors).
mapi fit	Fit a spec locally (in-process) or on the API (--remote).
mapi score	Score a fitted bundle locally, or a model version on the API (--remote).
mapi catalog	Show the catalog of the locally installed plugins (or the API's with --remote).
mapi login	Sign in to the API (browser OIDC, device code, or an API token).
mapi logout	Forget the stored sign-in and API token of the profile.
mapi whoami	Who you are, how you are signed in, and the projects you can use.
mapi use	Select the project commands act in (sent as X-Mapi-Project), or show it.
mapi usage	Cost and quota use of the selected project (or --tenant) for a UTC day or month.
mapi signup	Create a workspace: sends a verification e-mail (valid 24 hours).
mapi verify-email	Redeem a verification token: creates your workspace and its default project.
mapi serve	Start the local development stack (API, embedded Postgres, GCS shim).
mapi approve	Approve (or --reject) a validated model version as a reviewer.
mapi optimize	Split a marketing budget across channels with a fitted marketing-mix model.
mapi choose	Help me choose: a few questions about your goal and data, then the best fits.
mapi about	The About card of anything a user can pick: what it does in plain words, when to use it and when not, what it needs, assumes and gives.
mapi runs	Inspect and control runs on the API.
mapi runs ls	List runs, newest first. Use filters to find runs by metric, param, tag or name.
mapi runs get	Show one run (state, failure, cost, problem).
mapi runs logs	Print captured log lines (untrusted text, control characters stripped).
mapi runs watch	Follow a run's live events until it ends (--json: one JSON event per line).
mapi runs cancel	Request cancellation (idempotent).
mapi runs retry	Start a new run from a failed one (e.g. one resource class up).
mapi runs metrics	Show the metrics of a run: one row for each series, or the points of one metric.
mapi runs params	Show the params of a run.
mapi runs log-metric	Add a metric point to a run. You can also do this after the run ends.
mapi runs log-param	Add a param to a run. A param cannot change after you set it.
mapi runs tag	Set or remove tags of a run.
mapi runs rename	Set the name of a run.
mapi runs note	Set the note of a run. An empty note removes the note.
mapi runs media	Show the images and tables that a run logged. You can also download them.
mapi runs log-image	Add an image to a run. You can also do this after the run ends.
mapi runs compare	Compare runs: a table of metric values, then the params that are different.
mapi runs views	Save, list and delete run views (a saved search of the runs table).
mapi runs views ls	List the saved run views of the project.
mapi runs views save	Save a search of the runs table as a view. A view with the same name is replaced.
mapi runs views rm	Delete a saved run view. The runs do not change.
mapi experiments	Make and change experiments (named groups of runs).
mapi experiments ls	List the experiments of the project, newest first.
mapi experiments create	Make an experiment.
mapi experiments show	Show one experiment.
mapi experiments rename	Change the name of an experiment.
mapi experiments archive	Archive an experiment. An archived experiment does not accept new runs.
mapi experiments unarchive	Make an archived experiment active again.
mapi experiments rm	Delete an experiment. Its runs stay, without an experiment. Its saved views are deleted.
mapi experiments add	Add runs to an experiment. A run moves out of its previous experiment.
mapi experiments remove	Remove runs from an experiment. The runs stay, without an experiment.
mapi datasets	Datasets on the API.
mapi datasets ls	List datasets.
mapi datasets upload	Upload one or more files as a new dataset version (signed PUT + sandboxed ingest run).
mapi datasets ingest	Ingest an already uploaded file as a new dataset version, e.g. a raw HDF5 file after 'mapi datasets inspect' showed which arrays to map.
mapi datasets inspect	List the groups and arrays of an upload (path, shape, dtype, dims hint) without ingesting it - what a raw-HDF5 mapping needs. A local file is uploaded first; ingest it later with 'mapi datasets ingest DATASET UPLOAD_ID --mapping FILE'.
mapi datasets upload-images	Upload a folder of images as a new image collection version.
mapi datasets missing-images	Show how many images of a folder the dataset does not have yet (nothing is uploaded).
mapi datasets upload-weights	Upload pretrained network weights (a .safetensors file) as a new dataset version. A model reads the version as a side table.
mapi plugin	Plugin authoring: scaffold and test model plugins.
mapi plugin init	Scaffold a plugin package (model, entry point and contract-kit tests).
mapi plugin test	Run the plugin's tests (contract kit) with this interpreter; extra args go to pytest.
mapi spec	Spec document tools.
mapi spec upgrade	Upgrade a document through the registered converters (N-1 → N).
mapi config	Client configuration (~/.config/mapi/config.toml).
mapi config show	Resolved settings and where each came from (secrets are never shown).
mapi config path	Print the config file location.
mapi config set	Set a key of the profile (--profile, MAPI_PROFILE, else the default profile).
mapi config unset	Remove a key from the profile (token too: prefer mapi logout).
mapi tokens	API tokens of the selected project (secrets are shown once, at creation).
mapi tokens ls	List tokens (yours, or everyone's with --all).
mapi tokens get	Show one token (never its secret).
mapi tokens create	Mint a token in the selected project. Its secret is shown once.
mapi tokens revoke	Revoke a token: programs using it stop working at once.
mapi admin	Platform operator commands: tenants, quotas, kill switches, executors, audit.
mapi admin audit	The platform audit log, newest first (times in UTC).
mapi admin tenants	All tenants (create, change tier/status/residency).
mapi admin tenants ls	List all tenants.
mapi admin tenants get	Show one tenant.
mapi admin tenants create	Create a tenant.
mapi admin tenants update	Change a tenant's name, trust tier, status or data residency.
mapi admin quotas	Quota policies per token, tenant or the platform.
mapi admin quotas ls	List quota policies.
mapi admin quotas set	Create or REPLACE the policy of (scope, subject): limits left out are removed.
mapi admin quotas rm	Remove a policy (the tier default applies again).
mapi admin kill-switches	Platform-wide emergency controls (audited).
mapi admin kill-switches get	Show the kill switches.
mapi admin kill-switches set	Flip kill switches (confirmation shows the change; the server audits it).
mapi admin executors	Executor health, capacity and conformance.
mapi admin executors ls	Executor health, load and conformance.
mapi admin executors get	One executor.
mapi admin executors disable	Disable an executor: no new run is placed on it (incident containment).
mapi admin executors enable	Enable an executor again.
mapi endpoints	Endpoints: stable aliases for promoted model versions (promote, score, snippets).
mapi endpoints ls	List the project's endpoints.
mapi endpoints get	Show an endpoint, the version it serves and its promotion gate.
mapi endpoints history	Promotions and rollbacks, newest first.
mapi endpoints promote	Point an alias at a model version, through the scorecard promotion gate.
mapi endpoints rollback	Point the alias back at an earlier revision's version.
mapi endpoints schema	What to send: the input schema frozen at promotion and an example payload.
mapi endpoints score	Score the endpoint's current version and wait for the result.
mapi endpoints forecast	Forecast with your latest actuals and the dates to forecast (no refit).
mapi endpoints snippets	Ready-to-run code that scores the endpoint (reads the token from MAPI_TOKEN).
mapi webhooks	Webhooks of the selected project (secrets are shown once, at creation).
mapi webhooks ls	List webhooks (never their secrets).
mapi webhooks get	Show one webhook (never its secret).
mapi webhooks create	Add a webhook. Its signing secret is printed once.
mapi webhooks update	Change a webhook: switch it back on after it was paused or disabled automatically, or change its events, URL or description. The secret is unchanged.
mapi webhooks rotate	New signing secret (printed once); the current one keeps signing for 24 hours.
mapi webhooks deliveries	The delivery log, newest first.
mapi webhooks replay	Send a delivery's event again (a new delivery).
mapi webhooks rm	Delete a webhook and its delivery log.
mapi plots	Render plots to files and share them as embed links.
mapi plots render	Render one plot to a PNG, SVG or PDF file.
mapi plots embed	Create a read-only embed link for a saved plot. Its URL is printed once.
mapi plots embeds	List a saved plot's embed links (redacted).
mapi plots revoke	Revoke an embed link: dashboards showing it stop at once.
mapi guided	Guided mode: templates, column detection and drafts (stores nothing).
mapi guided templates	List the guided templates, or one template's questions.
mapi guided detect	Suggest which column answers each question of a template.
mapi guided draft	Answers -> the ingest mapping and the ModelSpec YAML (nothing is stored).
mapi priors	Business priors: translate beliefs into model priors.
mapi priors preview	Translate beliefs into priors in the sandbox and preview them.
mapi tenant	Your workspace (tenant): verification status, GDPR export and deletion.
mapi tenant status	Verification (e-mail, identity, code upload) and any deletion of the tenant.
mapi tenant export	GDPR export: everything the tenant stored, as one zip archive.
mapi tenant delete	Schedule deletion of the whole tenant (cancellable during the grace period).
mapi workflows	Workflows: validate, save, run and watch DAGs of tests, transforms and models.
mapi workflows validate	Check a workflow file on the server (nothing is saved): unknown nodes, parameters, ports, conditions and cycles, each with a JSON pointer.
mapi workflows apply	Create the workflow named in the file, or save the file as its next revision (an unchanged file adds nothing).
mapi workflows create	Create a workflow from a file or a gallery template (revision 1).
mapi workflows ls	List the project's workflows.
mapi workflows get	Show a workflow (and with --yaml its document at the latest or a given revision).
mapi workflows revisions	Revisions, newest first, and whether each can run.
mapi workflows archive	Archive a workflow (it can no longer run) or bring it back with --undo.
mapi workflows rm	Delete a workflow with its runs, schedules and triggers.
mapi workflows templates	The gallery of ready-made workflows, each in plain words.
mapi workflows template	One template's About card and its nodes.
mapi workflows init	Write a gallery template as a YAML file to edit, validate and apply.
mapi workflows run	Start a run (inputs are pinned to exact versions when it starts).
mapi workflows watch	Follow a run live: every node's status, branch decisions, then the summary (--json: one JSON event per line).
mapi workflows status	A run's status, nodes, decisions and outputs.
mapi workflows runs	Runs of a workflow, newest first.
mapi workflows nodes	The nodes of a run with what each found.
mapi workflows node	One node in full: resolved parameters, result, outputs and child runs.
mapi workflows output	Download a node output's file (a derived dataset, a fitted bundle), verified.
mapi workflows cancel	Cancel a run and its running children.
mapi workflows nodes-catalog	The node implementations a workflow can use, in plain words.
mapi workflows schedules	Cron schedules of a workflow.
mapi workflows schedules ls	A workflow's schedules.
mapi workflows schedules add	Run the workflow on a schedule (at most every 15 minutes).
mapi workflows schedules pause	Pause a schedule.
mapi workflows schedules resume	Resume a paused schedule.
mapi workflows schedules rm	Delete a schedule.
mapi workflows triggers	Run a workflow when a dataset gets a new version.
mapi workflows triggers ls	A workflow's dataset triggers.
mapi workflows triggers add	Run the workflow whenever the dataset gets a new version.
mapi workflows triggers rm	Delete a trigger.
mapi governance	Governance: the check catalog and the policies models must pass.
mapi governance checks	The checks a policy can require, in plain words.
mapi governance policies	Project and tenant-wide governance policies.
mapi governance policies ls	Policies in force in the project (tenant-wide first), or a tenant's.
mapi governance policies get	A policy's latest version with every check and threshold.
mapi governance policies create	Add a policy from a file (name, applies_to, checks, require_approval, ...).
mapi governance policies update	Save the file as the policy's next version.
mapi governance policies retire	Retire a policy (its versions stay for audit).
mapi governance policies versions	Every version of a project policy, newest first.
mapi validate	Validate a model version against the governance policies (or a workflow file).
mapi validate model	Run the governance checks on a model version and show every result.
mapi validate workflow	Check a workflow file on the server (same as mapi workflows validate).
mapi validations	Validations: the review queue, evidence, resubmission, deprecation, evidence packs.
mapi validations ls	Validations of the project, most recently changed first.
mapi validations get	A validation: status, every result, approvals and history.
mapi validations evidence	Every check result with its evidence (numbers, tables).
mapi validations cancel	Stop running checks (back to draft).
mapi validations resubmit	Run the checks again after a failure or a rejection.
mapi validations deprecate	Retire a validated model version (audited with the reason).
mapi validations pack	Export the evidence pack for an auditor (self-contained HTML, or JSON).
mapi explore	Explore a dataset or a model (sections computed in the sandbox), compare models.
mapi explore dataset	Explore a dataset version: profile, distributions, time plots, missingness, outliers, correlations, cross-correlation with the KPI, ACF/PACF, stationarity, STL, VIF, group comparisons and data-quality warnings.
mapi explore model	Explore a model version: parameters, diagnostics, fit vs actual, residual tests, decomposition, response curves, IRF/FEVD, forecasts, backtests and comparisons.
mapi explore compare	Compare model versions on their shared holdout: metrics, ranking and pairwise Diebold-Mariano tests (is the difference more than luck?).
mapi explore get	An exploration's sections (and with --out its views).

mapi

Usage: mapi [OPTIONS] COMMAND [ARGS]...

  The modeling-api command line.

  Local commands (new, check, fit, score, catalog, plugin, spec) need no server. Remote commands
  (runs, datasets, tokens, usage, admin, endpoints, webhooks, plots, guided, priors, tenant,
  signup, workflows, governance, validate, validations, approve, explore, optimize, choose,
  about, --remote) use the API from --url, MAPI_URL or a profile in ~/.config/mapi/config.toml,
  signed in with `mapi login` (or --token / MAPI_TOKEN), in the project chosen with `mapi use`
  (or --project / MAPI_PROJECT). --json prints machine-readable output on stdout.

Options:
  --url <str>           API base URL (default: MAPI_URL, profile, local)
  --token <str>         Bearer token (default: MAPI_TOKEN, profile)
  --profile <str>       Config profile (default: MAPI_PROFILE)
  --project <str>       <tenant>/<project> to act in (default: MAPI_PROJECT, mapi use)
  --json                Machine-readable JSON on stdout
  --version             Show the version
  --install-completion  Install completion for the current shell.
  --show-completion     Show completion for the current shell, to copy it or customize the
                        installation.
  -h, --help            Show this message and exit.

Commands:
  new           Scaffold a ModelSpec YAML from a template (geo-mmm, forecast, tabular, glm).
  check         Statically validate a spec (exit status 1 when it has errors).
  fit           Fit a spec locally (in-process) or on the API (--remote).
  score         Score a fitted bundle locally, or a model version on the API (--remote).
  catalog       Show the catalog of the locally installed plugins (or the API's with...
  login         Sign in to the API (browser OIDC, device code, or an API token).
  logout        Forget the stored sign-in and API token of the profile.
  whoami        Who you are, how you are signed in, and the projects you can use.
  use           Select the project commands act in (sent as X-Mapi-Project), or show it.
  usage         Cost and quota use of the selected project (or --tenant) for a UTC day or...
  signup        Create a workspace: sends a verification e-mail (valid 24 hours).
  verify-email  Redeem a verification token: creates your workspace and its default project.
  serve         Start the local development stack (API, embedded Postgres, GCS shim).
  approve       Approve (or --reject) a validated model version as a reviewer.
  optimize      Split a marketing budget across channels with a fitted marketing-mix model.
  choose        Help me choose: a few questions about your goal and data, then the best fits.
  about         The About card of anything a user can pick: what it does in plain words,...
  runs          Inspect and control runs on the API.
  experiments   Make and change experiments (named groups of runs).
  datasets      Datasets on the API.
  plugin        Plugin authoring: scaffold and test model plugins.
  spec          Spec document tools.
  config        Client configuration (~/.config/mapi/config.toml).
  tokens        API tokens of the selected project (secrets are shown once, at creation).
  admin         Platform operator commands: tenants, quotas, kill switches, executors, audit.
  endpoints     Endpoints: stable aliases for promoted model versions (promote, score,...
  webhooks      Webhooks of the selected project (secrets are shown once, at creation).
  plots         Render plots to files and share them as embed links.
  guided        Guided mode: templates, column detection and drafts (stores nothing).
  priors        Business priors: translate beliefs into model priors.
  tenant        Your workspace (tenant): verification status, GDPR export and deletion.
  workflows     Workflows: validate, save, run and watch DAGs of tests, transforms and models.
  governance    Governance: the check catalog and the policies models must pass.
  validate      Validate a model version against the governance policies (or a workflow file).
  validations   Validations: the review queue, evidence, resubmission, deprecation,...
  explore       Explore a dataset or a model (sections computed in the sandbox), compare...

mapi new

Usage: mapi new [OPTIONS] [template]

  Scaffold a ModelSpec YAML from a template (geo-mmm, forecast, tabular, glm).

Arguments:
  template  One of: geo-mmm, forecast, tabular, glm

Options:
  -o, --output <path>  Spec file to write (default: spec.yaml)
  --name <str>         metadata.name (default: the template name)
  --project <str>      metadata.project  [default: default]
  --with-data          Also write the fixture's tiny sample data (zarr zips)
  --force              Overwrite existing files
  --list               List the templates
  -h, --help           Show this message and exit.

mapi check

Usage: mapi check [OPTIONS] {spec_file}

  Statically validate a spec (exit status 1 when it has errors).

Arguments:
  spec_file  ModelSpec YAML/JSON  [required]

Options:
  --data <path>    Dataset (.zarr.zip, or a .tree.zip tree dataset) giving the raw schema
  --schema <path>  Raw DataSchema (JSON/YAML) instead of data
  --stages         Show the schema at every stage
  --remote <str>   Validate on the API at this URL ('@' = configured URL)
  --dataset <str>  (remote) dataset ref overriding data.dataset
  -h, --help       Show this message and exit.

mapi fit

Usage: mapi fit [OPTIONS] {spec_file}

  Fit a spec locally (in-process) or on the API (--remote).

Arguments:
  spec_file  ModelSpec YAML  [required]

Options:
  --data <path>                   Fit data (.zarr.zip); required locally
  --side-table <str>              NAME=PATH for each data.side_tables entry
  --schema <path>                 Raw DataSchema (JSON/YAML) of --data
  --out <path>                    Bundle directory (default: bundles/<name>)
  --remote <str>                  Fit on the API at this URL ('@' = configured URL)
  --resource-class <S|M|L|XL|GPU>
                                  (remote) S, M, L, XL or GPU
  --wait / --no-wait              (remote) follow the run  [default: wait]
  --timeout <float>               (local) give up after N seconds
  --experiment <str>              (remote) Put the run in this experiment (an id or a name)
  -h, --help                      Show this message and exit.

mapi score

Usage: mapi score [OPTIONS] {request}

  Score a fitted bundle locally, or a model version on the API (--remote).

Arguments:
  request  ScoreRequest YAML  [required]

Options:
  --bundle <path>     (local) bundle directory from 'mapi fit'
  --data <path>       (local) data payload
  --scenario <path>   (local) scenario payload
  --side-table <str>  (local) NAME=PATH
  -o, --out <path>    Write the result DataTree (.zarr.zip)
  --remote <str>      Score on the API ('@' = configured URL)
  --model <str>       (remote) model id
  --version <int>     (remote) version
  --wait <int range>  (remote) Prefer: wait=N seconds  [default: 60; 0<=x<=60]
  --timeout <float>   Give up after N seconds
  -h, --help          Show this message and exit.

mapi catalog

Usage: mapi catalog [OPTIONS] [section]:<all|models|steps|plots>

  Show the catalog of the locally installed plugins (or the API's with --remote).

Arguments:
  section:<all|models|steps|plots>
                                  all, models, steps or plots  [default: all]

Options:
  --remote <str>  Read the API's catalog ('@' = configured URL)
  -h, --help      Show this message and exit.

mapi login

Usage: mapi login [OPTIONS]

  Sign in to the API (browser OIDC, device code, or an API token).

Options:
  --with-token             Store an API token read from stdin (no browser sign-in)
  --device                 Sign in with a code on another device (no local browser)
  --no-browser             Print the sign-in URL instead of opening a browser
  --issuer <str>           OIDC issuer URL (saved to the profile)
  --client-id <str>        OIDC client id (saved to the profile)
  --discovery-url <str>    Where the issuer's discovery document lives, when not under the
                           issuer (e.g. http://127.0.0.1:8000/dev/idp for the dev profile; saved
                           to the profile)
  --port <int range>       Loopback port (0: any free port)  [default: 0; 0<=x<=65535]
  --timeout <float range>  Seconds to wait for the browser  [default: 300.0; x>=1]
  --verify / --no-verify   Check the token with GET /v1/me  [default: verify]
  -h, --help               Show this message and exit.

mapi logout

Usage: mapi logout [OPTIONS]

  Forget the stored sign-in and API token of the profile.

Options:
  --revoke    Also revoke the stored API token on the server (it stops working everywhere)
  -h, --help  Show this message and exit.

mapi whoami

Usage: mapi whoami [OPTIONS]

  Who you are, how you are signed in, and the projects you can use.

Options:
  -h, --help  Show this message and exit.

mapi use

Usage: mapi use [OPTIONS] [project]

  Select the project commands act in (sent as X-Mapi-Project), or show it.

Arguments:
  project  <tenant>/<project> (or a project id when unambiguous)

Options:
  --unset                 Clear the project selection of the profile
  --verify / --no-verify  Check membership with GET /v1/me  [default: verify]
  -h, --help              Show this message and exit.

mapi usage

Usage: mapi usage [OPTIONS]

  Cost and quota use of the selected project (or --tenant) for a UTC day or month.

Options:
  --period <day|month>            UTC day or month  [default: month]
  --start <%Y-%m-%d|%Y-%m-%dT%H:%M:%S>
                                  A UTC date inside the period (e.g. 2026-09-01; default: now)
  --group-by <resource_class|project|day|token|run>
                                  Break the totals down
  --tenant <str>                  The whole tenant instead of the project (tenant admins)
  -h, --help                      Show this message and exit.

mapi signup

Usage: mapi signup [OPTIONS]

  Create a workspace: sends a verification e-mail (valid 24 hours).

Options:
  --email <str>         Your work e-mail address  [required]
  --name <str>          Your name  [required]
  --organisation <str>  Names the new workspace
  --accept-terms        Accept the terms of service (2026-10)
  -h, --help            Show this message and exit.

mapi verify-email

Usage: mapi verify-email [OPTIONS] {token}

  Redeem a verification token: creates your workspace and its default project.

Arguments:
  token  The mev_… token from the e-mail link  [required]

Options:
  -h, --help  Show this message and exit.

mapi serve

Usage: mapi serve [OPTIONS]

  Start the local development stack (API, embedded Postgres, GCS shim).

  Extra arguments are passed through to "mapi-server dev".

Options:
  --host <str>        Bind address
  --port <int range>  [1<=x<=65535]
  -h, --help          Show this message and exit.

mapi approve

Usage: mapi approve [OPTIONS] {validation_id}

  Approve (or --reject) a validated model version as a reviewer.

  Needs a signed-in session (``mapi login``) of a member with the reviewer capability who did
  not submit it; API tokens can never approve.

Arguments:
  validation_id  Validation awaiting approval  [required]

Options:
  --reject             Reject instead (needs --comment)
  -c, --comment <str>
  -y, --yes            Do not ask
  -h, --help           Show this message and exit.

mapi optimize

Usage: mapi optimize [OPTIONS] {model_ref}

  Split a marketing budget across channels with a fitted marketing-mix model.

Arguments:
  model_ref  model://project/name@vN, name@vN or name  [required]

Options:
  -v, --version <int range>  [x>=1]
  --budget <float range>     Total to spend  [x>=0]
  --change-pct <float>       Or: change today's total by N %
  --objective <str>          mean (default), p10 (cautious), cvar5, ...
  --channel <str>            Bounds per channel: tv='{"max_multiplier": 1.5}' (repeat)
  --frontier <int range>     Also price N budgets  [3<=x<=50]
  --by-geo                   Allocate per geo and channel
  --request <path>           An OptimizeRequest YAML/JSON (flags override it)
  --timeout <float range>    [default: 900.0; x>=1]
  -h, --help                 Show this message and exit.

mapi choose

Usage: mapi choose [OPTIONS]

  Help me choose: a few questions about your goal and data, then the best fits.

Options:
  -a, --answer <str>              question=answer (repeat; skips the questions); e.g.
                                  goal=forecast
  --kind <model|step|split|template|workflow_template|node_kind|node|check|dataset|spec|plot>
                                  Rank one kind instead: model, step, node, check, ...
  -n, --limit <int range>         [default: 5; 1<=x<=50]
  --about <int range>             About cards to show for the top items  [default: 3; x>=0]
  --expert                        Show the maths and references
  -h, --help                      Show this message and exit.

mapi about

Usage: mapi about [OPTIONS] {item_id}

  The About card of anything a user can pick: what it does in plain words, when to use it and
  when not, what it needs, assumes and gives.

Arguments:
  item_id  A model, step, node, check or template id  [required]

Options:
  --kind <model|step|split|template|workflow_template|node_kind|node|check|dataset|spec|plot>
  --expert                        Show the maths and references
  -h, --help                      Show this message and exit.

mapi runs

Usage: mapi runs [OPTIONS] COMMAND [ARGS]...

  Inspect and control runs on the API.

Options:
  -h, --help  Show this message and exit.

Commands:
  ls          List runs, newest first.
  get         Show one run (state, failure, cost, problem).
  logs        Print captured log lines (untrusted text, control characters stripped).
  watch       Follow a run's live events until it ends (--json: one JSON event per line).
  cancel      Request cancellation (idempotent).
  retry       Start a new run from a failed one (e.g.
  metrics     Show the metrics of a run: one row for each series, or the points of one metric.
  params      Show the params of a run.
  log-metric  Add a metric point to a run.
  log-param   Add a param to a run.
  tag         Set or remove tags of a run.
  rename      Set the name of a run.
  note        Set the note of a run.
  media       Show the images and tables that a run logged.
  log-image   Add an image to a run.
  compare     Compare runs: a table of metric values, then the params that are different.
  views       Save, list and delete run views (a saved search of the runs table).

mapi runs ls

Usage: mapi runs ls [OPTIONS]

  List runs, newest first. Use filters to find runs by metric, param, tag or name.

Options:
  --kind <ingest|describe|validate|fit|score|evaluate|derive|render|optimize|sweep|backtest|sbc|campaign|translate_priors|workflow|workflow_node|explore|governance|inspect>
                                  Filter by kind
  --state <created|rejected|queued|dispatching|provisioning|running|stalled|finalizing|succeeded|partial|failed|cancelling|cancelled>
                                  Filter by state
  --spec <str>                    Filter by spec id
  --parent <str>                  Show only the child runs of this run
  --name <str>                    Show only runs with this text in the name
  --tag <str>                     Show only runs with this tag: KEY or KEY=VALUE. You can use
                                  the option more than one time.
  -f, --filter <str>              Show only runs that agree with this filter, for example
                                  'metric.rmse < 0.5' or 'param.fit.draws >= 1000'. You can use
                                  the option more than one time.
  --order-by <str>                Sort the runs by this value, for example '-metric.rmse' (a '-'
                                  sorts from high to low). The default is '-created_at'.
  -c, --column <str>              Add a column with this value, for example 'metric.rmse' or
                                  'param.fit.draws'. You can use the option more than one time.
  -e, --experiment <str>          Show only the runs of this experiment
  --view <str>                    Use the search of this saved view. Other options add to the
                                  search or replace a part of it.
  -n, --limit <int range>         At most N runs  [default: 20; x>=1]
  -h, --help                      Show this message and exit.

mapi runs get

Usage: mapi runs get [OPTIONS] {run_id}

  Show one run (state, failure, cost, problem).

Arguments:
  run_id  Run id  [required]

Options:
  -h, --help  Show this message and exit.

mapi runs logs

Usage: mapi runs logs [OPTIONS] {run_id}

  Print captured log lines (untrusted text, control characters stripped).

Arguments:
  run_id  Run id  [required]

Options:
  --attempt <int range>    [x>=1]
  --stream <str>           stdout, stderr, system or user
  --level <str>            Show only lines at this level or higher: debug, info, warning or
                           error
  -n, --limit <int range>  At most N  [x>=1]
  -h, --help               Show this message and exit.

mapi runs watch

Usage: mapi runs watch [OPTIONS] {run_id}

  Follow a run's live events until it ends (--json: one JSON event per line).

Arguments:
  run_id  Run id  [required]

Options:
  --from <int>  Resume after this event id
  -h, --help    Show this message and exit.

mapi runs cancel

Usage: mapi runs cancel [OPTIONS] {run_id}

  Request cancellation (idempotent).

Arguments:
  run_id  Run id  [required]

Options:
  -h, --help  Show this message and exit.

mapi runs retry

Usage: mapi runs retry [OPTIONS] {run_id}

  Start a new run from a failed one (e.g. one resource class up).

Arguments:
  run_id  Run id of a failed run  [required]

Options:
  --resource-class <S|M|L|XL|GPU>
                                  S, M, L, XL or GPU (one NVIDIA L4 GPU)
  --seed <int range>              [x>=0]
  --reason <str>
  -h, --help                      Show this message and exit.

mapi runs metrics

Usage: mapi runs metrics [OPTIONS] {run_id}

  Show the metrics of a run: one row for each series, or the points of one metric.

Arguments:
  run_id  Run id  [required]

Options:
  --key <str>           Show the points of this metric, not the summary of all
  --points <int range>  With --key: the maximum points for each series  [default: 1000;
                        10<=x<=10000]
  -h, --help            Show this message and exit.

mapi runs params

Usage: mapi runs params [OPTIONS] {run_id}

  Show the params of a run.

Arguments:
  run_id  Run id  [required]

Options:
  --prefix <str>  Show only keys that start with this text
  -h, --help      Show this message and exit.

mapi runs log-metric

Usage: mapi runs log-metric [OPTIONS] {run_id} {key} {value}

  Add a metric point to a run. You can also do this after the run ends.

Arguments:
  run_id  Run id  [required]
  key     Metric key, for example revenue_lift  [required]
  value   Value (a number)  [required]

Options:
  --step <int range>  Step of the point  [x>=0]
  --label <str>       Label KEY=VALUE. You can use the option more than one time.
  -h, --help          Show this message and exit.

mapi runs log-param

Usage: mapi runs log-param [OPTIONS] {run_id} {key} {value}

  Add a param to a run. A param cannot change after you set it.

Arguments:
  run_id  Run id  [required]
  key     Param key, for example analyst  [required]
  value   Value: a number, true, false or text  [required]

Options:
  --text      Keep the value as text (do not read a number)
  -h, --help  Show this message and exit.

mapi runs tag

Usage: mapi runs tag [OPTIONS] {run_id} [tags]...

  Set or remove tags of a run.

Arguments:
  run_id   Run id  [required]
  tags...  Tags to set: KEY=VALUE ...

Options:
  --delete <str>  Remove the tag KEY. You can use the option more than one time.
  -h, --help      Show this message and exit.

mapi runs rename

Usage: mapi runs rename [OPTIONS] {run_id} {name}

  Set the name of a run.

Arguments:
  run_id  Run id  [required]
  name    New name (an empty name removes the name)  [required]

Options:
  -h, --help  Show this message and exit.

mapi runs note

Usage: mapi runs note [OPTIONS] {run_id} {text}

  Set the note of a run. An empty note removes the note.

Arguments:
  run_id  Run id  [required]
  text    Note text, or '-' to read the note from stdin  [required]

Options:
  -h, --help  Show this message and exit.

mapi runs media

Usage: mapi runs media [OPTIONS] {run_id}

  Show the images and tables that a run logged. You can also download them.

Arguments:
  run_id  Run id  [required]

Options:
  --key <str>             Show only this media key
  --download <directory>  Write the files to this directory, with names KEY-LABELS-STEP.EXT
  -h, --help              Show this message and exit.

mapi runs log-image

Usage: mapi runs log-image [OPTIONS] {run_id} {key} {file}

  Add an image to a run. You can also do this after the run ends.

Arguments:
  run_id  Run id  [required]
  key     Media key, for example samples  [required]
  file    PNG or JPEG file (at most 4 MB)  [required]

Options:
  --step <int range>  Step of the image  [x>=0]
  --label <str>       Label KEY=VALUE. You can use the option more than one time.
  --caption <str>     Text to show with the image
  -h, --help          Show this message and exit.

mapi runs compare

Usage: mapi runs compare [OPTIONS] {run_ids}...

  Compare runs: a table of metric values, then the params that are different.

Arguments:
  run_ids...  2 to 10 run ids  [required]

Options:
  -k, --key <str>  Compare this metric. You can use the option more than one time. The default
                   is the metrics that most of the runs have.
  --agg <str>      The value to show for each metric: last, min or max  [default: last]
  --all-params     Show all params, not only the params that differ
  -h, --help       Show this message and exit.

mapi runs views

Usage: mapi runs views [OPTIONS] COMMAND [ARGS]...

  Save, list and delete run views (a saved search of the runs table).

Options:
  -h, --help  Show this message and exit.

Commands:
  ls    List the saved run views of the project.
  save  Save a search of the runs table as a view.
  rm    Delete a saved run view.

mapi runs views ls

Usage: mapi runs views ls [OPTIONS]

  List the saved run views of the project.

Options:
  -e, --experiment <str>  Show only the views of this experiment
  -h, --help              Show this message and exit.

mapi runs views save

Usage: mapi runs views save [OPTIONS] {name}

  Save a search of the runs table as a view. A view with the same name is replaced.

Arguments:
  name  Name of the view  [required]

Options:
  -f, --filter <str>              A filter, for example 'metric.rmse < 0.5'. You can use the
                                  option more than one time.
  -c, --column <str>              A column, for example 'metric.rmse'. You can use the option
                                  more than one time.
  --order-by <str>                Sort order, for example '-metric.rmse'
  --tag <str>                     A tag: KEY or KEY=VALUE. You can use the option more than one
                                  time.
  --kind <ingest|describe|validate|fit|score|evaluate|derive|render|optimize|sweep|backtest|sbc|campaign|translate_priors|workflow|workflow_node|explore|governance|inspect>
                                  Kind of run
  --state <created|rejected|queued|dispatching|provisioning|running|stalled|finalizing|succeeded|partial|failed|cancelling|cancelled>
                                  State of run
  -e, --experiment <str>          Save the view in this experiment. The view then shows only its
                                  runs.
  -h, --help                      Show this message and exit.

mapi runs views rm

Usage: mapi runs views rm [OPTIONS] {view}

  Delete a saved run view. The runs do not change.

Arguments:
  view  View id or name  [required]

Options:
  -y, --yes   Do not ask for confirmation
  -h, --help  Show this message and exit.

mapi experiments

Usage: mapi experiments [OPTIONS] COMMAND [ARGS]...

  Make and change experiments (named groups of runs).

Options:
  -h, --help  Show this message and exit.

Commands:
  ls         List the experiments of the project, newest first.
  create     Make an experiment.
  show       Show one experiment.
  rename     Change the name of an experiment.
  archive    Archive an experiment.
  unarchive  Make an archived experiment active again.
  rm         Delete an experiment.
  add        Add runs to an experiment.
  remove     Remove runs from an experiment.

mapi experiments ls

Usage: mapi experiments ls [OPTIONS]

  List the experiments of the project, newest first.

Options:
  --name <str>             Show only experiments with this name
  --archived / --active    Show only archived experiments, or only active experiments. The
                           default shows all experiments.
  -n, --limit <int range>  At most N  [default: 50; x>=1]
  -h, --help               Show this message and exit.

mapi experiments create

Usage: mapi experiments create [OPTIONS] {name}

  Make an experiment.

Arguments:
  name  Name of the experiment (unique in the project)  [required]

Options:
  --description <str>  Text that tells what the runs compare
  -h, --help           Show this message and exit.

mapi experiments show

Usage: mapi experiments show [OPTIONS] {exp}

  Show one experiment.

Arguments:
  exp  Experiment id or name  [required]

Options:
  -h, --help  Show this message and exit.

mapi experiments rename

Usage: mapi experiments rename [OPTIONS] {exp} {name}

  Change the name of an experiment.

Arguments:
  exp   Experiment id or name  [required]
  name  New name  [required]

Options:
  -h, --help  Show this message and exit.

mapi experiments archive

Usage: mapi experiments archive [OPTIONS] {exp}

  Archive an experiment. An archived experiment does not accept new runs.

Arguments:
  exp  Experiment id or name  [required]

Options:
  -h, --help  Show this message and exit.

mapi experiments unarchive

Usage: mapi experiments unarchive [OPTIONS] {exp}

  Make an archived experiment active again.

Arguments:
  exp  Experiment id or name  [required]

Options:
  -h, --help  Show this message and exit.

mapi experiments rm

Usage: mapi experiments rm [OPTIONS] {exp}

  Delete an experiment. Its runs stay, without an experiment. Its saved views are deleted.

Arguments:
  exp  Experiment id or name  [required]

Options:
  -y, --yes   Do not ask for confirmation
  -h, --help  Show this message and exit.

mapi experiments add

Usage: mapi experiments add [OPTIONS] {exp} {runs}...

  Add runs to an experiment. A run moves out of its previous experiment.

Arguments:
  exp      Experiment id or name  [required]
  runs...  Run ids to add  [required]

Options:
  -h, --help  Show this message and exit.

mapi experiments remove

Usage: mapi experiments remove [OPTIONS] {exp} {runs}...

  Remove runs from an experiment. The runs stay, without an experiment.

Arguments:
  exp      Experiment id or name  [required]
  runs...  Run ids to remove  [required]

Options:
  -h, --help  Show this message and exit.

mapi datasets

Usage: mapi datasets [OPTIONS] COMMAND [ARGS]...

  Datasets on the API.

Options:
  -h, --help  Show this message and exit.

Commands:
  ls              List datasets.
  upload          Upload one or more files as a new dataset version (signed PUT + sandboxed...
  ingest          Ingest an already uploaded file as a new dataset version, e.g.
  inspect         List the groups and arrays of an upload (path, shape, dtype, dims hint)...
  upload-images   Upload a folder of images as a new image collection version.
  missing-images  Show how many images of a folder the dataset does not have yet (nothing...
  upload-weights  Upload pretrained network weights (a .safetensors file) as a new dataset...

mapi datasets ls

Usage: mapi datasets ls [OPTIONS]

  List datasets.

Options:
  -n, --limit <int range>  [default: 50; x>=1]
  -h, --help               Show this message and exit.

mapi datasets upload

Usage: mapi datasets upload [OPTIONS] {files}...

  Upload one or more files as a new dataset version (signed PUT + sandboxed ingest run).

  One FILE without --node/--concat/--merge is a plain single-file upload. Several files (or any
  of those flags) make ONE version from all of them:

    mapi datasets upload 2024.nc 2025.nc --name cubes --concat year=2024,2025
    mapi datasets upload a.nc b.nc --name obs --merge --join outer
    mapi datasets upload img.nc psf.nc --name lens --node / --node /instrument

  --node PATH: where a file goes in the tree, once (every file) or once per file in file order
  (default /). Files that share a node are combined by --concat DIM=LABEL (one label per
  combined file in file order: repeat the flag or list LABEL,LABEL,...; numeric labels are
  numbers) or by --merge (variables on shared coords); --join exact|inner|outer aligns their
  coords. --mapping is given once (every file it can read) or once per file. Raw HDF5
  (.h5/.hdf5/.he5) needs a mapping with an 'hdf5' section: see 'mapi datasets inspect'.

Arguments:
  files...  .zarr.zip, .nc, .h5/.hdf5/.he5, .csv or .parquet (several: one version)  [required]

Options:
  --name <str>                Dataset name (created when missing)  [required]
  --mapping <path>            IngestMapping YAML/JSON (required for csv/parquet/raw HDF5); once
                              or per file
  --node <str>                Tree node of the files (once) or of each file (in order)
  --concat DIM=LABEL          Stack the files sharing a node along DIM, one label per file (or
                              DIM=L1,L2)
  --merge                     Merge the variables of the files sharing a node
  --join <exact|inner|outer>  Coord alignment for --concat/--merge (default exact)
  -m, --message <str>
  --wait / --no-wait          Wait for the ingest run  [default: wait]
  --timeout <float>
  -h, --help                  Show this message and exit.

mapi datasets ingest

Usage: mapi datasets ingest [OPTIONS] {dataset} {upload_id}

  Ingest an already uploaded file as a new dataset version, e.g. a raw HDF5 file after 'mapi
  datasets inspect' showed which arrays to map.

Arguments:
  dataset    Dataset name or id  [required]
  upload_id  A staged upload (from 'mapi datasets inspect')  [required]

Options:
  --mapping <path>     IngestMapping YAML/JSON (e.g. an 'hdf5' mapping)  [required]
  -m, --message <str>
  --wait / --no-wait   Wait for the ingest run  [default: wait]
  --timeout <float>
  -h, --help           Show this message and exit.

mapi datasets inspect

Usage: mapi datasets inspect [OPTIONS] {dataset} {target}

  List the groups and arrays of an upload (path, shape, dtype, dims hint) without ingesting it -
  what a raw-HDF5 mapping needs. A local file is uploaded first; ingest it later with 'mapi
  datasets ingest DATASET UPLOAD_ID --mapping FILE'.

Arguments:
  dataset  Dataset name or id (a file is staged into it, created when missing)  [required]
  target   A local file to upload and inspect, or an upload id (upl_...)  [required]

Options:
  --timeout <float>  [default: 300.0]
  -h, --help         Show this message and exit.

mapi datasets upload-images

Usage: mapi datasets upload-images [OPTIONS] {dataset} {directory}

  Upload a folder of images as a new image collection version.

  The command calculates the sha256 of each image, asks the server which images the base version
  does not have, and uploads only those, in zip parts. With --state, an interrupted upload
  continues from where it stopped: run the same command again.

    mapi datasets upload-images pets ./pets --label-from-folder --wait
    mapi datasets upload-images scans ./scans --manifest labels.csv --label-column class

Arguments:
  dataset    Dataset name (created when missing) or id  [required]
  directory  The folder with the images  [required]

Options:
  --manifest <file>            A CSV, TSV or Parquet table with one row per image (column path:
                               the file)
  --label-from-folder          Use the first folder of each path as its label
  --id-column <str>            The manifest column with image ids
  --label-column <str>         The manifest column with labels
  --split-column <str>         The manifest column with train/test values
  --path-column <str>          The manifest column with the file paths  [default: path]
  --size HxW                   The image size for samples and models
  --resize <stretch|crop|pad>  How images get the --size  [default: stretch]
  --mode <auto|gray|rgb>       The image channels  [default: auto]
  --base-version <int range>   Compare with this version (default: the latest image collection
                               version)  [x>=1]
  --no-base                    Upload all images (do not compare with a version)
  --part-size <str>            Maximum size of one zip part (for example 256MB)
  --state <path>               A file that records the upload, to continue it later
  -m, --message <str>
  --wait                       Wait for the ingest run
  --timeout <float>
  -h, --help                   Show this message and exit.

mapi datasets missing-images

Usage: mapi datasets missing-images [OPTIONS] {dataset} {directory}

  Show how many images of a folder the dataset does not have yet (nothing is uploaded).

Arguments:
  dataset    Dataset name or id  [required]
  directory  The folder with the images  [required]

Options:
  --manifest <file>           A CSV, TSV or Parquet table with one row per image (column path:
                              the file)
  --path-column <str>         The manifest column with the file paths  [default: path]
  --base-version <int range>  Compare with this version (default: the latest image collection
                              version)  [x>=1]
  --no-base                   Upload all images (do not compare with a version)
  -h, --help                  Show this message and exit.

mapi datasets upload-weights

Usage: mapi datasets upload-weights [OPTIONS] {dataset} {file}

  Upload pretrained network weights (a .safetensors file) as a new dataset version. A model
  reads the version as a side table.

Arguments:
  dataset  Dataset name (created when missing) or id  [required]
  file     A .safetensors file of network weights  [required]

Options:
  --arch <file>        A JSON file with the network architecture (when the file does not have
                       it)
  -m, --message <str>
  --wait / --no-wait   Wait for the ingest run  [default: wait]
  --timeout <float>
  -h, --help           Show this message and exit.

mapi plugin

Usage: mapi plugin [OPTIONS] COMMAND [ARGS]...

  Plugin authoring: scaffold and test model plugins.

Options:
  -h, --help  Show this message and exit.

Commands:
  init  Scaffold a plugin package (model, entry point and contract-kit tests).
  test  Run the plugin's tests (contract kit) with this interpreter; extra args go to pytest.

mapi plugin init

Usage: mapi plugin init [OPTIONS] {name}

  Scaffold a plugin package (model, entry point and contract-kit tests).

Arguments:
  name  Distribution name, e.g. acme-demand  [required]

Options:
  --dir <path>       Parent directory (default: current)  [default: .]
  --namespace <str>  Plugin id namespace (default: module)
  --force            Write into a non-empty dir
  -h, --help         Show this message and exit.

mapi plugin test

Usage: mapi plugin test [OPTIONS] [path]

  Run the plugin's tests (contract kit) with this interpreter; extra args go to pytest.

Arguments:
  path  Plugin package directory  [default: .]

Options:
  --contract-only  Only tests marked mapi_contract
  -h, --help       Show this message and exit.

mapi spec

Usage: mapi spec [OPTIONS] COMMAND [ARGS]...

  Spec document tools.

Options:
  -h, --help  Show this message and exit.

Commands:
  upgrade  Upgrade a document through the registered converters (N-1 → N).

mapi spec upgrade

Usage: mapi spec upgrade [OPTIONS] {spec_file}

  Upgrade a document through the registered converters (N-1 → N).

  The result is re-validated as a typed document. Comments are not preserved when the document
  changes (it is re-serialised as canonical YAML).

Arguments:
  spec_file  Spec YAML/JSON  [required]

Options:
  --to <str>           Target apiVersion  [default: mapi/v1]
  -o, --output <path>  Write here (default: stdout)
  --in-place           Rewrite the file
  --check              Only report whether an upgrade is needed (exit 1)
  -h, --help           Show this message and exit.

mapi config

Usage: mapi config [OPTIONS] COMMAND [ARGS]...

  Client configuration (~/.config/mapi/config.toml).

Options:
  -h, --help  Show this message and exit.

Commands:
  show   Resolved settings and where each came from (secrets are never shown).
  path   Print the config file location.
  set    Set a key of the profile (--profile, MAPI_PROFILE, else the default profile).
  unset  Remove a key from the profile (``token`` too: prefer ``mapi logout``).

mapi config show

Usage: mapi config show [OPTIONS]

  Resolved settings and where each came from (secrets are never shown).

Options:
  -h, --help  Show this message and exit.

mapi config path

Usage: mapi config path [OPTIONS]

  Print the config file location.

Options:
  -h, --help  Show this message and exit.

mapi config set

Usage: mapi config set [OPTIONS] {key} {value}

  Set a key of the profile (--profile, MAPI_PROFILE, else the default profile).

Arguments:
  key    One of: max_retries, oidc_client_id, oidc_discovery_url, oidc_issuer, project, timeout,
         url, verify  [required]
  value  [required]

Options:
  -h, --help  Show this message and exit.

mapi config unset

Usage: mapi config unset [OPTIONS] {key}

  Remove a key from the profile (``token`` too: prefer ``mapi logout``).

Arguments:
  key  A key to remove from the profile  [required]

Options:
  -h, --help  Show this message and exit.

mapi tokens

Usage: mapi tokens [OPTIONS] COMMAND [ARGS]...

  API tokens of the selected project (secrets are shown once, at creation).

Options:
  -h, --help  Show this message and exit.

Commands:
  ls      List tokens (yours, or everyone's with --all).
  get     Show one token (never its secret).
  create  Mint a token in the selected project.
  revoke  Revoke a token: programs using it stop working at once.

mapi tokens ls

Usage: mapi tokens ls [OPTIONS]

  List tokens (yours, or everyone's with --all).

Options:
  --all                           Everyone's tokens in the project (project admins)
  --status <active|expired|revoked>
                                  active, expired or revoked
  -n, --limit <int range>         [default: 50; x>=1]
  -h, --help                      Show this message and exit.

mapi tokens get

Usage: mapi tokens get [OPTIONS] {token_id}

  Show one token (never its secret).

Arguments:
  token_id  tok_… id  [required]

Options:
  -h, --help  Show this message and exit.

mapi tokens create

Usage: mapi tokens create [OPTIONS] {name}

  Mint a token in the selected project. Its secret is shown once.

Arguments:
  name  A name to recognise the token by  [required]

Options:
  -s, --scope <str>              models:read, runs:create, score:<endpoint alias> or
                                 score:<model id> (score:* for every endpoint and model),
                                 datasets:write, endpoints:promote, webhooks:manage,
                                 plugins:publish, admin (repeatable)  [required]
  --expires-in-days <int range>  Lifetime  [default: 90; 1<=x<=365]
  --rate-limit <int range>       Requests per minute  [x>=1]
  --budget <float range>         vCPU-seconds per period  [x>=0.001]
  --budget-period <day|month>    day or month  [default: month]
  --save                         Store the token in the profile instead of printing it
  -h, --help                     Show this message and exit.

mapi tokens revoke

Usage: mapi tokens revoke [OPTIONS] {token_id}

  Revoke a token: programs using it stop working at once.

Arguments:
  token_id  tok_… id  [required]

Options:
  -y, --yes   Do not ask for confirmation
  -h, --help  Show this message and exit.

mapi admin

Usage: mapi admin [OPTIONS] COMMAND [ARGS]...

  Platform operator commands: tenants, quotas, kill switches, executors, audit.

Options:
  -h, --help  Show this message and exit.

Commands:
  audit          The platform audit log, newest first (times in UTC).
  tenants        All tenants (create, change tier/status/residency).
  quotas         Quota policies per token, tenant or the platform.
  kill-switches  Platform-wide emergency controls (audited).
  executors      Executor health, capacity and conformance.

mapi admin audit

Usage: mapi admin audit [OPTIONS]

  The platform audit log, newest first (times in UTC).

Options:
  --tenant <str>
  --project-id <str>
  --actor <str>
  --action <auth.login|auth.login_failed|auth.logout|tenant.create|tenant.update|tenant.suspend|tenant.reactivate|tenant.delete|project.create|project.update|project.delete|member.add|member.update|member.remove|token.create|token.revoke|token.auth_failed|quota.update|quota.delete|quota.denied|kill_switch.update|executor.evidence_update|executor.update|run.create|run.cancel|run.integrity_failure|dataset.download|model.artifact_link|endpoint.promote|plugin.publish|plugin.yank|event.rejected|auth.signup|auth.signup_rejected|auth.email_verified|auth.signup_flagged|auth.signup_review|tenant.verification_update|tenant.deletion_request|tenant.deletion_cancel|tenant.deletion_retry|tenant.purged|tenant.export|project.guided_lock|endpoint.create|endpoint.promote_override|endpoint.rollback|endpoint.delete|webhook.create|webhook.update|webhook.delete|webhook.secret_rotate|webhook.replay|webhook.disabled|webhook.url_blocked|plot.embed_create|plot.embed_revoke|workflow.create|workflow.revision|workflow.update|workflow.delete|workflow.run|workflow.run_cancel|workflow.schedule_create|workflow.schedule_update|workflow.schedule_delete|workflow.trigger_create|workflow.trigger_delete|policy.create|policy.update|policy.delete|model.validation_request|model.validation_transition|model.approve|model.reject|model.deprecate|model.evidence_export|endpoint.promote_not_validated|dataset.about_update|run.update|run.log|experiment.create|experiment.update|experiment.delete|run_view.save|run_view.delete>
  --outcome <success|denied|error>
  --since <%Y-%m-%d|%Y-%m-%dT%H:%M:%S>
  --until <%Y-%m-%d|%Y-%m-%dT%H:%M:%S>
  -n, --limit <int range>         At most N rows  [default: 50; x>=1]
  -h, --help                      Show this message and exit.

mapi admin tenants

Usage: mapi admin tenants [OPTIONS] COMMAND [ARGS]...

  All tenants (create, change tier/status/residency).

Options:
  -h, --help  Show this message and exit.

Commands:
  ls      List all tenants.
  get     Show one tenant.
  create  Create a tenant.
  update  Change a tenant's name, trust tier, status or data residency.

mapi admin tenants ls

Usage: mapi admin tenants ls [OPTIONS]

  List all tenants.

Options:
  --status <active|suspended|deleting>
  --tier <internal|verified|public|self-hosted-trusted>
  -n, --limit <int range>         At most N rows  [default: 100; x>=1]
  -h, --help                      Show this message and exit.

mapi admin tenants get

Usage: mapi admin tenants get [OPTIONS] {tenant_id}

  Show one tenant.

Arguments:
  tenant_id  [required]

Options:
  -h, --help  Show this message and exit.

mapi admin tenants create

Usage: mapi admin tenants create [OPTIONS] {tenant_id}

  Create a tenant.

Arguments:
  tenant_id  A lowercase slug, e.g. acme  [required]

Options:
  --name <str>                    Display name  [required]
  --tier <internal|verified|public|self-hosted-trusted>
                                  [default: verified]
  --residency <str>               eu, us, asia or a region  [default: us]
  --admin-email <str>             Invite this address as tenant admin
  -y, --yes                       Do not ask for confirmation
  -h, --help                      Show this message and exit.

mapi admin tenants update

Usage: mapi admin tenants update [OPTIONS] {tenant_id}

  Change a tenant's name, trust tier, status or data residency.

Arguments:
  tenant_id  [required]

Options:
  --name <str>
  --tier <internal|verified|public|self-hosted-trusted>
  --status <active|suspended|deleting>
                                  suspended: read-only; deleting: no access
  --reason <str>                  Required to suspend or delete
  --residency <str>               Applies to new runs only
  -y, --yes                       Do not ask for confirmation
  -h, --help                      Show this message and exit.

mapi admin quotas

Usage: mapi admin quotas [OPTIONS] COMMAND [ARGS]...

  Quota policies per token, tenant or the platform.

Options:
  -h, --help  Show this message and exit.

Commands:
  ls   List quota policies.
  set  Create or REPLACE the policy of (scope, subject): limits left out are removed.
  rm   Remove a policy (the tier default applies again).

mapi admin quotas ls

Usage: mapi admin quotas ls [OPTIONS]

  List quota policies.

Options:
  --scope <token|tenant|global>
  --subject <str>                Token id or tenant id
  -n, --limit <int range>        At most N rows  [default: 100; x>=1]
  -h, --help                     Show this message and exit.

mapi admin quotas set

Usage: mapi admin quotas set [OPTIONS] {scope}:<token|tenant|global> {subject}

  Create or REPLACE the policy of (scope, subject): limits left out are removed.

Arguments:
  scope:<token|tenant|global>  token, tenant or global  [required]
  subject                      Token id, tenant id, or * for global  [required]

Options:
  --vcpu-seconds-per-day <float range>
                                  [x>=0]
  --vcpu-seconds-per-month <float range>
                                  [x>=0]
  --concurrent-runs <int range>   [x>=0]
  --max-fanout-tasks <int range>  [x>=1]
  --storage <str>                 e.g. 100GiB
  --egress-per-month <str>        e.g. 5GiB
  --requests-per-minute <int range>
                                  [x>=1]
  --max-resource-class <S|M|L|XL|GPU>
  --note <str>                    Why (shown in listings)
  -y, --yes                       Do not ask for confirmation
  -h, --help                      Show this message and exit.

mapi admin quotas rm

Usage: mapi admin quotas rm [OPTIONS] {scope}:<token|tenant|global> {subject}

  Remove a policy (the tier default applies again).

Arguments:
  scope:<token|tenant|global>  [required]
  subject                      [required]

Options:
  -y, --yes   Do not ask for confirmation
  -h, --help  Show this message and exit.

mapi admin kill-switches

Usage: mapi admin kill-switches [OPTIONS] COMMAND [ARGS]...

  Platform-wide emergency controls (audited).

Options:
  -h, --help  Show this message and exit.

Commands:
  get  Show the kill switches.
  set  Flip kill switches (confirmation shows the change; the server audits it).

mapi admin kill-switches get

Usage: mapi admin kill-switches get [OPTIONS]

  Show the kill switches.

Options:
  -h, --help  Show this message and exit.

mapi admin kill-switches set

Usage: mapi admin kill-switches set [OPTIONS]

  Flip kill switches (confirmation shows the change; the server audits it).

Options:
  --reason <str>             Why (audited); required  [required]
  --untrusted-code <on|off>  off: pause every run of uploaded plugin code
  --spend-cap <str>          Stop new compute past this platform spend (e.g. 500)
  --clear-spend-cap          Remove the spend cap
  --spend-cap-period <str>   day or month
  --cancel-untrusted-runs    With --untrusted-code off: also cancel every unfinished run of
                             uploaded code (in-flight ones included); without it they keep
                             running
  -y, --yes                  Do not ask for confirmation
  -h, --help                 Show this message and exit.

mapi admin executors

Usage: mapi admin executors [OPTIONS] COMMAND [ARGS]...

  Executor health, capacity and conformance.

Options:
  -h, --help  Show this message and exit.

Commands:
  ls       Executor health, load and conformance.
  get      One executor.
  disable  Disable an executor: no new run is placed on it (incident containment).
  enable   Enable an executor again.

mapi admin executors ls

Usage: mapi admin executors ls [OPTIONS]

  Executor health, load and conformance.

Options:
  -h, --help  Show this message and exit.

mapi admin executors get

Usage: mapi admin executors get [OPTIONS] {name}

  One executor.

Arguments:
  name  [required]

Options:
  -h, --help  Show this message and exit.

mapi admin executors disable

Usage: mapi admin executors disable [OPTIONS] {name}

  Disable an executor: no new run is placed on it (incident containment).

Arguments:
  name  [required]

Options:
  --reason <str>  Why (audited); required  [required]
  -y, --yes       Do not ask for confirmation
  -h, --help      Show this message and exit.

mapi admin executors enable

Usage: mapi admin executors enable [OPTIONS] {name}

  Enable an executor again.

Arguments:
  name  [required]

Options:
  --reason <str>  Why (audited); required  [required]
  -y, --yes       Do not ask for confirmation
  -h, --help      Show this message and exit.

mapi endpoints

Usage: mapi endpoints [OPTIONS] COMMAND [ARGS]...

  Endpoints: stable aliases for promoted model versions (promote, score, snippets).

Options:
  -h, --help  Show this message and exit.

Commands:
  ls        List the project's endpoints.
  get       Show an endpoint, the version it serves and its promotion gate.
  history   Promotions and rollbacks, newest first.
  promote   Point an alias at a model version, through the scorecard promotion gate.
  rollback  Point the alias back at an earlier revision's version.
  schema    What to send: the input schema frozen at promotion and an example payload.
  score     Score the endpoint's current version and wait for the result.
  forecast  Forecast with your latest actuals and the dates to forecast (no refit).
  snippets  Ready-to-run code that scores the endpoint (reads the token from MAPI_TOKEN).

mapi endpoints ls

Usage: mapi endpoints ls [OPTIONS]

  List the project's endpoints.

Options:
  -n, --limit <int range>  [default: 50; x>=1]
  -h, --help               Show this message and exit.

mapi endpoints get

Usage: mapi endpoints get [OPTIONS] {alias}

  Show an endpoint, the version it serves and its promotion gate.

Arguments:
  alias  Endpoint alias  [required]

Options:
  -h, --help  Show this message and exit.

mapi endpoints history

Usage: mapi endpoints history [OPTIONS] {alias}

  Promotions and rollbacks, newest first.

Arguments:
  alias  Endpoint alias  [required]

Options:
  -n, --limit <int range>  [default: 20; x>=1]
  -h, --help               Show this message and exit.

mapi endpoints promote

Usage: mapi endpoints promote [OPTIONS] {alias} [model]

  Point an alias at a model version, through the scorecard promotion gate.

Arguments:
  alias  Endpoint alias (created when new)  [required]
  model  model://project/name@vN (or --version-id)

Options:
  --version-id <str>              Model version id (mv_…) instead
  --override                      Override a 'needs_override' gate (signed-in project admins)
  --reason <str>                  Why (required with --override; audited)
  --expected-revision <int range>
                                  Fail if the alias moved (0: new)  [x>=0]
  --description <str>
  -y, --yes                       Do not ask for confirmation
  -h, --help                      Show this message and exit.

mapi endpoints rollback

Usage: mapi endpoints rollback [OPTIONS] {alias}

  Point the alias back at an earlier revision's version.

Arguments:
  alias  Endpoint alias  [required]

Options:
  --reason <str>             Why (audited)  [required]
  --to-revision <int range>  Default: the previous revision  [x>=1]
  -y, --yes                  Do not ask for confirmation
  -h, --help                 Show this message and exit.

mapi endpoints schema

Usage: mapi endpoints schema [OPTIONS] {alias}

  What to send: the input schema frozen at promotion and an example payload.

Arguments:
  alias  Endpoint alias  [required]

Options:
  --example   Print only the example payload (JSON)
  -h, --help  Show this message and exit.

mapi endpoints score

Usage: mapi endpoints score [OPTIONS] {alias} [payload]

  Score the endpoint's current version and wait for the result.

Arguments:
  alias    Endpoint alias  [required]
  payload  EndpointScoreCall JSON file ('-' = stdin)

Options:
  --example              Send the endpoint's example payload
  --mode <str>           predict, forecast, …
  --periods <int range>  Forecast horizon (periods)  [x>=1]
  --horizon-dim <str>    [default: time]
  --data <str>           dataset:// ref, XrJSON .json, .zarr.zip or .nc file
  --scenario <str>       Like --data
  --draws <int range>    Draws to return  [x>=0]
  -o, --out <path>       Write the result DataTree (.zarr.zip)
  --wait <int range>     Prefer: wait=N  [default: 60; 0<=x<=60]
  --timeout <float>      Give up after N seconds
  -h, --help             Show this message and exit.

mapi endpoints forecast

Usage: mapi endpoints forecast [OPTIONS] {alias} [table]

  Forecast with your latest actuals and the dates to forecast (no refit).

  The table has the columns of `mapi endpoints schema ALIAS` (Input table): the time column, the
  target and any drivers. Rows with the target filled are actuals: the model updates its state
  with them using its fitted parameters and forecasts from the last one. Rows after them with
  the target empty are forecast; without such rows, --periods (default 8) are appended. The
  answer says what the forecast was conditioned on.

Arguments:
  alias  Endpoint alias  [required]
  table  CSV (header row) or JSON rows in the endpoint's input layout: actuals with the target
         filled, dates to forecast with it empty ('-' = stdin)

Options:
  --actuals <path>           Rows with the target filled (CSV/JSON)
  --future <str>             A date to forecast (repeatable), or a CSV/JSON file of future rows
                             with their driver values
  --periods <int range>      Periods to append after the last actual  [x>=1]
  --future-covariates <str>  Empty future drivers: carry_last, seasonal_naive, zero or supplied
                             [default: carry_last]
  --wait <int range>         Prefer: wait=N  [default: 60; 0<=x<=60]
  --timeout <float>          Give up after N seconds
  --dry-run                  Print the call body (JSON) and send nothing
  -h, --help                 Show this message and exit.

mapi endpoints snippets

Usage: mapi endpoints snippets [OPTIONS] {alias}

  Ready-to-run code that scores the endpoint (reads the token from MAPI_TOKEN).

  With one --language only the code is printed, so it can be redirected to a file.

Arguments:
  alias  Endpoint alias  [required]

Options:
  -l, --language <python|typescript|curl|r|apps_script|notebook>
                                  python, typescript, curl, r, apps_script, notebook
  --base-url <str>                API URL to embed (default: the server's)
  -h, --help                      Show this message and exit.

mapi webhooks

Usage: mapi webhooks [OPTIONS] COMMAND [ARGS]...

  Webhooks of the selected project (secrets are shown once, at creation).

Options:
  -h, --help  Show this message and exit.

Commands:
  ls          List webhooks (never their secrets).
  get         Show one webhook (never its secret).
  create      Add a webhook.
  update      Change a webhook: switch it back on after it was paused or disabled...
  rotate      New signing secret (printed once); the current one keeps signing for 24 hours.
  deliveries  The delivery log, newest first.
  replay      Send a delivery's event again (a new delivery).
  rm          Delete a webhook and its delivery log.

mapi webhooks ls

Usage: mapi webhooks ls [OPTIONS]

  List webhooks (never their secrets).

Options:
  -n, --limit <int range>  [default: 50; x>=1]
  -h, --help               Show this message and exit.

mapi webhooks get

Usage: mapi webhooks get [OPTIONS] {webhook_id}

  Show one webhook (never its secret).

Arguments:
  webhook_id  whk_… id  [required]

Options:
  -h, --help  Show this message and exit.

mapi webhooks create

Usage: mapi webhooks create [OPTIONS] {url}

  Add a webhook. Its signing secret is printed once.

Arguments:
  url  https:// URL that receives the deliveries  [required]

Options:
  -e, --event <run.succeeded|run.failed|model.version.ready|endpoint.promoted|score.completed|tenant.deletion.completed|workflow.run.succeeded|workflow.run.failed|model.validation.checks_passed|model.validation.checks_failed|model.validation.awaiting_approval|model.validated|model.rejected|model.deprecated|dataset.version.created|optimize.completed>
                                  Event to subscribe to (repeatable)  [required]
  --description <str>
  --inactive                      Create it paused (no deliveries yet)
  -h, --help                      Show this message and exit.

mapi webhooks update

Usage: mapi webhooks update [OPTIONS] {webhook_id}

  Change a webhook: switch it back on after it was paused or disabled automatically, or change
  its events, URL or description. The secret is unchanged.

Arguments:
  webhook_id  whk_… id  [required]

Options:
  --enable / --disable            Switch deliveries on (resets the failure count) or pause them
  -e, --event <run.succeeded|run.failed|model.version.ready|endpoint.promoted|score.completed|tenant.deletion.completed|workflow.run.succeeded|workflow.run.failed|model.validation.checks_passed|model.validation.checks_failed|model.validation.awaiting_approval|model.validated|model.rejected|model.deprecated|dataset.version.created|optimize.completed>
                                  Replace the subscribed events (repeatable)
  --url <str>                     New https:// receiver URL
  --description <str>
  -h, --help                      Show this message and exit.

mapi webhooks rotate

Usage: mapi webhooks rotate [OPTIONS] {webhook_id}

  New signing secret (printed once); the current one keeps signing for 24 hours.

Arguments:
  webhook_id  whk_… id  [required]

Options:
  -y, --yes   Do not ask for confirmation
  -h, --help  Show this message and exit.

mapi webhooks deliveries

Usage: mapi webhooks deliveries [OPTIONS] {webhook_id}

  The delivery log, newest first.

Arguments:
  webhook_id  whk_… id  [required]

Options:
  --status <pending|succeeded|retrying|failed|blocked>
                                  Only deliveries in this state
  -n, --limit <int range>         [default: 20; x>=1]
  -h, --help                      Show this message and exit.

mapi webhooks replay

Usage: mapi webhooks replay [OPTIONS] {webhook_id} {delivery_id}

  Send a delivery's event again (a new delivery).

Arguments:
  webhook_id   whk_… id  [required]
  delivery_id  whd_… id  [required]

Options:
  -h, --help  Show this message and exit.

mapi webhooks rm

Usage: mapi webhooks rm [OPTIONS] {webhook_id}

  Delete a webhook and its delivery log.

Arguments:
  webhook_id  whk_… id  [required]

Options:
  -y, --yes   Do not ask for confirmation
  -h, --help  Show this message and exit.

mapi plots

Usage: mapi plots [OPTIONS] COMMAND [ARGS]...

  Render plots to files and share them as embed links.

Options:
  -h, --help  Show this message and exit.

Commands:
  render  Render one plot to a PNG, SVG or PDF file.
  embed   Create a read-only embed link for a saved plot.
  embeds  List a saved plot's embed links (redacted).
  revoke  Revoke an embed link: dashboards showing it stop at once.

mapi plots render

Usage: mapi plots render [OPTIONS]

  Render one plot to a PNG, SVG or PDF file.

Options:
  --saved <str>          A saved plot (plt_…)
  --model <str>          Model id (mdl_…)
  --version <int range>  [x>=1]
  --plot <str>           Plot id of the model version
  --spec <file>          A PlotSpec JSON file
  -f, --format <str>     png, svg or pdf  [default: png]
  --scale <float range>  [default: 2.0; 0.1<=x<=8.0]
  --width <int range>    [16<=x<=4096]
  --height <int range>   [16<=x<=4096]
  -o, --out <path>       Where to write (default: <plot>.<fmt>)
  --wait <int range>     Prefer: wait=N  [default: 60; 0<=x<=60]
  --timeout <float>      Give up after N seconds  [default: 300.0]
  -h, --help             Show this message and exit.

mapi plots embed

Usage: mapi plots embed [OPTIONS] {plot_id}

  Create a read-only embed link for a saved plot. Its URL is printed once.

Arguments:
  plot_id  Saved plot id (plt_…)  [required]

Options:
  --expires-in-days <int range>  [default: 30; 1<=x<=365]
  --label <str>                  To recognise the link by
  --allow-origin <str>           Site that may frame the link (repeatable)
  -h, --help                     Show this message and exit.

mapi plots embeds

Usage: mapi plots embeds [OPTIONS] {plot_id}

  List a saved plot's embed links (redacted).

Arguments:
  plot_id  Saved plot id (plt_…)  [required]

Options:
  -n, --limit <int range>  [default: 50; x>=1]
  -h, --help               Show this message and exit.

mapi plots revoke

Usage: mapi plots revoke [OPTIONS] {plot_id} {embed_id}

  Revoke an embed link: dashboards showing it stop at once.

Arguments:
  plot_id   Saved plot id (plt_…)  [required]
  embed_id  Embed id (emb_…)  [required]

Options:
  -y, --yes   Do not ask for confirmation
  -h, --help  Show this message and exit.

mapi guided

Usage: mapi guided [OPTIONS] COMMAND [ARGS]...

  Guided mode: templates, column detection and drafts (stores nothing).

Options:
  -h, --help  Show this message and exit.

Commands:
  templates  List the guided templates, or one template's questions.
  detect     Suggest which column answers each question of a template.
  draft      Answers -> the ingest mapping and the ModelSpec YAML (nothing is stored).

mapi guided templates

Usage: mapi guided templates [OPTIONS] [template_id]

  List the guided templates, or one template's questions.

Arguments:
  template_id  Show one template's questions

Options:
  -h, --help  Show this message and exit.

mapi guided detect

Usage: mapi guided detect [OPTIONS] {template_id}

  Suggest which column answers each question of a template.

Arguments:
  template_id  Template id (geo_mmm, …)  [required]

Options:
  --csv <file>      Profile this CSV locally
  --dataset <str>   A stored version: dataset://project/name@vN
  --columns <file>  Column profiles (JSON list)
  -h, --help        Show this message and exit.

mapi guided draft

Usage: mapi guided draft [OPTIONS] {template_id}

  Answers -> the ingest mapping and the ModelSpec YAML (nothing is stored).

Arguments:
  template_id  Template id (geo_mmm, …)  [required]

Options:
  --name <str>          Name of the spec (and model)  [required]
  --dataset <str>       Name the upload's dataset gets  [required]
  -a, --answer <str>    QUESTION=VALUE (repeatable; lists: a,b,c)
  --answers <file>      Answers as a JSON object
  --csv <file>          Profile this CSV locally
  --detect              Pre-fill answers from detection (needs --csv)
  --format <str>        csv, parquet or mff  [default: csv]
  --yaml-out <path>     Write the spec YAML here
  --mapping-out <path>  Write the ingest mapping JSON here
  -h, --help            Show this message and exit.

mapi priors

Usage: mapi priors [OPTIONS] COMMAND [ARGS]...

  Business priors: translate beliefs into model priors.

Options:
  -h, --help  Show this message and exit.

Commands:
  preview  Translate beliefs into priors in the sandbox and preview them.

mapi priors preview

Usage: mapi priors preview [OPTIONS]

  Translate beliefs into priors in the sandbox and preview them.

Options:
  --beliefs <file>        BusinessPriors (YAML/JSON)  [required]
  --spec <str>            Saved spec id (spc_…)
  --revision <int range>  [x>=1]
  --document <file>       An unsaved spec (YAML)
  --lift-tests <file>     A list of lift tests (YAML/JSON)
  --dataset <str>         Override the spec's data.dataset
  --draws <int range>     [default: 500; 50<=x<=2000]
  --seed <int range>      [x>=0]
  -o, --out <path>        Write the translation (JSON) here
  --timeout <float>       Give up after N s  [default: 600.0]
  -h, --help              Show this message and exit.

mapi tenant

Usage: mapi tenant [OPTIONS] COMMAND [ARGS]...

  Your workspace (tenant): verification status, GDPR export and deletion.

Options:
  -h, --help  Show this message and exit.

Commands:
  status  Verification (e-mail, identity, code upload) and any deletion of the tenant.
  export  GDPR export: everything the tenant stored, as one zip archive.
  delete  Schedule deletion of the whole tenant (cancellable during the grace period).

mapi tenant status

Usage: mapi tenant status [OPTIONS]

  Verification (e-mail, identity, code upload) and any deletion of the tenant.

Options:
  -t, --tenant <str>  Tenant id (default: the selected project's tenant)
  -h, --help          Show this message and exit.

mapi tenant export

Usage: mapi tenant export [OPTIONS]

  GDPR export: everything the tenant stored, as one zip archive.

Options:
  -t, --tenant <str>  Tenant id (default: the selected project's tenant)
  --include <str>     metadata, datasets, models, audit, usage (repeatable)
  -o, --out <path>    Archive path (default: <tenant>-export.zip)
  --no-wait           Start the export and print its id only
  --id <str>          Download an export started earlier (exp_…)
  --timeout <float>   Give up after N s  [default: 3600]
  -h, --help          Show this message and exit.

mapi tenant delete

Usage: mapi tenant delete [OPTIONS]

  Schedule deletion of the whole tenant (cancellable during the grace period).

Options:
  -t, --tenant <str>  Tenant id (default: the selected project's tenant)
  --reason <str>      Why (kept with the record)
  --confirm <str>     The tenant id, to delete without the prompt (scripts)
  --cancel            Cancel a scheduled deletion instead
  -h, --help          Show this message and exit.

mapi workflows

Usage: mapi workflows [OPTIONS] COMMAND [ARGS]...

  Workflows: validate, save, run and watch DAGs of tests, transforms and models.

Options:
  -h, --help  Show this message and exit.

Commands:
  validate       Check a workflow file on the server (nothing is saved): unknown nodes,...
  apply          Create the workflow named in the file, or save the file as its next...
  create         Create a workflow from a file or a gallery template (revision 1).
  ls             List the project's workflows.
  get            Show a workflow (and with --yaml its document at the latest or a given...
  revisions      Revisions, newest first, and whether each can run.
  archive        Archive a workflow (it can no longer run) or bring it back with --undo.
  rm             Delete a workflow with its runs, schedules and triggers.
  templates      The gallery of ready-made workflows, each in plain words.
  template       One template's About card and its nodes.
  init           Write a gallery template as a YAML file to edit, validate and apply.
  run            Start a run (inputs are pinned to exact versions when it starts).
  watch          Follow a run live: every node's status, branch decisions, then the summary...
  status         A run's status, nodes, decisions and outputs.
  runs           Runs of a workflow, newest first.
  nodes          The nodes of a run with what each found.
  node           One node in full: resolved parameters, result, outputs and child runs.
  output         Download a node output's file (a derived dataset, a fitted bundle), verified.
  cancel         Cancel a run and its running children.
  nodes-catalog  The node implementations a workflow can use, in plain words.
  schedules      Cron schedules of a workflow.
  triggers       Run a workflow when a dataset gets a new version.

mapi workflows validate

Usage: mapi workflows validate [OPTIONS] {file}

  Check a workflow file on the server (nothing is saved): unknown nodes, parameters, ports,
  conditions and cycles, each with a JSON pointer.

Arguments:
  file  Workflow YAML or JSON  [required]

Options:
  -h, --help  Show this message and exit.

mapi workflows apply

Usage: mapi workflows apply [OPTIONS] {file}

  Create the workflow named in the file, or save the file as its next revision (an unchanged
  file adds nothing).

Arguments:
  file  Workflow YAML or JSON  [required]

Options:
  -m, --message <str>
  -h, --help           Show this message and exit.

mapi workflows create

Usage: mapi workflows create [OPTIONS] [file]

  Create a workflow from a file or a gallery template (revision 1).

Arguments:
  file  Workflow YAML or JSON

Options:
  -t, --template <str>  Copy a gallery template instead
  -m, --message <str>
  -h, --help            Show this message and exit.

mapi workflows ls

Usage: mapi workflows ls [OPTIONS]

  List the project's workflows.

Options:
  --archived               Archived workflows
  -n, --limit <int range>  [default: 50; x>=1]
  -h, --help               Show this message and exit.

mapi workflows get

Usage: mapi workflows get [OPTIONS] {workflow}

  Show a workflow (and with --yaml its document at the latest or a given revision).

Arguments:
  workflow  Workflow name or id  [required]

Options:
  -r, --revision <int range>  [x>=1]
  --yaml                      Print the document as YAML
  -h, --help                  Show this message and exit.

mapi workflows revisions

Usage: mapi workflows revisions [OPTIONS] {workflow}

  Revisions, newest first, and whether each can run.

Arguments:
  workflow  Workflow name or id  [required]

Options:
  -n, --limit <int range>  [default: 20; x>=1]
  -h, --help               Show this message and exit.

mapi workflows archive

Usage: mapi workflows archive [OPTIONS] {workflow}

  Archive a workflow (it can no longer run) or bring it back with --undo.

Arguments:
  workflow  Workflow name or id  [required]

Options:
  --undo      Unarchive
  -h, --help  Show this message and exit.

mapi workflows rm

Usage: mapi workflows rm [OPTIONS] {workflow}

  Delete a workflow with its runs, schedules and triggers.

Arguments:
  workflow  Workflow name or id  [required]

Options:
  -y, --yes   Do not ask
  -h, --help  Show this message and exit.

mapi workflows templates

Usage: mapi workflows templates [OPTIONS]

  The gallery of ready-made workflows, each in plain words.

Options:
  -h, --help  Show this message and exit.

mapi workflows template

Usage: mapi workflows template [OPTIONS] {template_id}

  One template's About card and its nodes.

Arguments:
  template_id  Gallery template id  [required]

Options:
  --expert    Show the maths and references
  -h, --help  Show this message and exit.

mapi workflows init

Usage: mapi workflows init [OPTIONS] {template_id}

  Write a gallery template as a YAML file to edit, validate and apply.

Arguments:
  template_id  Gallery template id  [required]

Options:
  --name <str>      metadata.name (default: the template id)
  --into <str>      metadata.project (default: the selected project)
  -o, --out <path>  File to write (default: <name>.yaml)
  --offline         Use the templates bundled with the CLI
  --force           Overwrite the file
  -h, --help        Show this message and exit.

mapi workflows run

Usage: mapi workflows run [OPTIONS] {workflow}

  Start a run (inputs are pinned to exact versions when it starts).

Arguments:
  workflow  Workflow name or id  [required]

Options:
  -i, --input <str>               name=dataset://project/name@version (repeat)
  -p, --param <str>               name=value, JSON values allowed (repeat)
  -r, --revision <int range>      [x>=1]
  --no-cache                      Recompute every node
  --resource-class <S|M|L|XL|GPU>
                                  S, M, L, XL or GPU (one NVIDIA L4 GPU)
  --experiment <str>              Put the workflow run and its node runs in this experiment (an
                                  id or a name)
  -w, --watch                     Show node status live until the run ends
  -h, --help                      Show this message and exit.

mapi workflows watch

Usage: mapi workflows watch [OPTIONS] {run_id}

  Follow a run live: every node's status, branch decisions, then the summary (--json: one JSON
  event per line).

Arguments:
  run_id  Workflow run id  [required]

Options:
  --from <int>  Resume after this event
  -h, --help    Show this message and exit.

mapi workflows status

Usage: mapi workflows status [OPTIONS] {run_id}

  A run's status, nodes, decisions and outputs.

Arguments:
  run_id  Workflow run id  [required]

Options:
  -h, --help  Show this message and exit.

mapi workflows runs

Usage: mapi workflows runs [OPTIONS] {workflow}

  Runs of a workflow, newest first.

Arguments:
  workflow  Workflow name or id  [required]

Options:
  --status <queued|running|succeeded|failed|cancelling|cancelled>
  -n, --limit <int range>         [default: 20; x>=1]
  -h, --help                      Show this message and exit.

mapi workflows nodes

Usage: mapi workflows nodes [OPTIONS] {run_id}

  The nodes of a run with what each found.

Arguments:
  run_id  Workflow run id  [required]

Options:
  --status <pending|queued|running|succeeded|cached|skipped|failed|cancelled>
  -h, --help                      Show this message and exit.

mapi workflows node

Usage: mapi workflows node [OPTIONS] {run_id} {node_id}

  One node in full: resolved parameters, result, outputs and child runs.

Arguments:
  run_id   Workflow run id  [required]
  node_id  Node id  [required]

Options:
  -h, --help  Show this message and exit.

mapi workflows output

Usage: mapi workflows output [OPTIONS] {run_id} {node_id} {port}

  Download a node output's file (a derived dataset, a fitted bundle), verified.

Arguments:
  run_id   Workflow run id  [required]
  node_id  Node id  [required]
  port     Output port, e.g. data or model  [required]

Options:
  -o, --out <path>  Where to write the file  [required]
  -h, --help        Show this message and exit.

mapi workflows cancel

Usage: mapi workflows cancel [OPTIONS] {run_id}

  Cancel a run and its running children.

Arguments:
  run_id  Workflow run id  [required]

Options:
  -h, --help  Show this message and exit.

mapi workflows nodes-catalog

Usage: mapi workflows nodes-catalog [OPTIONS]

  The node implementations a workflow can use, in plain words.

Options:
  --kind <test|transform|branch|split|search|model|evaluate|compare|select|governance|report|plot|subworkflow>
                                  test, transform, model, ...
  --about <str>                   Show one node's About card
  --expert
  -h, --help                      Show this message and exit.

mapi workflows schedules

Usage: mapi workflows schedules [OPTIONS] COMMAND [ARGS]...

  Cron schedules of a workflow.

Options:
  -h, --help  Show this message and exit.

Commands:
  ls      A workflow's schedules.
  add     Run the workflow on a schedule (at most every 15 minutes).
  pause   Pause a schedule.
  resume  Resume a paused schedule.
  rm      Delete a schedule.

mapi workflows schedules ls

Usage: mapi workflows schedules ls [OPTIONS] {workflow}

  A workflow's schedules.

Arguments:
  workflow  Workflow name or id  [required]

Options:
  -h, --help  Show this message and exit.

mapi workflows schedules add

Usage: mapi workflows schedules add [OPTIONS] {workflow} {cron}

  Run the workflow on a schedule (at most every 15 minutes).

Arguments:
  workflow  Workflow name or id  [required]
  cron      Cron expression, e.g. "0 6 * * 1"  [required]

Options:
  --tz <str>                  IANA time zone  [default: UTC]
  -i, --input <str>
  -p, --param <str>
  -r, --revision <int range>  [x>=1]
  --description <str>
  -h, --help                  Show this message and exit.

mapi workflows schedules pause

Usage: mapi workflows schedules pause [OPTIONS] {workflow} {schedule_id}

  Pause a schedule.

Arguments:
  workflow     Workflow name or id  [required]
  schedule_id  Schedule id  [required]

Options:
  -h, --help  Show this message and exit.

mapi workflows schedules resume

Usage: mapi workflows schedules resume [OPTIONS] {workflow} {schedule_id}

  Resume a paused schedule.

Arguments:
  workflow     Workflow name or id  [required]
  schedule_id  Schedule id  [required]

Options:
  -h, --help  Show this message and exit.

mapi workflows schedules rm

Usage: mapi workflows schedules rm [OPTIONS] {workflow} {schedule_id}

  Delete a schedule.

Arguments:
  workflow     Workflow name or id  [required]
  schedule_id  Schedule id  [required]

Options:
  -y, --yes
  -h, --help  Show this message and exit.

mapi workflows triggers

Usage: mapi workflows triggers [OPTIONS] COMMAND [ARGS]...

  Run a workflow when a dataset gets a new version.

Options:
  -h, --help  Show this message and exit.

Commands:
  ls   A workflow's dataset triggers.
  add  Run the workflow whenever the dataset gets a new version.
  rm   Delete a trigger.

mapi workflows triggers ls

Usage: mapi workflows triggers ls [OPTIONS] {workflow}

  A workflow's dataset triggers.

Arguments:
  workflow  Workflow name or id  [required]

Options:
  -h, --help  Show this message and exit.

mapi workflows triggers add

Usage: mapi workflows triggers add [OPTIONS] {workflow} {dataset}

  Run the workflow whenever the dataset gets a new version.

Arguments:
  workflow  Workflow name or id  [required]
  dataset   dataset://project/name  [required]

Options:
  -i, --input <str>       Workflow input to bind  [default: data]
  --debounce <int range>  Seconds to wait for more versions  [x>=0]
  -p, --param <str>
  -h, --help              Show this message and exit.

mapi workflows triggers rm

Usage: mapi workflows triggers rm [OPTIONS] {workflow} {trigger_id}

  Delete a trigger.

Arguments:
  workflow    Workflow name or id  [required]
  trigger_id  Trigger id  [required]

Options:
  -y, --yes
  -h, --help  Show this message and exit.

mapi governance

Usage: mapi governance [OPTIONS] COMMAND [ARGS]...

  Governance: the check catalog and the policies models must pass.

Options:
  -h, --help  Show this message and exit.

Commands:
  checks    The checks a policy can require, in plain words.
  policies  Project and tenant-wide governance policies.

mapi governance checks

Usage: mapi governance checks [OPTIONS]

  The checks a policy can require, in plain words.

Options:
  --about <str>  Show one check's About card
  --expert       The statistics behind it
  -h, --help     Show this message and exit.

mapi governance policies

Usage: mapi governance policies [OPTIONS] COMMAND [ARGS]...

  Project and tenant-wide governance policies.

Options:
  -h, --help  Show this message and exit.

Commands:
  ls        Policies in force in the project (tenant-wide first), or a tenant's.
  get       A policy's latest version with every check and threshold.
  create    Add a policy from a file (name, applies_to, checks, require_approval, ...).
  update    Save the file as the policy's next version.
  retire    Retire a policy (its versions stay for audit).
  versions  Every version of a project policy, newest first.

mapi governance policies ls

Usage: mapi governance policies ls [OPTIONS]

  Policies in force in the project (tenant-wide first), or a tenant's.

Options:
  --scope <str>   tenant or project (default: both)
  --tenant <str>  List a tenant's own policies instead
  -h, --help      Show this message and exit.

mapi governance policies get

Usage: mapi governance policies get [OPTIONS] {policy_id}

  A policy's latest version with every check and threshold.

Arguments:
  policy_id  Policy id  [required]

Options:
  --tenant <str>
  -h, --help      Show this message and exit.

mapi governance policies create

Usage: mapi governance policies create [OPTIONS] {file}

  Add a policy from a file (name, applies_to, checks, require_approval, ...).

Arguments:
  file  Policy YAML or JSON  [required]

Options:
  --tenant <str>  Create a tenant-wide policy (tenant admins)
  -h, --help      Show this message and exit.

mapi governance policies update

Usage: mapi governance policies update [OPTIONS] {policy_id} {file}

  Save the file as the policy's next version.

Arguments:
  policy_id  Policy id  [required]
  file       Policy YAML or JSON  [required]

Options:
  --tenant <str>
  --expected-version <int range>  Refuse if it changed since  [x>=1]
  -h, --help                      Show this message and exit.

mapi governance policies retire

Usage: mapi governance policies retire [OPTIONS] {policy_id}

  Retire a policy (its versions stay for audit).

Arguments:
  policy_id  Policy id  [required]

Options:
  --tenant <str>
  -y, --yes
  -h, --help      Show this message and exit.

mapi governance policies versions

Usage: mapi governance policies versions [OPTIONS] {policy_id}

  Every version of a project policy, newest first.

Arguments:
  policy_id  Policy id  [required]

Options:
  -h, --help  Show this message and exit.

mapi validate

Usage: mapi validate [OPTIONS] COMMAND [ARGS]...

  Validate a model version against the governance policies (or a workflow file).

Options:
  -h, --help  Show this message and exit.

Commands:
  model     Run the governance checks on a model version and show every result.
  workflow  Check a workflow file on the server (same as ``mapi workflows validate``).

mapi validate model

Usage: mapi validate model [OPTIONS] {model}

  Run the governance checks on a model version and show every result.

  Exit status 1 when a blocking check failed (``checks_failed``).

Arguments:
  model  model://project/name@vN, name@vN or name  [required]

Options:
  -v, --version <int range>  [x>=1]
  --policy <str>             Only these policies (repeat)
  --note <str>
  --dataset <str>            dataset:// for the data checks
  --wait / --no-wait         Wait for the checks  [default: wait]
  --timeout <float range>    [default: 3600.0; x>=1]
  -h, --help                 Show this message and exit.

mapi validate workflow

Usage: mapi validate workflow [OPTIONS] {file}

  Check a workflow file on the server (same as ``mapi workflows validate``).

Arguments:
  file  Workflow YAML or JSON  [required]

Options:
  -h, --help  Show this message and exit.

mapi validations

Usage: mapi validations [OPTIONS] COMMAND [ARGS]...

  Validations: the review queue, evidence, resubmission, deprecation, evidence packs.

Options:
  -h, --help  Show this message and exit.

Commands:
  ls         Validations of the project, most recently changed first.
  get        A validation: status, every result, approvals and history.
  evidence   Every check result with its evidence (numbers, tables).
  cancel     Stop running checks (back to draft).
  resubmit   Run the checks again after a failure or a rejection.
  deprecate  Retire a validated model version (audited with the reason).
  pack       Export the evidence pack for an auditor (self-contained HTML, or JSON).

mapi validations ls

Usage: mapi validations ls [OPTIONS]

  Validations of the project, most recently changed first.

Options:
  --status <draft|checks_running|checks_passed|checks_failed|awaiting_approval|validated|rejected|deprecated>
  --queue                         The reviewers' queue (awaiting approval)
  -n, --limit <int range>         [default: 50; x>=1]
  -h, --help                      Show this message and exit.

mapi validations get

Usage: mapi validations get [OPTIONS] {validation_id}

  A validation: status, every result, approvals and history.

Arguments:
  validation_id  Validation id  [required]

Options:
  -h, --help  Show this message and exit.

mapi validations evidence

Usage: mapi validations evidence [OPTIONS] {validation_id}

  Every check result with its evidence (numbers, tables).

Arguments:
  validation_id  Validation id  [required]

Options:
  -h, --help  Show this message and exit.

mapi validations cancel

Usage: mapi validations cancel [OPTIONS] {validation_id}

  Stop running checks (back to draft).

Arguments:
  validation_id  Validation id  [required]

Options:
  --note <str>
  -h, --help    Show this message and exit.

mapi validations resubmit

Usage: mapi validations resubmit [OPTIONS] {validation_id}

  Run the checks again after a failure or a rejection.

Arguments:
  validation_id  Validation id  [required]

Options:
  --note <str>
  -h, --help    Show this message and exit.

mapi validations deprecate

Usage: mapi validations deprecate [OPTIONS] {validation_id}

  Retire a validated model version (audited with the reason).

Arguments:
  validation_id  Validation id  [required]

Options:
  --reason <str>  Why it should no longer be used  [required]
  -y, --yes
  -h, --help      Show this message and exit.

mapi validations pack

Usage: mapi validations pack [OPTIONS] {validation_id}

  Export the evidence pack for an auditor (self-contained HTML, or JSON).

Arguments:
  validation_id  Validation id  [required]

Options:
  -o, --out <path>  pack.html (static page) or pack.json  [required]
  --no-plots
  -h, --help        Show this message and exit.

mapi explore

Usage: mapi explore [OPTIONS] COMMAND [ARGS]...

  Explore a dataset or a model (sections computed in the sandbox), compare models.

Options:
  -h, --help  Show this message and exit.

Commands:
  dataset  Explore a dataset version: profile, distributions, time plots, missingness,...
  model    Explore a model version: parameters, diagnostics, fit vs actual, residual tests,...
  compare  Compare model versions on their shared holdout: metrics, ranking and pairwise...
  get      An exploration's sections (and with --out its views).

mapi explore dataset

Usage: mapi explore dataset [OPTIONS] {ref}

  Explore a dataset version: profile, distributions, time plots, missingness, outliers,
  correlations, cross-correlation with the KPI, ACF/PACF, stationarity, STL, VIF, group
  comparisons and data-quality warnings.

Arguments:
  ref  dataset://project/name@vN, name@vN or name  [required]

Options:
  -v, --version <int range>  [x>=1]
  -s, --section <str>        overview, timeseries, stationarity, ccf, stl, ...
  --kpi <str>                The result to relate drivers to
  --facet-by <str>
  --max-lag <int range>      [x>=1]
  --option <str>             Any other request field, key=value
  -o, --out <path>           Write the views here
  --show <str>               Print one section's view
  --timeout <float range>    [default: 900.0; x>=1]
  -h, --help                 Show this message and exit.

mapi explore model

Usage: mapi explore model [OPTIONS] {ref}

  Explore a model version: parameters, diagnostics, fit vs actual, residual tests,
  decomposition, response curves, IRF/FEVD, forecasts, backtests and comparisons.

Arguments:
  ref  model://project/name@vN, name@vN or name  [required]

Options:
  -v, --version <int range>  [x>=1]
  -s, --section <str>        params, diagnostics, fit, residuals, irf, ...
  --horizon <int range>      [x>=1]
  --compare-with <str>
  --option <str>
  -o, --out <path>
  --show <str>
  --timeout <float range>    [default: 900.0; x>=1]
  -h, --help                 Show this message and exit.

mapi explore compare

Usage: mapi explore compare [OPTIONS] {models}...

  Compare model versions on their shared holdout: metrics, ranking and pairwise Diebold-Mariano
  tests (is the difference more than luck?).

Arguments:
  models...  Two to eleven model://… refs  [required]

Options:
  --horizon <int range>    [x>=1]
  -o, --out <path>
  --timeout <float range>  [default: 900.0; x>=1]
  -h, --help               Show this message and exit.

mapi explore get

Usage: mapi explore get [OPTIONS] {run_id}

  An exploration's sections (and with --out its views).

Arguments:
  run_id  Explore run id  [required]

Options:
  -o, --out <path>
  --show <str>
  -h, --help        Show this message and exit.