> For the complete documentation index, see [llms.txt](https://docs.pipekit.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pipekit.io/reference/cli/commands.md).

# Commands

The Pipekit CLI's core commands: login, submit, get run, get workflow-node, list, stop/terminate/restart/retry, logs, update cluster, import workflows.

Every command listed here is also doable via the [REST API](/reference/rest-api.md), the [Python SDK](/reference/python-sdk.md), and the UI. For the MCP Server (LLM client integration), see [AI > Setup](/ai/setup.md).

## Log in

```bash
pipekit login
```

You'll be prompted to pick either username/password or SSO, depending on how your account was created. After login, the CLI stores your access token at `~/.pipekit/token` (override via `PIPEKIT_CONFIG_DIR`).

For non-interactive login (CI, containers), see [Advanced > Non-interactive login](/reference/cli/advanced.md#non-interactive-login).

## Submit a workflow

```bash
pipekit submit --cluster-name=<cluster> --namespace=<ns> path/to/workflow.yaml
```

If no Pipe with the workflow's `generateName` exists on the cluster, Pipekit creates one. Subsequent submissions of the same workflow add new Runs to the existing Pipe. For the Pipe / Run model, see [Concepts > Workflow vs Pipe vs Run](/concepts/workflow-vs-pipe-vs-run.md).

| Flag             | Shorthand | Type                    | Description                                                  |
| ---------------- | --------- | ----------------------- | ------------------------------------------------------------ |
| `--namespace`    | `-n`      | string                  | Name of the namespace to submit the workflow to.             |
| `--cluster-name` | `-c`      | string                  | Name of the cluster to submit the workflow to. **Required.** |
| `--open-ui`      |           | bool                    | Open the UI for the submitted workflow.                      |
| `--parameter`    | `-p`      | stringArray (key=value) | Pass input parameter(s).                                     |
| `--wait`         | `-w`      | bool                    | Wait for the submitted workflow to complete.                 |
| `--pipe-name`    | `-d`      | string                  | Name of the Pipe to submit the workflow to.                  |
| `--json`         |           | bool                    | Output the run details in JSON format.                       |

## Get information about a Run

```bash
pipekit get run --run-uuid=<uuid>
```

You can also look up a Run by `(cluster, namespace, workflow-name)`:

```bash
pipekit get run --cluster-name=clusterA --namespace=default --workflow-name=workflowA
```

If multiple Runs match, the latest one is returned.

| Flag              | Shorthand | Type   | Description                                             |
| ----------------- | --------- | ------ | ------------------------------------------------------- |
| `--run-uuid`      | `-r`      | string | Run UUID of the workflow you want to get.               |
| `--cluster-name`  | `-c`      | string | Name of the cluster where the workflow is located.      |
| `--namespace`     | `-n`      | string | Kubernetes namespace where the workflow is/was running. |
| `--workflow-name` | `-w`      | string | Name of the workflow.                                   |

## Get information about one workflow node

A workflow node is one entry in a Run's graph. This command reports the node's status and the Kubernetes node it ran on, including that machine's instance type.

```bash
pipekit get workflow-node --run-uuid=<uuid> --node-id=<id>
```

`--node-id` accepts the node ID, its name, or its display name. A name can match more than one node, which happens when a step is retried or runs inside a loop. The command then lists the matching node IDs and asks you to pick one.

`Kubernetes Node` and `Instance Type` read `-` for a node that does not run a pod, such as a DAG, Steps, or StepGroup node. `Instance Type` also reads `-` in these cases:

* The cluster runs a Pipekit Agent that does not report the instance type.
* The Kubernetes node has no `node.kubernetes.io/instance-type` label.
* Cluster scraping is turned off with `features.metrics.scrapeCluster`.
* Pipekit holds no metrics for that node, or the metrics query failed.
* Two machines used the same Kubernetes node name around the same time, so Pipekit cannot tell which one ran the step.

| Flag         | Shorthand | Type   | Description                                                  |
| ------------ | --------- | ------ | ------------------------------------------------------------ |
| `--run-uuid` | `-r`      | string | **Required.** Run UUID of the Run the node belongs to.       |
| `--node-id`  |           | string | **Required.** ID, name or display name of the workflow node. |

## List clusters, Pipes, and Runs

### List clusters

```bash
pipekit list clusters
```

### List Pipes

```bash
pipekit list pipes --cluster-name=<cluster>
```

| Flag             | Shorthand | Type   | Description                                     |
| ---------------- | --------- | ------ | ----------------------------------------------- |
| `--all`          | `-A`      | bool   | Get all Pipes, both enabled and disabled.       |
| `--cluster-name` | `-c`      | string | Name of the cluster to list from. **Required.** |
| `--enabled`      |           | bool   | Enabled/disabled switch (default true).         |

### List Runs

```bash
pipekit list runs --cluster-name=<cluster>
```

| Flag             | Shorthand | Type        | Description                                         |
| ---------------- | --------- | ----------- | --------------------------------------------------- |
| `--cluster-name` | `-c`      | string      | Name of the cluster to list from.                   |
| `--all`          | `-A`      | bool        | Get all Runs, regardless of status.                 |
| `--statuses`     | `-s`      | stringArray | Get Runs with a given status (defaults to running). |

## Run actions: stop, terminate, restart, retry

```bash
# Stop a running workflow (exit handlers complete)
pipekit stop --run-uuid=<uuid>

# Terminate a running workflow immediately (no exit handlers)
pipekit terminate --run-uuid=<uuid>

# Resubmit a workflow with the same parameters
pipekit restart --run-uuid=<uuid>

# Rerun only the failed steps of a finished workflow
pipekit retry --run-uuid=<uuid>
```

`stop` and `terminate` take the same flag:

| Flag         | Shorthand | Type   | Description                                                                |
| ------------ | --------- | ------ | -------------------------------------------------------------------------- |
| `--run-uuid` | `-r`      | string | Run UUID of the running workflow you want to stop/terminate. **Required.** |

`restart` takes:

| Flag         | Shorthand | Type   | Description                                            |
| ------------ | --------- | ------ | ------------------------------------------------------ |
| `--run-uuid` | `-r`      | string | Run UUID of the run you want to restart. **Required.** |
| `--open-ui`  |           | bool   | Open the UI of the resubmitted workflow.               |
| `--wait`     | `-w`      | bool   | Wait for the workflow to complete.                     |

### Choose between restart and retry

`restart` runs the whole workflow again from the beginning. `retry` keeps the steps that already succeeded and reruns only the failed ones, which is faster on large workflows where a few steps failed.

If you come from the Argo CLI, `pipekit restart` matches `argo resubmit` and `pipekit retry` matches `argo retry`.

### Retry a workflow

Name the run either by its run UUID, or by workflow name together with the cluster and namespace:

```bash
# Retry every failed step, by workflow name
pipekit retry my-wf --cluster-name=production --namespace=argo

# Retry every failed step, by run UUID
pipekit retry --run-uuid=<uuid>

# Reset one node and every node below it
pipekit retry --run-uuid=<uuid> --node-field-selector=id=5

# Rerun a node that already succeeded
pipekit retry --run-uuid=<uuid> --node-field-selector=id=5 --restart-successful

# Override parameters and wait for the result
pipekit retry my-wf -c production -n argo -p message=modified --wait
```

`retry` takes:

| Flag                    | Shorthand | Type        | Description                                                                                  |
| ----------------------- | --------- | ----------- | -------------------------------------------------------------------------------------------- |
| `--run-uuid`            | `-r`      | string      | Run UUID of the run you want to retry. Use this instead of a workflow name.                  |
| `--cluster-name`        | `-c`      | string      | Cluster the workflow ran on. Required with a workflow name.                                  |
| `--namespace`           | `-n`      | string      | Kubernetes namespace. Required with a workflow name.                                         |
| `--node-field-selector` |           | string      | Nodes to reset, for example `id=5`. Leave it out to retry every failed node.                 |
| `--restart-successful`  |           | bool        | Also rerun nodes that already succeeded and match `--node-field-selector`.                   |
| `--parameter`           | `-p`      | stringArray | Parameter to override on the retried workflow, as `KEY=VALUE`. Repeat the flag for each one. |
| `--wait`                | `-w`      | bool        | Wait for the workflow to complete.                                                           |

{% hint style="info" %}
Retry reads the step status from the workflow. If your Argo Workflows controller offloads that status to a database, give the Pipekit agent access to that database. Without it, the retry fails with an error.
{% endhint %}

## View pod logs

```bash
pipekit logs --run-uuid=<uuid> --follow
```

Filter by pod and container name; follow the stream to tail logs as they're produced.

| Flag          | Shorthand | Type   | Description                                |
| ------------- | --------- | ------ | ------------------------------------------ |
| `--run-uuid`  | `-r`      | string | UUID of the Run. **Required.**             |
| `--container` | `-c`      | string | Name of the container to filter logs by.   |
| `--pod`       | `-p`      | string | Name of the pod to filter logs by.         |
| `--node-id`   | `-n`      | string | ID of the workflow node to filter logs by. |
| `--follow`    | `-f`      | bool   | Follow log stream until the Run finishes.  |

## Update a cluster

```bash
pipekit update cluster <cluster-name> --status=active
pipekit update cluster <cluster-name> --name=production --description="Production cluster"
```

Requires admin permissions.

| Argument/Flag   | Type   | Description                                               |
| --------------- | ------ | --------------------------------------------------------- |
| `cluster-name`  | string | Name of the cluster to update. **Required (positional).** |
| `--name`        | string | New name for the cluster.                                 |
| `--description` | string | New description for the cluster.                          |
| `--status`      | string | New status for the cluster (`active` or `inactive`).      |

## Import from Workflow Archive

Admins can import archived workflows from an [Argo Workflow Archive](https://argo-workflows.readthedocs.io/en/stable/workflow-archive/) into Pipekit:

```bash
pipekit import workflows --cluster-name=<cluster>
```

{% hint style="warning" %}
The import of [Workflow Archive Logs](https://argo-workflows.readthedocs.io/en/stable/configure-archive-logs/) is not supported.
{% endhint %}

| Flag                  | Shorthand | Type    | Description                                                                           |
| --------------------- | --------- | ------- | ------------------------------------------------------------------------------------- |
| `--cluster-name`      | `-c`      | string  | Name of the cluster to assign workflows to. **Required.**                             |
| `--argoServerURI`     |           | string  | Argo Server URI (defaults to `localhost:2746`).                                       |
| `--argoAuthToken`     |           | string  | Argo Server authentication token.                                                     |
| `--batchSize`         |           | integer | Number of workflows to fetch from the Workflow Archive per API call (defaults to 10). |
| `--argoServerSubPath` |           | string  | Sub-path used when connecting to Argo Server.                                         |
| `--insecure`          | `-k`      | bool    | Skip TLS verification (defaults to false).                                            |
| `--useSSL`            |           | bool    | Use SSL when connecting to Argo Server (defaults to true).                            |

## What's next

* [Cron Workflows](/reference/cli/cron-workflows.md): CronWorkflow lifecycle commands.
* [Using with Hera](/reference/cli/using-with-hera.md): token generation for Hera-authored workflows.
* [Advanced](/reference/cli/advanced.md): Docker container usage, non-interactive login, token storage, log-level flags.