Overview
This page explains how the Bacalhau CLI is structured and which global flags are most commonly used. Understanding these fundamentals will help you work efficiently with all Bacalhau commands.
What You'll Learn
- The general structure and organization of Bacalhau commands
- How global flags affect command behavior regardless of the specific command
- How to customize output formats and control connection settings
- How to specify configuration files and data directories
- Where to find more detailed command references
CLI Structure
Bacalhau commands follow a consistent pattern that makes them intuitive and predictable:
bacalhau <top-level-command> <subcommand> [flags]
Top-Level Commands
Bacalhau's CLI groups commands into logical categories:
agent
: Client-side commands for checking health, version, and node informationjob
: Core job management (create, list, describe, stop, retrieve logs, etc.)node
: Cluster node management and inspectionconfig
: Client configuration managementdocker
: Imperative command for running Docker-based jobs
Command Examples
# Get version information
bacalhau agent version
# List recent jobs
bacalhau job list
# Submit a Docker job (imperative style)
bacalhau docker run ubuntu:latest -- echo "Hello World"
# View compute nodes in the cluster
bacalhau node list
Global Flags
These flags work with any command and provide consistent behavior across the CLI. They're especially useful for scripting and automation.
Connection Settings
Flag | Description | Default |
---|---|---|
--api-host string | Hostname for the Bacalhau API | localhost |
--api-port int | Port for the Bacalhau API | 1234 |
Example:
bacalhau job list --api-host mycluster.example.com --api-port 8080
Configuration Management
Flag | Description | Default |
---|---|---|
-c, --config string | Config file(s) or dot separated path(s) to config values | - |
--data-dir string | The filesystem path where Bacalhau stores its data | ~/.bacalhau |
Examples:
# Use a custom config file
bacalhau job list --config /path/to/custom/config.yaml
# Specify a custom data directory
bacalhau job list --data-dir /path/to/bacalhau/data
# Configure a specific value using dot notation
bacalhau serve --orchestrator -c WebUI.Enabled=true
Output Formatting
Flag | Description | Example Values |
---|---|---|
--output format | Output format style | json , yaml , table |
--pretty | Format JSON or YAML output for readability | - |
Examples:
# Get machine-readable job list
bacalhau job list --output json
# Get pretty-printed JSON
bacalhau job list --output json --pretty
# Get YAML output
bacalhau job list --output yaml
Getting Help
For detailed information about any command's available flags:
bacalhau <command> --help
This will show all available options, including both global flags and command-specific flags.
Tip: For full details on each command's available flags, see the CLI Reference or type bacalhau <command> --help
.