# CLI (/docs/cli)



```bash
actio build [...files]   # Compile .actio.yml files into GitHub Actions workflows
actio watch [...files]   # Watch .actio.yml files and rebuild on change
actio check [...files]   # Verify generated workflows are up to date (= build --check)
actio init [file]        # Scaffold a starter .actio.yml file
actio schema             # Print the Actio JSON Schema (--out <file> to save locally)
```

## `build` options [#build-options]

| Flag                                 | Description                                                                                     |
| ------------------------------------ | ----------------------------------------------------------------------------------------------- |
| `--config <file>`                    | Path to an actio config file (overrides auto-discovery)                                         |
| `--out-dir <dir>`                    | Output directory (default `.github/workflows`)                                                  |
| `--target <profile>`                 | Output target profile (`legacy` or `github-actions-native-dependencies-preview`)                |
| `--check`                            | Verify output is up to date without writing (CI drift check)                                    |
| `--stdout`                           | Write generated YAML to stdout instead of files                                                 |
| `-w, --watch`                        | Rebuild on change and keep running (like `tsc --watch`)                                         |
| `--no-validate`                      | Skip schema validation of generated output                                                      |
| `--no-header`                        | Omit the generated-by-Actio banner                                                              |
| `--no-source-map`                    | Do not write a `.yml.map` source map beside each workflow                                       |
| `--no-annotate`                      | Do not inject the `actio-annotate` runtime failure-mapping job                                  |
| `--pin` / `--no-pin`                 | Force pinning of `uses:`/`docker://` refs on or off (overrides config)                          |
| `--pin-github` (`--pin-first-party`) | Also pin first-party `actions/*` and `github/*` refs                                            |
| `--offline`                          | Resolve pins from the lockfile only; fail (exit `2`) if anything is unresolved                  |
| `--strict`                           | Flag YAML 1.1 merge keys (`<<`) in source for strict YAML 1.2.2 (default off, overrides config) |

## Watch mode [#watch-mode]

`actio build --watch` (or `actio watch`) does a full build, then watches your
`.actio.yml` files and their directories — so brand-new files are picked up too —
rebuilding on save. Saves are debounced, each rebuild prints a timestamped summary,
and a transpile error is reported without stopping the watcher (exit stays `0`).
Press `Ctrl+C` to stop.


## Sitemap

Browse the full documentation: [Markdown sitemap](https://austenstone.github.io/actio/sitemap.md) · [XML sitemap](https://austenstone.github.io/actio/sitemap.xml)