> ## Documentation Index
> Fetch the complete documentation index at: https://smartcloud.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> Validate and migrate smartcloud configs from the command line.

The `smartcloud` command checks configs and converts v1 configs, without running the action.

The CLI is not published to a registry yet. Run it from a checkout of this repository:

```sh theme={null}
pnpm install
pnpm nx run @resnovas/smartcloud:build
node apps/cli/dist/main.js --help
```

The examples below write `smartcloud` for `node apps/cli/dist/main.js`.

## validate

```sh theme={null}
smartcloud validate [path]
```

Checks a config and every preset it extends, merges them under the [locked preset rules](/configuration#add-never-change), and prints where the config was built from and any migration warnings.

Without a path, it uses the first of `.github/smartcloud.yml`, `.github/smartcloud.yaml` and `.github/config.json` in the current directory.

```text theme={null}
$ smartcloud validate
.github/smartcloud.yml is a valid smartcloud config.
Built from: Resnovas/.github/smartcloud/house.yml@main, .github/smartcloud.yml
```

A config that fails prints one line starting `smartcloud:` and exits with code 1.

## migrate

```sh theme={null}
smartcloud migrate [input] [--out <file>]
```

Converts a v1 JSON config (default `.github/config.json`) to v2 YAML, and prints a warning for every v1 key it does not carry over. The output starts with a schema hint for editors, and is proven to decode before it is written.

| Option        | Meaning                                             |
| ------------- | --------------------------------------------------- |
| `--out`, `-o` | Write the YAML to this file instead of printing it. |

A v2 file given to `migrate` is rewritten unchanged. See [Migrating from v1](/migration) for worked examples.

## check-commit

```sh theme={null}
smartcloud check-commit <file> [--author-name <name> --author-email <email>] [--config <file>]
```

Checks a commit message against the DCO sign-off and AI attribution rules before the commit exists, and exits with code 1 when any rule is broken. The author defaults to git's own, and the config to the repository's in the working directory, or smartcloud's defaults when there is none. Comment lines are ignored, as git ignores them.

Use it as a git `commit-msg` hook, so a commit that would fail the pull request check is stopped locally:

```sh .git/hooks/commit-msg theme={null}
#!/bin/sh
exec npx --yes @resnovas/smartcloud check-commit "$1"
```

## dry-run

```sh theme={null}
smartcloud dry-run --repo <owner/name> (--pr <n> | --issue <n> | --event <event>) [--config <file>] [--features <a,b>]
```

Runs every feature against a real pull request, issue or repository event, through the dry-run layer. It reads GitHub as the action would, then prints the job summary and every write the run would make. It never writes.

| Option            | Meaning                                                                                          |
| ----------------- | ------------------------------------------------------------------------------------------------ |
| `--repo`          | The repository, as `owner/name`.                                                                 |
| `--pr`, `--issue` | Simulate this pull request or issue, built from its current state on GitHub.                     |
| `--event`         | Simulate `schedule`, `push` or `workflow_dispatch`.                                              |
| `--config`        | Use this local config file instead of the repository's own config on its default branch.         |
| `--features`      | Only these features, comma separated. An empty list, such as `--features ,`, runs every feature. |

Give exactly one of `--pr`, `--issue` or `--event`.

## plan settings

```sh theme={null}
smartcloud plan settings --repo <owner/name> [--config <file>]
```

Prints every repository settings step the config would apply, with its request, without applying any of them.

## sync

```sh theme={null}
smartcloud sync --repo <owner/name> --out <dir> [--config <file>]
```

Renders the files the sync feature would write to the repository into a local directory, with each file's status (added, updated, made executable or unchanged), and lists any conflicts. Nothing is sent to GitHub. Every file is checked before any is written: one that would land outside the directory, or be written through a symlink inside it, stops the command with nothing written.

## Tokens

`dry-run`, `plan settings` and `sync` always read GitHub. `validate` needs a token only to read presets named in `extends`, so validating a config without presets works offline. When it does need one, it uses `GITHUB_TOKEN` if set, and otherwise the token of the signed-in GitHub CLI (`gh auth token`). The token is never printed.