CLI Reference
Version: 0.1.0
Single-binary configuration management — validate, check, and apply WCL playbooks, test packages in disposable instances, and scaffold/emit authoring aids.
§ 1Global switches
| Switch | Value | Description | Remarks |
|---|---|---|---|
| --var | KEY=VALUE | Override a playbook variable. Repeatable. VALUE parses as a WCL expression when possible, else a plain string. | — |
| --var-file | PATH | Merge a WCL file's top-level name = value pairs into scope (evaluate standalone; cannot reference other variables). | — |
| --jobs | N | Worker pool size (default min(cpu_count, 8)); forwarded into test instances. | — |
| --continue-on-error | — | Continue dispatching steps after an Error (check/apply). | — |
| --json | — | JSON output: a single schema-stable object on stdout at completion; script log output never goes to stdout. | — |
| --no-color | — | Plain ASCII output (auto-selected when stdout is not a TTY). | — |
| --log-file | PATH | Enable NDJSON file logging (independent of terminal mode). | — |
| --log-level | LEVEL | File log level (independent of terminal verbosity), default info. | — |
| -v, --verbose | — | Increase terminal verbosity (repeatable: -v, -vv, -vvv). | — |
| --password-stdin | — | Read the secrets password from stdin. Alternative to $CONFIG_WEAVE_PASSWORD; exactly one source may be given, and there is no prompt. | — |
| --password-file | PATH | Read the secrets password from a file (one trailing newline is stripped). | — |
§ 2Commands
- config-weave secrets encrypt
- config-weave secrets decrypt
§ 2.1config-weave validate
Full validation pipeline (WCL syntax, schema, refs, DAG, wscript compilation of every script), no execution.
| Argument | Required | Description | Remarks |
|---|---|---|---|
| playbook-dir | required | The playbook directory (contains playbook.wcl). | — |
config-weave validate ./my-playbook§ 2.2config-weave check
Report configuration status of all steps in a play (never mutates).
| Argument | Required | Description | Remarks |
|---|---|---|---|
| playbook-dir | required | The playbook directory. | — |
| play | required | The play to check. | — |
config-weave check ./my-playbook baseline§ 2.3config-weave apply
Apply all unconfigured steps in a play (converge the machine), then re-check each.
| Argument | Required | Description | Remarks |
|---|---|---|---|
| playbook-dir | required | The playbook directory. | — |
| play | required | The play to apply. | — |
config-weave apply ./my-playbook baseline§ 2.4config-weave list
List all plays defined in the playbook.
| Argument | Required | Description | Remarks |
|---|---|---|---|
| playbook-dir | required | The playbook directory. | — |
config-weave list ./my-playbook§ 2.5config-weave test
Run package convergence tests in disposable vmlab instances (containers or VMs) using the three-run protocol.
| Argument | Required | Description | Remarks |
|---|---|---|---|
| playbook-dir | required | The playbook directory. | — |
| filter | optional | Limit to a package or one test: pkg or pkg:test. | — |
| Switch | Value | Description | Remarks |
|---|---|---|---|
| --image | IMAGE | Run every container test against this OCI image instead of its own. | — |
| --template | REF | Run every VM test against this vmlab template instead of its own. | — |
| --keep | — | Leave instances running for post-mortem debugging (handle reported). | — |
| --binary | PATH | Static linux config-weave binary to copy into instances. | — |
| --binary-windows | PATH | Windows config-weave binary for windows guests. | — |
config-weave test ./my-playbook core:file_present_converges§ 2.6config-weave docs
Generate wdoc documentation for the playbook (shares the validation pipeline).
| Argument | Required | Description | Remarks |
|---|---|---|---|
| playbook-dir | required | The playbook directory. | — |
| outdir | optional | Output directory (default <dir>/docs/). | — |
config-weave docs ./my-playbook§ 2.7config-weave wscripti
Emit weave.wscripti (the host API interface) plus a starter wscript.toml so editors and the wscript LSP type-check scripts against the exact host surface.
| Argument | Required | Description | Remarks |
|---|---|---|---|
| outdir | optional | Output directory (default: cwd). | — |
config-weave wscripti ./my-playbook/pkgs/core/resources§ 2.8config-weave init
Scaffold a skeleton playbook with an example package, resource and gatherer.
| Argument | Required | Description | Remarks |
|---|---|---|---|
| dir | required | Destination directory for the new playbook. | — |
config-weave init ./my-playbook§ 2.9config-weave secrets
Encrypt, decrypt or re-key the secret("…") values in playbook.wcl. Works on the raw source, so it is never blocked by the very validation error it clears.
config-weave secrets encrypt
Encrypt every plaintext secret() in place. The password must match the values already encrypted in the file, so a new secret can only be added by someone who can read the existing ones.
| Argument | Required | Description | Remarks |
|---|---|---|---|
| playbook-dir | optional | The playbook directory (default .). | — |
CONFIG_WEAVE_PASSWORD='…' config-weave secrets encrypt ./my-playbookconfig-weave secrets decrypt
Rewrite encrypted values back to plaintext so they can be edited. Leaves the real values on disk in the clear — re-encrypt before committing.
| Argument | Required | Description | Remarks |
|---|---|---|---|
| playbook-dir | optional | The playbook directory (default .). | — |
CONFIG_WEAVE_PASSWORD='…' config-weave secrets decrypt ./my-playbookconfig-weave secrets rekey
Change the password: decrypt with the old one, then re-encrypt every value under a fresh salt — sweeping up any still-plaintext calls in the same pass.
| Argument | Required | Description | Remarks |
|---|---|---|---|
| playbook-dir | optional | The playbook directory (default .). | — |
| Switch | Value | Description | Remarks |
|---|---|---|---|
| --new-password-file | PATH | Read the new password from a file. Alternative to $CONFIG_WEAVE_NEW_PASSWORD. | — |
CONFIG_WEAVE_PASSWORD='old' CONFIG_WEAVE_NEW_PASSWORD='new' config-weave secrets rekey ./my-playbook§ 2.10config-weave version
Print version information.
config-weave version