---
# @generated by sylphx-gen. Do not edit.
title: "sylphx workflows distributed_runs"
description: "The sylphx workflows distributed_runs commands of Sylphx Workflows: every verb, with its argument, its flags and a run line."
type: reference
product: jobs
summary: "Every sylphx workflows distributed_runs command: its argument, its flags and a run line."
updated: 2026-09-28
nav: false
---

> **This method is not served on the public API.** `api.sylphx.com` does not route this call: its backend is not deployed behind the public API, or does not implement the call. This page documents the contract. It is kept out of the sidebar and of search engines.

The `distributed_runs` commands of Sylphx Workflows, as the CLI spells them: the same
calls as [the `distributed_runs` API page](/docs/api/distributed_runs), typed for the
shell. [Install, sign in and the grammar](/docs/cli) are on the CLI index.

## run

Starts a run of a distributed job. The same `Idempotency-Key` returns the same run for 24h.

**`ID`** — The id segment of the new Resource's name; the server assigns one when omitted.

**CLI**

```bash
sylphx workflows distributed-runs run --parent orgs/acme/projects/shop/envs/production/distributed_jobs/distributed-job
```

`POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/distributed_jobs/distributed-job/distributed_runs` · scope `workflows:run` · effect `write` · [Request, response and examples](/docs/api/distributed_runs/create)

**Flags**

| Flag | Type | What it does |
| --- | --- | --- |
| `--parent` | `string` | The parent to create in; defaults to the linked project or the key's scope. |
| `--meta.labels` | `key=value` | Caller-writable, indexed labels (AIP-122 label rules). Repeat the flag for each value. |
| `--meta.annotations` | `key=value` | Caller-writable, unindexed annotations. Repeat the flag for each value. |
| `--meta.display-name` | `string` | Caller-writable human-readable name. |
| `--args` | `string` | Arguments of every worker of this run (the job's when empty). Repeat the flag for each value. |
| `--env` | `key=value` | Environment overrides of this run. Repeat the flag for each value. |
| `--shards` | `json` | The run's own shards (the customer's planner output); without them the job's `shard_count` makes index-only shards. Repeat the flag for each value. |
| `--open-manifest` | `bool` | Keep the manifest open: `:addShards` appends until it is closed. |
| `--dry-run` | `bool` | Validate and print the result without writing (validate_only). |

## get

Gets a distributed run: its state, shard and worker counts, and usage.

**`NAME`** — the resource's name; a bare id is enough below the linked
project.

**CLI**

```bash
sylphx workflows distributed-runs get orgs/acme/projects/shop/envs/production/distributed_jobs/distributed-job/distributed_runs/distributed-run
```

`GET https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/distributed_jobs/distributed-job/distributed_runs/distributed-run` · scope `workflows:read` · effect `read` · [Request, response and examples](/docs/api/distributed_runs/get)

## list

Lists a distributed job's runs, newest first.

**`PARENT`** — optional: the CLI fills it from the linked project or the
key's scope when it is left out.

**CLI**

```bash
sylphx workflows distributed-runs list orgs/acme/projects/shop/envs/production/distributed_jobs/distributed-job
```

`GET https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/distributed_jobs/distributed-job/distributed_runs` · scope `workflows:read` · effect `read` · [Request, response and examples](/docs/api/distributed_runs/list)

**Flags**

| Flag | Type | What it does |
| --- | --- | --- |
| `--page-size` | `int` | At most this many; default 50, clamped to 1000. |
| `--page-token` | `string` | `next_page_token` of the previous page. |
| `--filter` | `string` | AIP-160 filter over labels and filterable fields. |
| `--order-by` | `string` | AIP-132 ordering over filterable fields. |

## cancel

Cancels a distributed run: workers get SIGTERM and 30s, then leases are released; finished shards are kept. A closed run fails with INVALID_STATE.

**`NAME`** — the resource's name; a bare id is enough below the linked
project.

**CLI**

```bash
sylphx workflows distributed-runs cancel orgs/acme/projects/shop/envs/production/distributed_jobs/distributed-job/distributed_runs/distributed-run --yes
```

`POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/distributed_jobs/distributed-job/distributed_runs/distributed-run:cancel` · scope `workflows:run` · effect `destructive` · [Request, response and examples](/docs/api/distributed_runs/cancel)

**Flags**

| Flag | Type | What it does |
| --- | --- | --- |
| `--reason` | `string` | Why the run is cancelled. |
| `--yes` | `bool` | Do not ask before this destructive call. |

## add-shards

Appends shards to a run started with an open manifest; `close` ends the manifest, and the run ends once those shards are done.

**`NAME`** — the resource's name; a bare id is enough below the linked
project.

**CLI**

```bash
sylphx workflows distributed-runs add-shards orgs/acme/projects/shop/envs/production/distributed_jobs/distributed-job/distributed_runs/distributed-run
```

`POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/distributed_jobs/distributed-job/distributed_runs/distributed-run:addShards` · scope `workflows:run` · effect `write` · [Request, response and examples](/docs/api/distributed_runs/add_shards)

**Flags**

| Flag | Type | What it does |
| --- | --- | --- |
| `--shards` | `json` | The shards to append. Repeat the flag for each value. |
| `--close` | `bool` | Close the manifest: the run ends once its shards are done. |

## read-shards

Reads a page of the run's shards, in queue order.

**`NAME`** — the resource's name; a bare id is enough below the linked
project.

**CLI**

```bash
sylphx workflows distributed-runs read-shards orgs/acme/projects/shop/envs/production/distributed_jobs/distributed-job/distributed_runs/distributed-run
```

`GET https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/distributed_jobs/distributed-job/distributed_runs/distributed-run:readShards` · scope `workflows:read` · effect `read` · [Request, response and examples](/docs/api/distributed_runs/read_shards)

**Flags**

| Flag | Type | What it does |
| --- | --- | --- |
| `--page-size` | `int` | At most this many; default 100, clamped to 1000. |
| `--page-token` | `string` | `next_page_token` of the previous page. |
| `--state-filter` | `enum` | Only shards in this state; unset reads every shard. One of `pending`, `leased`, `succeeded`, `failed`. |

## read-workers

Reads a page of the run's workers.

**`NAME`** — the resource's name; a bare id is enough below the linked
project.

**CLI**

```bash
sylphx workflows distributed-runs read-workers orgs/acme/projects/shop/envs/production/distributed_jobs/distributed-job/distributed_runs/distributed-run
```

`GET https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/distributed_jobs/distributed-job/distributed_runs/distributed-run:readWorkers` · scope `workflows:read` · effect `read` · [Request, response and examples](/docs/api/distributed_runs/read_workers)

**Flags**

| Flag | Type | What it does |
| --- | --- | --- |
| `--page-size` | `int` | At most this many; default 100, clamped to 1000. |
| `--page-token` | `string` | `next_page_token` of the previous page. |