How to Run a Probe Workflow from the Command Line: A Complete Guide

Run a Probe workflow by invoking the probe binary with a YAML file path, optionally adding flags like --verbose or --dag-ascii to control output and execution.

Probe is a single-binary Go command-line tool developed by linyows/probe that reads YAML workflow definitions and executes them with built-in dependency management and real-time progress reporting. Whether you are running health checks, integration tests, or deployment validations, the CLI provides a streamlined interface to execute complex job graphs directly from your terminal.

Installing the Probe Binary

Before executing workflows, install the probe command using Go's install mechanism. This compiles the binary and places it in your $GOPATH/bin or $HOME/go/bin directory.

go install github.com/linyows/probe/cmd/probe@latest

Verify the installation by checking the version flag, which triggers the parseArgs function in cmd/probe/main.go to display build information.

probe --version

Basic Workflow Execution

To run a Probe workflow from the command line, pass the path to a YAML workflow file as the first non-flag argument. The entry point in cmd/probe/main.go delegates to runProbe, which initializes a Probe instance via Probe.New and begins execution.

probe ./workflow.yml

The CLI accepts comma-separated paths for multiple workflows, or directories that yamlFiles() will expand automatically. Relative paths are resolved against the current working directory, which is essential for workflows that reference embedded actions or external scripts.

Command-Line Flags and Options

The parseArgs function in cmd/probe/main.go#L75-L115 supports several flags that modify execution behavior and output formatting.

Verbose Logging

Enable detailed per-step logging to debug workflow execution or inspect variable resolution.

probe ./workflow.yml --verbose

When passed, the c.Verbose boolean propagates through Probe.New to the Printer component, emitting granular output for each job and step transition.

Response Time Tracking

Add timing metrics to the execution report to measure latency for HTTP requests or command invocations.

probe ./workflow.yml --rt

The --rt flag enables the response time column in the final summary, providing performance insights without modifying the workflow definition.

Visualizing Workflow Dependencies

Probe can render the job dependency graph without executing the workflow, useful for validating needs relationships before runtime. The CLI delegates to Workflow.RenderDagAscii or Workflow.RenderDagMermaid via the DagAscii and DagMermaid methods in probe.go.

ASCII Art Output

Generate a terminal-friendly diagram showing job dependencies:

probe ./workflow.yml --dag-ascii

Mermaid Diagram Output

Generate Markdown-compatible Mermaid syntax for documentation or CI/CD reports:

probe ./workflow.yml --dag-mermaid

Both visualization modes skip the actual Workflow.Start execution path and exit after rendering the graph structure.

Running Built-in Test Servers

Probe includes standalone plugin servers for testing workflows locally. The runBuiltinActions function allows you to start temporary services that your workflows can target.

Start a temporary HTTP server to test HTTP actions without external dependencies:

probe builtin http

Similarly, SMTP and other protocol servers can be launched to validate email-sending workflows in isolated environments.

Internal Execution Architecture

Understanding the internal flow helps troubleshoot execution issues. When you run probe ./workflow.yml, the following sequence occurs:

1. CLI Parsing: main() in cmd/probe/main.go#L31-L35 invokes c.start(os.Args) to parse flags and extract the workflow path.
2. Probe Initialization: runProbe calls Probe.New(path, verbose) in probe.go#L28-L40, setting up the TTY flag and configuration defaults.
3. YAML Loading: Load in probe.go#L72-L104 resolves file paths, concatenates multiple YAML documents, and validates IDs via validateIDs and validateRepeatLimits.
4. Workflow Start: Workflow.Start in workflow.go#L22-L61 initializes the JobScheduler, resolves variables, and begins concurrent job execution.
5. Job Execution: The JobScheduler tracks needs dependencies, while executor.go runs steps sequentially within each job, handling skipif, retry, and repeat logic.
6. Result Reporting: The Printer renders real-time spinners and final summaries. Probe.ExitStatus in probe.go#L52-L55 returns exit code 0 for success or 1 if any job fails.

Summary

• Installation: Use go install github.com/linyows/probe/cmd/probe@latest to obtain the binary.
• Basic syntax: Execute workflows with probe <workflow.yml> where the argument resolves via yamlFiles().
• Debug options: Add --verbose for detailed logs or --rt to display response times.
• Visualization: Use --dag-ascii or --dag-mermaid to preview job dependencies without execution.
• Test infrastructure: Launch built-in servers like probe builtin http for isolated testing.
• Exit codes: The CLI returns 0 on full success or 1 if any job fails, suitable for CI/CD pipeline integration.

Frequently Asked Questions

How do I run multiple Probe workflows in a single command?

Pass comma-separated file paths or directories as the first argument. The yamlFiles() function in probe.go expands directories and wildcards, concatenating all YAML contents into a single Workflow model before execution begins.

What happens if a job fails during execution?

Probe tracks exit status through Probe.ExitStatus in probe.go#L52-L55. If any job fails, the CLI exits with code 1, making it compatible with shell scripts and CI pipelines that need to detect failure states automatically.

Can I see the job dependency graph without running the workflow?

Yes. Use --dag-ascii for terminal diagrams or --dag-mermaid for Markdown-compatible output. These flags invoke Workflow.RenderDagAscii or RenderDagMermaid and skip the execution phase entirely.

How does Probe handle workflow validation?

During the loading phase in probe.go#L72-L104, Probe validates that job and step IDs are unique via validateIDs, checks that repeat and retry limits are within bounds, and injects default configurations through setDefaultsToSteps before the scheduler begins execution.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}