CLI Reference¶

Global options must be placed before the subcommand. Use collider -v <command> for debug logging; some pkg subcommands use -v for --version.

collider [-v] [--offline] <command> [options]

Use collider <command> --help for command-specific help.

Global Options¶

As noted above, global options must precede the subcommand. The effective offline mode is the global --offline OR the per-command --offline: passing either one is enough.

init¶

Create collider.json in the current project.

collider init

Refuses to run outside a Meson project (no meson.build found).

If the meson.build project() declaration has no license: field, a hint is emitted at init time to avoid discovering the gap only when publishing.

setup¶

Configure a Meson project.

collider setup [--sourcedir PATH] [--builddir PATH] [--allow-drift] -- [meson args]

Examples:

collider setup
collider setup --builddir build
collider setup -- --buildtype=debug

collider setup forces Meson to use Collider's wraps for managed dependencies (via --force-fallback-for) so the build matches the locked versions rather than system copies. The forced set is scoped to collider.lock when present, or all wraps in subprojects/ (with a warning) when it is absent; a malformed collider.lock aborts with EX_DATAERR. A user-supplied --force-fallback-for or -Dforce_fallback_for is honored as-is.

When collider.lock is present, setup verifies that each locked wrap on disk still matches its recorded hash. If an installed .wrap was modified, setup aborts with EX_DATAERR before configuring Meson; run collider lock to re-lock or pass --allow-drift to build anyway (downgrades to a warning). The hash covers the .wrap descriptor only, not the extracted subproject source. A wrap committed into a consumer repo under Git line-ending normalization (core.autocrlf or a .gitattributes text rule) can be re-hashed differently than it was locked and trip the gate; use --allow-drift if that applies. See Wrap Fallback Enforcement.

lock¶

Resolve dependencies from collider.json and write collider.lock.

collider lock [--offline]

A repository's releases.json is untrusted input. Individual malformed entries (non-object shape, unsafe name or version segment) are skipped at the index boundary with a single warning, and the rest of the repository still loads. If a package the resolver directly needs has no usable version anywhere and its metadata was rejected, lock refuses to write a lockfile against corrupt data and aborts with EX_DATAERR. The same fail-closed check applies to install and pkg add.

install¶

Install dependencies. Uses collider.lock when present, falls back to collider.json otherwise.

When using collider.lock, install requires each package's origin repository to be configured. The origin is the repository URL recorded in the lockfile at lock time. If a configured repository's URL does not match the locked origin (after URL normalization), install fails with EX_CONFIG.

With --offline, if the origin repository requires network access, install falls back to the local cache and emits a warning that origin provenance cannot be verified.

collider install [--frozen] [--offline]

patch¶

Create a patch archive from Git changes.

collider patch [--builddir PATH] [--base REV] [--output PATH] [--list]
               [--include-uncommitted / --no-include-uncommitted]

publish¶

Generate a wrap and source archive, then publish to a repository.

collider publish <repo> [--builddir PATH] [--patch-archive PATH]
                        [--push-token-env VAR] [--insecure] [--dry-run]

unpublish¶

Remove a package version from a repository.

collider unpublish <repo> <package> <version> [--push-token-env VAR] [--insecure]

repo add¶

Add a repository entry to config.json.

collider repo add <name> <type> <url> [--publish-url URL]

repo remove¶

Remove a repository entry from config.json.

collider repo remove <name>

Alias: collider repo rm <name>

repo list¶

List configured repositories.

collider repo list

Alias: collider repo ls

pkg add¶

Add a package dependency and install it into subprojects/.

collider pkg add <name> [--version SPEC] [--offline] [--force]
                 [--include PKG] ... [--exclude PKG] ...
                 [--include-conditional] [--exclude-optional]

Alias: collider pkg install

Fails if the package is already installed unless --force is given. If the wrap is installed only as a transitive dependency, pkg add promotes it into collider.json without reinstalling it. Does not update collider.lock.

pkg remove¶

Remove a dependency from collider.json. Collider removes the installed wrap only when it can prove the package is no longer needed; otherwise it leaves the wrap in place. When it does remove a package, it deletes both the .wrap descriptor and the extracted source tree under subprojects/ (the directory the wrap declares via directory=, plus the legacy <name> directory), so a stale tree cannot later satisfy a Meson dependency().

collider pkg remove <name>

Alias: collider pkg rm <name>

Does not update collider.lock; you are warned to run collider lock if the removed package is still in the lockfile.

pkg prune¶

Remove orphaned Collider-managed transitive wraps that are no longer needed by any declared dependency. Only wraps proven to be Collider-managed via collider.lock are eligible for removal; manually placed wraps are never touched.

collider pkg prune [--dry-run]

If no lockfile exists, prune warns and does nothing. A corrupt lockfile is treated the same way to avoid accidental deletion. pkg prune does not rewrite collider.lock; after deletions, Collider warns you to run collider lock to refresh it.

pkg search¶

Search repositories or the local cache by package name.

collider pkg search <pattern> [--cache] [--repository NAME] ... [--version SPEC]

pkg info¶

Show versions, origins, and cache status for a package.

collider pkg info <name> [--repository NAME] ...

Alias: collider pkg policy

pkg upgrade¶

Upgrade one or all collider-managed dependencies.

collider pkg upgrade [<name>] [--version SPEC] [--offline]

Does not update collider.lock.

check¶

Detect drift between meson.build dependency() calls and collider.json.

collider check [--sourcedir PATH] [--include-conditional]

Reports untracked dependencies (called in meson.build but not in collider.json) and stale entries (in collider.json but absent from meson.build). Exits 0 when clean, non-zero on drift. Suitable for CI use.

status¶

Show collider-managed dependencies and local wrap status.

collider status

Reports tracked Collider dependencies from collider.json, system dependencies declared with "source": "system", transitive dependencies, and untracked wraps found in subprojects/. For tracked and transitive entries, Collider shows version information and whether the wrap is installed or missing. When collider.lock exists, transitive classification uses the lock. Otherwise, Collider re-resolves from collider.json when repository metadata is available. Lock drift (ok / modified / missing) is reported when a lockfile exists.

serve¶

Serve a filesystem repository over HTTP.

collider serve <path> [--host HOST] [--port PORT]
               [--push-token TOKEN] [--push-token-env VAR]
               [--publish-url URL]

Push routes are disabled unless a push token is configured.

Exit Codes¶

Subcommands return os.EX_* codes from the standard os module. The two non-EX_* codes come from the CLI wrapper and argparse.