Complete reference for all CLI commands and flags used in the DockyPody build system.
The dockypody.nu script is the canonical entry point for the DockyPody build system. It provides a unified interface to all build, test, validation, TLS, and CI operations.
# Show top-level help
nu scripts/dockypody.nu help
# Build commands
nu scripts/dockypody.nu build --service gaia
nu scripts/dockypody.nu build --all-services --show-build-order
# Test commands
nu scripts/dockypody.nu test --suite defaults
nu scripts/dockypody.nu test --suite all --verbose
# TLS commands
nu scripts/dockypody.nu tls ca
nu scripts/dockypody.nu tls certs
nu scripts/dockypody.nu tls clean
nu scripts/dockypody.nu tls clean --service-ca-only
# SSH commands
nu scripts/dockypody.nu ssh key
nu scripts/dockypody.nu ssh key --force
# CI commands (--target is mandatory for workflow)
nu scripts/dockypody.nu ci list-deps --service nextcloud
nu scripts/dockypody.nu ci workflow --target all --dry-run
nu scripts/dockypody.nu ci images --service nextcloud
nu scripts/dockypody.nu ci ghcr-purge --dry-run
# --max-deletes is a global budget across all services in the run
nu scripts/dockypody.nu ci ghcr-purge --dry-run=false --max-deletes=200
# Force-wipe is allowed only for a single service and only with --dry-run=false
nu scripts/dockypody.nu ci ghcr-purge --service nextcloud --dry-run=false --max-deletes=200 --force
# Optional partial-success policy: tolerate live delete failures and continue
nu scripts/dockypody.nu ci ghcr-purge --service nextcloud --dry-run=false --partial-success
# Validate commands
nu scripts/dockypody.nu validate --all-services
nu scripts/dockypody.nu validate --service gaia
nu scripts/dockypody.nu validate --service gaia --manifests-only
# Docs commands
nu scripts/dockypody.nu docs lint
nu scripts/dockypody.nu docs lint --fix| Subcommand | Description | Domain CLI |
|---|---|---|
build |
Build container images | build/cli.nu [build-cli] |
test |
Run test suites (--suite, --verbose) |
test/cli.nu [test-cli] |
validate |
Validate service configurations | validate/cli.nu [validate-cli] |
inspect |
Print guard-owned effective merged config | inspect/cli.nu [inspect-cli] |
tls ca |
Generate CA certificate | tls/cli.nu [tls-cli] |
tls certs |
Generate service certificates | tls/cli.nu [tls-cli] |
tls clean |
Remove TLS artifacts | tls/cli.nu [tls-cli] |
ssh key |
Generate SSH keypair | ssh/cli.nu [ssh-cli] |
ci list-deps |
List dependency services | ci/cli.nu [ci-cli] |
ci prepare-node-deps |
Download/load dep shards from run artifacts (CI) | ci/cli.nu [ci-cli] |
ci workflow |
Write CI workflow YAML (--target ..., --dry-run) | ci/cli.nu [ci-cli] |
ci images |
List canonical image references | ci/cli.nu [ci-cli] |
ci login-registry |
Log into default container registry | ci/cli.nu [ci-cli] |
ci ghcr-purge |
Purge stale GHCR package versions (SSOT-based) | ci/cli.nu [ci-cli] |
docs lint |
Lint documentation files | docs/cli.nu [docs-cli] |
dockypody.nu acts as a thin router that delegates to domain-specific CLI entrypoints:
- Each domain under
scripts/lib/exposes a<domain>-clifunction incli.nu - The router parses top-level commands and flags, then calls the appropriate domain CLI
- Domain CLIs handle subcommand routing and flag processing internally
- This pattern enables clean separation of concerns and testable domain logic
DockyPody owns the positional help contract:
- Top level:
nu scripts/dockypody.nu help - Single-command CLIs:
nu scripts/dockypody.nu build help,nu scripts/dockypody.nu test help,nu scripts/dockypody.nu validate help - Routed domains:
nu scripts/dockypody.nu tls help,nu scripts/dockypody.nu ssh help,nu scripts/dockypody.nu ci help,nu scripts/dockypody.nu docs help,nu scripts/dockypody.nu inspect help
Nushell intercepts --help and -h before dockypody.nu's main body runs,
so those flag forms are Nushell help, not DockyPody-owned command help.
All flags below live on scripts/dockypody.nu main. Each handler reads only its
subset; unrelated flags remain parsed but unused for that invocation.
Build-related: --service, --all-services, --push, --latest,
--extra-tag, --provenance, --version, --all-versions, --versions,
--latest-only, --platform, --matrix-json, --progress, --cache-bust,
--no-cache, --show-build-order, --dep-cache, --push-deps, --tag-deps,
--fail-fast, --pull, --disk-monitor,
--prune-cache-mounts, --plane.
Test: --suite, --verbose.
Validate: --service, --all-services, --manifests-only, --plane.
Inspect: --service, --version, --platform, --plane.
TLS: --service (comma-separated service names passed to clean), --filter
(comma list for cert generation subset), --service-ca-only, --skip-shared-ca,
--keep-empty-dirs, --dry-run, --force, --verbose.
SSH: --force.
CI (shared fields): --service, --version, --platform,
--dependencies (comma list), --target, --transitive,
--debug, --dry-run, --max-deletes, --force,
--partial-success.
Docs: --fix.
The sections below summarize commands other than build. Build flags remain the
bulk of this file starting at Build Command.
nu scripts/dockypody.nu test [--suite <name>] [--verbose]--suiteaccepts a runnable public suite name surfaced bynu scripts/dockypody.nu test help. The default suite nameallruns the current public bundle from that same inventory.
nu scripts/dockypody.nu validate [--service <name>] [--all-services]
[--manifests-only] [--plane tracked|local]--all-services: validate every discovered service (mutually exclusive with a single--service; seevalidate-clibehavior).--plane: config plane for this invocation.tracked(default) uses tracked manifests underservices/.localactivates the off-git local plane at.dockypody.local/and merges optional.dockypody.local/services/<service>/versions.nuonfragments; the command hard-errors when that root directory is missing. An empty.dockypody.local/root is valid. Service discovery still uses trackedservices/*.nuononly. Tracked CI generation consumes only tracked versions;--plane localis rejected atbuild --matrix-json,ci workflow, andci ghcr-purge.
Subcommands: effective-config.
nu scripts/dockypody.nu inspect effective-config --service <name>
[--version <ver>] [--platform <plat>] [--plane tracked|local]--service: required foreffective-config.--version: optional; defaults to the manifest default for the active plane.--platform: optional; required only for multi-platform services when you need a specific platform slice.--plane: config plane for this invocation.tracked(default) uses tracked manifests underservices/.localmerges optional.dockypody.local/services/<service>/versions.nuonfragments; the command hard-errors when.dockypody.local/is missing. Use--plane localwhen previewing or debugging dev-only version names that exist only in the local fragment.
Example (local-only version name):
nu scripts/dockypody.nu inspect effective-config --plane local --service nextcloud-contacts --version main-nc-masterSubcommands: ca, certs, clean; positional help is
nu scripts/dockypody.nu tls help.
nu scripts/dockypody.nu tls ca [--force] [--verbose]
nu scripts/dockypody.nu tls certs [--filter svc1,svc2] [--verbose]
nu scripts/dockypody.nu tls clean [--service a,b] [--dry-run]
[--skip-shared-ca] [--keep-empty-dirs] [--service-ca-only]TLS library helpers like copy-tls are module exports only; no tls copy
subcommand is routed through dockypody.nu.
tls ca --forceregenerates the shared CA even if it already exists. After a forced CA regeneration, regenerate service certificates withnu scripts/dockypody.nu tls certs.--filterapplies totls certsonly.--service,--dry-run,--skip-shared-ca,--keep-empty-dirs, and--service-ca-onlyapply totls cleanonly.
Subcommands: key.
nu scripts/dockypody.nu ssh key [--force]Invoke as nu scripts/dockypody.nu ci <subcommand> [flags].
| Subcommand | Role | Typical flags |
|---|---|---|
list-deps |
Print dependency names (stdout lines) | --service, optional --transitive, --debug |
prepare-node-deps |
Download shard artifacts when run in GitHub Actions | --service, --version, optional --platform, --dependencies (comma), --debug |
workflow |
Rewrite workflow files from templates | Mandatory --target (see targets below), --dry-run optional |
images |
Print canonical refs for caches | --service |
login-registry |
Registry login helper | --debug |
ghcr-purge |
Trim GHCR package versions vs SSOT | Optional --service (omit = all services), --dry-run, --max-deletes, --debug, --force (needs single service, no dry-run), --partial-success (default is strict failure on live delete errors) |
ci workflow --target must be exactly one of: all, build, build-push,
orchestrator, build-service, image-purge. An omitted or empty --target
is rejected by the routed ci-cli preflight before target resolution runs.
Generated workflows use ci prepare-node-deps plus workflow-local shard
artifacts for dependency reuse.
ci ghcr-purge reports run totals with separate planned, attempted,
deleted, failed, skipped, and charged counts. Dry-run reports planned
candidates but charges 0 against the live delete budget. Permission-denied
version lists are soft-skipped and named explicitly in the final summary.
--max-deletes defaults differ by entrypoint on purpose. The public CLI
default is 0, which means unlimited unless you pass a bound explicitly.
Bundled workflows keep bounded defaults instead: build-push.yml runs
ghcr-purge with --max-deletes=200, and image-purge.yml exposes a
max_deletes input that defaults to 100.
Subcommands: lint.
nu scripts/dockypody.nu docs lint [--fix]The routed dockypody.nu contract is repo-wide linting only. It always passes
an empty file list into the module API, so file discovery uses
git ls-files --cached --others --exclude-standard and respects
ignored/generated trees.
Autofix (--fix) replaces all occurrences of each forbidden pattern, rescans
the changed files, and exits successfully only when the rescan is clean.
nu scripts/dockypody.nu build --service <service-name> [options]Select the config plane for this invocation. Accepted values: tracked
(default) or local.
# Default: tracked manifests under services/
nu scripts/dockypody.nu build --service gaia
# Local plane: require .dockypody.local/ at repo root
nu scripts/dockypody.nu build --service gaia --plane localModes:
| Mode | Behavior |
|---|---|
tracked |
Use tracked service manifests under services/ (default) |
local |
Merge off-git version fragments from .dockypody.local/services/<service>/versions.nuon |
local requirements:
.dockypody.local/must exist at the repository root; otherwise the command hard-errors.- An empty
.dockypody.local/directory is valid. - An optional
.dockypody.local/services/directory with zero mirrors is also valid. - If a service mirror directory exists, it must contain
versions.nuon; an empty mirror hard-errors ("Incomplete local service mirror"). - Local fragments use the same
versions: [...]schema as tracked manifests. - Local fragments use the same JSONC-style authoring rules as tracked manifests. Do not use bare keys or NUON table syntax. Same-name versions are fully replaced; new names are appended. Local-only services and additive source ids are forbidden.
- Service discovery still uses tracked
services/*.nuononly. - Tracked CI generation consumes only tracked versions (never local).
--plane localis rejected atbuild --matrix-json,ci workflow, andci ghcr-purge.ci list-depsalways operates on tracked manifests (tracked-only by data; it does not reject the flag).
--plane is also accepted on validate and inspect effective-config with
the same modes and rules.
Example (preview a local-plane merge without building):
nu scripts/dockypody.nu inspect effective-config --plane local --service gaia --version masterBuild a specific service. Use this when you are not targeting
--all-services:
nu scripts/dockypody.nu build --service revad-baseBuild all discovered services in dependency order:
nu scripts/dockypody.nu build --all-servicesDiscovers all services in the services/ directory, resolves dependencies, computes the global build order, and builds all services in topological order.
Flag Conflicts:
- Mutually exclusive with
--service(explicit service selection) - Mutually exclusive with
--version(use--latest-onlyor--all-versionsinstead) - Mutually exclusive with
--versions(use--latest-onlyor--all-versionsinstead)
Compatible with:
--all-versions- Build all versions of all services--latest-only- Build only latest versions of all services--platform- Filter builds to a specific platform (skips services without that platform)--push,--latest,--extra-tag- Apply to all target services--push-deps,--tag-deps- Apply to dependencies of all services--cache-bust,--no-cache- Apply to all services--fail-fast- Stop on first failure--show-build-order- Show merged build order and exit--matrix-json- Generate CI matrix for all services (respects version and platform flags)
Behavior:
- Services without version manifests are skipped with a warning
- Services without the specified
--platformare skipped - Default version is built unless
--all-versionsor--latest-onlyis specified - Dependency graph is constructed per-service and merged with deduplication
- Continue-on-failure is default (use
--fail-fastto stop on first error)
Examples:
# Build all services with default versions
nu scripts/dockypody.nu build --all-services
# Build all services, all versions
nu scripts/dockypody.nu build --all-services --all-versions
# Build only latest versions of all services
nu scripts/dockypody.nu build --all-services --latest-only
# Build all services for debian platform only
nu scripts/dockypody.nu build --all-services --platform debian
# Generate CI matrix for all services
nu scripts/dockypody.nu build --all-services --matrix-json
# Show build order without building
nu scripts/dockypody.nu build --all-services --show-build-orderBuild a specific version from the manifest:
nu scripts/dockypody.nu build --service revad-base --version v3.10.1Build all versions defined in the manifest:
nu scripts/dockypody.nu build --service revad-base --all-versionsBuild only versions marked with latest: true:
nu scripts/dockypody.nu build --service revad-base --latest-onlyBuild multiple specific versions (comma-separated list):
nu scripts/dockypody.nu build --service revad-base --versions v3.10.1,masterNote: --version (singular) for single version, --versions (plural) for multiple versions.
Filter builds to a specific platform (requires platforms.nuon, even if that
manifest defines only one platform):
# Build only debian variant
nu scripts/dockypody.nu build --service my-service --version v1.0.0 --platform debian
# Build all debian versions
nu scripts/dockypody.nu build --service my-service --all-versions --platform debianYou can specify platforms inline with version names:
# Build only v1.0.0-debian
nu scripts/dockypody.nu build --service my-service --version v1.0.0-debian
# Build multiple platform-specific versions
nu scripts/dockypody.nu build --service my-service --versions "v1.0.0-debian,v1.0.0-alpine"Rules:
- Suffix format:
-<platform-name> - Suffix must match a platform in
platforms.nuon - Cannot have double dashes:
v1.0.0--debianis invalid - Cannot end with dash:
v1.0.0-is invalid
Conflicts:
- ERROR:
--version v1.0.0-debian --platform alpine(conflict) - CORRECT: Use one or the other
Output GitHub Actions matrix JSON:
nu scripts/dockypody.nu build --service revad-base --matrix-jsonOutput format:
{
"include": [
{
"version": "v1.0.0",
"platform": "",
"latest": true
}
]
}{
"include": [
{
"version": "v1.0.0",
"platform": "debian",
"latest": true
},
{
"version": "v1.0.0",
"platform": "alpine",
"latest": false
}
]
}Platform Field:
- Empty string (
"") = service resolved without an explicitplatforms.nuonmanifest - Non-empty string = platform name from
platforms.nuon, even when that manifest contains only one platform - Never
null- always a string (empty or platform name)
Override cache busting for all services in the build with a custom value:
# Use custom cache bust value for all services
nu scripts/dockypody.nu build --service cernbox-web --cache-bust "abc123"When set, this value applies to:
- Target service
- All dependencies (if auto-build enabled)
- All services in multi-version builds
Default behavior: Each service uses its own source refs hash (computed from service's sources), or Git SHA if no sources, or "local" if no Git.
Force cache invalidation by generating a random UUID for all services:
# Force rebuild of all services (no cache)
nu scripts/dockypody.nu build --service cernbox-web --no-cacheThis is equivalent to --cache-bust <random-uuid> but more convenient for forcing full rebuilds.
Note: Cache busting is per-service by default. Use these flags for global overrides.
Control dependency reuse behavior for CI builds:
# Disable hash-based skip (always build deps)
nu scripts/dockypody.nu build --service cernbox-web --dep-cache=off
# Hash-based skip + auto-build on missing/stale (default for CI)
nu scripts/dockypody.nu build --service cernbox-web --dep-cache=soft
# Strict validation, fail on missing/stale (no auto-build)
nu scripts/dockypody.nu build --service cernbox-web --dep-cache=strictModes:
| Mode | Behavior | Use Case |
|---|---|---|
off |
Always build deps, no hash skip | Local development, forced rebuilds |
soft |
Hash-based skip + auto-build on missing/stale | Default for CI workflows |
strict |
Hash validation, fail on missing/stale | Explicit dependency control |
Defaults:
- Local builds:
off(always build, rely on Docker layer cache) - CI builds:
soft(hash-based skip + auto-build)
Use cases:
--dep-cache=off: Force rebuild of all dependencies--dep-cache=soft: Standard CI workflow with cache reuse--dep-cache=strict: CI/CD scenarios where dependencies must be pre-built
Push dependencies to registry (independent of --push flag):
# Push dependencies but not target service
nu scripts/dockypody.nu build --service cernbox-web --push-deps
# Push both dependencies and target service
nu scripts/dockypody.nu build --service cernbox-web --push --push-depsBehavior:
- Only affects dependencies (not target service)
- Independent of
--pushflag - Can be used with or without
--push
Tag dependencies with --latest and/or --extra-tag (independent of target service tags):
# Tag dependencies as latest
nu scripts/dockypody.nu build --service cernbox-web --latest --tag-deps
# Tag dependencies with custom tag
nu scripts/dockypody.nu build --service cernbox-web --extra-tag stable --tag-deps
# Tag both dependencies and target
nu scripts/dockypody.nu build --service cernbox-web --latest --tag-depsBehavior:
- Propagates both
--latestand--extra-tagflags to dependencies - Independent of target service tags
- The tagging system checks each dependency's version manifest to determine if tags are actually applied
- If a dependency's version manifest doesn't allow a tag (e.g.,
latest: false), the tag is not applied even if the flag is propagated - Example: If
--tag-deps --latestis used, but a dependency's version haslatest: false, thelatesttag is not applied to that dependency
Display the dependency build order without actually building:
# Show build order for service (default version)
nu scripts/dockypody.nu build --service cernbox-web --show-build-order
# Show build order for specific version
nu scripts/dockypody.nu build --service cernbox-web --show-build-order --version v1.0.25
# Show build order for all versions
nu scripts/dockypody.nu build --service cernbox-web --show-build-order --all-versions
# Show build order for specific versions
nu scripts/dockypody.nu build --service cernbox-web --show-build-order --versions v1.0.25,ocm-webapp-share
# Show build order for latest versions only
nu scripts/dockypody.nu build --service cernbox-web --show-build-order --latest-onlySingle-Version Output Format:
=== Build Order ===
1. revad-base:v3.10.1
2. cernbox-revad:v3.10.1
3. cernbox-web:v1.0.25
Multi-Version Output Format:
=== Build Order ===
Version: v1.0.25
1. revad-base:v3.10.1
2. cernbox-revad:v3.10.1
3. cernbox-web:v1.0.25
Version: ocm-webapp-share
1. revad-base:ocm-webapp-share
2. cernbox-revad:ocm-webapp-share
3. cernbox-web:ocm-webapp-share
Multi-Platform Output Format:
For services using platforms.nuon, each version/platform combination is
displayed separately:
=== Build Order ===
Version: v1.0.25 (production)
1. revad-base:v3.10.1:production
2. cernbox-revad:v3.10.1:production
3. cernbox-web:v1.0.25:production
Version: v1.0.25 (development)
1. revad-base:v3.10.1:development
2. cernbox-revad:v3.10.1:development
3. cernbox-web:v1.0.25:development
Multi-Version Flags:
--all-versions- Show build order for all versions in the manifest--versions <list>- Show build order for specific versions (comma-separated)--latest-only- Show build order for versions markedlatest: true--platform <string>- Filter to a platform fromplatforms.nuon
Use cases:
- Debugging dependency resolution
- Understanding build order before building
- Verifying dependency graph construction
- Auditing dependency chains across multiple versions
- Previewing build order for release planning
Break on first failure (only applies to multi-version builds):
# Build all versions, stop on first failure
nu scripts/dockypody.nu build --service revad-base --all-versions --fail-fastDefault behavior:
- Single service builds: Always fail fast (errors propagate immediately, no summary generated)
- Multi-version builds (with or without platforms): Continue-on-failure by default (collect all failures, report summary)
- Dependency build failures: Always fail fast (regardless of
--fail-fastflag) - build stops immediately with error message
Note: The --fail-fast flag only applies to multi-version builds of the target service. Dependency build failures always cause immediate stop regardless of this flag.
Use cases:
- CI/CD scenarios where you want to stop immediately on failure
- Debugging specific version build issues
Push built images to registry:
nu scripts/dockypody.nu build --service revad-base --version v3.10.1 --pushSet build progress output format:
nu scripts/dockypody.nu build --service revad-base --all-versions --progress plainControl latest tag generation:
nu scripts/dockypody.nu build --service revad-base --version master --latest falseControl disk monitoring output during builds. off disables monitoring.
Any other non-off value enables the same basic disk usage snapshots.
Generated workflows currently pass basic.
# Enable basic disk monitoring
nu scripts/dockypody.nu build --service cernbox-web --all-versions --disk-monitor=basic
# Default: monitoring disabled
nu scripts/dockypody.nu build --service cernbox-web --all-versions --disk-monitor=offRuntime contract:
| Value | Behavior |
|---|---|
off |
No monitoring (default for local builds) |
any non-off |
Emit disk usage snapshots at build phases |
CI Default: basic (enabled for all services in generated workflows)
Prune BuildKit cache between version builds:
# Enable cache pruning
nu scripts/dockypody.nu build --service cernbox-web --all-versions --prune-cache-mounts
# Default: pruning disabled (local builds)
nu scripts/dockypody.nu build --service cernbox-web --all-versionsBehavior:
- Runs
docker builder prune -fafter each version build (clears all BuildKit cache) - Only affects multi-version builds (single-version builds have no intermediate phases)
- Preserves Docker image cache (only prunes build-time cache, not final images)
- Shows disk usage after prune to confirm the effect
- Non-fatal: failures are logged as warnings and builds continue
What gets pruned:
- Intermediate build layers
- Exec cache mounts (
RUN --mount=type=cacheentries) - Source cache
- Build context cache
What is preserved:
- Final Docker images
- Docker layer cache for images
Use cases:
- CI environments with limited disk space
- Multi-version builds where build cache accumulates (e.g.,
cernbox-webwith 8+ versions) - Investigating disk exhaustion issues
CI Default: Enabled for all services in generated workflows (prune_build_cache: true)
Local Usage: Typically not needed (persistent Docker cache is beneficial). Enable manually when simulating CI behavior or debugging disk issues.
- Multi-Version Builds Guide - Complete version management guide
- Multi-Platform Builds Guide - Complete platform management guide
- Build System - Build system architecture