# kindgi flows

> Manage flow registrations and which version runs where

## `kindgi flows`

**Synopsis**

```sh signature
kindgi flows <command>
```

Manage flow registrations and which version runs where.

**Commands**

| Command                                                                                                              | Description                                                                                                                                                                    |
| -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [`kindgi flows list`](https://docs.kindgi.com/v0.4.0/reference/cli/flows.md#kindgi-flows-list)                       | List registered flows (the latest version of each).                                                                                                                            |
| [`kindgi flows get`](https://docs.kindgi.com/v0.4.0/reference/cli/flows.md#kindgi-flows-get)                         | Fetch a registered flow: its latest version, or the version given.                                                                                                             |
| [`kindgi flows publish`](https://docs.kindgi.com/v0.4.0/reference/cli/flows.md#kindgi-flows-publish)                 | Register a flow definition at its version.                                                                                                                                     |
| [`kindgi flows unregister`](https://docs.kindgi.com/v0.4.0/reference/cli/flows.md#kindgi-flows-unregister)           | Unregister a specific flow version: new runs of it are refused; `kindgi flows reinstate` brings it back.                                                                       |
| [`kindgi flows versions`](https://docs.kindgi.com/v0.4.0/reference/cli/flows.md#kindgi-flows-versions)               | List the registered versions of a flow.                                                                                                                                        |
| [`kindgi flows reinstate`](https://docs.kindgi.com/v0.4.0/reference/cli/flows.md#kindgi-flows-reinstate)             | Bring back an unregistered flow version.                                                                                                                                       |
| [`kindgi flows pinned`](https://docs.kindgi.com/v0.4.0/reference/cli/flows.md#kindgi-flows-pinned)                   | Show the version of this flow that a run naming none would use in a project (or an org, or with neither the tenant), and why: a pinned version (with its scope) or the latest. |
| [`kindgi flows pinned-versions`](https://docs.kindgi.com/v0.4.0/reference/cli/flows.md#kindgi-flows-pinned-versions) | List every scope with a version of this flow pinned.                                                                                                                           |
| [`kindgi flows pin`](https://docs.kindgi.com/v0.4.0/reference/cli/flows.md#kindgi-flows-pin)                         | Pin a version of this flow for a scope, or move the scope's pin to it: its runs that name no version use it, from the next run.                                                |
| [`kindgi flows unpin`](https://docs.kindgi.com/v0.4.0/reference/cli/flows.md#kindgi-flows-unpin)                     | Remove a scope's own pin of this flow: its runs use the next scope up's pin, or the latest when nothing is pinned.                                                             |
| [`kindgi flows pin-history`](https://docs.kindgi.com/v0.4.0/reference/cli/flows.md#kindgi-flows-pin-history)         | The history of what was pinned or unpinned.                                                                                                                                    |

**See also**

- [Write a flow](https://docs.kindgi.com/v0.4.0/guides/flows/write-a-flow.md)
- [Flows](https://docs.kindgi.com/v0.4.0/guides/flows.md)

### `kindgi flows list`

**Synopsis**

```sh signature
kindgi flows list [--name=<prefix>] [--include-retired] [--limit=<n>] [--cursor=<c>]
```

List registered flows (the latest version of each).

**Options**

| Option              | Default              | Description                                                                                            |
| ------------------- | -------------------- | ------------------------------------------------------------------------------------------------------ |
| `--cursor <value>`  | none                 | Resume after this cursor, from the previous page's `nextCursor`.                                       |
| `--include-retired` | off                  | Include retired flows (every version unregistered), each as its highest version with `unregisteredAt`. |
| `--limit <value>`   | `25` (at most `100`) | The most to return (default 25, at most 100).                                                          |
| `--name <value>`    | none                 | Only flows whose id starts with this.                                                                  |

Every command also takes the [global flags](https://docs.kindgi.com/v0.4.0/reference/cli.md#global-flags).

**Examples**

List registered flows, retired ones too.

```sh
kindgi flows list --include-retired
```

**See also**

- [Write a flow](https://docs.kindgi.com/v0.4.0/guides/flows/write-a-flow.md)
- [Flows](https://docs.kindgi.com/v0.4.0/guides/flows.md)
- [`kindgi flows`](https://docs.kindgi.com/v0.4.0/reference/cli/flows.md#kindgi-flows)

### `kindgi flows get`

**Synopsis**

```sh signature
kindgi flows get <flow-id> [<version>]
```

Fetch a registered flow: its latest version, or the version given.

**Options**

Every command also takes the [global flags](https://docs.kindgi.com/v0.4.0/reference/cli.md#global-flags).

**Examples**

Fetch a flow's latest version.

```sh
kindgi flows get acme.nightly-digest
```

Fetch one version of a flow.

```sh
kindgi flows get acme.nightly-digest 0.1.0
```

**See also**

- [Write a flow](https://docs.kindgi.com/v0.4.0/guides/flows/write-a-flow.md)
- [Flows](https://docs.kindgi.com/v0.4.0/guides/flows.md)
- [`kindgi flows`](https://docs.kindgi.com/v0.4.0/reference/cli/flows.md#kindgi-flows)

### `kindgi flows publish`

**Synopsis**

```sh signature
kindgi flows publish --spec=<json-or-@file> [--project=<project-id>]
```

Register a flow definition at its version. The server checks it: no cycles, every node and edge resolves.

**Options**

| Option              | Default                      | Description                                                                         |
| ------------------- | ---------------------------- | ----------------------------------------------------------------------------------- |
| `--project <value>` | the tenant's default project | The project to register the flow in, by id (default: the tenant's default project). |
| `--spec <value>`    | required                     | The flow definition as JSON, or `@<file>` to read it from a file. Required.         |

Every command also takes the [global flags](https://docs.kindgi.com/v0.4.0/reference/cli.md#global-flags).

**Examples**

Register a flow definition from a file.

```sh
kindgi flows publish --spec=@flows/acme.nightly-digest.json
```

**See also**

- [Write a flow](https://docs.kindgi.com/v0.4.0/guides/flows/write-a-flow.md)
- [Flows](https://docs.kindgi.com/v0.4.0/guides/flows.md)
- [`kindgi flows`](https://docs.kindgi.com/v0.4.0/reference/cli/flows.md#kindgi-flows)

### `kindgi flows unregister`

**Synopsis**

```sh signature
kindgi flows unregister <flow-id> <version>
```

Unregister a specific flow version: new runs of it are refused; `kindgi flows reinstate` brings it back.

**Options**

Every command also takes the [global flags](https://docs.kindgi.com/v0.4.0/reference/cli.md#global-flags).

**Examples**

Unregister a flow version: new runs of it are refused.

```sh
kindgi flows unregister acme.nightly-digest 0.1.0
```

**See also**

- [Write a flow](https://docs.kindgi.com/v0.4.0/guides/flows/write-a-flow.md)
- [Flows](https://docs.kindgi.com/v0.4.0/guides/flows.md)
- [`kindgi flows`](https://docs.kindgi.com/v0.4.0/reference/cli/flows.md#kindgi-flows)

### `kindgi flows versions`

**Synopsis**

```sh signature
kindgi flows versions <flow-id> [--include-unregistered] [--limit=<n>] [--cursor=<c>]
```

List the registered versions of a flow.

**Options**

| Option                   | Default              | Description                                                                       |
| ------------------------ | -------------------- | --------------------------------------------------------------------------------- |
| `--cursor <value>`       | none                 | Resume after this cursor, from the previous page's `nextCursor`.                  |
| `--include-unregistered` | off                  | Include unregistered versions (each with `unregisteredAt`), a retired flow's too. |
| `--limit <value>`        | `25` (at most `100`) | The most to return (default 25, at most 100).                                     |

Every command also takes the [global flags](https://docs.kindgi.com/v0.4.0/reference/cli.md#global-flags).

**Examples**

List a flow's versions, unregistered ones too.

```sh
kindgi flows versions acme.nightly-digest --include-unregistered
```

**See also**

- [Write a flow](https://docs.kindgi.com/v0.4.0/guides/flows/write-a-flow.md)
- [Flows](https://docs.kindgi.com/v0.4.0/guides/flows.md)
- [`kindgi flows`](https://docs.kindgi.com/v0.4.0/reference/cli/flows.md#kindgi-flows)

### `kindgi flows reinstate`

**Synopsis**

```sh signature
kindgi flows reinstate <flow-id> <version>
```

Bring back an unregistered flow version.

**Options**

Every command also takes the [global flags](https://docs.kindgi.com/v0.4.0/reference/cli.md#global-flags).

**Examples**

Bring back an unregistered flow version.

```sh
kindgi flows reinstate acme.nightly-digest 0.1.0
```

**See also**

- [Write a flow](https://docs.kindgi.com/v0.4.0/guides/flows/write-a-flow.md)
- [Flows](https://docs.kindgi.com/v0.4.0/guides/flows.md)
- [`kindgi flows`](https://docs.kindgi.com/v0.4.0/reference/cli/flows.md#kindgi-flows)

### `kindgi flows pinned`

**Synopsis**

```sh signature
kindgi flows pinned <flow-id> [--project=<project-id> | --org=<org-id>]
```

Show the version of this flow that a run naming none would use in a project (or an org, or with neither the tenant), and why: a pinned version (with its scope) or the latest.

**Options**

| Option              | Default | Description                                                   |
| ------------------- | ------- | ------------------------------------------------------------- |
| `--org <value>`     | none    | An org, by id: its pin, else the tenant's.                    |
| `--project <value>` | none    | A project, by id: its pin, else its org's, else the tenant's. |

Every command also takes the [global flags](https://docs.kindgi.com/v0.4.0/reference/cli.md#global-flags).

**Examples**

Show the version of the flow that a run in a project would use, and why.

```sh
kindgi flows pinned acme.nightly-digest --project=<project-id>
```

**See also**

- [Write a flow](https://docs.kindgi.com/v0.4.0/guides/flows/write-a-flow.md)
- [Flows](https://docs.kindgi.com/v0.4.0/guides/flows.md)
- [`kindgi flows`](https://docs.kindgi.com/v0.4.0/reference/cli/flows.md#kindgi-flows)

### `kindgi flows pinned-versions`

**Synopsis**

```sh signature
kindgi flows pinned-versions <flow-id>
```

List every scope with a version of this flow pinned.

**Options**

Every command also takes the [global flags](https://docs.kindgi.com/v0.4.0/reference/cli.md#global-flags).

**Examples**

List every scope with a pinned version of the flow.

```sh
kindgi flows pinned-versions acme.nightly-digest
```

**See also**

- [Write a flow](https://docs.kindgi.com/v0.4.0/guides/flows/write-a-flow.md)
- [Flows](https://docs.kindgi.com/v0.4.0/guides/flows.md)
- [`kindgi flows`](https://docs.kindgi.com/v0.4.0/reference/cli/flows.md#kindgi-flows)

### `kindgi flows pin`

**Synopsis**

```sh signature
kindgi flows pin <flow-id> <version> (--tenant | --org=<org-id> | --project=<project-id>) [--reason=<text>]
```

Pin a version of this flow for a scope, or move the scope's pin to it: its runs that name no version use it, from the next run. Pinning the version already pinned there changes nothing. A tenant- or org-wide pin of a flow in an environment order is refused (`409 pin-scope-spans-environments`): pin it per project.

**Options**

| Option                      | Default                                           | Description                                                |
| --------------------------- | ------------------------------------------------- | ---------------------------------------------------------- |
| `--idempotency-key <value>` | none                                              | A retry with the same key returns the first call's result. |
| `--org <value>`             | required: one of `--tenant`, `--org`, `--project` | An org, by id.                                             |
| `--project <value>`         | required: one of `--tenant`, `--org`, `--project` | A project, by id.                                          |
| `--reason <value>`          | none                                              | Why, kept on the record.                                   |
| `--tenant`                  | required: one of `--tenant`, `--org`, `--project` | The whole tenant.                                          |

Every command also takes the [global flags](https://docs.kindgi.com/v0.4.0/reference/cli.md#global-flags).

**Examples**

Pin a version of the flow in a project, before publishing a new one to try.

```sh
kindgi flows pin acme.nightly-digest 0.1.0 --project=<project-id> --reason='Keep 0.1.0 while 0.2.0 is tried'
```

**See also**

- [Write a flow](https://docs.kindgi.com/v0.4.0/guides/flows/write-a-flow.md)
- [Flows](https://docs.kindgi.com/v0.4.0/guides/flows.md)
- [`kindgi flows`](https://docs.kindgi.com/v0.4.0/reference/cli/flows.md#kindgi-flows)

### `kindgi flows unpin`

**Synopsis**

```sh signature
kindgi flows unpin <flow-id> (--tenant | --org=<org-id> | --project=<project-id>) [--reason=<text>]
```

Remove a scope's own pin of this flow: its runs use the next scope up's pin, or the latest when nothing is pinned.

**Options**

| Option                      | Default                                           | Description                                                |
| --------------------------- | ------------------------------------------------- | ---------------------------------------------------------- |
| `--idempotency-key <value>` | none                                              | A retry with the same key returns the first call's result. |
| `--org <value>`             | required: one of `--tenant`, `--org`, `--project` | An org, by id.                                             |
| `--project <value>`         | required: one of `--tenant`, `--org`, `--project` | A project, by id.                                          |
| `--reason <value>`          | none                                              | Why, kept on the record.                                   |
| `--tenant`                  | required: one of `--tenant`, `--org`, `--project` | The whole tenant.                                          |

Every command also takes the [global flags](https://docs.kindgi.com/v0.4.0/reference/cli.md#global-flags).

**Examples**

Remove a project's own pin of the flow.

```sh
kindgi flows unpin acme.nightly-digest --project=<project-id>
```

**See also**

- [Write a flow](https://docs.kindgi.com/v0.4.0/guides/flows/write-a-flow.md)
- [Flows](https://docs.kindgi.com/v0.4.0/guides/flows.md)
- [`kindgi flows`](https://docs.kindgi.com/v0.4.0/reference/cli/flows.md#kindgi-flows)

### `kindgi flows pin-history`

**Synopsis**

```sh signature
kindgi flows pin-history <command>
```

The history of what was pinned or unpinned.

**Commands**

| Command                                                                                                                | Description                                                      |
| ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| [`kindgi flows pin-history list`](https://docs.kindgi.com/v0.4.0/reference/cli/flows.md#kindgi-flows-pin-history-list) | List this flow's pin history, newest first: every pin and unpin. |

**See also**

- [Write a flow](https://docs.kindgi.com/v0.4.0/guides/flows/write-a-flow.md)
- [Flows](https://docs.kindgi.com/v0.4.0/guides/flows.md)
- [`kindgi flows`](https://docs.kindgi.com/v0.4.0/reference/cli/flows.md#kindgi-flows)

#### `kindgi flows pin-history list`

**Synopsis**

```sh signature
kindgi flows pin-history list <flow-id> [--limit=<n>] [--cursor=<c>]
```

List this flow's pin history, newest first: every pin and unpin.

**Options**

| Option             | Default              | Description                                                      |
| ------------------ | -------------------- | ---------------------------------------------------------------- |
| `--cursor <value>` | none                 | Resume after this cursor, from the previous page's `nextCursor`. |
| `--limit <value>`  | `25` (at most `100`) | The most to return (default 25, at most 100).                    |

Every command also takes the [global flags](https://docs.kindgi.com/v0.4.0/reference/cli.md#global-flags).

**Examples**

List the flow's pins and unpins, newest first.

```sh
kindgi flows pin-history list acme.nightly-digest --limit=10
```

**See also**

- [Write a flow](https://docs.kindgi.com/v0.4.0/guides/flows/write-a-flow.md)
- [Flows](https://docs.kindgi.com/v0.4.0/guides/flows.md)
- [`kindgi flows pin-history`](https://docs.kindgi.com/v0.4.0/reference/cli/flows.md#kindgi-flows-pin-history)