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:

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

smartcloud validate [path]

Checks a config and every preset it extends, merges them under the locked preset rules, 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.

$ smartcloud validate
.github/smartcloud.yml is a valid smartcloud config.
Built from: Resnovas/.github/smartcloud/house.yml@main, .github/smartcloud.yml

Validation is strict: an unknown key or invalid value in the config or any preset is an error, where a run only drops it with a warning. A config that fails prints one line starting smartcloud: and exits with code 1.

migrate

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 for worked examples.

check-commit

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:

.git/hooks/commit-msg

#!/bin/sh
exec npx --yes @resnovas/smartcloud check-commit "$1"

dry-run

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

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

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.