Commands · reference
config-weave pkg
pkg installs packages into a playbook's pkgs/ directory from git repositories. The file pkgs/repo.wcl records the registered repositories and every installed package with the repository and exact commit it came from. Every subcommand shells out to the git binary, so your ambient credentials work against private repositories. Clones are shallow and cached under .repo-cache/<repo> in the playbook directory. See Packages, resources and gatherers for what a package is.
repo.wcl is tooling metadata, not playbook semantics. The playbook loader never reads it, so a broken repo.wcl breaks only the pkg commands, never check or apply. The first time the cache directory appears, the command prints a reminder to add .repo-cache/ to .gitignore when it is not already there. It never edits .gitignore itself.
Synopsis
config-weave pkg [--dir <PLAYBOOK>] <COMMAND>
Commands:
add Install a package from a registered repository into pkgs/
remove Delete an installed package and its repo.wcl entry
update Re-sync and re-copy installed packages
search Search package names and descriptions across registered repos
repo Manage the registered package repositories
Options
One option is shared by every pkg subcommand. The global options are accepted too but have no effect here.
| Option | Value | Meaning |
|---|---|---|
| --dir | PLAYBOOK | The playbook directory. Default .. Accepted before or after the subcommand. |
The default repository
When pkg add or pkg search runs and no repository is registered, including when repo.wcl does not exist yet, the command seeds the public standard library repository and saves it. Its name is stdlib, its URL is https://github.com/Configweave/config-weave-pkgs.git, and its packages live in the pkgs subdirectory of the checkout. A repo.wcl that lists at least one repository is always respected as written. The other subcommands operate only on what is already recorded.
pkg add
config-weave pkg add [--dir <PLAYBOOK>] <PACKAGE>
Installs one package. The command syncs every registered repository, finds the first one whose packages root holds <PACKAGE>/package.wcl, copies that directory into pkgs/<PACKAGE>, and records the package with the repository's head commit in repo.wcl. Repositories are searched in registration order. When several hold the package, the first wins and the others are reported as shadowed. The copy skips .git, node_modules, target, .vmlab and every other dot-directory.
| Argument | Meaning |
|---|---|
| PACKAGE | The package name, which is also the directory name under pkgs/. |
The command fails when the package is already recorded as installed, when pkgs/<PACKAGE> exists but was not installed by pkg add, when the name is not a valid package name, or when no repository holds it. A repository that cannot be synced still participates with its cached checkout when one exists, and the failure is reported as a warning.
pkg remove
config-weave pkg remove [--dir <PLAYBOOK>] <PACKAGE>
Deletes pkgs/<PACKAGE> and drops its entry from repo.wcl. When the directory is already gone the entry is still removed. A package that was never installed by pkg add is refused, with a note to delete the directory by hand. Repositories are not touched.
| Argument | Meaning |
|---|---|
| PACKAGE | The installed package to remove. |
pkg update
config-weave pkg update [--dir <PLAYBOOK>] [PACKAGE]
Re-syncs the source repositories and re-copies installed packages, then records the new commit. With no argument every installed package is updated. pkgs/<name> is a managed directory: when the source repository has moved, local edits inside it are lost. Keep local changes in a package of your own instead.
| Argument | Meaning |
|---|---|
| PACKAGE | One installed package to update. Optional. Must already be recorded in repo.wcl. |
pkg search
config-weave pkg search [--dir <PLAYBOOK>] <TERM>
Syncs every registered repository and prints the packages whose name or description contains the term, case-insensitively. Each row shows the repository, the package name and its description. An installed package is marked [installed], or [installed from <repo>] when it came from a different repository. Seeds the default repository when none is registered.
| Argument | Meaning |
|---|---|
| TERM | Substring to match against names and descriptions. |
pkg repo add
config-weave pkg repo add [--dir <PLAYBOOK>] [--branch <BRANCH>] [--subdir <SUBDIR>] <NAME> <URL>
Registers a git repository of packages in repo.wcl and syncs it into .repo-cache/<NAME> at once. The name becomes a directory under the cache, so it must be a valid name.
| Argument or option | Value | Meaning |
|---|---|---|
| NAME | The name the repository is known by locally. | |
| URL | Any URL git clone accepts, including SSH forms for private repositories. | |
| --branch | BRANCH | Branch to track. The remote's default branch when unset. |
| --subdir | SUBDIR | Subdirectory of the checkout that holds the package directories. The checkout root when unset. |
pkg repo remove
config-weave pkg repo remove [--dir <PLAYBOOK>] <NAME>
Unregisters a repository. Packages installed from it stay in pkgs/ and in repo.wcl.
| Argument | Meaning |
|---|---|
| NAME | The registered repository to remove. |
pkg repo list
config-weave pkg repo list [--dir <PLAYBOOK>]
Prints a table of the registered repositories with their URL, branch, subdirectory and cache state. The cache state is not synced when no clone exists, dirty when the clone has local modifications, or the short commit at the clone's head. This command reads local state only and never touches the network.
Examples
Install two packages from the standard library into the current playbook. The first call seeds the repository.
config-weave pkg add core
seeded package repo 'stdlib' (https://github.com/Configweave/config-weave-pkgs.git)
note: add '.repo-cache/' to ./.gitignore
installed 'core' from 'stdlib' @ 3f9c2a1
config-weave pkg add nginx
installed 'nginx' from 'stdlib' @ 3f9c2a1
Register a private repository whose packages live under packages/, then search it.
config-weave pkg --dir ./my-playbook repo add corp [email protected]:example/weave-pkgs.git --subdir packages
config-weave pkg --dir ./my-playbook search ldap
Bring every installed package up to date and confirm the state.
config-weave pkg update
config-weave pkg repo list
Exit status
0 when the operation completed, including a search with no matches. 2 on any error: a package or repository that does not exist, an invalid name, a repo.wcl that fails its schema, a directory that could not be copied or removed, or a git command that failed for the operation to proceed. A repository that fails to sync during add, update or search is a warning, not an error, as long as the operation can still complete.