CLI Reference

CLI Reference#

Both Python and Rust implementations share the same CLI interface with identical subcommands and flags.

Basic Commands#

# Run a workflow
tea run workflow.yaml --input '{"query": "hello"}'
tea run workflow.yaml --input @state.json

# Run with secrets
tea run workflow.yaml --secrets '{"api_key": "sk-123"}'
tea run workflow.yaml --secrets @secrets.json
tea run workflow.yaml --secrets-env TEA_SECRET_

# Streaming NDJSON output (for pipelines)
tea run workflow.yaml --stream

Interrupt Control#

# CLI interrupt control
tea run workflow.yaml --interrupt-before node1,node2
tea run workflow.yaml --interrupt-after classify
tea run workflow.yaml --auto-continue

See Human-in-the-Loop Guide for detailed interrupt workflow documentation.

Custom Actions (Python Only)#

# Load custom actions
tea run workflow.yaml --actions-module my_package.actions
tea run workflow.yaml --actions-file ./custom_actions.py

See Custom Actions Guide for creating custom action modules.

Resume from Checkpoint#

# Resume from checkpoint
tea resume checkpoint.pkl --workflow workflow.yaml
tea resume checkpoint.pkl --workflow workflow.yaml --input '{"update": "value"}'

Validation and Inspection#

# Validate workflow (without execution)
tea validate workflow.yaml
tea validate workflow.yaml --detailed

# Inspect workflow structure
tea inspect workflow.yaml
tea inspect workflow.yaml --format json
tea inspect workflow.yaml --format dot    # Graphviz output

Verbosity Control#

tea run workflow.yaml -v      # info
tea run workflow.yaml -vv     # debug
tea run workflow.yaml -vvv    # trace
tea run workflow.yaml -q      # quiet (errors only)

Exit Condition Control (TEA-CLI-008)#

# Exit with code 1 if final state matches condition
tea run workflow.yaml --fail-on-state 'final_status=failed'
tea run workflow.yaml --fail-on-state 'final_status=failed' --fail-on-state 'error=true'

# Useful for CI/CD pipelines to detect workflow failures
tea run workflow.yaml --fail-on-state 'validation_status=incomplete' && echo "Success" || echo "Failed"

The --fail-on-state option checks the final workflow state against key=value conditions:

  • Specify multiple conditions (any match triggers exit 1)

  • Comparison is string-based (numeric values are compared as strings)

  • Works with --stream, --show-graph, and default output modes

DOT File Execution (Python Only, TEA-GAME-001)#

# Execute DOT files with tmux (phases respect dependencies)
tea run --from-dot workflow.dot
tea run --from-dot workflow.dot --dot-session my-session
tea run --from-dot workflow.dot --dot-max-parallel 4
tea run --from-dot workflow.dot --dot-dry-run

# Workflow mode: run a YAML for each DOT node
tea run --from-dot stories.dot --dot-workflow bmad-validation.yaml
tea run --from-dot stories.dot --dot-workflow dev.yaml --dot-input '{"mode": "quick"}'

# Stop-on-failure control (TEA-CLI-008)
tea run --from-dot stories.dot --dot-stop-on-failure      # Default: stop after phase if any node fails
tea run --from-dot stories.dot --no-dot-stop-on-failure   # Continue all phases regardless of failures

# Resume from specific wave/step (TEA-CLI-009)
tea run --from-dot workflow.dot --dot-start-wave 3        # Skip waves 1-2, start from wave 3
tea run --from-dot workflow.dot --dot-start-step 2        # Skip step 1 in wave 1
tea run --from-dot workflow.dot --dot-start-wave 2 --dot-start-step 3  # Skip wave 1, skip steps 1-2 in wave 2
tea run --from-dot workflow.dot --dot-start-from "Build"  # Start from node "Build" (finds wave/step)
tea run --from-dot workflow.dot --dot-start-wave 2 --dot-dry-run  # Preview skipped/executed nodes

Exit code behavior for --from-dot:

  • Exit code 0: All nodes completed successfully

  • Exit code 1: One or more nodes failed (actual exit codes captured)

Wave/step selection options (TEA-CLI-009):

  • --dot-start-wave N: Skip waves 1 to N-1, start from wave N (1-based)

  • --dot-start-step M: Skip steps 1 to M-1 in the starting wave (1-based)

  • --dot-start-from <label>: Start from node with this label (mutually exclusive with wave/step options)

Version and Implementation Info#

tea --version                 # tea 0.1.0
tea --impl                    # python or rust
tea --version --impl          # tea 0.1.0 (python)

# Show help
tea --help
tea run --help

Example Output#

================================================================================
Running agent from: examples/yaml_agent_example.yaml
================================================================================

Initial state: {
  "query": "artificial intelligence"
}

[check] search
[check] validate_results
[check] summarize
[check] format_output
[check] save_report

================================================================================
[check] Completed
================================================================================
Final state: {...}

Actions Loading Priority#

When multiple action sources are specified, they are loaded in this order (later sources override earlier):

  1. Built-in actions (lowest priority)

  2. CLI --actions-module flags (in order specified)

  3. CLI --actions-file flags (in order specified)

  4. YAML imports: section (highest priority - overrides CLI actions)

Security Warning#

The --actions-module and --actions-file flags execute Python code from the specified modules. Only load actions from trusted sources. For production use, prefer installed packages over local files.

See Also#

Contents