# uip or jobs

> `uip or jobs` manages process executions: start jobs from processes, stop and restart them, resume suspended jobs, and inspect logs, traces, healing-agent data, and state history. Every job is identified by a GUID key that is globally unique — most verbs resolve the folder from the key automatically.

`uip or jobs` manages process executions: start jobs from processes, stop and restart them, resume suspended jobs, and inspect logs, traces, healing-agent data, and state history. Every job is identified by a GUID key that is globally unique — most verbs resolve the folder from the key automatically.

## Synopsis

```
uip or jobs <verb> [options]
```

## Verbs

| Verb | Purpose |
|---|---|
| `list` | List jobs, optionally scoped to a folder and filtered by state, process, source, or time range. |
| `get` | Fetch one job by key, including input/output arguments and (for Pending jobs) diagnostic reasons. |
| `start` | Start one or more jobs for a process; optionally wait for completion and download output. |
| `stop` | Soft-stop or force-kill one or more running/pending jobs. |
| `restart` | Create a new job from a faulted or stopped job. |
| `resume` | Resume a suspended job, optionally with updated input arguments. |
| `logs` | Fetch robot execution logs for a job; filter by level or export to CSV. |
| `traces` | Fetch LlmOps execution traces for an agentic (Agent-type) job. |
| `healing-data` | Download healing-agent recovery data (screenshots, UI data, logs) as a ZIP. |
| `history` | Show state transitions for a job. |

## uip or jobs list

List jobs across a tenant or folder. Returns job key, state, process name, timing, and machine info.

### Options

| Short | Long | Value | Default | Description |
|---|---|---|---|---|
| `-t` | `--tenant` | name | session default | Override the tenant selected at auth time. |
| — | `--folder-path` | path | — | Scope to a folder by path (for example, `Shared`). Omit for cross-folder listing. |
| — | `--folder-key` | GUID | — | Scope to a folder by key. |
| — | `--state` | enum | — | `Pending`, `Running`, `Successful`, `Faulted`, `Stopped`, `Stopping`, `Suspended`, `Resumed`, `Terminating`. |
| — | `--process-name` | text | — | Contains-match on process (release) name. |
| — | `--source` | enum | — | Filter by job source type (for example, `Manual`, `Schedule`, `Queue`, `Agent`). |
| — | `--created-after` | ISO 8601 | — | Jobs created on or after this date/time. |
| — | `--created-before` | ISO 8601 | — | Jobs created strictly before this date/time. |
| — | `--started-after` | ISO 8601 | — | Jobs started on or after this date/time. |
| — | `--started-before` | ISO 8601 | — | Jobs started strictly before this date/time. |
| — | `--ended-after` | ISO 8601 | — | Jobs ended on or after this date/time. |
| — | `--ended-before` | ISO 8601 | — | Jobs ended strictly before this date/time. |
| `-l` | `--limit` | number | `50` | Page size. |
| — | `--offset` | number | `0` | Skip count. |
| — | `--order-by` | field | `Id desc` | OData sort expression. |
| — | `--all-fields` | flag | off | Return the full API payload instead of the curated summary. |

### Examples

```bash
# List the 50 most recent jobs in the tenant
uip or jobs list

# Running jobs in a specific folder, newest first
uip or jobs list --folder-path "Shared" --state Running

# Pull only job keys and states, script-friendly
uip or jobs list --state Faulted --limit 200 \
    --output-filter 'Data[].{key:Key, state:State}'
```

### Data shape (--output json)

```json
{
  "Code": "JobList",
  "Data": [
    {
      "Key": "b2c3d4e5-0000-0000-0000-000000000001",
      "State": "Running",
      "ProcessName": "InvoiceProcessing",
      "ReleaseKey": "c3d4e5f6-0000-0000-0000-000000000001",
      "Source": "Manual",
      "Type": "Unattended",
      "Priority": "Normal",
      "Machine": "prod-worker-01",
      "MachineKey": "a1b2c3d4-0000-0000-0000-000000000001",
      "StartTime": "2025-04-15T10:30:00Z",
      "EndTime": "",
      "CreationTime": "2025-04-15T10:29:55Z"
    }
  ],
  "Pagination": { "Returned": 1, "Limit": 50, "Offset": 0, "HasMore": false }
}
```

## uip or jobs get

Fetch one job by GUID key. Returns state, input/output arguments, timing, machine info, and error details if faulted. If the job's state is `Pending`, the output also includes `PendingReasons` (the API's diagnostic report on why the job has not started — robot availability, capacity, etc.). No folder context is required.

If the job has an `OutputFile`, it is automatically downloaded to the current directory (or `--output-dir`) as `output-<job-key>.dat`. Pass `--no-download` to skip.

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<job-key>` | yes | Job key (GUID). Find it with `uip or jobs list`. |

### Options

| Short | Long | Value | Default | Description |
|---|---|---|---|---|
| `-t` | `--tenant` | name | session default | Override the tenant. |
| — | `--output-dir` | path | current dir | Directory for the downloaded `OutputFile`. |
| — | `--no-download` | flag | off | Skip automatic `OutputFile` download. |
| — | `--all-fields` | flag | off | Return the full API payload. |

### Examples

```bash
uip or jobs get b2c3d4e5-0000-0000-0000-000000000001

# Skip the output-file download (useful in read-only containers)
uip or jobs get b2c3d4e5-0000-0000-0000-000000000001 --no-download

# Extract just output arguments
uip or jobs get b2c3d4e5-0000-0000-0000-000000000001 \
    --output-filter 'Data.OutputArguments'
```

### Data shape (--output json)

```json
{
  "Code": "JobGet",
  "Data": {
    "Key": "b2c3d4e5-0000-0000-0000-000000000001",
    "State": "Successful",
    "ReleaseName": "InvoiceProcessing",
    "StartTime": "2025-04-15T10:30:00Z",
    "EndTime": "2025-04-15T10:32:11Z",
    "InputArguments": "{\"invoicePath\":\"/data/inv.pdf\"}",
    "OutputArguments": "{\"result\":\"Processed\"}",
    "HostMachineName": "prod-worker-01",
    "FolderKey": "a1b2c3d4-0000-0000-0000-000000000001"
  }
}
```

## uip or jobs start

Start one or more jobs for a process. The `<process-key>` is the GUID returned by `uip or processes list` (not `packages list`). Folder is optional — if neither `--folder-path` nor `--folder-key` is provided, it is inferred from the process.

Use `uip or packages entry-points` to see input/output argument schemas for a package version before starting.

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<process-key>` | yes | Process (release) key (GUID) from `uip or processes list`. |

### Options

#### Identity and tenant

| Short | Long | Value | Default | Description |
|---|---|---|---|---|
| `-t` | `--tenant` | name | session default | Override the tenant. |
| — | `--folder-path` | path | inferred | Folder path; inferred from the process if omitted. |
| — | `--folder-key` | GUID | inferred | Folder key; inferred from the process if omitted. |

#### Execution strategy

| Short | Long | Value | Default | Description |
|---|---|---|---|---|
| — | `--strategy` | enum | `ModernJobsCount` | `ModernJobsCount`, `All`, `Specific`, `JobsCount`. |
| — | `--jobs-count` | number | `1` | How many jobs to create (for count-based strategies). |
| — | `--runtime-type` | enum | folder config | `Unattended`, `Headless`, `Serverless`, `NonProduction`, `Development`, `TestAutomation`. |
| — | `--job-priority` | enum | — | `Low`, `Normal`, `High`. |
| — | `--reference` | text | — | Free-form reference string stored on the job. |
| — | `--run-as-me` | flag | off | Run under the caller's identity. |
| — | `--user-keys` | CSV | — | User GUIDs to run as (resolved to non-attended robots). |
| — | `--machine-keys` | CSV | — | Machine GUIDs to target. |

#### Input and attachments

| Short | Long | Value | Default | Description |
|---|---|---|---|---|
| — | `--input-arguments` | JSON | — | Inline JSON payload. Auto-offloads to `InputFile` above 10K chars. Mutually exclusive with `--input-file`. |
| — | `--input-file` | path | — | Upload a file as the job's `InputFile`. Mutually exclusive with `--input-arguments`. |
| — | `--attachment` | `[name=]path` | — | Upload a file and attach it. Repeatable. `--attachment ./doc.pdf` auto-names from the filename; `--attachment invoice=./report.pdf` sets an explicit name. |
| — | `--attachment-id` | GUID | — | Attach an existing attachment by ID. Repeatable. Find IDs with `attachments list --job-key`. |
| — | `--environment-variables` | JSON | — | Environment variables as a JSON string. Validated before submission. |

#### Waiting for completion

| Short | Long | Value | Default | Description |
|---|---|---|---|---|
| — | `--wait-for-completion` | flag | off | Poll until the job reaches `Successful`, `Faulted`, or `Stopped`. |
| — | `--timeout` | seconds | `300` | Max wait time (requires `--wait-for-completion`). |
| — | `--poll-interval` | seconds | `5` | Polling interval (requires `--wait-for-completion`). |
| — | `--output-dir` | path | current dir | Where to save `OutputFile` (requires `--wait-for-completion`). |
| — | `--no-download` | flag | off | Skip `OutputFile` download (requires `--wait-for-completion`). |

:::note
`--user-keys` resolves each user GUID to their non-attended robot in the target folder. Attended and AttendedStudioWeb robot types are filtered out — CLI-started jobs need unattended robots. If no unattended robots exist for the users in this folder, the command fails.
:::

### Examples

```bash
# Minimal — start one job for a process
uip or jobs start c3d4e5f6-0000-0000-0000-000000000001

# Start with input arguments and wait for completion
uip or jobs start c3d4e5f6-0000-0000-0000-000000000001 \
    --input-arguments '{"invoicePath":"/data/inv.pdf"}' \
    --wait-for-completion --timeout 600

# Upload a file as input and attach a supporting document
uip or jobs start c3d4e5f6-0000-0000-0000-000000000001 \
    --input-file ./payload.json \
    --attachment invoice=./report.pdf
```

### Data shape (--output json)

Without `--wait-for-completion`:

```json
{
  "Code": "JobStarted",
  "Data": {
    "Jobs": [
      {
        "Key": "b2c3d4e5-0000-0000-0000-000000000099",
        "State": "Pending",
        "ProcessName": "InvoiceProcessing",
        "Source": "Manual",
        "Type": "Unattended",
        "Priority": "Normal",
        "Machine": "",
        "StartTime": "",
        "EndTime": "",
        "CreationTime": "2025-04-15T10:29:55Z"
      }
    ]
  }
}
```

With `--wait-for-completion`, the `Code` is `JobCompleted` (or `JobFaulted` on failure) and `Data` is the same shape as `jobs get` plus a `Duration` field. If the job faulted, the process exits with code `1`.

### Verb-specific exit-code overrides

- `--wait-for-completion` + job ends in `Faulted`: exits `1` even though the command succeeded in observing the outcome.
- `--wait-for-completion` + timeout reached: exits `1` with the current job key in `Instructions` so you can poll with `jobs get`.

## uip or jobs stop

Stop one or more running or pending jobs. With a single key, respects `--strategy` (`SoftStop` or `Kill`). With multiple keys, always force-stops (kill) via the bulk API — `--strategy` is ignored in that case. No folder context needed; resolved from the first job key.

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<job-keys...>` | yes | One or more job keys (GUIDs). |

### Options

| Short | Long | Value | Default | Description |
|---|---|---|---|---|
| `-t` | `--tenant` | name | session default | Override the tenant. |
| — | `--strategy` | enum | `SoftStop` | `SoftStop` (graceful) or `Kill` (immediate). Only applies to single-key stops. |

### Examples

```bash
uip or jobs stop b2c3d4e5-0000-0000-0000-000000000001
uip or jobs stop b2c3d4e5-0000-0000-0000-000000000001 --strategy Kill
uip or jobs stop key-1 key-2 key-3   # bulk force-stop
```

### Data shape (--output json)

Single key:

```json
{
  "Code": "JobStopped",
  "Data": {
    "JobKey": "b2c3d4e5-0000-0000-0000-000000000001",
    "Strategy": "SoftStop",
    "Status": "Stop requested"
  }
}
```

Multiple keys return `Code: "JobsStopped"` with `JobKeys`, `Strategy: "Kill (force stop)"`, and a `Status` string.

## uip or jobs restart

Create a new job from a faulted or stopped job. Folder is resolved from the job key.

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<job-key>` | yes | Job key (GUID) to restart. |

### Options

| Short | Long | Value | Default | Description |
|---|---|---|---|---|
| `-t` | `--tenant` | name | session default | Override the tenant. |

### Examples

```bash
uip or jobs restart b2c3d4e5-0000-0000-0000-000000000001
uip or jobs restart b2c3d4e5-0000-0000-0000-000000000001 --output-filter 'Data.Key'
```

### Data shape (--output json)

```json
{
  "Code": "JobRestarted",
  "Data": {
    "Key": "b2c3d4e5-0000-0000-0000-000000000050",
    "State": "Pending",
    "ProcessName": "InvoiceProcessing",
    "Status": "Restart requested"
  }
}
```

## uip or jobs resume

Resume a suspended job. Jobs become suspended when they use the `Suspend` activity in a long-running workflow. Optionally pass new `--input-arguments` to continue with updated data.

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<job-key>` | yes | Job key (GUID) to resume. |

### Options

| Short | Long | Value | Default | Description |
|---|---|---|---|---|
| `-t` | `--tenant` | name | session default | Override the tenant. |
| — | `--input-arguments` | JSON | — | Replacement input arguments. |

### Examples

```bash
uip or jobs resume b2c3d4e5-0000-0000-0000-000000000001
uip or jobs resume b2c3d4e5-0000-0000-0000-000000000001 \
    --input-arguments '{"approved":true}'
```

### Data shape (--output json)

```json
{
  "Code": "JobResumed",
  "Data": {
    "Key": "b2c3d4e5-0000-0000-0000-000000000001",
    "State": "Resumed",
    "ProcessName": "ApprovalFlow",
    "Status": "Resume requested"
  }
}
```

## uip or jobs logs

Fetch robot execution logs for a job. Logs are returned newest-first. Use `--level` to filter by severity. With `--export`, the logs are exported server-side to CSV and downloaded when ready.

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<job-key>` | yes | Job key (GUID). Validated as a UUID before any API call. |

### Options

| Short | Long | Value | Default | Description |
|---|---|---|---|---|
| `-t` | `--tenant` | name | session default | Override the tenant. |
| — | `--level` | enum | — | `Fatal`, `Error`, `Warning`, `Info`, `Trace`. |
| `-l` | `--limit` | number | `50` | Page size. |
| — | `--offset` | number | `0` | Skip count. |
| — | `--export` | flag | off | Export to CSV via the server-side export API. |
| `-o` | `--output` | path | `robot-logs-<job-key>.csv` | Output CSV path. Only with `--export`. |

### Examples

```bash
uip or jobs logs b2c3d4e5-0000-0000-0000-000000000001 --level Error --limit 100
uip or jobs logs b2c3d4e5-0000-0000-0000-000000000001 --export -o ./run.csv
uip or jobs logs b2c3d4e5-0000-0000-0000-000000000001 \
    --level Error --output-filter 'Data[].Message'
```

### Data shape (--output json)

Inline mode:

```json
{
  "Code": "JobLogs",
  "Data": [
    {
      "Level": "Error",
      "TimeStamp": "2025-04-15T10:31:02Z",
      "Message": "Selector not found: ctrl[name='submit']"
    }
  ]
}
```

`--export` emits `Code: "JobLogsExported"` with `JobKey`, `FileName`, `Size`, and `ExportId`.

## uip or jobs traces

Fetch LlmOps execution traces for an agentic job — LLM interactions, tool calls, and agent decisions. Only available for Agent-type processes. Folder is resolved from the job key.

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<job-key>` | yes | Job key (GUID). |

### Options

| Short | Long | Value | Default | Description |
|---|---|---|---|---|
| `-t` | `--tenant` | name | session default | Override the tenant. |

### Examples

```bash
uip or jobs traces b2c3d4e5-0000-0000-0000-000000000001
uip or jobs traces b2c3d4e5-0000-0000-0000-000000000001 \
    --output-filter 'Data.messages'
```

### Data shape (--output json)

The raw API payload is passed through unchanged under `Data`:

```json
{
  "Code": "JobTraces",
  "Data": { "...": "raw LlmOps trace payload" }
}
```

## uip or jobs healing-data

Download healing-agent (Autopilot for Robots) recovery data as a ZIP: screenshots, UI element data, and recovery logs. Only available for jobs where the healing agent was active. The command triggers an async export, polls the export API until it finishes, then downloads the resulting ZIP.

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<job-key>` | yes | Job key (GUID). |

### Options

| Short | Long | Value | Default | Description |
|---|---|---|---|---|
| `-t` | `--tenant` | name | session default | Override the tenant. |
| — | `--directory-prefix` | prefix | — | Path prefix filter applied to exported files. |
| `-o` | `--output` | path | `healing-agent-data-<job-key>.zip` | Output ZIP path. |

### Examples

```bash
uip or jobs healing-data b2c3d4e5-0000-0000-0000-000000000001
uip or jobs healing-data b2c3d4e5-0000-0000-0000-000000000001 \
    -o ./recovery.zip
uip or jobs healing-data b2c3d4e5-0000-0000-0000-000000000001 \
    --output-filter 'Data.FileName'
```

### Data shape (--output json)

```json
{
  "Code": "JobHealingData",
  "Data": {
    "JobKey": "b2c3d4e5-0000-0000-0000-000000000001",
    "FileName": "healing-agent-data-b2c3d4e5-0000-0000-0000-000000000001.zip",
    "Size": 254318,
    "ExportId": 4711
  }
}
```

:::note
The server-side export is polled up to 30 times at 2-second intervals (60 seconds total). If it does not complete in that window, the command exits `1` with the export ID so you can retry.
:::

## uip or jobs history

Fetch state transition history for a job (`Pending` → `Running` → `Successful`/`Faulted`). Folder is resolved from the job key.

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<job-key>` | yes | Job key (GUID). |

### Options

| Short | Long | Value | Default | Description |
|---|---|---|---|---|
| `-t` | `--tenant` | name | session default | Override the tenant. |

### Examples

```bash
uip or jobs history b2c3d4e5-0000-0000-0000-000000000001
uip or jobs history b2c3d4e5-0000-0000-0000-000000000001 \
    --output-filter 'Data[].{state:State, ts:Timestamp}'
uip or jobs history b2c3d4e5-0000-0000-0000-000000000001 --output table
```

### Data shape (--output json)

```json
{
  "Code": "JobHistory",
  "Data": [
    { "State": "Pending", "Timestamp": "2025-04-15T10:29:55Z", "JobId": 1001 },
    { "State": "Running", "Timestamp": "2025-04-15T10:30:00Z", "JobId": 1001 },
    { "State": "Successful", "Timestamp": "2025-04-15T10:32:11Z", "JobId": 1001 }
  ]
}
```

## Exit codes

See [Exit codes](./exit-codes.md) for the shared contract. Verb-specific overrides:

- `jobs start --wait-for-completion` exits `1` if the observed job ends `Faulted` or the wait times out.
- `jobs healing-data` exits `1` if the server-side export does not complete within ~60 seconds.

## Related commands

- [`uip or processes`](./uip-orchestrator-processes.md) — manage the process (release) bindings that `jobs start` targets.
- [`uip or packages`](./uip-orchestrator-packages.md) — especially `packages entry-points` to discover input/output argument schemas.
- [`uip or attachments`](./uip-orchestrator-attachments.md) — list and download job attachments.
- [`uip or users`](./uip-orchestrator-users.md) — resolve usernames to keys for `--user-keys`.
- [`uip or machines`](./uip-orchestrator-machines.md) — resolve machine names to keys for `--machine-keys`.

## See also

- [Global options](./global-options.md) — `--output`, `--output-filter`, `--log-level`, `--log-file`.
- [Sessions](./concepts-sessions.md) — how tenant and folder context are resolved.
- [Your first pipeline](./first-pipeline.md) — an end-to-end walkthrough using `jobs start --wait-for-completion`.