# Workflows

Use `moi-cli workflow` to query, deploy, and run workflows from a terminal, read workflow-job state and results, and cancel a job when necessary. The CLI calls the Product API; it is not used to invoke Genesis models.

## Prerequisites

- `moi-cli` is available.
- The Product API endpoint, personal access token, and target workspace are configured.
- You have a workflow ID; deploying a workflow also requires a checked workflow DSL.

Run the following command to see the subcommands actually provided by the current version:

```bash
moi-cli workflow --help
```

## Inspect workflows

List workflows in the current workspace:

```bash
moi-cli -o workflow list --workspace-id "$WORKSPACE_ID"
```

Read one workflow's details:

```bash
moi-cli -o workflow get \
  --workspace-id "$WORKSPACE_ID" \
  --workflow-id "$WORKFLOW_ID"
```

The global `-o` option returns JSON, which is suitable for reading workflow IDs, state, and available operations. If the workspace is saved in configuration, you can omit `--workspace-id` from a subcommand.

## Start a workflow

```bash
moi-cli -o workflow run \
  --workspace-id "$WORKSPACE_ID" \
  --workflow-id "$WORKFLOW_ID"
```

Save `workflow_run.execution_id` from the response as the workflow-job ID:

```bash
export EXECUTION_ID='<EXECUTION_ID>'
```

The current `workflow run` command accepts only a workspace ID and workflow ID; it does not provide a runtime `values` parameter. To pass values to a run form, use the [AI Studio API](../../api/ai-studio/data-processing/workflow-jobs-recovery.md) or [AI Studio SDK](../../sdk/ai-studio/guides/workflows-workitems-lineage.md).

Returning a workflow-job ID only means the platform accepted the run request; it does not mean the workflow has completed.

## Query state and results

Query workflow-job details:

```bash
moi-cli -o workflow get-run \
  --workspace-id "$WORKSPACE_ID" \
  --workflow-id "$WORKFLOW_ID" \
  --execution-id "$EXECUTION_ID"
```

Get workflow-job results:

```bash
moi-cli -o workflow get-run-result \
  --workspace-id "$WORKSPACE_ID" \
  --workflow-id "$WORKFLOW_ID" \
  --execution-id "$EXECUTION_ID"
```

In a script, bound both the total wait time and number of polling attempts. Stop when a terminal state is returned or the limit is reached; after a timeout, retain the workflow-job ID and return its current state instead of automatically running the workflow again.

## Cancel a workflow job

Before cancellation, run `get-run` and confirm the workflow job can still be cancelled:

```bash
moi-cli -o workflow cancel-run \
  --workspace-id "$WORKSPACE_ID" \
  --workflow-id "$WORKFLOW_ID" \
  --execution-id "$EXECUTION_ID"
```

After the cancellation command returns, run `get-run` again to confirm server-side state. Cancelling a workflow job does not automatically roll back results already written by an operator to a database, file system, or external service.

## Common subcommands

| Task | Subcommands |
| --- | --- |
| List and read workflows | `list`, `get` |
| Deploy a workflow | `deploy` |
| Pause or resume a workflow | `pause`, `resume` |
| Run a workflow | `run` |
| Query workflow jobs | `list-runs`, `list-all-runs`, `get-run`, `get-run-by-id` |
| Read results and operators | `get-run-result`, `get-run-node` |
| Handle retries and operator reruns | `retry-run`, `get-run-node-rerun-plan`, `create-run-node-rerun` |
| Cancel a workflow job or rerun | `cancel-run`, `cancel-run-rerun` |
| WorkItem API Service | `get-workitem-api-service`, `publish-workitem-api-service`, `invoke-workitem-api-service` |
| Artifacts and lineage | `artifact-lineage-overview`, `artifact-output-blocks`, `artifact-node` |

For commands that use `--json` or `--json-file` for complex input, see the relevant [AI Studio API documentation](../../api/ai-studio/data-processing/index.md). Do not infer argument names or request bodies from other subcommands.

## Manage WorkItem services, operators, and templates

| Task | Commands | Notes |
| --- | --- | --- |
| Inspect available WorkItems | `workitem-catalog`, `workitem-catalog-item` | Confirm an item before publishing or invoking a service. |
| Manage WorkItem API services | `get-workitem-api-service`, `publish-workitem-api-service`, `invoke-workitem-api-service`, `enable-workitem-api-service`, `disable-workitem-api-service` | Publishing, enabling, disabling, and invoking affect service availability. |
| Invoke services dynamically | `invoke-dynamic-service`, `invoke-workflow-dynamic-service` | Use confirmed service or workflow objects. |
| Manage custom operators | `custom-operators`, `create-custom-operator`, `get-custom-operator`, `test-custom-operator`, `update-custom-operator`, `enable-custom-operator`, `disable-custom-operator`, `delete-custom-operator` | Read existing operators and state before a write or deletion. |
| Manage workflow templates | `workflow-templates`, `get-workflow-template`, `create-workflow-template`, `update-workflow-template`, `delete-workflow-template` | Use `--json` or `--json-file` for complex definitions. |

Publishing, enabling, disabling, invoking, and deleting can change availability or runtime state. Read the existing object and state first, and provide complex definitions with `--json` or `--json-file`.

## Inspect artifacts and revisions

| Task | Commands | Notes |
| --- | --- | --- |
| Inspect lineage and output | `catalog-file-lineage-overview`, `artifact-lineage-overview`, `artifact-output-blocks`, `artifact-node` | Read artifacts, nodes, and outputs first. |
| Manage artifact-block revisions | `artifact-block-revisions`, `create-artifact-block-revision`, `switch-artifact-effective-revisions` | Query state after creating or switching a revision. |
| Manage node-block revisions | `artifact-node-block-revisions`, `create-artifact-node-block-revision`, `switch-artifact-node-effective-revisions` | Use artifact and node identifiers. |
| Rerun an artifact node | `create-artifact-node-rerun`, `create-target-artifact-node-revision-rerun` | Submission only starts a later state change; inspect run records afterwards. |

## Inspect import context and run details

| Task | Commands | Notes |
| --- | --- | --- |
| Inspect import context with workflow and execution IDs | `get-run-import-context`, `list-run-import-files`, `get-run-node` | Provide both workflow and execution IDs. |
| Inspect import context with an execution ID only | `get-run-import-context-by-id`, `list-run-import-files-by-id`, `get-run-node-by-id` | Use when only an execution ID is available. |
| Inspect or adjust run state | `list-file-executions`, `refresh-run`, `pause-run`, `resume-run` | Inspect file-execution records before a state change. |
| Inspect or cancel rerun branches | `list-run-rerun-branches`, `get-run-rerun`, `cancel-run-rerun` | Confirm the branch state before cancellation. |
| Retry, cancel, or delete a run | `retry-run`, `batch-retry-failed-files`, `cancel-run`, `delete-run` | These commands change a run or its records. |

## Next steps

- [Run, query, and cancel with the AI Studio API](../../api/ai-studio/data-processing/workflow-jobs-recovery.md)
- [Manage workflows with the AI Studio SDK](../../sdk/ai-studio/guides/workflows-workitems-lineage.md)
- [Rerun an operator](../../api/ai-studio/data-processing/workflow-jobs-recovery.md)