# 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:

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

## Validate and inspect

Run `validate` after editing `foga.yml`:

```bash
foga validate
foga validate --profile mpi
```

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

```bash
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`:

```bash
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:

```bash
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:

```bash
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:

```bash
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`:

```bash
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:

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

A profile can override that default:

```yaml
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`.