> For the complete documentation index, see [llms.txt](https://docs.eyepop.ai/developer-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.eyepop.ai/developer-documentation/cli/run.md).

# Run Inference

Run models on images, video, and datasets from the terminal

`eyepop run` is the core workflow. A flag names the **target** (what to run) and `--media-path` names the **media** (what to run it on):

```bash
eyepop run --model <alias-or-uuid> --media-path <media>
```

### Targets

| Target                    | Meaning                                                                                     | Example                                           |
| ------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------- |
| `--model <alias-or-uuid>` | A published model or ability                                                                | `--model eyepop.person:latest`                    |
| `--pop <pop>`             | A Pop from `eyepop get pops`, an ability, or the Pop itself as JSON/YAML (inline or a file) | `--pop people-common-objects`, `--pop ./pop.json` |
| `--session <uuid>`        | An existing session or deployment                                                           | `--session 73a991ac-...`                          |

Exactly one target per run. A published model is the usual choice — list what you can run with `eyepop get models`, and published abilities with `eyepop get abilities`.

On a machine running an [on-premise instance](/developer-documentation/cli/on-premise.md), you can omit the target entirely and the run uses the pop that instance serves.

{% hint style="info" %}
Prefer a guided flow? `eyepop tui` lists your runnable models and walks you through picking media and running. Running `eyepop run` with no target and no media prints its help.
{% endhint %}

### Run on media

Run a model on a single image:

```bash
eyepop run --model eyepop.person:latest --media-path image.jpg
```

Ask a VLM ability a question about the image:

```bash
eyepop run --model <vlm-ability> --media-path image.jpg --prompt "Describe this image"
```

Run several sources, or a directory recursively:

```bash
eyepop run --model eyepop.person:latest --media-path image1.jpg --media-path image2.jpg
eyepop run --model eyepop.person:latest --media-path ./images --recursive
```

`--concurrency` runs several inputs at once. `--no-cache` forces fresh inference instead of reusing a cached result; it applies to VLM ability runs, with or without `--prompt`, and `eyepop run` refuses it on `--pop`, `--session`, and any `--model` alias that resolves to a published model.

### Evaluate on a dataset

Scoring against a dataset is its own command — `eyepop evaluate` takes an ability and a dataset:

```bash
eyepop evaluate --ability my-namespace.find-kittens:latest --dataset people
```

Scope to a partition, or return immediately with a request id instead of waiting:

```bash
eyepop evaluate --ability my-namespace.find-kittens:latest --dataset people --partition test
eyepop evaluate --ability my-namespace.find-kittens:latest --dataset people --no-wait
```

Check or watch the evaluation:

```bash
eyepop get evals <request_id>
eyepop get evals <request_id> --watch
```

### Run a Pop or an existing session

```bash
eyepop run --pop people-common-objects --media-path image.jpg
eyepop run --session <session_uuid> --media-path image.jpg
```

A Pop you wrote yourself runs straight from its file: `eyepop run --pop ./pop.json --media-path image.jpg`. To keep it warm between runs, create a deployment from it with `eyepop create deployment --pop ./pop.json` (see [Persistent Sessions](/developer-documentation/cli/persistent-sessions.md)) and run against it with `--session`.

Pops and sessions take media only. To score against a dataset, use `eyepop evaluate`.

### Next steps

* [Command Reference](/developer-documentation/cli/reference.md) — every `run` and `evaluate` flag
* [Resources](/developer-documentation/cli/resources.md) — find the models, abilities, and pops to run