# uip agent run

> Syntax and options for `uip agent run`, which starts and monitors agent jobs on Orchestrator.

`uip agent run` starts and monitors agent jobs on Orchestrator. Internally, each subcommand calls the standard Orchestrator Jobs / Releases OData endpoints — the same endpoints that [`uip or jobs`](./uip-orchestrator-jobs.md) exposes — scoped to the releases produced by [`uip agent deploy`](./uip-agent-deploy.md).

Every subcommand requires an active CLI session (`uip login`). If no `--folder-id` is passed, the command uses the folder bound to the current session.

## Synopsis

```
uip agent run start <releaseKeyOrName> [-i <json>] [--folder-id <id>] [-t <tenant>] [--login-validity <minutes>]
uip agent run status <jobId>                         [--folder-id <id>] [-t <tenant>] [--login-validity <minutes>]
uip agent run list                                   [--folder-id <id>] [--filter <odata>] [-t <tenant>] [--login-validity <minutes>]
```

All `uip agent run` subcommands honor the [global options](./global-options.md) (`--output`, `--output-filter`, `--log-level`, `--log-file`). Exit codes follow the [standard contract](./exit-codes.md).

## uip agent run start

Start a job for a deployed agent release.

### Arguments

- `<releaseKeyOrName>` *(required)* — Either a release key (GUID) or a release name. If the value is not a GUID, the command performs a name lookup against the Releases OData endpoint (`$filter=Name eq '<name>'`).

### Options

| Flag | Default | Purpose |
|---|---|---|
| `-i, --inputs <json>` | `{}` | Input arguments as a JSON string. Must be valid JSON. |
| `--folder-id <id>` | *login folder* | Orchestrator folder Org Unit ID. Sent as `X-UIPATH-OrganizationUnitId`. |
| `-t, --tenant <tenant>` | *login tenant* | Target tenant. |
| `--login-validity <minutes>` | `10` | Minimum minutes of token validity required. |

### Examples

```bash
# Start by release key (the exact key from 'agent run list')
uip agent run start a1b2c3d4-0000-0000-0000-000000000401 -i '{"input":"hello"}'

# Start by release name (resolved via OData lookup)
uip agent run start InvoiceAgent -i '{"invoiceUrl":"…"}' --folder-id 42

# Start with no inputs
uip agent run start InvoiceAgent
```

### Data shape (--output json)

```json
{
  "Code": "AgentJobStarted",
  "Data": {
    "JobId": 12345,
    "JobKey": "a1b2c3d4-0000-0000-0000-000000000410",
    "State": "Pending"
  }
}
```

`JobId` is the numeric ID you pass to `uip agent run status`. `JobKey` is the GUID equivalent, useful for cross-references against the Orchestrator UI or `uip or jobs` commands. Jobs are started with `Strategy: ModernJobsCount` and `JobsCount: 1`.

## uip agent run status

Fetch the current state of a single job.

### Arguments

- `<jobId>` *(required)* — Numeric Orchestrator job ID (from `run start` or `uip or jobs list`).

### Options

Same as `run start` (`--folder-id`, `-t/--tenant`, `--login-validity`).

### Examples

```bash
# Quick status check
uip agent run status 12345

# Explicit folder
uip agent run status 12345 --folder-id 42
```

### Data shape (--output json)

```json
{
  "Code": "AgentJobStatus",
  "Data": {
    "JobId": 12345,
    "State": "Successful",
    "ReleaseName": "InvoiceAgent",
    "StartTime": "2025-04-15T10:30:00Z",
    "EndTime": "2025-04-15T10:31:12Z",
    "Info": "…",
    "Output": { "...": "..." }
  }
}
```

- `State` values mirror Orchestrator's job states (`Pending`, `Running`, `Successful`, `Faulted`, `Stopped`, `Suspended`, …).
- `Info` is only present when the job carries a status message (typically on failure).
- `Output` is `OutputArguments` parsed as JSON. If parsing fails, the raw string is returned instead.

## uip agent run list

List the agent releases available in a folder.

### Arguments

None.

### Options

| Flag | Default | Purpose |
|---|---|---|
| `--folder-id <id>` | *login folder* | Orchestrator folder Org Unit ID. |
| `--filter <odata>` | — | Additional OData `$filter` expression appended to the default query (which already sorts by `Name`). |
| `-t, --tenant <tenant>` | *login tenant* | Target tenant. |
| `--login-validity <minutes>` | `10` | Minimum minutes of token validity required. |

### Examples

```bash
# List all releases in the login folder
uip agent run list

# List in a specific folder
uip agent run list --folder-id 42

# Filter by name prefix
uip agent run list --filter "startswith(Name,'Invoice')"
```

### Data shape (--output json)

```json
{
  "Code": "AgentReleaseList",
  "Data": [
    {
      "Name": "InvoiceAgent",
      "ReleaseKey": "a1b2c3d4-0000-0000-0000-000000000401",
      "ProcessKey": "InvoiceAgent",
      "Version": "1.0.0",
      "FolderId": 42
    }
  ]
}
```

An empty folder returns a `Message` log entry (`No releases found in this folder. Publish an agent first.`) and no success payload.

## Related

- [`uip agent deploy`](./uip-agent-deploy.md) — publishes the releases that `run list` enumerates.
- [`uip agent eval run start`](./uip-agent-eval.md#uip-agent-eval-run) — the evaluation equivalent of `run start`, targeting the Agent Runtime service rather than an Orchestrator job.
- [Orchestrator: jobs](./uip-orchestrator-jobs.md) — the full jobs API (stop, restart, logs, attachments).

## See also

- [Authentication](./authentication.md) — sessions, tenants, and `--login-validity`.
- [Global options](./global-options.md), [Exit codes](./exit-codes.md).