<!-- @generated by usage-cli from usage spec -->
# `mise oci run`

- **Usage**: `mise oci run [FLAGS] [-- CMD]…`
- **Source code**: [`src/cli/oci/run.rs`](https://github.com/jdx/mise/blob/main/src/cli/oci/run.rs)

[experimental] Build an OCI image from the current mise.toml and run a command in it

Equivalent to `mise oci build` followed by `docker run` / `podman run`.
The built image is loaded into the local container engine (podman pulls
the OCI layout natively; docker receives it via `docker load`) and the
given command is executed inside it with stdin/stdout/stderr inherited.

Requires `mise settings experimental=true` (or `MISE_EXPERIMENTAL=1`) and
one of: `podman`, `docker`.

## Arguments

### `[-- CMD]…`

Command and arguments to run inside the container (after `--`)

## Flags

### `--engine <ENGINE>`

Container engine to use (`auto`, `podman`, or `docker`)

**Choices:**

- `auto`
- `podman`
- `docker`

**Default:** `auto`

### `--from <FROM>`

Base image reference for the build (ignored with --image-dir)

### `--image-dir <IMAGE_DIR>`

Use an already-built OCI image layout instead of building fresh

### `--include-global`

Also include tools from the global / system config (default: project-only)

See `mise oci build --help` for details.

### `--keep`

Keep the loaded image in the engine's storage after the run

By default, both the container (`--rm`) and the loaded image are removed when the command exits, so repeated `mise oci run` calls don't accumulate images in podman / docker storage. Pass `--keep` to retain the image under the tag mise used (`mise-oci:run-*` for docker; the pulled image ID for podman).

### `--mount-point <MOUNT_POINT>`

Override in-image mount point (ignored with --image-dir)

### `--no-mise`

Don't embed the mise binary (ignored with --image-dir)

### `--owner <UID[:GID]>`

UID[:GID] to assign to every tar entry when building (conflicts with --image-dir)

Overrides [oci].user_id / [oci].group_id. Defaults to 0:0. If GID is omitted, it defaults to UID. This affects file ownership only; [oci].user controls the image USER directive.

### `--volume… <HOST:CONTAINER>`

Bind-mount a host path (repeatable, `HOST:CONTAINER[:MODE]`)

Note: unlike `docker run -v`, there's no `-v` short flag here because mise reserves `-v` for --verbose. Use `--volume` or `--mount`.

### `-e --env… <KEY=VAL>`

Set environment variable in the container (repeatable, `KEY=VAL`)

### `-i --interactive`

Run interactively (pass `-i` to the engine)

### `-t --tty`

Allocate a TTY (pass `-t` to the engine)

### `-w --workdir <WORKDIR>`

Working directory inside the container

Examples:

```
Build the current mise.toml and drop into bash:
$ mise oci run -it -- bash

Run a one-shot command with env + volume (note: `-v` is reserved
for --verbose, so use `--volume`):
$ mise oci run -e DEBUG=1 --volume $PWD:/work -w /work -- npm test

Re-use a previously built layout (skip the build step):
$ mise oci build -o ./img && mise oci run --image-dir ./img -- node -e 'console.log(process.version)'
```

Engines:

```
Prefers podman (loads OCI layouts natively). Falls back to docker
(loaded via docker load). Pass --engine podman or --engine docker to override.
```
