Workflow Commands

These commands manage the workflow lifecycle: validation, deployment, execution, and inspection.

mantle validate

Check a workflow YAML file for structural errors. This command is fully offline — it does not connect to a database or make any network requests. Global config flags are ignored.

Usage:
  mantle validate <file>

Arguments:

Example (valid workflow):

$ mantle validate workflow.yaml
workflow.yaml: valid

Example (invalid workflow):

$ mantle validate bad-workflow.yaml
bad-workflow.yaml:1:1: error: name must match ^[a-z][a-z0-9-]*$ (name)
bad-workflow.yaml: error: at least one step is required (steps)

Errors include file name, line number, column number, message, and the field path. The command exits with code 1 if any validation errors are found.

See the Workflow Reference for a complete list of validation rules.

mantle apply

Validate a workflow definition and store it as a new immutable version in the database. If the content has not changed since the last applied version, no new version is created.

Usage:
  mantle apply <file>

Arguments:

Example (first apply):

$ mantle apply workflow.yaml
Applied fetch-and-summarize version 1

Example (no changes):

$ mantle apply workflow.yaml
No changes — fetch-and-summarize is already at version 1

Example (updated workflow):

$ mantle apply workflow.yaml
Applied fetch-and-summarize version 2

The apply command:

1. Reads and parses the YAML file
2. Runs the same validation as mantle validate
3. Computes a SHA-256 hash of the file content
4. Compares the hash against the latest stored version
5. If the content changed, inserts a new version row in workflow_definitions

Requires a database connection. If validation fails, nothing is written to the database.

mantle plan

Diff a local workflow file against the version stored in the database. Shows what will change before you apply. Runs validation first — if the file is invalid, the diff is not shown.

Usage:
  mantle plan <file>

Arguments:

Example (new workflow):

$ mantle plan workflow.yaml
+ fetch-and-summarize (new)

Plan: 1 workflow to create

Example (changed workflow):

$ mantle plan workflow.yaml
~ fetch-and-summarize (version 1 → 2)
  ~ steps[1].params.model: gpt-4 → gpt-4o

Plan: 1 workflow to update (version 1 → 2)

Example (no changes):

$ mantle plan workflow.yaml
No changes — fetch-and-summarize is at version 2

Requires a database connection.

mantle run

Execute a workflow by name. Uses the latest applied version.

Usage:
  mantle run <workflow> [flags]

Arguments:

Flags:

Example:

$ mantle run fetch-and-summarize --input url=https://api.example.com/data
Running fetch-and-summarize (version 2)...
Execution abc123-def456: completed
  fetch-data: completed
  summarize: completed

If the workflow references a credential and you have MANTLE_ENCRYPTION_KEY configured, the engine uses the Postgres-backed credential resolver. Without the encryption key, credentials fall back to environment variables only.

Errors:

If the workflow has not been applied:

Error: workflow "my-workflow" not found — have you run 'mantle apply'?

mantle cancel

Cancel a running or pending workflow execution. Marks the execution and any in-progress steps as cancelled.

Usage:
  mantle cancel <execution-id>

Arguments:

Example:

$ mantle cancel abc123-def456
Cancelled execution abc123-def456

If the execution has already finished:

$ mantle cancel abc123-def456
Execution abc123-def456 is already completed

mantle logs

View execution logs. When called with an execution ID, shows step-by-step detail. When called without arguments, lists recent executions with optional filters.

Usage:
  mantle logs [execution-id] [flags]

Arguments:

Flags (list mode only):

Example — detail mode (with execution ID):

$ mantle logs abc123-def456
Execution: abc123-def456
Workflow:  fetch-and-summarize (version 2)
Status:    completed
Started:   2026-03-18T14:30:00Z
Completed: 2026-03-18T14:30:05Z
Duration:  5.123s

Steps:
  fetch-data           completed (1.2s)
  summarize            completed (3.9s)

If a step failed, the error is shown below the step:

Steps:
  fetch-data           failed (0.5s)
    error: ai/completion: API returned 401: Unauthorized

Example — list mode (without arguments):

$ mantle logs
ID                                     WORKFLOW             VERSION STATUS     STARTED              COMPLETED
----------------------------------------------------------------------------------------------------------------------------
a1b2c3d4-e5f6-7890-abcd-ef1234567890  fetch-and-summarize        2 completed  2026-03-18 14:30:00  2026-03-18 14:30:05
b2c3d4e5-f6a7-8901-bcde-f12345678901  hello-world                1 completed  2026-03-18 14:28:00  2026-03-18 14:28:01

2 execution(s) shown.

Example — filtered list:

$ mantle logs --workflow hello-world --status failed --since 24h --limit 10

mantle status

View the current state of a workflow execution with a summary of step statuses.

Usage:
  mantle status <execution-id>

Arguments:

Example:

$ mantle status abc123-def456
Execution: abc123-def456
Workflow:  fetch-and-summarize (version 2)
Status:    completed
Started:   2026-03-18T14:30:00Z
Completed: 2026-03-18T14:30:05Z

Steps:
  completed: 2