cikick CLI
The cikick binary is provided by @cikick/cli. It loads the repository’s cikick.config.ts, synthesizes workflows and cikick.lock.json, verifies drift, and runs package migrations. Fleet operations live in a separate binary: see cikick-fleet CLI.
cikick <command> [options]Commands
Section titled “Commands”| Command | Purpose | Writes | Fails (exit 1) when |
|---|---|---|---|
synth |
Synthesize workflows, managed files and the lockfile | Generated files, cikick.lock.json |
Any finding has severity error; frozen lock is missing entries; config or resolver error |
check |
Verify generated files are up to date (frozen) | Nothing | Drift detected, any error finding, or lock is missing entries |
lock |
Resolve action refs and update the lockfile only | cikick.lock.json |
Any error finding; resolver error |
update |
Run package migrations, then synth | Config (via migrations), generated files, lockfile | Synth has error findings; a migration throws |
migrate <pkg> |
Run one package’s migrations explicitly | Whatever the migrations write | Package not installed; invalid semver; a migration throws |
secrets |
Print the declared secrets manifest | Nothing | Config cannot be loaded |
init |
Write a starter cikick.config.ts |
cikick.config.ts |
Directory is not writable |
Usage errors reported by the argument parser (unknown command or option, missing required option) also exit with a non-zero status. Uncaught errors are printed as the bare error message to stderr and exit with code 1.
Shared option
Section titled “Shared option”Every command accepts:
| Option | Default | Description |
|---|---|---|
--dir <repo> |
process.cwd() |
Repository directory. Config, lockfile, package.json and outputs are all resolved relative to it. |
Configuration discovery
Section titled “Configuration discovery”The repository config is the first existing file among cikick.config.ts, cikick.config.mts, cikick.config.js, cikick.config.mjs in --dir. It is loaded with jiti, uncached. The default export must be either an App or a function (app: App) => void | Promise<void>. If none exists the command fails with No cikick.config.ts (or .js/.mjs) found in <dir>. Run \npx cikick init`.`
For function exports, cikick creates new App({ outdir: <dir> }), registers any checks exported by installed cikick packages (see below), then calls your function.
cikick packages
Section titled “cikick packages”Dependencies and devDependencies listed in the repo’s package.json are inspected. An installed package whose own package.json has a string cikick field is a cikick package; that field names a module exporting { migrations, checks? } (see CikickPackageExports in @cikick/core). Its checks are added to the app before your config runs; its migrations are used by update and migrate. Installed versions are recorded in cikick.lock.json under packages. See Migrations.
Resolver order
Section titled “Resolver order”Action refs that are not already full 40-character SHAs and not already in the lockfile are resolved by a FallbackResolver:
GitResolver: runsgit ls-remote https://github.com/<owner>/<repo>forrefs/tags/<ref>, its peeled^{}form, andrefs/heads/<ref>(30 s timeout; needsgitonPATH; no token needed). Tags win over branches; annotated tags are dereferenced to the commit.GitHubResolver: on any failure of the first, callsGET https://api.github.com/repos/<owner>/<repo>/commits/<ref>, sendingAuthorization: Bearer $GITHUB_TOKENwhenGITHUB_TOKENis set and non-empty.
If both fail, the last error (from the GitHub API) is thrown. synth --frozen and check use no network resolver at all: a ref missing from the lockfile raises FrozenLockError before any resolution. synth and lock without --frozen use the order above. See Lockfile and pinning.
Environment variables
Section titled “Environment variables”| Variable | Used by | Effect |
|---|---|---|
GITHUB_TOKEN |
synth, lock, update (non-frozen) |
Bearer token for the GitHub API fallback resolver. Optional; unauthenticated requests are rate-limited. Not used by GitResolver. |
No other environment variables are read by cikick.
cikick synth [--dir <repo>] [--frozen] [--refresh]| Option | Default | Description |
|---|---|---|
--dir <repo> |
cwd | Repository directory. |
--frozen |
off | Fail if a non-SHA action ref is missing from cikick.lock.json. No resolver is used. |
--refresh |
off | Ignore existing lock entries and re-resolve every non-SHA ref. Combined with --frozen this always fails if any non-SHA ref exists. |
Reads: config, installed cikick packages, cikick.lock.json (empty lockfile if absent), and patchFiles of merged managed files. Writes: every synthesized file (workflows under .github/workflows/<id>.yml and managed files) and cikick.lock.json. seeded files that already exist are kept. Files are written even if findings contain errors; the exit code reflects the findings.
Output lines, in order: wrote <path> for each written file (sorted by path) then wrote cikick.lock.json; kept <path> (seeded) for each preserved seeded file; then one line per finding.
Finding format: <SEVERITY padded to 5> [<checkId>] <path>: <message>.
Exit code: 1 if any finding has severity error, otherwise 0. A FrozenLockError or resolver error is printed and exits 1.
npx cikick synthwrote .github/workflows/ci.ymlwrote cikick.lock.jsonWARN [require-timeout] .github/workflows/ci.yml: job "test" has no timeout-minutescikick check [--dir <repo>]Synthesizes in memory with frozen: true and compares against disk. Writes nothing. Intended for CI: see CI check guide.
Drift means a generated file is missing or differs byte-for-byte from the synthesized content (seeded files drift only when missing), or cikick.lock.json differs from the expected serialization (including the recorded packages versions). A missing lockfile counts as drift only if actions need locking.
Output: drift: <path> for each drifted path, then findings in the same format as synth. If any drift exists, stderr also gets Generated files are out of date. Run \npx cikick synth` and commit.` Nothing is printed on a clean run.
Exit code: 1 if there is drift or any error finding (warnings alone pass); a ref missing from the lock prints the FrozenLockError message and exits 1; otherwise 0.
drift: .github/workflows/ci.ymldrift: cikick.lock.jsonGenerated files are out of date. Run `npx cikick synth` and commit.cikick lock [--dir <repo>] [--refresh]| Option | Default | Description |
|---|---|---|
--dir <repo> |
cwd | Repository directory. |
--refresh |
off | Re-resolve every non-SHA action ref. |
Runs a non-frozen synth in memory and writes only cikick.lock.json; workflow files are not touched. Output: wrote cikick.lock.json. Findings are not printed by this command, but an error finding still sets exit code 1.
update
Section titled “update”cikick update [--dir <repo>] [--dry-run]| Option | Default | Description |
|---|---|---|
--dir <repo> |
cwd | Repository directory. |
--dry-run |
off | List the migrations that would run; change nothing. |
For each discovered cikick package, compares the version recorded in the lockfile (packages) with the installed version:
- Not in the lockfile: logs
<pkg>@<version>: first adoption, recording version (no migrations). - Installed older than locked: logs
<pkg>: installed <v> is older than locked <l>; skipping migrations. - Different version: logs
<pkg>: <from> -> <to>and plans every migration withfrom < migration.version <= to, ascending.
Without --dry-run, planned migrations run in order (log: migrate <pkg>@<version>: <description>); the ts-morph project for the config is saved after each, then a full synth runs (non-frozen, resolver order above) which records the new package versions in the lockfile. With --dry-run, logs would run <pkg>@<version>: <description> per migration, or no migrations to run, and exits 0.
Exit code: 1 if the final synth has error findings or a migration throws; otherwise 0. See Migrations and the Renovate guide.
@your-org/wf-node: 1.2.0 -> 1.3.0migrate @your-org/wf-node@1.3.0: rename input node-version to nodeVersionwrote .github/workflows/ci.ymlwrote cikick.lock.jsonmigrate
Section titled “migrate”cikick migrate <pkg> --from <version> [--to <version>] [--dir <repo>]| Option | Default | Description |
|---|---|---|
<pkg> |
required | Name of an installed cikick package. |
--from <version> |
required | Version migrating from (exclusive lower bound). |
--to <version> |
installed version | Version migrating to (inclusive upper bound). |
--dir <repo> |
cwd | Repository directory. |
Runs pkg’s migrations with from < version <= to, skipping everything if from >= to. Logs migrate <pkg>@<version>: <description> per migration. It does not run synth and does not update the lockfile; run cikick synth afterwards. Errors: <pkg> is not an installed cikick package of <dir>; Invalid semver "<v>".
npx cikick migrate @your-org/wf-node --from 1.2.0 --to 1.3.0secrets
Section titled “secrets”cikick secrets [--dir <repo>] [--json]| Option | Default | Description |
|---|---|---|
--dir <repo> |
cwd | Repository directory. |
--json |
off | Print the manifest as indented JSON (SecretManifestEntry[]). |
Loads the config and prints every secret declared through secret(), sorted by name, scope, environment. Prints No secrets declared. when empty. This command only reads declarations; it does not contact GitHub (see Secrets and cikick-fleet secrets report).
NAME SCOPE ENVIRONMENT MAX AGE (d) PROVIDERAWS_ROLE_ARN env production - -NPM_TOKEN repo - 90 npmcikick init [--dir <repo>]Writes a starter cikick.config.ts (a ci workflow with checkout and an echo step) into --dir. If cikick.config.ts already exists it prints cikick.config.ts already exists, leaving it untouched and does not overwrite (only that exact filename is checked). Otherwise prints wrote cikick.config.ts. In both cases it then prints a package.json scripts hint (cikick:synth, cikick:check) and a sample renovate.json that runs npx cikick update as a post-upgrade task. Exit code 0.