Usage Guide

What is iapetus?

iapetus is a workflow engine for automating, testing, and orchestrating command-line tasks. It is ideal for CI/CD, DevOps, E2E testing, and any scenario where you want to run and validate CLI tools in sequence or parallel, with dependencies and assertions.

When to use iapetus: - Automate complex shell or container workflows - Validate CLI tools, microservices, or scripts - Run integration/E2E tests for your stack - Orchestrate tasks in CI/CD pipelines

Key Concepts

  • Workflow: A collection of tasks with dependencies and global config.

  • Task: A single command or operation, with its own config and assertions.

  • Backend: The environment where a task runs (e.g., bash, docker, custom plugin).

  • Assertion: A check to validate task results (e.g., output contains “foo”).

  • Plugin: A backend implementation that runs tasks in a specific environment.

  • Hook: Custom logic triggered on task events (start, success, failure).

YAML vs Go Usage

You can define workflows in YAML (for config-driven use) or Go (for full flexibility).

YAML Example:

name: my-wf
backend: bash
env_map:
  FOO: bar
steps:
  - name: hello
    command: echo
    args: ["hello"]
    timeout: 5s
    backend: docker
    env_map:
      BAR: baz
    raw_asserts:
      - output_contains: hello

To run a YAML workflow:

wf, err := iapetus.LoadWorkflowFromYAML("workflow.yaml")
if err != nil { log.Fatal(err) }
err = wf.Run()

Go Example:

task := iapetus.NewTask("hello", 5*time.Second, nil).
    AddCommand("echo").
    AddArgs("hello world").
    AssertOutputContains("hello")
workflow := iapetus.NewWorkflow("my-wf", zap.NewNop())
workflow.Backend = "bash"
workflow.AddTask(*task)
err := workflow.Run()

Defining and Running Workflows

  1. Define tasks (with commands, args, env, assertions, etc.)

  2. Add tasks to a workflow (set backend, env, hooks, etc.)

  3. Run the workflow

task1 := iapetus.NewTask("step1", 5*time.Second, nil).
    AddCommand("echo").AddArgs("foo").AssertOutputContains("foo")
task2 := iapetus.NewTask("step2", 5*time.Second, nil).
    AddCommand("echo").AddArgs("bar")
task2.Depends = []string{"step1"}
wf := iapetus.NewWorkflow("demo", zap.NewNop())
wf.AddTask(*task1)
wf.AddTask(*task2)
wf.Run()

Best Practices

  • Use Retries for flaky steps

  • Use Timeout to prevent hangs

  • Use EnvMap for environment variables

  • Use hooks for custom logging or metrics

  • Keep YAML workflows simple for CI/CD

Troubleshooting

  • “command not found”: Ensure the command exists in your environment or Docker image

  • “permission denied”: Check permissions

  • “Go not installed”: Install Go from https://golang.org/dl/

  • For more, see the FAQ in the main README

See Also