#CLI Reference

This page documents the current Opal command-line surface directly from the implementation.

#Global options

#--log-level <level>

• Default: info
• Supported values:
  • trace
  • debug
  • info
  • warn
  • error

Example:

opal --log-level debug plan

#Commands

#opal run

Runs a pipeline locally.

#Options

#-p, --pipeline <path>

• Which .gitlab-ci.yml file to use
• Defaults to <workdir>/.gitlab-ci.yml

#-w, --workdir <path>

• Context directory
• Defaults to the current working directory

#-b, --base-image <image>

• Optional fallback image when the pipeline/job does not define one

#-E, --env <glob>

• Repeatable
• Forwards selected host environment variables into every job
• Uses globset glob syntax

Examples:

opal run -E CI_* -E 'AWS_ACCESS_KEY_ID' -E 'APP_??'

#--max-parallel-jobs <n>

• Default: 5
• Maximum number of pipeline jobs Opal runs concurrently in a single invocation

#--trace-scripts

• Enables shell tracing with set -x in generated job scripts

#--engine <engine>

• Default: auto
• Accepted values:
  • auto
  • container
  • docker
  • podman
  • nerdctl
  • orbstack
  • sandbox

Notes:

• On macOS, auto uses Apple container.
• On Linux, auto uses podman.
• On macOS, nerdctl is treated as Linux-oriented rather than as a first-class host engine.
• sandbox maps to Anthropic's srt CLI and runs scripts in a sandboxed local process model rather than container-image flags.
• Use .opal/config.toml [sandbox] / [[jobs]].sandbox_* settings to control srt --settings, debug mode, and generated network/filesystem/policy settings.
• You can override the auto default in config with [engine].default.

#--no-tui

• Disables the Ratatui interface and prints plain terminal output instead
• Parallel jobs still run in parallel in this mode.
• When multiple jobs emit logs concurrently, Opal prefixes each streamed line with the job name so interleaved output stays attributable.

#--gitlab-base-url <url>

• Optional GitLab API base URL
• Default when used with GitLab features: https://gitlab.com
• Also available through OPAL_GITLAB_BASE_URL

#--gitlab-token <token>

• Optional GitLab personal access token
• Used for cross-project artifact/include features that require GitLab API access
• Also available through OPAL_GITLAB_TOKEN

#--job <name>

• Repeatable
• Limits execution to selected jobs plus their required upstream dependency closure

Examples:

opal run --job rust-checks
opal run --job package-linux --job deploy-summary

#opal plan

Builds the evaluated execution plan without starting containers.

When opal plan runs in an interactive terminal, it opens the formatted plan in your pager by default.

#Options

#-p, --pipeline <path>

• Which .gitlab-ci.yml file to inspect
• Defaults to <workdir>/.gitlab-ci.yml

#-w, --workdir <path>

• Context directory
• Defaults to the current working directory

#--gitlab-base-url <url>

• Optional GitLab API base URL for GitLab-backed include resolution
• Also available through OPAL_GITLAB_BASE_URL

#--gitlab-token <token>

• Optional GitLab token for GitLab-backed include resolution
• Also available through OPAL_GITLAB_TOKEN

#--job <name>

• Repeatable
• Limits the printed plan to selected jobs plus their required upstream dependency closure

#--no-pager

• Prints the formatted plan directly to stdout instead of opening a pager

#--json

• Emits the execution plan as JSON
• Disables pager behavior automatically

Example:

opal plan --job package-linux
opal plan --no-pager --job package-linux
opal plan --json --job package-linux

#opal view

Opens the history/log browser for previous runs.

#Options

#-w, --workdir <path>

• Context directory
• Defaults to the current working directory

#opal completions <shell>

Prints a shell completion script to stdout.

Supported shells:

• bash
• elvish
• fish
• powershell
• zsh

Examples:

opal completions zsh > "${fpath[1]}/_opal"
opal completions fish > ~/.config/fish/completions/opal.fish
opal completions bash > ~/.local/share/bash-completion/completions/opal

#opal mcp

Starts the MCP server over stdio.

This command is intended for MCP clients that launch Opal as a subprocess and speak JSON-RPC over stdin/stdout.

The current MCP tool surface includes opal_plan, opal_run, opal_run_status, opal_view, opal_history_list, opal_failed_jobs, opal_run_diff, opal_logs_search, opal_job_rerun, opal_plan_explain, and opal_engine_status. opal_run, opal_job_rerun, and opal_logs_search start background operations; opal_view also uses the same background path when include_log or include_runtime_summary is requested. Poll these operations with opal_run_status. opal_history_list supports status, job, branch, pipeline-file, and RFC3339 date-range filters. MCP history, latest-run lookup, and resources are scoped to the current checkout instead of showing unrelated runs from the same $XDG_DATA_HOME/opal tree.

Example:

opal mcp

#Related environment variables

These are not command-line flags, but they change CLI/runtime behavior and are worth knowing:

• OPAL_GITLAB_BASE_URL
  • fallback for --gitlab-base-url
• OPAL_GITLAB_TOKEN
  • fallback for --gitlab-token
• XDG_DATA_HOME
  • sets the data root as $XDG_DATA_HOME/opal for runs, logs, artifacts, cache, and history
• XDG_CONFIG_HOME
  • sets the global config path as $XDG_CONFIG_HOME/opal/config.toml
• OPAL_RUN_MANUAL=1
  • makes manual jobs auto-run in contexts that respect manual-run toggling
• OPAL_DEBUG=1
  • enables script tracing like --trace-scripts

#Common examples

Run the default repo pipeline locally:

opal run

Rerun one recorded job name from the latest Opal history entry against the current checkout:

opal run --rerun-job rust-checks

Rerun a job name from a specific recorded run:

opal run --rerun-job ui-docs-check --rerun-run-id gitlab-ci-70212f44

Run one job plus required upstreams:

opal run --no-tui --job rust-checks

Preview the evaluated DAG only:

opal plan

Inspect a subgraph:

opal plan --job package-linux

Generate a completion script:

opal completions zsh