> AI agents: this is one page from Mammoth Analytics documentation. The index of all pages as Markdown is https://mammoth.io/docs/llms.txt. Append `.md` to any docs URL, or send `Accept: text/markdown`, to get Markdown.

# mammoth workflow

> All 31 mammoth workflow commands with examples, arguments and confirmation flags: Create and manage workflows.

> Generated from mammoth-cli 2.4.2, released 2026-11-02: `mammoth schema list`, `mammoth capability list` and the CLI's own `--help`. Do not edit by hand; run `npm run docs:capabilities`.

Create and manage workflows. 31 commands.

Every command also takes the [global flags](https://mammoth.io/docs/build/cli/global-flags/) (`--output`, `--yes`, `--confirm`, `--dry-run`, `--input`, `--profile`, ...), which are not repeated below. `--input` takes a JSON or YAML document of the input fields; `mammoth schema get COMMAND_ID` prints a command's full input schema.

**Confirmation.** Commands marked `--yes --confirm TARGET` or `--yes` always need those flags, even at a terminal: they never prompt. Commands marked "`--yes` or prompt" ask at an interactive terminal (table output, no `--no-input`) and otherwise need `--yes`. `--dry-run` skips confirmation and sends nothing.

## Summary

| Command | What it does | Effect | Confirmation |
|---|---|---|---|
| [`workflow archive`](#mammoth-workflow-archive) | Archive a workflow, or bring it back. Workflow id is positional. | Benign mutation | — |
| [`workflow attach-dataset`](#mammoth-workflow-attach-dataset) | Attach a dataset to a workflow. Workflow id and dataset id are positional. | Benign mutation | — |
| [`workflow canvas`](#mammoth-workflow-canvas) | Update a workflow's canvas state. Workflow id is positional. | Benign mutation | — |
| [`workflow cleanup`](#mammoth-workflow-cleanup) | Clean up ghost (orphaned skeleton) workflows in the active project. | Destructive | `--yes` or prompt |
| [`workflow create`](#mammoth-workflow-create) | Create a workflow. Name comes from a positional or the 'name' field. | Benign mutation | — |
| [`workflow delete`](#mammoth-workflow-delete) | Delete one workflow by id. Prompt or '--yes' required. | Destructive | `--yes` or prompt |
| [`workflow duplicate`](#mammoth-workflow-duplicate) | Duplicate a workflow into a new workflow of the same project and wait for the copies. | Benign mutation | — |
| [`workflow from-template`](#mammoth-workflow-from-template) | Instantiate a workflow from a workspace template. | Benign mutation | — |
| [`workflow get`](#mammoth-workflow-get) | Get one workflow by id in the active project. | Read | — |
| [`workflow graph`](#mammoth-workflow-graph) | Get the active project's workflow graph. | Read | — |
| [`workflow list`](#mammoth-workflow-list) | List workflows in the active project. | Read | — |
| [`workflow resolve-held`](#mammoth-workflow-resolve-held) | Settle a change that a workflow Save held back. Workflow id and change key are positional. | Benign mutation | — |
| [`workflow save`](#mammoth-workflow-save) | Save a workflow's unsaved canvas changes and wait for the run. Workflow id is positional. | Benign mutation | — |
| [`workflow save-cancel-step`](#mammoth-workflow-save-cancel-step) | Cancel one step of a workflow's running Save. Workflow id, run id and step are positional. | Benign mutation | — |
| [`workflow save-undo`](#mammoth-workflow-save-undo) | Undo a workflow's latest finished Save and wait for the undo run. Prompt or '--yes'. | Destructive | `--yes` or prompt |
| [`workflow update`](#mammoth-workflow-update) | Update a workflow's metadata. Workflow id is positional. | Benign mutation | — |
| [`workflow workspace-datasets`](#mammoth-workflow-workspace-datasets) | List workspace datasets available to workflows in the active project. | Read | — |
| [`workflow workspace-exports`](#mammoth-workflow-workspace-exports) | List workspace exports available to workflows in the active project. | Read | — |
| [`workflow workspace-sources`](#mammoth-workflow-workspace-sources) | List workspace sources available to workflows in the active project. | Read | — |
| [`workflow block add`](#mammoth-workflow-block-add) | Add a skeleton block to a workflow. Workflow id is positional. | Benign mutation | — |
| [`workflow block auth`](#mammoth-workflow-block-auth) | Patch a workflow block's auth credentials. | Benign mutation | `--yes --confirm TARGET` |
| [`workflow block config`](#mammoth-workflow-block-config) | Promote a configured skeleton block to a real resource. | Benign mutation | — |
| [`workflow block type`](#mammoth-workflow-block-type) | Patch a workflow block's connector/handler type. | Benign mutation | — |
| [`workflow template build`](#mammoth-workflow-template-build) | Add a template's steps to a workflow and start the Save that builds them. | Benign mutation | — |
| [`workflow template fit`](#mammoth-workflow-template-fit) | Match a template's roles to the columns of the tables you chose. | Read | — |
| [`workflow template get`](#mammoth-workflow-template-get) | Get a template's inputs, roles and settings. | Read | — |
| [`workflow template list`](#mammoth-workflow-template-list) | List the catalog's workflow templates, most searched first within each family. | Read | — |
| [`workflow template preview`](#mammoth-workflow-template-preview) | Run a template on the first rows of your tables and run its checks. | Read | — |
| [`workflow template rank`](#mammoth-workflow-template-rank) | Rank project tables by how well they fit one input of a template (columns only). | Read | — |
| [`workflow template sample-result`](#mammoth-workflow-template-sample-result) | Show a template's result on its own sample rows (computed in memory, nothing imported). | Read | — |
| [`workflow template samples`](#mammoth-workflow-template-samples) | Import a template's sample tables into the project (once), to try it without data. | Benign mutation | — |

## workflow commands

### mammoth workflow archive

Archive a workflow, or bring it back. Workflow id is positional.

```bash
mammoth workflow archive 123 --input '{"archived": true}'
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `WORKFLOW_ID` | positional | yes | — | `int` | ID of the workflow. |
| `archived` | `--input` field | yes | — | `bool` |  |
| `dataset_ids` | `--input` field | no | — | `list[int]` |  |

- **Effect:** Benign mutation, scope `project` · **Confirmation:** none
- **Preconditions:** Input: {archived: true|false, dataset_ids?: \[int\]}. The dataset ids are the workflow's datasets now; it reads as active once it has others.
- **Id:** `workflow.archive` · **Result:** `WorkflowArchiveResult` · **Backed by:** SDK `mammoth.api.workflows.WorkflowsAPI.set_archived`, API `PUT /workspaces/{workspace_id}/projects/{project_id}/workflows/{workflow_id}/archived` (SetArchived)

### mammoth workflow attach-dataset

Attach a dataset to a workflow. Workflow id and dataset id are positional.

```bash
mammoth workflow attach-dataset 123 456
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `WORKFLOW_ID` | positional | yes | — | `int` | ID of the workflow. |
| `DATASOURCE_ID` | positional | yes | — | `int` | ID of the datasource. |

- **Effect:** Benign mutation, scope `project` · **Confirmation:** none
- **Preconditions:** Takes the dataset to attach as the second positional, DATASOURCE_ID. No input document.
- **Id:** `workflow.attach-dataset` · **Result:** `WorkflowAttachDatasetResult` · **Backed by:** SDK `mammoth.api.workflows.WorkflowsAPI.attach_dataset`, API `POST /workspaces/{workspace_id}/projects/{project_id}/workflows/{workflow_id}/datasets` (AttachDataset)

### mammoth workflow canvas

Update a workflow's canvas state. Workflow id is positional.

```bash
mammoth workflow canvas 12 --input '{"canvas_state": {"proposed_changes": [{"op": "add_view", "dataset_id": 415, "name": "Urgent tickets", "ref": "urgent"}, {"op": "add_step", "view_ref": "urgent", "transform": "filter", "params": {"condition": {"column": "Priority", "operator": "EQ", "value": "Urgent"}}, "label": "Keep urgent tickets"}, {"op": "send_to_new_dataset", "dataset_id": 415, "view_ref": "urgent", "name": "Urgent tickets by team"}]}}'
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `WORKFLOW_ID` | positional | yes | — | `int` | ID of the workflow. |
| `canvas_state` | `--input` field | yes | — | `dict[str, any]` |  |

- **Effect:** Benign mutation, scope `project` · **Confirmation:** none
- **Preconditions:** Proposes changes to a workflow for the user to review and Save on the Workflows canvas; nothing is built until they Save, and Save builds every change in flow order. Use it when the user asks to suggest, sketch or draft a workflow, or wants to review first. Steps inside a view are changes too: propose the filters, calculations and other tasks a proposed or existing view needs as add_step changes in the same call, never as view commands run afterwards. WORKFLOW_ID is the workflow's record id (URL id w12 is record 12); an unnamed workflow has none, so name it first with workflow create --seed_datasource_id. Input: {"canvas_state": {"proposed_changes": \[...\]}}, each change one of (integer ids from workflow graph): {op: add_view, dataset_id, name, ref?}; {op: rename_view, dataset_id, view_id, name}; {op: trash_view, dataset_id, view_id}; {op: rename_dataset, dataset_id, name}; {op: trash_dataset, dataset_id}; {op: send_to_new_dataset, dataset_id, view_id, name, ref?}; {op: send_to_dataset, dataset_id, view_id, target_dataset_id}; {op: join, dataset_id, view_id, with_dataset_id, with_view_id, join_type?, on?, select?, column_prefix?} (with join_type INNER|LEFT|RIGHT|OUTER, on \[{left, right}\] and select \[columns\], Save builds the join); {op: export, dataset_id, view_id, connector?, destination?, connection_id?, settings?} (an existing connection and the destination's settings, never a credential); {op: add_source, name, dataset_name, ref?, kind?, url?, connector?, connection_id?, settings?} (kind url with a link, or connection with an existing connection; with neither it waits for the user's data); {op: lookup, view_id, lookup_view_id, key, source, value, new_column?, label?, ref?}; {op: add_step, view_id, transform, params, label, after_ref?, ref?} (transform is a view transform kind such as filter, discard-duplicates or sort, and params is exactly that command's --input: schema get view.transform.\<kind\>; after_ref names an earlier add_step on the same view); {op: update_step, view_id, task_id, params, label?}; {op: remove_step, view_id, task_id}. A later change in the same call can point at something an earlier one proposes: give the earlier change a ref, then use view_ref, dataset_ref or target_dataset_ref in place of the id (an add_step on a proposed view uses view_ref) (a new dataset's ref also names its first view), so a whole shape is proposed in one call. A step is checked when proposed; a refused one says how to fix it. Join, export and complex steps (join, lookup, ai, add-sql, generate-sql, pivot, crosstab, window, unnest) arrive needing setup in the Data Editor. Tell the user the changes wait on the canvas for their review.
- **Id:** `workflow.canvas` · **Result:** `WorkflowCanvasResult` · **Backed by:** SDK `mammoth.api.workflows.WorkflowsAPI.canvas`, API `PATCH /workspaces/{workspace_id}/projects/{project_id}/workflows/{workflow_id}/canvas` (UpdateCanvasState)

### mammoth workflow cleanup

Clean up ghost (orphaned skeleton) workflows in the active project.

```bash
mammoth workflow cleanup --yes
```

- **Effect:** Destructive, scope `project` · **Confirmation:** `--yes`, or answer the prompt at an interactive terminal
- **Preconditions:** Deletes the active project's ghost (orphaned, half-created) workflows for good; real workflows are untouched. Needs --project or an active project, and a prompt or --yes.
- **Id:** `workflow.cleanup` · **Result:** `WorkflowCleanupResult` · **Backed by:** SDK `mammoth.api.workflows.WorkflowsAPI.cleanup`, API `POST /workspaces/{workspace_id}/projects/{project_id}/workflows/cleanup` (CleanupGhostWorkflows)

### mammoth workflow create

Create a workflow. Name comes from a positional or the 'name' field.

```bash
mammoth workflow create 'Revenue report'
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `NAME` | positional | no | — | `str` | Name of the new workflow; or pass it via the 'name' input field. Or the `name` input field. |
| `name` | `--input` field | no | — | `str` |  |
| `shape` | `--input` field | no | `blank` | `str` |  |
| `purpose` | `--input` field | no | — | `str` |  |
| `seed_datasource_id` | `--input` field | no | — | `int` |  |

- **Effect:** Benign mutation, scope `project` · **Confirmation:** none
- **Preconditions:** With seed_datasource_id set to a workflow's root dataset id (workflow graph lists each workflow's datasets), names that existing unnamed workflow and returns its record id; without it, starts a new empty workflow.
- **Id:** `workflow.create` · **Result:** `WorkflowCreateResult` · **Backed by:** SDK `mammoth.api.workflows.WorkflowsAPI.create`, API `POST /workspaces/{workspace_id}/projects/{project_id}/workflows` (CreateWorkflow)

### mammoth workflow delete

Delete one workflow by id. Prompt or '--yes' required.

```bash
mammoth workflow delete 123 --yes
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `WORKFLOW_ID` | positional | yes | — | `int` | ID of the workflow. |

- **Effect:** Destructive, scope `project` · **Confirmation:** `--yes`, or answer the prompt at an interactive terminal
- **Preconditions:** Required inputs: WORKFLOW_ID.
- **Id:** `workflow.delete` · **Result:** `WorkflowDeleteResult` · **Backed by:** SDK `mammoth.api.workflows.WorkflowsAPI.delete`, API `DELETE /workspaces/{workspace_id}/projects/{project_id}/workflows/{workflow_id}` (DeleteWorkflow)

### mammoth workflow duplicate

Duplicate a workflow into a new workflow of the same project and wait for the copies.

```bash
mammoth workflow duplicate 123 --input '{"name": "Revenue report", "dataset_ids": [1]}'
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `SOURCE_WORKFLOW_ID` | positional | no | — | `int` | ID of the workflow to copy; or pass 'source_workflow_id' in --input. Or the `source_workflow_id` input field. |
| `name` | `--input` field | yes | — | `str` |  |
| `dataset_ids` | `--input` field | yes | — | `list[int]` |  |
| `source_workflow_id` | `--input` field | no | — | `int` |  |
| `wait` | `--input` field | no | `true` | `bool` |  |
| `timeout` | `--input` field | no | — | `float` |  |

- **Effect:** Benign mutation, scope `project` · **Confirmation:** none · **Waits:** waits for the job to finish (`--job-timeout`, `--return-running`)
- **Preconditions:** Copies the chosen datasets, with their rows, views and steps, into a new workflow. Automations and outside exports are not copied.
- **Id:** `workflow.duplicate` · **Result:** `WorkflowDuplicateResult` · **Backed by:** SDK `mammoth.api.workflows.WorkflowsAPI.duplicate`, API `POST /workspaces/{workspace_id}/projects/{project_id}/workflows/duplicate` (DuplicateWorkflow)

### mammoth workflow from-template

Instantiate a workflow from a workspace template.

```bash
mammoth workflow from-template 123 --input '{"workflow_name": "Revenue report"}'
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `TEMPLATE_ID` | positional | yes | — | `int` | ID of the template. |
| `workflow_name` | `--input` field | yes | — | `str` |  |

- **Effect:** Benign mutation, scope `project` · **Confirmation:** none
- **Preconditions:** Required inputs: TEMPLATE_ID.
- **Id:** `workflow.from-template` · **Result:** `WorkflowFromTemplateResult` · **Backed by:** SDK `mammoth.api.workflows.WorkflowsAPI.from_template`, API `POST /workspaces/{workspace_id}/projects/{project_id}/workflows/from-template` (InstantiateFromTemplate)

### mammoth workflow get

Get one workflow by id in the active project.

```bash
mammoth workflow get 123
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `WORKFLOW_ID` | positional | yes | — | `int` | ID of the workflow. |

- **Effect:** Read, scope `project` · **Confirmation:** none
- **Preconditions:** Required inputs: WORKFLOW_ID.
- **Id:** `workflow.get` · **Result:** `WorkflowGetResult` · **Backed by:** SDK `mammoth.api.workflows.WorkflowsAPI.get`, API `GET /workspaces/{workspace_id}/projects/{project_id}/workflows/{workflow_id}` (GetWorkflow)

### mammoth workflow graph

Get the active project's workflow graph.

```bash
mammoth workflow graph
```

- **Effect:** Read, scope `project` · **Confirmation:** none
- **Id:** `workflow.graph` · **Result:** `WorkflowGraphResult` · **Backed by:** SDK `mammoth.api.workflows.WorkflowsAPI.graph`, API `GET /workspaces/{workspace_id}/projects/{project_id}/workflows/graph` (GetProjectWorkflowGraph)

### mammoth workflow list

List workflows in the active project.

```bash
mammoth workflow list
```

- **Effect:** Read, scope `project` · **Confirmation:** none · **Pages:** `single_page`
- **Id:** `workflow.list` · **Result:** `WorkflowListResult` · **Backed by:** SDK `mammoth.api.workflows.WorkflowsAPI.list`, API `GET /workspaces/{workspace_id}/projects/{project_id}/workflows` (ListWorkflows)

### mammoth workflow resolve-held

Settle a change that a workflow Save held back. Workflow id and change key are positional.

```bash
mammoth workflow resolve-held 123 Status --input '{"built": true}'
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `WORKFLOW_ID` | positional | yes | — | `int` | ID of the workflow. |
| `KEY` | positional | yes | — | `str` | Key identifying the resource. |
| `built` | `--input` field | yes | — | `bool` |  |
| `expected_version` | `--input` field | no | — | `int` |  |

- **Effect:** Benign mutation, scope `project` · **Confirmation:** none
- **Preconditions:** Takes the change's key as the second positional, KEY. Input: {built: true|false (true: already in Mammoth, not built again; false: lift the hold so the next Save builds it), expected_version?: int}.
- **Id:** `workflow.resolve-held` · **Result:** `WorkflowResolveHeldResult` · **Backed by:** SDK `mammoth.api.workflows.WorkflowsAPI.resolve_held`, API `POST /workspaces/{workspace_id}/projects/{project_id}/workflows/{workflow_id}/held/resolve` (ResolveHeldChange)

### mammoth workflow save

Save a workflow's unsaved canvas changes and wait for the run. Workflow id is positional.

```bash
mammoth workflow save 123
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `WORKFLOW_ID` | positional | yes | — | `int` | ID of the workflow. |
| `keys` | `--input` field | no | — | `list[str]` |  |
| `expected_version` | `--input` field | no | — | `int` |  |

- **Effect:** Benign mutation, scope `project` · **Confirmation:** none
- **Preconditions:** Input (optional): {keys?: \[change keys to save\], expected_version?: int}. Omitted keys save every unsaved change; a stale expected_version fails with 409.
- **Id:** `workflow.save` · **Result:** `WorkflowSaveResult` · **Backed by:** SDK `mammoth.api.workflows.WorkflowsAPI.save`, API `POST /workspaces/{workspace_id}/projects/{project_id}/workflows/{workflow_id}/save` (SaveWorkflow)

### mammoth workflow save-cancel-step

Cancel one step of a workflow's running Save. Workflow id, run id and step are positional.

```bash
mammoth workflow save-cancel-step 123 resource-123 456
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `WORKFLOW_ID` | positional | yes | — | `int` | ID of the workflow. |
| `RUN_ID` | positional | yes | — | `str` | ID of the Save run (from 'workflow save' or 'workflow get'). |
| `STEP` | positional | yes | — | `int` | Number of the step to cancel (0 or more). |

- **Effect:** Benign mutation, scope `project` · **Confirmation:** none
- **Preconditions:** Cancels one step of a running Save; steps that need it are skipped. Best effort: a job already started may still finish.
- **Id:** `workflow.save-cancel-step` · **Result:** `WorkflowSaveCancelStepResult` · **Backed by:** SDK `mammoth.api.workflows.WorkflowsAPI.cancel_save_step`, API `POST /workspaces/{workspace_id}/projects/{project_id}/workflows/{workflow_id}/save/{run_id}/steps/{step}/cancel` (CancelWorkflowSaveStep)

### mammoth workflow save-undo

Undo a workflow's latest finished Save and wait for the undo run. Prompt or '--yes'.

```bash
mammoth workflow save-undo 123 resource-123 --yes
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `WORKFLOW_ID` | positional | yes | — | `int` | ID of the workflow. |
| `RUN_ID` | positional | yes | — | `str` | ID of the run. |

- **Effect:** Destructive, scope `project` · **Confirmation:** `--yes`, or answer the prompt at an interactive terminal · **Waits:** waits for the job to finish (`--job-timeout`, `--return-running`)
- **Preconditions:** Removes what the Save built (datasets, views, steps). Prompts, or pass --yes. Waits for the undo run.
- **Id:** `workflow.save-undo` · **Result:** `WorkflowSaveUndoResult` · **Backed by:** SDK `mammoth.api.workflows.WorkflowsAPI.undo_save`, API `POST /workspaces/{workspace_id}/projects/{project_id}/workflows/{workflow_id}/save/{run_id}/undo` (UndoWorkflowSave)

### mammoth workflow update

Update a workflow's metadata. Workflow id is positional.

```bash
mammoth workflow update 123
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `WORKFLOW_ID` | positional | yes | — | `int` | ID of the workflow. |
| `name` | `--input` field | no | — | `str` |  |
| `purpose` | `--input` field | no | — | `str` |  |
| `pipeline_summary` | `--input` field | no | — | `str` |  |
| `notes` | `--input` field | no | — | `str` |  |

- **Effect:** Benign mutation, scope `project` · **Confirmation:** none
- **Preconditions:** WORKFLOW_ID is the workflow's record id: URL id w12 is record 12. An unnamed workflow (base64 URL id) has no record; name it with workflow create --seed_datasource_id \<its root dataset id\> instead.
- **Id:** `workflow.update` · **Result:** `WorkflowUpdateResult` · **Backed by:** SDK `mammoth.api.workflows.WorkflowsAPI.update`, API `PATCH /workspaces/{workspace_id}/projects/{project_id}/workflows/{workflow_id}` (UpdateWorkflow)

### mammoth workflow workspace-datasets

List workspace datasets available to workflows in the active project.

```bash
mammoth workflow workspace-datasets
```

- **Effect:** Read, scope `project` · **Confirmation:** none
- **Id:** `workflow.workspace-datasets` · **Result:** `WorkflowWorkspaceDatasetsResult` · **Backed by:** SDK `mammoth.api.workflows.WorkflowsAPI.workspace_datasets`, API `GET /workspaces/{workspace_id}/projects/{project_id}/workflows/workspace-datasets` (ListWorkspaceDatasets)

### mammoth workflow workspace-exports

List workspace exports available to workflows in the active project.

```bash
mammoth workflow workspace-exports
```

- **Effect:** Read, scope `project` · **Confirmation:** none
- **Id:** `workflow.workspace-exports` · **Result:** `WorkflowWorkspaceExportsResult` · **Backed by:** SDK `mammoth.api.workflows.WorkflowsAPI.workspace_exports`, API `GET /workspaces/{workspace_id}/projects/{project_id}/workflows/workspace-exports` (ListWorkspaceExports)

### mammoth workflow workspace-sources

List workspace sources available to workflows in the active project.

```bash
mammoth workflow workspace-sources
```

- **Effect:** Read, scope `project` · **Confirmation:** none
- **Id:** `workflow.workspace-sources` · **Result:** `WorkflowWorkspaceSourcesResult` · **Backed by:** SDK `mammoth.api.workflows.WorkflowsAPI.workspace_sources`, API `GET /workspaces/{workspace_id}/projects/{project_id}/workflows/workspace-sources` (ListWorkspaceSources)

## workflow block

### mammoth workflow block add

Add a skeleton block to a workflow. Workflow id is positional.

```bash
mammoth workflow block add 123 --input '{"block_type": "source"}'
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `WORKFLOW_ID` | positional | yes | — | `int` | ID of the workflow. |
| `block_type` | `--input` field | yes | — | `str` |  |
| `display_name` | `--input` field | no | — | `str` |  |
| `connection_type` | `--input` field | no | — | `str` |  |
| `position_hint` | `--input` field | no | — | `dict[str, any]` |  |

- **Effect:** Benign mutation, scope `project` · **Confirmation:** none
- **Preconditions:** Required inputs: WORKFLOW_ID.
- **Id:** `workflow.block.add` · **Result:** `WorkflowBlockAddResult` · **Backed by:** SDK `mammoth.api.workflows.WorkflowsAPI.block_add`, API `POST /workspaces/{workspace_id}/projects/{project_id}/workflows/{workflow_id}/blocks` (AddSkeletonBlock)

### mammoth workflow block auth

Patch a workflow block's auth credentials.

```bash
mammoth workflow block auth 123 456 --input '{"auth_data": {"name": "Status"}}' --yes --confirm 123
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `WORKFLOW_ID` | positional | yes | — | `int` | ID of the workflow. |
| `BLOCK_ID` | positional | yes | — | `int` | ID of the block. |
| `auth_data` | `--input` field | yes | — | `dict[str, any]` |  |

- **Effect:** Benign mutation, scope `project` · **Confirmation:** always `--yes --confirm TARGET`, even at a terminal (TARGET is the exact id or name acted on; the `confirmation_required` error's hint names it)
- **Preconditions:** Required inputs: WORKFLOW_ID, BLOCK_ID.
- **Id:** `workflow.block.auth` · **Result:** `WorkflowBlockAuthResult` · **Backed by:** SDK `mammoth.api.workflows.WorkflowsAPI.block_auth`, API `PATCH /workspaces/{workspace_id}/projects/{project_id}/workflows/{workflow_id}/blocks/{block_id}/auth` (PatchBlockAuth)

### mammoth workflow block config

Promote a configured skeleton block to a real resource.

```bash
mammoth workflow block config 123 456
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `WORKFLOW_ID` | positional | yes | — | `int` | ID of the workflow. |
| `BLOCK_ID` | positional | yes | — | `int` | ID of the block. |

- **Effect:** Benign mutation, scope `project` · **Confirmation:** none
- **Preconditions:** Required inputs: WORKFLOW_ID, BLOCK_ID.
- **Id:** `workflow.block.config` · **Result:** `WorkflowBlockConfigResult` · **Backed by:** SDK `mammoth.api.workflows.WorkflowsAPI.block_config`, API `PATCH /workspaces/{workspace_id}/projects/{project_id}/workflows/{workflow_id}/blocks/{block_id}/config` (PromoteSkeletonBlock)

### mammoth workflow block type

Patch a workflow block's connector/handler type.

```bash
mammoth workflow block type 123 456 --input '{"connection_type": "postgres"}'
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `WORKFLOW_ID` | positional | yes | — | `int` | ID of the workflow. |
| `BLOCK_ID` | positional | yes | — | `int` | ID of the block. |
| `connection_type` | `--input` field | yes | — | `str` |  |

- **Effect:** Benign mutation, scope `project` · **Confirmation:** none
- **Preconditions:** Required inputs: WORKFLOW_ID, BLOCK_ID.
- **Id:** `workflow.block.type` · **Result:** `WorkflowBlockTypeResult` · **Backed by:** SDK `mammoth.api.workflows.WorkflowsAPI.block_type`, API `PATCH /workspaces/{workspace_id}/projects/{project_id}/workflows/{workflow_id}/blocks/{block_id}/type` (PatchBlockType)

## workflow template

### mammoth workflow template build

Add a template's steps to a workflow and start the Save that builds them.

```bash
mammoth workflow template build bank-reconciliation --input '{"inputs": {"main": 101}, "matches": {"main": {"amount": {"column": "Amount"}}}, "destination_name": "Bank reconciliation"}'
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `KEY` | positional | yes | — | `str` | Workflow template key, from 'workflow template list'. |
| `inputs` | `--input` field | yes | — | `dict[str, int]` |  |
| `matches` | `--input` field | yes | — | `dict[str, dict[str, dict[str, any]]]` |  |
| `destination_name` | `--input` field | yes | — | `str` |  |
| `settings` | `--input` field | no | — | `dict[str, any]` |  |
| `destination_emails` | `--input` field | no | — | `list[str]` |  |

- **Effect:** Benign mutation, scope `project` · **Confirmation:** none
- **Preconditions:** Input: {inputs, matches, destination_name, settings?, destination_emails?} as in workflow template preview; the server refuses a build whose own preview could not run. Answers while the Save runs: follow it with workflow get WORKFLOW_ID (canvas_state.save_run).
- **Id:** `workflow.template.build` · **Result:** `WorkflowTemplateBuildResult`

### mammoth workflow template fit

Match a template's roles to the columns of the tables you chose.

```bash
mammoth workflow template fit bank-reconciliation --input '{"inputs": {"main": 101}}'
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `KEY` | positional | yes | — | `str` | Workflow template key, from 'workflow template list'. |
| `inputs` | `--input` field | yes | — | `dict[str, int]` |  |

- **Effect:** Read, scope `project` · **Confirmation:** none
- **Preconditions:** Input: {inputs: {INPUT_KEY: DATASET_ID}}. Read-only; the matches it proposes go into the preview and build inputs.
- **Id:** `workflow.template.fit` · **Result:** `WorkflowTemplateFitResult`

### mammoth workflow template get

Get a template's inputs, roles and settings.

```bash
mammoth workflow template get bank-reconciliation
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `KEY` | positional | yes | — | `str` | Workflow template key, from 'workflow template list'. |

- **Effect:** Read, scope `project` · **Confirmation:** none
- **Preconditions:** Read-only: the inputs, roles and settings the other template commands take.
- **Id:** `workflow.template.get` · **Result:** `WorkflowTemplateGetResult`

### mammoth workflow template list

List the catalog's workflow templates, most searched first within each family.

```bash
mammoth workflow template list
```

- **Effect:** Read, scope `project` · **Confirmation:** none
- **Preconditions:** Lists the project workflow-template catalog (ready-made reconciliations and reports), not the workspace templates of 'template list'. Pick a key, then run workflow template get KEY.
- **Id:** `workflow.template.list` · **Result:** `WorkflowTemplateListResult`

### mammoth workflow template preview

Run a template on the first rows of your tables and run its checks.

```bash
mammoth workflow template preview bank-reconciliation --input '{"inputs": {"main": 101}, "matches": {"main": {"amount": {"column": "Amount"}}}}'
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `KEY` | positional | yes | — | `str` | Workflow template key, from 'workflow template list'. |
| `inputs` | `--input` field | yes | — | `dict[str, int]` |  |
| `matches` | `--input` field | yes | — | `dict[str, dict[str, dict[str, any]]]` |  |
| `settings` | `--input` field | no | — | `dict[str, any]` |  |

- **Effect:** Read, scope `project` · **Confirmation:** none
- **Preconditions:** Input: {inputs: {INPUT_KEY: DATASET_ID}, matches: {INPUT_KEY: {ROLE_KEY: {column: NAME}}}, settings?: {}}. Read-only: runs the template on the first rows of your tables.
- **Id:** `workflow.template.preview` · **Result:** `WorkflowTemplatePreviewResult`

### mammoth workflow template rank

Rank project tables by how well they fit one input of a template (columns only).

```bash
mammoth workflow template rank bank-reconciliation --input '{"input_key": "main", "dataset_ids": [101, 102]}'
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `KEY` | positional | yes | — | `str` | Workflow template key, from 'workflow template list'. |
| `input_key` | `--input` field | yes | — | `str` |  |
| `dataset_ids` | `--input` field | yes | — | `list[int]` |  |

- **Effect:** Read, scope `project` · **Confirmation:** none
- **Preconditions:** Input: {input_key: INPUT_KEY, dataset_ids: \[1 to 200 dataset ids\]}. Judges each table from its column names and types alone, so it reads no rows.
- **Id:** `workflow.template.rank` · **Result:** `WorkflowTemplateRankResult`

### mammoth workflow template sample-result

Show a template's result on its own sample rows (computed in memory, nothing imported).

```bash
mammoth workflow template sample-result bank-reconciliation
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `KEY` | positional | yes | — | `str` | Workflow template key, from 'workflow template list'. |

- **Effect:** Read, scope `project` · **Confirmation:** none
- **Preconditions:** Computed in memory on the template's own sample rows; nothing is imported.
- **Id:** `workflow.template.sample-result` · **Result:** `WorkflowTemplateSampleResultResult`

### mammoth workflow template samples

Import a template's sample tables into the project (once), to try it without data.

```bash
mammoth workflow template samples bank-reconciliation
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `KEY` | positional | yes | — | `str` | Workflow template key, from 'workflow template list'. |

- **Effect:** Benign mutation, scope `project` · **Confirmation:** none
- **Preconditions:** Imports the template's sample tables into the project, once, so the template can be tried without your own data.
- **Id:** `workflow.template.samples` · **Result:** `WorkflowTemplateSamplesResult`

---
Source: https://mammoth.io/docs/build/cli/workflow.md · Updated: 2026-11-02
