# The `mime` command line

Generated from the command line's own parser by `mime docs build`; nothing here is written by hand. The flags of `mime` itself come first (each says whether it may come anywhere on the line), then each command, grouped as `mime --help` groups them.

## Options of `mime` itself

- `--traceback`: print a refused command's full traceback, every frame and chained error (it may come anywhere on the line)
- `--plain`: draw nothing but plain text on a terminal, as when output is piped (NO_COLOR and TERM=dumb ask the same); it may come anywhere on the line
- `-V`, `--version`: print MIME's version and exit

## Run

### `mime run`

load a saved experiment, run it, and save the run beside its outputs

```
mime run [--no-xla-cache] [--duration DURATION] --out OUT [--history] [--record OUTPUT] [--every DURATION] [--stage-every DURATION] [--full] [--commands LOG] folder
```

- `folder`: a folder written by Experiment.save
- `--no-xla-cache`: keep no XLA compilation cache: compile everything afresh (by default one is kept in the user's cache directory, capped in size, so that a second run of an experiment compiles less)
- `--duration` `DURATION`: the simulated time, a whole number of the experiment's base steps (10s, 500ms, 250us, 2min, 1h, or a bare number, which is seconds); the length the saved experiment declares when not given (required, with --commands the exception, when it declares none)
- `--out` `OUT`: the folder to write the outputs, the record and the run's saved form to
- `--history`: write every step's fields, not only the last
- `--record` `OUTPUT`: a per-step output to record as a series, <observation id>.<output> or an observation's id for all of its own (repeat it for more)
- `--every` `DURATION`: the spacing of the recorded series' samples, a whole number of base steps (default: every step); a unit as for --duration
- `--stage-every` `DURATION`: write the recording layer (recording.usdc, over the run's own stage) with a sample every DURATION, a whole number of the run's chunks; a unit as for --duration
- `--full`: on a terminal, also print the load report, the build report's summary and every reading (the summary leads with what needs attention and keeps the rest back; piped output is always whole, and so are the files)
- `--commands` `LOG`: replay a live session from the command log it wrote (commands.jsonl): its run folder again, in place of --duration

Example:

```sh
mime run my_experiment --duration 10s --out my_run
```

### `mime serve`

serve a saved experiment's live session (mime.live/1, over ZMQ)

```
mime serve [--no-xla-cache] [--commands ENDPOINT] [--frames ENDPOINT] [--chunk SECONDS] [--pace FACTOR] [--unpaced] [--out DIR] [--select FIELD] [--json-frames] [--start] [--remote] [--ready-file FILE] [--outlive-launcher] [--idle-timeout DURATION] [--max-wall DURATION] [--watch PATH] folder
```

- `folder`: a folder written by Experiment.save
- `--no-xla-cache`: keep no XLA compilation cache: compile everything afresh (by default one is kept in the user's cache directory, capped in size, so that a second run of an experiment compiles less)
- `--commands` `ENDPOINT`: where to take commands, a REP socket (default: tcp://127.0.0.1:5555; port 0 takes any free one)
- `--frames` `ENDPOINT`: where to send frames, a PUB socket (default: tcp://127.0.0.1:5556)
- `--chunk` `SECONDS`: the simulated time each chunk steps, one frame each (default: about 1/60 s, whole base steps and control periods)
- `--pace` `FACTOR`: run at FACTOR times real time (default: 1)
- `--unpaced`: run as fast as it runs
- `--out` `DIR`: the run folder it writes when it stops (default: ./<experiment>-live-<time>/)
- `--select` `FIELD`: a field the frames carry, <node>.<field> (repeat it; default: every bound pose and vector, every per-step output and every flag)
- `--json-frames`: send frames as JSON, for debugging
- `--start`: start stepping at once, before a client's start
- `--remote`: allow an address that is not loopback (no authentication: prefer an SSH tunnel)
- `--ready-file` `FILE`: write the bound endpoints as JSON to FILE once the sockets listen
- `--outlive-launcher`: serve on when the process that launched it is gone (by default the session stops then, writing its run folder, as on SIGTERM)
- `--idle-timeout` `DURATION`: stop, writing the run folder, when no client has been connected that long (10min, 2h; default: never). Like --max-wall, it stops at the end of the chunk in hand
- `--max-wall` `DURATION`: stop, writing the run folder, when the session has run that long, wall time from when it opened (default: never). The chunk in hand is finished first, as for SIGTERM: the stop comes at the end of the chunk in hand, later than the limit by what is left of it (the first compiles)
- `--watch` `PATH`: a row of the live view's table of values, <node>.<field> or <node>.<field>[0:3] (repeat it; all, or none to hide the table; default: each scalar output, each flag and each body's position). It chooses what is shown and adds nothing to the frames

Example:

```sh
mime serve my_experiment --start
```

### `mime verify`

load, rebuild, check the hash, and rerun against the reference outputs; it keeps no XLA compilation cache, compiling as a fresh process would

Load a saved experiment, rebuild it, check it against its lock and rerun its reference steps. It keeps no XLA compilation cache, whatever mime run does: a verification compiles as a fresh process would.

```
mime verify folder
```

- `folder`: a folder written by Experiment.save

Example:

```sh
mime verify my_experiment
```

### `mime pending`

what a saved experiment leaves pending, with the lines to paste to seal it

```
mime pending folder
```

- `folder`: a folder written by Experiment.save, or its document (experiment.mime.yaml), edited, to check it as it is

Example:

```sh
mime pending my_experiment
```

## Share

### `mime pack`

write a saved experiment folder as one bundle file

```
mime pack [--out OUT] folder
```

- `folder`: a folder written by Experiment.save
- `--out` `OUT`: the bundle file (default: <folder>.mimebundle beside the folder)

Example:

```sh
mime pack my_experiment --out my_experiment.mimebundle
```

### `mime card`

a saved experiment's card (Markdown), or its NOTICE, offline, exactly as mime push will publish them

```
mime card [--out OUT] [--notice] folder
```

- `folder`: a folder written by Experiment.save
- `--out` `OUT`: write it to this file (default: print it)
- `--notice`: the NOTICE (each file's licence, credit, verdict and declared permission) in place of the card

Example:

```sh
mime card my_experiment --notice
```

### `mime pull`

get a bundle by DOI, address or file, unpack it into a new folder, and fetch its assets

```
mime pull [--link {-,env}] [--from SERVICE] [--signed-in] [--into INTO] [--no-assets] [--yes] [--max-bundle-bytes BYTES] [source]
```

- `source`: a DOI (10.5281/zenodo.1234567; a concept DOI pulls the latest version), an https:// address, a bundle file, a record's share link (in quotes; --link keeps it out of sight), or with --from a record's number
- `--link` `{-,env}`: a record's share link, read in place of the source: `--link -` asks for it with no echo, `--link env` reads it from MIME_SHARE_LINK. A link given as the source stays in your shell's history and, while pull runs, in its arguments, which any account on this machine can read (ps, /proc/<pid>/cmdline) unless /proc is mounted with hidepid
- `--from` `SERVICE`: read the published record of this number at the service's records API (zenodo-sandbox: its DOIs do not resolve through doi.org) (one of `zenodo`, `zenodo-sandbox`)
- `--signed-in`: with --from, send the token `mime credentials` stored for that service, for a record or files shared with your account (without it, pull sends no token)
- `--into` `INTO`: the new folder (default: ./<the experiment's name>/)
- `--no-assets`: unpack only; fetch the assets later with `mime assets fetch <folder>`
- `--yes`: download assets over the size MIME asks about without asking
- `--max-bundle-bytes` `BYTES`: the most a bundle may be when nothing states its size (default: 500 MB)

Example:

```sh
mime pull 10.5281/zenodo.1234567 --into my_experiment
```

### `mime push`

show the plan, then make or update the experiment's draft record on Zenodo and upload its files (nothing is published)

```
mime push [--to TO] [--init | --setup | --defaults | --status | --discard | --publish] [--confirm DOI[@FINGERPRINT]] [--yes] [--full-plan] [--keep-site-edits | --overwrite-site-edits] [folder]
```

- `folder`: a folder written by Experiment.save
- `--to` `TO`: the service: zenodo, or zenodo-sandbox to try it on Zenodo's test service (required, but for --setup and --defaults) (one of `zenodo`, `zenodo-sandbox`)
- `--init`: write sharing.yaml, the record's credit and description, from what the folder knows and your sharing defaults
- `--setup`: make or edit sharing.yaml a field at a time, in a terminal: each field explained, Enter skips it or keeps the value shown; then save your defaults if you like
- `--defaults`: show your sharing defaults (your name, ORCID iD, affiliation and the rest you repeat from record to record) and where they live; takes no folder
- `--status`: the draft as the service holds it, against what push uploaded
- `--discard`: delete the draft (only a draft can be deleted)
- `--publish`: publish the draft, the one step that cannot be undone: the plan, the confirmation in words, each declared permission asked, then the record number typed
- `--confirm` `DOI[@FINGERPRINT]`: with --publish, from a script: the draft's reserved DOI, in place of the record number typed (it must be that draft's); once a push changed the draft after first printing its DOI, the DOI and the fingerprint the last push printed beside it
- `--yes`: delete the draft with --discard without asking (it never publishes, declares a permission or settles a site edit)
- `--full-plan`: the full plan: every file inside the bundle with its tier and verdict, every field sent
- `--keep-site-edits`: keep each edit made on the service's site that sharing.yaml can hold, written into it, without asking
- `--overwrite-site-edits`: write the draft's metadata from sharing.yaml and the folder over what was edited on the service's site since push last wrote it (without it, such an edit stops the push)

Example:

```sh
mime push my_experiment --to zenodo-sandbox
```

### `mime credentials`

the access token mime push will use, kept where a commit cannot publish it

```
mime credentials <command>
```

Example:

```sh
mime credentials status
```

#### `mime credentials set`

read a token (hidden) and store it

```
mime credentials set {zenodo,zenodo-sandbox}
```

- `{zenodo,zenodo-sandbox}`

Example:

```sh
mime credentials set zenodo-sandbox
```

#### `mime credentials remove`

delete the stored token

```
mime credentials remove {zenodo,zenodo-sandbox}
```

- `{zenodo,zenodo-sandbox}`

Example:

```sh
mime credentials remove zenodo-sandbox
```

#### `mime credentials status`

whether there is a token, where from, and its last four characters, if 32 or more

```
mime credentials status [{zenodo,zenodo-sandbox}]
```

- `{zenodo,zenodo-sandbox}`

Example:

```sh
mime credentials status zenodo
```

## Environment

### `mime env`

the environment a run is made in

```
mime env <command>
```

Example:

```sh
mime env check my_experiment --variant cpu
```

#### `mime env check`

hold this environment to MIME's pins and the GPU requested, then apply the precision the experiment's lock records

```
mime env check --variant VARIANT [--gpu TYPE] [--base] [--lab FILE] [--xla-cache DIR] [--mime-version VERSION] [--record FILE] [folder]
```

- `folder`: a saved experiment, whose lock's precision to apply
- `--variant` `VARIANT`: the pins to hold the environment to (one of `cpu`, `cuda12`)
- `--gpu` `TYPE`: the exact GPU type requested (T4, L4, A10, L40S, RTX-PRO-6000, A100-40GB, A100-80GB, H100!, H200, B200, B300); without it, the CPU
- `--base`: hold Python, the OS and the image's own distributions to MIME's base image for this series
- `--lab` `FILE`: the lab's requirements file, pinned beside MIME's
- `--xla-cache` `DIR`: keep XLA's compilation cache under DIR, in its directory for this jaxlib and device
- `--mime-version` `VERSION`: the version of the MIME wheel pinned for the run; without it MIME is not held to one
- `--record` `FILE`: also write what the check found as JSON

Example:

```sh
mime env check my_experiment --variant cpu
```

### `mime modal`

write the script that runs a saved experiment on Modal

```
mime modal [--gpu TYPE] [--deterministic] [--python SERIES] [--out OUT] [--checkout CHECKOUT] [--lab-requirements FILE] [--no-xla-cache] [--timeout TIMEOUT] [--max-containers MAX_CONTAINERS] [--cpu CPU] [--memory MEMORY] folder
```

- `folder`: a folder written by Experiment.save
- `--gpu` `TYPE`: an exact GPU type (T4, L4, A10, L40S, RTX-PRO-6000, A100-40GB, A100-80GB, H100!, H200, B200, B300); without it, a CPU
- `--deterministic`: turn XLA's deterministic GPU mode on (--xla_gpu_deterministic_ops), recorded in the run's lock
- `--python` `SERIES`: the Python series of the image (default: the lock's)
- `--out` `OUT`: the folder to write the script to (default: <folder>-modal beside the experiment)
- `--checkout` `CHECKOUT`: build MIME's wheel from this checkout (default: the checkout MIME is installed from, else the release's wheel on PyPI)
- `--lab-requirements` `FILE`: the lab's hashed requirements file, in place of the version pins the lock names
- `--no-xla-cache`: keep no XLA compilation cache on a Volume
- `--timeout` `TIMEOUT`: seconds a run may take (default: 7200)
- `--max-containers` `MAX_CONTAINERS`: containers a function may run in at once (default: 1)
- `--cpu` `CPU`: CPU cores to request (default: 4)
- `--memory` `MEMORY`: MiB of memory to request (default: 8192)

Example:

```sh
mime modal my_experiment --gpu A100-40GB
```

### `mime cache`

the XLA compilation cache mime run and mime serve keep

```
mime cache <command>
```

Example:

```sh
mime cache clear
```

#### `mime cache clear`

delete the compilation cache in the user's cache directory

```
mime cache clear
```

Example:

```sh
mime cache clear
```

### `mime assets`

large files referenced by sha256 and fetched on request

```
mime assets <command>
```

Example:

```sh
mime assets fetch my_experiment
```

#### `mime assets list`

every known asset, cached or missing, with its size

```
mime assets list
```

Example:

```sh
mime assets list
```

#### `mime assets fetch`

store assets in the cache (the cache, then the primary location, then backups), then hash them in full

```
mime assets fetch [--all] [name-or-folder ...]
```

- `name-or-folder`: an asset's name, or an experiment folder: exactly the assets its lock references
- `--all`: every known asset

Example:

```sh
mime assets fetch my_experiment
```

#### `mime assets check`

re-hash every cached asset in full

```
mime assets check
```

Example:

```sh
mime assets check
```

#### `mime assets sources`

each asset's terms, tier and locations, each looked at now (reachable or not, and why), downloading nothing

```
mime assets sources name-or-folder [name-or-folder ...]
```

- `name-or-folder`: an asset's name, a saved folder (its lock's assets and its meshes' manifests), a folder holding visuals.json, or a manifest file

Example:

```sh
mime assets sources my_experiment
```

#### `mime assets audit`

find in a wheel, an sdist, an archive or a directory any file whose bytes may not be redistributed, and any mesh with no record (exit 1 when anything is found)

```
mime assets audit [--manifest FILE] wheel-sdist-or-directory [wheel-sdist-or-directory ...]
```

- `wheel-sdist-or-directory`: a wheel, an sdist, a zip or tar archive, or a directory
- `--manifest` `FILE`: a manifest whose records count too (repeat it); the target's own manifests and locks, the installed sources' and the local cache's baked meshes always count

Example:

```sh
mime assets audit dist/mime_engine-0.3.0-py3-none-any.whl
```

### `mime visuals`

descriptions' meshes MIME does not ship, baked into the asset cache, and the overlay that draws them on a stage

```
mime visuals <command>
```

Example:

```sh
mime visuals list
```

#### `mime visuals list`

every visual set MIME has a recipe for, baked or not, with its licence

```
mime visuals list
```

Example:

```sh
mime visuals list
```

#### `mime visuals fetch`

download a description's meshes from their pinned upstream, check each file's sha256, and bake them into the asset cache

```
mime visuals fetch description-or-folder
```

- `description-or-folder`: a description's folder (its visuals.json), a description or manifest file, a saved or run folder (the manifests its lock holds), or a set's name from mime visuals list

Example:

```sh
mime visuals fetch examples/descriptions/ar4/
```

#### `mime visuals view`

the layer that opens a stage, a recording or a folder's with the baked meshes drawn, for any USD viewer

```
mime visuals view target
```

- `target`: a stage or recording file, a run folder or a saved folder

Example:

```sh
mime visuals view my_run
```

#### `mime visuals web`

one web page of a stage, a recording or a folder's, to open in a browser or share: the scene, its recording and the meshes whose terms let them be shared

```
mime visuals web [--out FILE] [--glb FILE] [--slow-motion FACTOR] [--caption TEXT] [--cdn] [--open] target
```

- `target`: a stage or recording file, a run folder or a saved folder
- `--out` `FILE`: the page to write (default: <the experiment's name>.html here); never inside a saved or run folder
- `--glb` `FILE`: also write the scene alone as a glTF binary file
- `--slow-motion` `FACTOR`: display seconds per simulated second (default: a recording shorter than 4 s slowed to about 8 s)
- `--caption` `TEXT`: a line shown above the page's notes
- `--cdn`: load the viewer from jsDelivr, held to its hash, rather than inline it (1.4 MB smaller; the page then needs the network)
- `--open`: open the page in the default browser

Example:

```sh
mime visuals web my_run --open
```

### `mime completion`

print a completion script for bash, zsh or fish

```
mime completion {bash,zsh,fish}
```

- `{bash,zsh,fish}`: the shell to write the script for

Example:

```sh
mime completion bash > ~/.local/share/bash-completion/completions/mime
```

## Reference

### `mime registry`

every registered entry and what it declares

```
mime registry [--json]
```

- `--json`: the whole export, as JSON

Example:

```sh
mime registry --json
```

### `mime docs`

the documentation's sources

```
mime docs <command>
```

Example:

```sh
mime docs check --base origin/v0.3
```

#### `mime docs check`

every check of the documentation's sources

```
mime docs check [--root ROOT] [--base REVISION] [--skip-hash-seed-builds] [--skip-evidence] [--skip-example-runs]
```

- `--root` `ROOT`: the checkout to check (default: here)
- `--base` `REVISION`: fail on a README start-list line this revision's list does not hold (CI passes origin/v0.3)
- `--skip-hash-seed-builds`: do not build the pages in fresh processes under eight hash seeds (the tests of the other checks pass it to stay fast; CI never does)
- `--skip-evidence`: do not collect the test suite to resolve the evidence the specification and the anomaly registry cite (the tests of the other checks pass it, on copies of the checkout; CI never does)
- `--skip-example-runs`: do not run the scripts the guides' output blocks name to regenerate those blocks (the platform smoke job passes it: the printed numbers are a Linux run's; CI's docs check never does)

Example:

```sh
mime docs check --base origin/v0.3
```

#### `mime docs build`

generate the pages (never committed) from the registry and the hand-written sources

```
mime docs build [--root ROOT] [--out OUT] [--junit DIRECTORY] [--collection FILE] [--skip-evidence]
```

- `--root` `ROOT`: the checkout to build from (default: here)
- `--out` `OUT`: the directory to write index.md and pages/ to (default: <root>/docs/_build)
- `--junit` `DIRECTORY`: the default lane's JUnit reports (every .xml under this directory): the evidence counts page reads each cited test's outcome there; without it every row prints 'outcome not read (no lane report)' (CI passes it)
- `--collection` `FILE`: a collection of the test suite, as mime docs check writes it (JSON), to resolve the evidence in (the hash-seed builds of mime docs check pass it; without it the files the evidence names are collected)
- `--skip-evidence`: do not collect the tests the evidence counts page cites: every row reads 'not read' (the tests of the other pages pass it; CI never does)

Example:

```sh
mime docs build --out docs_pages
```