# uip aops pipelines

> Syntax and options for `uip aops pipeline` and `uip aops execution`, which manage CICD pipelines and inspect or control their runs.

`uip aops pipeline` manages CI/CD pipelines — list, fetch, create, update, run, delete. `uip aops execution` inspects and controls one pipeline run — fetch metadata, stream logs, fetch job details, or stop it. Both call the CICD service, a separate identifier namespace from the SourceControl commands on the [connections](./uip-aops-connections.md)/[projects](./uip-aops-projects.md) pages. See the [`uip aops` overview](./uip-aops.md) for shared concepts.

:::note
**`pipeline update <id> --file` is full-replace (HTTP PUT semantics)** and expects the **`EditPipelineDto`** shape, not the `PipelineDto` that `pipeline get` returns by default. Don't pipe `pipeline get <id> > p.json` straight into `update --file p.json` — use `pipeline get <id> --for-update --output-file <path>` instead, which writes the already-transformed shape.
:::

## Synopsis

```text
uip aops pipeline list [--repository-ids <csv>] [--offset <n>] [--limit <n>] [--search <term>]
uip aops pipeline state
uip aops pipeline processes
uip aops pipeline process <process-id>
uip aops pipeline repos
uip aops pipeline get <pipeline-id> [--for-update] [--output-file <path>]
uip aops pipeline search [--name <name> | --prefix <prefix>]
uip aops pipeline create --file <path> [--telemetry-flow-id <id>]
uip aops pipeline update <pipeline-id> --file <path>
uip aops pipeline delete <pipeline-id> -y
uip aops pipeline run <pipeline-id>
uip aops pipeline save-and-run --file <path> [--telemetry-flow-id <id>]
uip aops pipeline executions <pipeline-id> [--offset <n>] [--limit <n>]
uip aops pipeline executions-bulk --ids <csv>

uip aops execution get <execution-id> [--with-arguments]
uip aops execution logs [execution-id] [--job-key <key>] [--follow] [--limit <n>] [--poll-interval <ms>] [--timeout <ms>]
uip aops execution details [execution-id] [--job-key <key>]
uip aops execution stop [execution-id] [--job-key <key>] [--wait] [--poll-interval <ms>] [--timeout <ms>]
```

## uip aops pipeline list

List pipelines visible in the active runtime environment (set via the StudioAdmin UI — switch tenants/folders there if you don't see what you expect).

### Options

| Long | Value | Description |
|---|---|---|
| `--repository-ids <csv>` | comma-separated | Narrow to one or more SC repository UUIDs (from `connection repos`). |
| `--offset <n>` | integer | Number to skip. Must be a multiple of `--limit`. Default `0`. |
| `--limit <n>` | integer | Maximum to return. Default `20`. |
| `--search <term>` | string | Server-side substring filter on pipeline name. |

### Data shape (--output json)

```json
{
  "Code": "PipelineList",
  "Data": [
    { "PipelineId": "11111111-2222-3333-4444-555555555555", "Name": "release-main", "Repository": "automation-hub", "LastRunState": "Successful", "LastRunEnd": "2026-05-05T14:23:00.000Z" }
  ]
}
```

A curated row per pipeline — use `pipeline get <id>` for the full DTO, including branch and project binding.

## uip aops pipeline state

Fetch a runtime-environment-wide snapshot of pipelines state — counts and roll-up state used by the StudioAdmin dashboard. A cheap way to confirm the runtime environment is reachable before listing or mutating.

### Data shape (--output json)

```json
{ "Code": "PipelinesState", "Data": {} }
```

## uip aops pipeline processes

List automation processes that pipelines can be bound to.

### Data shape (--output json)

```json
{
  "Code": "PipelineProcesses",
  "Data": [ { "ProcessId": "33333333-4444-5555-6666-777777777777", "Name": "InvoiceProcessing", "Description": "Daily invoice ingest", "Package": "MyOrg.Invoice.Processing", "Version": "1.2.0" } ]
}
```

A curated row per process — use the returned `ProcessId` as `PipelineDto`'s `processIdentifier` when authoring a pipeline. Drill into one with `pipeline process <process-id>` for the full DTO including arguments.

## uip aops pipeline process

Resolve a single automation process by identifier.

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<process-id>` | yes | Process identifier from `pipeline processes`. |

### Data shape (--output json)

```json
{ "Code": "PipelineProcess", "Data": {} }
```

## uip aops pipeline repos

List SourceControl repositories that have at least one pipeline.

### Data shape (--output json)

```json
{ "Code": "PipelineRepos", "Data": [] }
```

## uip aops pipeline get

Fetch a pipeline by identifier.

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<pipeline-id>` | yes | Pipeline identifier from `pipeline list`. |

### Options

| Long | Value | Description |
|---|---|---|
| `--for-update` | flag | Return the `EditPipelineDto` shape instead of the full `PipelineDto`, with server-only fields stripped — feed the result straight into `pipeline update --file` without manual transformation. |
| `--output-file <path>` | path | Also write the payload to this file as JSON (UTF-8, 2-space indent). Stdout still emits the full structured envelope. |

`--for-update` keeps the DTO's own key casing in `Data` (not PascalCased). `--output-filter` runs against `Data` as printed and is case-sensitive — with `--for-update`, match the DTO's own field names.

### Examples

```bash
uip aops pipeline get 11111111-2222-3333-4444-555555555555

uip aops pipeline get 11111111-2222-3333-4444-555555555555 --for-update --output-file ./pipeline.json
```

### Data shape (--output json)

```json
{ "Code": "PipelineGet", "Data": { "identifier": "11111111-2222-3333-4444-555555555555", "name": "release-main" } }
```

## uip aops pipeline search

Find a pipeline by name.

### Options

| Long | Value | Description |
|---|---|---|
| `--name <name>` | string | Exact-match lookup. Returns a single `PipelineDto`. |
| `--prefix <prefix>` | string | Startswith query. Returns an array. |

Exactly one of `--name`/`--prefix` is required — passing both, or neither, fails client-side before any network call.

### Examples

```bash
uip aops pipeline search --name "release-main"

uip aops pipeline search --prefix "release-"
```

### Data shape (--output json)

```json
{ "Code": "PipelineSearch", "Data": {} }
```

No match fails with `Pipeline '<name>' not found.` (for `--name`) or `No pipelines matched prefix '<prefix>'.` (for `--prefix`) rather than an empty success.

## uip aops pipeline create

Create a new pipeline from a JSON file conforming to `PipelineDto`.

### Options

| Long | Value | Required | Description |
|---|---|---|---|
| `--file <path>` | path | **yes** | JSON file containing the `PipelineDto` to create. Do not include a server-assigned `identifier`. |
| `--telemetry-flow-id <id>` | string | no | Telemetry flow id for server-side correlation. |

### Data shape (--output json)

```json
{ "Code": "PipelineCreated", "Data": { "identifier": "11111111-2222-3333-4444-555555555555" } }
```

Capture the returned `identifier` for follow-up `run`/`update`/`delete` calls. A conflict error usually means a pipeline with the same name already exists.

## uip aops pipeline update

Update an existing pipeline. **Full replace (HTTP PUT)** — any field the file omits is cleared server-side.

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<pipeline-id>` | yes | Pipeline to update. Must match the file's `identifier` field if that field is set. |

### Options

| Long | Value | Required | Description |
|---|---|---|---|
| `--file <path>` | path | **yes** | JSON file containing the `EditPipelineDto` to apply. |

Only `EditPipelineDto`'s own keys are sent — a file carrying an unrecognized key (including one that's merely miscased) is rejected outright rather than silently dropped as a partial wipe.

### Data shape (--output json)

```json
{ "Code": "PipelineUpdated", "Data": { "Pipeline": { "identifier": "11111111-2222-3333-4444-555555555555", "name": "release-main" } } }
```

`Data.Pipeline` echoes the request that was sent, not the file as read from disk.

## uip aops pipeline delete

Delete a pipeline by identifier. Permanent — running executions are not auto-stopped, but new runs are rejected immediately.

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<pipeline-id>` | yes | Pipeline identifier from `pipeline list`. |

### Options

| Long | Description |
|---|---|
| `-y, --yes` | **Required.** Confirms this irreversible operation. |

### Data shape (--output json)

```json
{ "Code": "PipelineDeleted", "Data": { "PipelineId": "11111111-2222-3333-4444-555555555555" } }
```

## uip aops pipeline run

Trigger a pipeline run. Returns 202 immediately — the run is queued asynchronously.

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<pipeline-id>` | yes | Pipeline identifier from `pipeline list`. |

### Data shape (--output json)

```json
{ "Code": "PipelineRunStarted", "Data": { "PipelineId": "11111111-2222-3333-4444-555555555555" } }
```

Use `pipeline executions <pipeline-id>` to discover the new execution id, then `execution logs --follow` to track it.

## uip aops pipeline save-and-run

Persist a pipeline DTO from JSON and immediately run it.

### Options

| Long | Value | Required | Description |
|---|---|---|---|
| `--file <path>` | path | **yes** | JSON file containing the `PipelineDto` to save and run. |
| `--telemetry-flow-id <id>` | string | no | Telemetry flow id for server-side correlation. |

### Data shape (--output json)

```json
{
  "Code": "PipelineSavedAndRunStarted",
  "Data": { "pipeline": { "identifier": "11111111-2222-3333-4444-555555555555" }, "executionId": "22222222-3333-4444-5555-666666666666" }
}
```

`executionId` is lifted out of the persisted pipeline's `latestPipelineExecution` for immediate chaining into `execution logs --follow`; it's `null` if the field is absent.

## uip aops pipeline executions

List executions for a pipeline.

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<pipeline-id>` | yes | Pipeline identifier from `pipeline list`. |

### Options

| Long | Value | Description |
|---|---|---|
| `--offset <n>` | integer | Number to skip. Must be a multiple of `--limit`. Default `0`. |
| `--limit <n>` | integer | Maximum to return. Default `20`. |

### Data shape (--output json)

```json
{
  "Code": "PipelineExecutions",
  "Data": [ { "ExecutionId": "22222222-3333-4444-5555-666666666666", "BuildNumber": "42", "CommitRef": "0123456789abcdef0123456789abcdef01234567", "State": "Successful", "EnqueuedAt": "2026-05-05T14:21:00.000Z", "EndedAt": "2026-05-05T14:23:00.000Z" } ]
}
```

Drill into one with `execution get <execution-id>` for the full DTO (run mode, triggering user, `jobExecutionIdentifier`, failure code).

## uip aops pipeline executions-bulk

Fetch metadata for several pipeline executions in one round-trip.

### Options

| Long | Value | Required | Description |
|---|---|---|---|
| `--ids <csv>` | comma-separated | **yes** | Pipeline **execution** identifiers (from `pipeline executions`) — not pipeline ids. |

### Data shape (--output json)

```json
{ "Code": "PipelineExecutionsBulk", "Data": [] }
```

## uip aops execution

Inspect and control pipeline executions. All verbs except `get` accept either an `<execution-id>` positional (the CLI looks up the underlying `jobKey` for you) or `--job-key <key>` to skip that lookup when you already have it. `get` is keyed by execution id only.

### uip aops execution get

Fetch a pipeline execution's metadata by execution id.

#### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<execution-id>` | yes | From `pipeline executions <pipeline-id>`. |

#### Options

| Long | Description |
|---|---|
| `--with-arguments` | Also fetch the runtime input arguments the pipeline ran with (parsed JSON, or the raw string if parsing fails). One extra round-trip. |

#### Data shape (--output json)

```json
{ "Code": "ExecutionGet", "Data": { "identifier": "22222222-3333-4444-5555-666666666666", "state": "Successful", "inputArguments": { "ArgumentName": "value" } } }
```

Use the returned `jobExecutionIdentifier` as `--job-key` for `logs`/`details`/`stop` to skip their auto-lookup.

### uip aops execution logs

Fetch logs for an execution.

#### Arguments

| Name | Required | Purpose |
|---|---|---|
| `[execution-id]` | conditionally | Required unless `--job-key` is set; required regardless if `--follow` is set (state polling is execution-id-keyed). |

#### Options

| Long | Value | Description |
|---|---|---|
| `--job-key <key>` | string | Use this job key directly, skipping the execution-id lookup. |
| `--follow` | flag | Stream logs until the execution reaches a terminal state (`Successful`/`Faulted`/`Stopped`). |
| `--limit <n>` | integer | Page size per log fetch. Default `200`. |
| `--poll-interval <ms>` | integer | Interval between polls when `--follow` is set. Default `2000`. |
| `--timeout <ms>` | integer | Maximum time to follow before giving up. Default `1800000` (30 minutes). |

Without `--follow`: prints the current log slice and exits (`Code: "ExecutionLogs"`). With `--follow`: log lines stream to **stderr** as they arrive (not subject to `--log-level`, not captured by `--log-file` — redirect stderr explicitly to keep them), and stdout emits a final envelope with the terminal state and line count (`Code: "ExecutionLogsFollowed"`).

#### Examples

```bash
uip aops execution logs 22222222-3333-4444-5555-666666666666

uip aops execution logs 22222222-3333-4444-5555-666666666666 --follow 2> build.log
```

#### Data shape (--output json)

```json
{ "Code": "ExecutionLogsFollowed", "Data": { "state": "Successful", "lineCount": 42 } }
```

### uip aops execution details

Fetch the underlying job-execution detail document — robot, machine, release, and host context. Useful when triaging a failure to see which runner it ran on.

#### Arguments

| Name | Required | Purpose |
|---|---|---|
| `[execution-id]` | conditionally | Required unless `--job-key` is set. |

#### Options

| Long | Value | Description |
|---|---|---|
| `--job-key <key>` | string | Use this job key directly, skipping the execution-id lookup. |

#### Data shape (--output json)

```json
{ "Code": "ExecutionDetails", "Data": {} }
```

### uip aops execution stop

Request a stop on a pipeline execution. **Idempotent** — calling it on an already-terminal execution returns the current state without erroring.

#### Arguments

| Name | Required | Purpose |
|---|---|---|
| `[execution-id]` | conditionally | Required unless `--job-key` is set; required regardless if `--wait` is set. |

#### Options

| Long | Value | Description |
|---|---|---|
| `--job-key <key>` | string | Use this job key directly, skipping the execution-id lookup. |
| `--wait` | flag | Poll until the execution settles to terminal instead of returning immediately. |
| `--poll-interval <ms>` | integer | Interval between polls when `--wait` is set. Default `2000`. |
| `--timeout <ms>` | integer | Maximum time to wait when `--wait` is set. Default `300000` (5 minutes). |

#### Examples

```bash
uip aops execution stop 22222222-3333-4444-5555-666666666666

uip aops execution stop 22222222-3333-4444-5555-666666666666 --wait
```

#### Data shape (--output json)

```json
{ "Code": "ExecutionStopRequested", "Data": { "identifier": "22222222-3333-4444-5555-666666666666", "state": "Stopping" } }
```

With `--wait`, the final envelope is `Code: "ExecutionStopped"` with the settled `state`. Calling `stop` on an execution that's already terminal returns `Code: "ExecutionAlreadyTerminal"` instead of re-issuing the stop.

## Related

- [`uip aops`](./uip-aops.md) — overview and concepts.
- [`connections`](./uip-aops-connections.md) — discover the repository a pipeline builds from.
- [`projects`](./uip-aops-projects.md) — discover the process a pipeline binds to.

## See also

- [Global options](./global-options.md)
- [Exit codes](./exit-codes.md)