Skip to content
Zart

CLI Overview

The zart CLI lets you manage durable executions from the terminal — perfect for development workflows, operator tooling, and AI agent integration.

Installation

Section titled “Installation”
Terminal window
cargo install zart-cli

Or download a pre-built binary from the GitHub releases page.

Configuration

Section titled “Configuration”

The CLI reads database configuration from the environment:

Terminal window
export DATABASE_URL="postgres://user:pass@localhost/mydb"

Or use a .env file in the working directory. All commands respect the --database-url flag to override the environment variable:

Terminal window
zart --database-url "postgres://..." status exec-abc-123

Commands

Section titled “Commands”

zart migrate

Section titled “zart migrate”

Run database migrations to create or update the Zart schema. Safe to run on every deploy — migrations are idempotent.

Terminal window
zart migrate
# Applied 3 migrations successfully.

zart schedule

Section titled “zart schedule”

Schedule a new workflow execution.

Terminal window
zart schedule <task-name> [--data <json>] [--id <execution-id>]
Terminal window
# Schedule with auto-generated execution ID
zart schedule onboarding --data '{"email":"user@example.com","user_id":"u123"}'


# Schedule with explicit ID (idempotent — safe to run twice)
zart schedule checkout \
  --data '{"order_id":"ord-456","total":9900}' \
  --id checkout-ord-456

Output:

Scheduled execution: exec-7f3a9b2c
Task:  onboarding
Status: pending

zart status

Section titled “zart status”

Query the current status of an execution.

Terminal window
zart status <execution-id> [--verbose]
Terminal window
zart status exec-7f3a9b2c
# execution_id: exec-7f3a9b2c
# task:         onboarding
# status:       running
# started_at:   2026-04-04T10:23:11Z
# steps:        2 completed, 1 running


zart status exec-7f3a9b2c --verbose
# ... includes per-step details and attempt history

zart cancel

Section titled “zart cancel”

Cancel a pending or running execution.

Terminal window
zart cancel <execution-id>
Terminal window
zart cancel exec-7f3a9b2c
# Cancelled execution: exec-7f3a9b2c

zart wait

Section titled “zart wait”

Block until an execution completes (or fails), with an optional timeout.

Terminal window
zart wait <execution-id> [--timeout <seconds>]
Terminal window
# Wait up to 60 seconds, then print final status
zart wait exec-7f3a9b2c --timeout 60
# {"status":"completed","output":{"customer_id":"cus_abc"}}

Exits with code 0 on success, 1 on failure, 2 on timeout.

zart event

Section titled “zart event”

Deliver an event to a waiting execution.

Terminal window
zart event <execution-id> <event-name> [--data <json>]
Terminal window
zart event exec-7f3a9b2c email-verified \
  --data '{"token":"tk_xyz789","verified_at":"2026-04-04T10:25:00Z"}'
# Event delivered to exec-7f3a9b2c: email-verified

zart list

Section titled “zart list”

List executions with optional filtering.

Terminal window
zart list [--status <status>] [--task <task-name>] [--limit <n>]
Terminal window
# List all running executions
zart list --status running


# List recent onboarding executions
zart list --task onboarding --limit 20

Status values: pending, running, waiting, completed, failed.

Global Flags

Section titled “Global Flags”
FlagDescription
--database-url <url>Database connection string (overrides DATABASE_URL)
--jsonOutput as JSON instead of human-readable text
--quietSuppress non-error output
--helpShow help text
--versionShow CLI version

Exit Codes

Section titled “Exit Codes”
CodeMeaning
0Success
1Execution failed or command error
2Timeout (for zart wait)
3Execution not found

Next Steps

Section titled “Next Steps”