CLI Usage

This page explains the main foga CLI workflows and how command selection, profiles, inspection, and dry-run mode fit together. Use foga --help or foga <command> --help for the complete option list generated by the installed CLI.

Configuration file

By default, foga reads ./foga.yml from the current working directory. Use --config when the configuration file lives somewhere else:

foga validate
foga --config path/to/foga.yml validate

Validate and inspect

Run validate after editing foga.yml:

foga validate
foga validate --profile mpi

Run inspect when you need to see the resolved configuration without executing commands:

foga inspect
foga inspect --profile mpi
foga inspect build cpp --target cpp_tests
foga inspect test python --runner unit
foga inspect docs --target python-api
foga inspect --full build cpp

Top-level foga inspect prints the full resolved config. Command-specific inspection prints a concise summary, the relevant config fragment, and the planned commands for the selected workflow unless --full is set.

Preview with dry-run

Dry-run mode prints planned commands without executing them. Use it before moving local scripts, CI jobs, or release steps to foga:

foga build --dry-run
foga test --dry-run

Dry-run output is useful for checking selected profiles, target or runner filtering, generated backend arguments, hook ordering, and working assumptions before running the real command.

Run workflows

Most workflow commands support --profile to apply a named profile before resolving commands:

foga build --profile mpi
foga test --profile mpi --dry-run
foga deploy --profile release --dry-run

Build, test, format, and lint commands can select Python workflows, C++ workflows, or both:

foga build python
foga build cpp --target cpp_tests
foga test python --runner unit
foga test cpp
foga format python --target python-style
foga lint cpp

Target-based commands use --target to select one or more named targets:

foga docs --target site --dry-run
foga install --target editable --dry-run
foga deploy --target pypi --dry-run

Selection and defaults

When a command supports configured defaults, foga uses them only when the CLI does not select a specific runner, target, or workflow kind.

  • test.default_runners controls which test runners run when foga test is called without --runner.

  • docs.default_targets, format.default_targets, lint.default_targets, install.default_targets, and deploy.default_targets control which targets run when the matching command is called without --target.

  • build.default, format.default, and lint.default control the default workflow kind when the command is called without python, cpp, or all.

  • Explicit --runner, --target, python, cpp, or all selections take precedence over configured defaults.

Clean generated paths

Use clean to remove the paths configured under clean.paths:

foga clean

Override precedence

foga resolves configuration in this order:

  1. Base foga.yml

  2. Selected profile overrides from profiles.<name>

  3. CLI overrides for the active command

For example, this base config runs the unit test runner by default:

test:
  default_runners: [unit]
  runners:
    unit:
      backend: pytest
      path: tests/unit
    integration:
      backend: pytest
      path: tests/integration

A profile can override that default:

profiles:
  ci:
    test:
      default_runners: [unit, integration]

With this config, foga test --profile ci runs both test runners. The command foga test --profile ci --runner unit runs only unit for that invocation, but the configured ci profile still keeps default_runners: [unit, integration] in foga.yml.