The ZeitFlow CLI is a lightweight command-line tool that lets you create workflows, execute runs, inspect results, and configure MCP — all without opening a browser. It's designed with AI agents in mind: every command supports `--output json` for machine-readable responses, uses a consistent `zeitflow ` grammar, and is fully discoverable via `--help`. --- ## Installation ```bash npm install -g @zeitflow/cli ``` ### Requirements - Node.js 18+ --- ## Quick Start ```bash # 1. Authenticate (opens browser to /connect) zeitflow auth login # 2. Verify zeitflow auth status # 3. List your workflows zeitflow workflow list ``` --- ## Global Options Every command supports these flags: | Flag | Description | |------|-------------| | `--output json` | Machine-readable JSON output (default: `text`) | | `--help` | Show help | | `--version` | Print version | You can set `ZEITFLOW_URL` as an environment variable to override the default API URL. --- ## Authentication — `zeitflow auth` | Command | Description | |---------|-------------| | `zeitflow auth login` | Open browser to /connect, paste token to authenticate | | `zeitflow auth login --token ` | Save token directly (for scripting) | | `zeitflow auth logout` | Remove stored credentials | | `zeitflow auth status` | Show current auth state and API URL | Configuration is stored at `~/.zeitflow/config.json` — the same file used by `@zeitflow/mcp`, so if you've already authenticated with one, the other picks it up automatically. --- ## Workflows — `zeitflow workflow` Alias: `wf` ### Listing and creating ```bash # List all workflows zeitflow workflow list # Filter by status zeitflow workflow list --status published # Create a new workflow zeitflow workflow create --name "Customer Onboarding" zeitflow workflow create --name "Daily Report" --description "Summarizes metrics" # Get full details (nodes, connections, config) zeitflow workflow get 42 ``` ### Status management ```bash # Publish a workflow so it can be executed zeitflow workflow publish 42 # Archive it zeitflow workflow publish 42 --status archived # Revert to draft zeitflow workflow publish 42 --status draft ``` ### Deleting ```bash zeitflow workflow delete 42 ``` ### Executing ```bash # Run with no input zeitflow workflow run 42 # Pass input data as JSON zeitflow workflow run 42 --input '{"email":"alice@example.com","name":"Alice"}' # Trigger a specific entry node zeitflow workflow run 42 --entry-node entry_abc123 ``` --- ## Executions — `zeitflow execution` Alias: `exec` | Command | Description | |---------|-------------| | `zeitflow execution list --workflow 42` | List executions for a workflow | | `zeitflow execution get ` | Get execution details (status, input, output) | | `zeitflow execution logs ` | View full execution logs | | `zeitflow execution logs --level error` | Filter to errors only | | `zeitflow execution logs --node ai_123` | Filter to a specific node | --- ## Node Management — `zeitflow workflow` Build workflows entirely from the CLI by adding nodes, connecting them, and updating their config. ### Adding nodes ```bash # Add an AI node (config is the INNER config — the CLI wraps it under aiConfig automatically) zeitflow workflow add-node --workflow 42 --node-type ai --label "Summarize" \ --config '{"model":"google/gemini-2.0-flash-001","systemPrompt":"You are a summarizer.","userPrompt":"Summarize: {{entry.content}}","outputType":"text"}' # Add an email node zeitflow workflow add-node --workflow 42 --node-type email --label "Send Summary" \ --config '{"to":["{{entry.email}}"],"subject":"Summary: {{entry.title}}","message":"{{summarize.output}}"}' # Add a condition node zeitflow workflow add-node --workflow 42 --node-type condition --label "Is Urgent" \ --config '{"leftValue":"{{classify.output}}","operator":"contains","rightValue":"urgent"}' ``` ### Connecting nodes ```bash # Simple connection zeitflow workflow connect --workflow 42 --from entry_abc --to ai_def # Condition node — specify which branch (true/false) zeitflow workflow connect --workflow 42 --from condition_123 --to slack_456 --source-handle true zeitflow workflow connect --workflow 42 --from condition_123 --to email_789 --source-handle false ``` ### Updating nodes ```bash # Update a node's label zeitflow workflow update-node --workflow 42 --node ai_def --label "Classify Ticket" # Update config zeitflow workflow update-node --workflow 42 --node ai_def \ --config '{"model":"google/gemini-2.0-flash-001","userPrompt":"Classify: {{entry.message}}"}' # Add entry fields (required for input data to flow through) zeitflow workflow update-node --workflow 42 --node entry_abc \ --fields '[{"key":"name","name":"Name","type":"text"},{"key":"email","name":"Email","type":"text"}]' ``` ### Other node commands | Command | Description | |---------|-------------| | `zeitflow workflow list-nodes 42` | List all nodes in a workflow | | `zeitflow workflow remove-node --workflow 42 --node ai_def` | Remove a node and its connections | ### Variable reference syntax Nodes reference outputs from upstream nodes using `{{node_label.field}}`. Labels are converted to snake_case: - Entry node labeled "New Ticket" with field key `subject` → `{{new_ticket.subject}}` - AI node labeled "Classify" → `{{classify.output}}` - Email node labeled "Send Alert" → `{{send_alert.status}}` --- ## Validating — `zeitflow workflow validate` Check a workflow for common issues before executing. ```bash zeitflow workflow validate 42 ``` Checks for: - **Missing entry fields** — entry node has no input fields defined - **Broken variable references** — `{{foo.bar}}` but no upstream node named "foo" exists - **Unreachable nodes** — nodes that can't be reached from any entry point - **Missing AI prompts** — AI nodes with no user prompt - **Empty email recipients** — email nodes with no `to` addresses - **Bad condition wiring** — condition node connections missing `sourceHandle` - **Entry field mismatches** — `{{entry.name}}` but the entry node doesn't have a "name" field Returns exit code 1 if errors are found, making it usable in CI/scripts. ```bash # JSON output for automation zeitflow workflow validate 42 --output json ``` --- ## Diagnostics — `zeitflow doctor` Check your CLI configuration and connectivity. ```bash zeitflow doctor ``` Checks: - Config file exists and is readable - API token is present and valid - API server is reachable - Token has correct permissions --- ## Templates — `zeitflow template` Alias: `tpl` | Command | Description | |---------|-------------| | `zeitflow template list` | List available templates | | `zeitflow template list --visibility public` | List public templates | | `zeitflow template get ` | Get template details | | `zeitflow template use ` | Create a workflow from a template | | `zeitflow template use --name "My Workflow"` | Create with a custom name | | `zeitflow template create --workflow 42 --name "My Template" --category "Sales"` | Create a template from a workflow | | `zeitflow template delete ` | Delete a template | ### Creating a template from a workflow ```bash zeitflow template create \ --workflow 42 \ --name "Customer Support Triage" \ --category "Customer Support" \ --description "Classify tickets and route to Slack or email" \ --visibility public \ --tags "ai,slack,email,support" ``` --- ## Integrations — `zeitflow integration` Alias: `int` | Command | Description | |---------|-------------| | `zeitflow integration list` | List available integrations | | `zeitflow integration info ` | Show integration details and config schema | --- ## Generating Workflows — `zeitflow workflow generate` Describe a workflow in natural language and let AI build it. ```bash zeitflow workflow generate "Take a support ticket, classify it as urgent or normal, send urgent ones to Slack and normal ones via email" # Use with an existing workflow to modify it zeitflow workflow generate "Add an SMS notification node after the email" --workflow 42 ``` --- ## Setup MCP — `zeitflow setup mcp` Interactively generate MCP config for your IDE or AI client. ```bash # Interactive — prompts you to pick a client zeitflow setup mcp # Specify client directly zeitflow setup mcp --client claude-desktop # Write config to the client's config file automatically zeitflow setup mcp --client cursor --save # Machine-readable output for scripting zeitflow setup mcp --client claude-code --output json ``` Supported clients: `claude-desktop`, `claude-code`, `cursor`, `vscode`, `windsurf`. For Claude Code, it also shows the one-liner CLI command as an alternative. --- ## Opening Workflows — `zeitflow workflow open` Open a workflow directly in the browser editor. ```bash zeitflow workflow open 42 ``` This launches your default browser to the workflow's visual editor page — useful when you've been building from the CLI and want to see or tweak the result visually. --- ## Visualizing Workflows — `zeitflow workflow visualize` Render an ASCII graph of your workflow's structure in the terminal. Alias: `viz` ```bash zeitflow workflow visualize 42 ``` Example output: ``` Lead Scoring [>> Entry] Entry → Score Lead [AI Score Lead] Score Lead → Is Hot [?? Is Hot] Is Hot —[yes]→ Notify Sales Is Hot —[no]→ Draft Follow Up [## Notify Sales] [AI Draft Follow Up] Draft Follow Up → Send Follow Up [@@ Send Follow Up] 5 nodes, 5 connections ``` Node type icons: `>>` entry, `AI` ai, `@@` email, `##` slack, `!!` sms, `TG` telegram, `??` condition, `CL` scheduler, `OK` review, `YT` youtube. Condition branches are labeled `yes`/`no`. Use `--output json` for a machine-readable graph structure. --- ## Built-in Guide — `zeitflow guide` The CLI embeds this entire guide so AI agents can access it without a browser. ```bash # Print the full guide zeitflow guide # Search for a specific topic zeitflow guide search "variable" # JSON output (for AI agents) zeitflow guide --output json ``` --- ## End-to-End Example Build a content summarizer entirely from the CLI — create the workflow, add nodes, wire them up, validate, and execute. ```bash # 1. Create the workflow (auto-creates an entry node) zeitflow workflow create --name "Content Summarizer" # -> Workflow created (id: 42, entry node: entry_abc) # 2. Add entry fields so input data flows through zeitflow workflow update-node --workflow 42 --node entry_abc \ --fields '[{"key":"title","name":"Title","type":"text"},{"key":"content","name":"Content","type":"text"},{"key":"email","name":"Email","type":"text"}]' # 3. Add an AI summarizer node zeitflow workflow add-node --workflow 42 --node-type ai --label "Summarize" \ --config '{"model":"google/gemini-2.0-flash-001","systemPrompt":"Summarize content with bullet points. Keep it under 200 words.","userPrompt":"Summarize:\n\n{{entry.content}}","outputType":"text"}' # -> Node added (id: ai_def) # 4. Add an email node zeitflow workflow add-node --workflow 42 --node-type email --label "Send Summary" \ --config '{"to":["{{entry.email}}"],"subject":"Summary: {{entry.title}}","message":"{{summarize.output}}"}' # -> Node added (id: email_ghi) # 5. Connect the nodes zeitflow workflow connect --workflow 42 --from entry_abc --to ai_def zeitflow workflow connect --workflow 42 --from ai_def --to email_ghi # 6. Validate before running zeitflow workflow validate 42 # -> Workflow is valid — no issues found # 7. Execute zeitflow workflow run 42 --input '{"title":"ZeitFlow","content":"ZeitFlow is a visual workflow builder...","email":"me@example.com"}' # 8. Check the result zeitflow execution logs 99 ``` --- ## Tips for AI Agents 1. **Always use `--output json`** — parse structured data, not formatted tables 2. **Set `ZEITFLOW_URL` in your environment** to point at a custom API endpoint 3. **Check `zeitflow auth status --output json`** before making API calls to confirm authentication 4. **Run `--help`** to discover all available commands and flags 5. **Aliases save keystrokes**: `wf` (workflow), `exec` (execution), `ls` (list), `rm` (delete) --- ## Troubleshooting **"Not authenticated. Run: zeitflow auth login"** You haven't saved an API token yet. Run `zeitflow auth login` to open the browser and authenticate. **"API error (401)"** Your token is invalid or expired. Run `zeitflow auth login` to re-authenticate with a fresh token. **"API error (429)"** Rate limited. Wait a minute and try again. Workflows API allows 100 requests/hour. **"Request failed" or network errors** Can't reach the API server. Check that your URL is correct with `zeitflow auth status` and that the server is running.