> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vlm.run/llms.txt
> Use this file to discover all available pages before exploring further.

# execute

> Execute agents with files, skills, and structured output

The `vlmrun execute` command submits agent executions via the `/v1/agent/execute` endpoint. Upload files, attach skills, and get structured JSON output.

## Basic Usage

```bash theme={"theme":{"light":"github-light","dark":"dark-plus"}}
# Execute a named agent with a file
vlmrun execute -n my-agent:v1 -i invoice.pdf

# Execute with a prompt and schema
vlmrun execute -p "Extract invoice fields" -i doc.pdf --schema schema.json

# Execute with multiple files and toolsets
vlmrun execute -n my-agent:v1 -i a.jpg -i b.pdf -t image -t document
```

## Agent Names

Use `<agent-name>:<agent-version>` format. If `--name` is omitted, the prompt is used to identify the agent.

```bash theme={"theme":{"light":"github-light","dark":"dark-plus"}}
vlmrun execute -n invoice-extractor:v2 -i invoice.pdf
vlmrun execute -p "Describe this image" -i photo.jpg
```

## Using Skills

Attach skills inline from a local directory or reference server-side skills by ID. Only one of `--skill` or `--skill-id` may be provided.

```bash theme={"theme":{"light":"github-light","dark":"dark-plus"}}
# Inline skill from a local directory
vlmrun execute -n my-agent:v1 -i img.jpg --skill ./my-skill

# Server-side skill reference
vlmrun execute -n my-agent:v1 -i img.jpg --skill-id my-skill:latest
```

## Models

| Model                 | Description           |
| --------------------- | --------------------- |
| `vlmrun-orion-1:lite` | Lightweight           |
| `vlmrun-orion-1:fast` | Speed-optimized       |
| `vlmrun-orion-1:auto` | Auto-select (default) |
| `vlmrun-orion-1:pro`  | Most capable          |

```bash theme={"theme":{"light":"github-light","dark":"dark-plus"}}
vlmrun execute -n my-agent:v1 -i photo.jpg -m vlmrun-orion-1:pro
```

## Toolsets

Enable specific tool categories with `--toolset` (repeatable):

```bash theme={"theme":{"light":"github-light","dark":"dark-plus"}}
vlmrun execute -n my-agent:v1 -i photo.jpg -t image -t web
```

Available toolsets: `core`, `image`, `image-gen`, `world-gen`, `viz`, `document`, `video`, `web`.

## Async Execution

By default the CLI waits for execution to complete. Use `--no-wait` to submit and return immediately:

```bash theme={"theme":{"light":"github-light","dark":"dark-plus"}}
# Submit and return immediately
vlmrun execute -n my-agent:v1 -i photo.jpg --no-wait

# Check status later
vlmrun executions get <execution-id>
```

## Output Formats

```bash theme={"theme":{"light":"github-light","dark":"dark-plus"}}
# Rich formatted output (default)
vlmrun execute -n my-agent:v1 -i invoice.pdf

# JSON output for scripting
vlmrun execute -n my-agent:v1 -i invoice.pdf -f json

# Pipe JSON to jq
vlmrun execute -n my-agent:v1 -i invoice.pdf -f json | jq '.response'
```

## Prompt Sources

The prompt can be text or a path to a `.txt`/`.md` file:

```bash theme={"theme":{"light":"github-light","dark":"dark-plus"}}
# Inline text
vlmrun execute -p "Extract all line items" -i invoice.pdf

# From a file
vlmrun execute -p instructions.md -i invoice.pdf
```

## Options Reference

| Option                 | Short | Description                                          |
| ---------------------- | ----- | ---------------------------------------------------- |
| `--name`               | `-n`  | Agent name as `<name>:<version>`                     |
| `--prompt`             | `-p`  | Prompt text or path to a `.txt`/`.md` file           |
| `--input`              | `-i`  | Input file (repeatable)                              |
| `--schema`             |       | Path to a JSON schema file for the response model    |
| `--skill`              | `-k`  | Path to a local skill directory (repeatable)         |
| `--skill-id`           |       | Server-side skill as `<name>:<version>` (repeatable) |
| `--toolset`            | `-t`  | Tool category to enable (repeatable)                 |
| `--model`              | `-m`  | Model variant (default: `vlmrun-orion-1:auto`)       |
| `--wait` / `--no-wait` |       | Wait for completion (default: `--wait`)              |
| `--timeout`            |       | Timeout in seconds when waiting (default: `300`)     |
| `--poll-interval`      |       | Seconds between status checks (default: `5`)         |
| `--callback-url`       |       | Webhook URL called on completion                     |
| `--format`             | `-f`  | Output format (`json`)                               |