Skip to content

Latest commit

 

History

History
855 lines (613 loc) · 27.7 KB

File metadata and controls

855 lines (613 loc) · 27.7 KB

CLI Reference

Overview

Complete reference for all CLI commands and flags used in the DockyPody build system.

Unified CLI: dockypody

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.

Basic Usage

# 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

Available Subcommands

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]

CLI Architecture

dockypody.nu acts as a thin router that delegates to domain-specific CLI entrypoints:

  • Each domain under scripts/lib/ exposes a <domain>-cli function in cli.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

Help routing

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.

Router flags snapshot

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.

Non-build commands (reference)

The sections below summarize commands other than build. Build flags remain the bulk of this file starting at Build Command.

test

nu scripts/dockypody.nu test [--suite <name>] [--verbose]
  • --suite accepts a runnable public suite name surfaced by nu scripts/dockypody.nu test help. The default suite name all runs the current public bundle from that same inventory.

validate

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; see validate-cli behavior).
  • --plane: config plane for this invocation. tracked (default) uses tracked manifests under services/. local activates the off-git local plane at .dockypody.local/ and merges optional .dockypody.local/services/<service>/versions.nuon fragments; the command hard-errors when that root directory is missing. An empty .dockypody.local/ root is valid. Service discovery still uses tracked services/*.nuon only. Tracked CI generation consumes only tracked versions; --plane local is rejected at build --matrix-json, ci workflow, and ci ghcr-purge.

inspect

Subcommands: effective-config.

nu scripts/dockypody.nu inspect effective-config --service <name>
     [--version <ver>] [--platform <plat>] [--plane tracked|local]
  • --service: required for effective-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 under services/. local merges optional .dockypody.local/services/<service>/versions.nuon fragments; the command hard-errors when .dockypody.local/ is missing. Use --plane local when 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-master

tls

Subcommands: 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 --force regenerates the shared CA even if it already exists. After a forced CA regeneration, regenerate service certificates with nu scripts/dockypody.nu tls certs.
  • --filter applies to tls certs only.
  • --service, --dry-run, --skip-shared-ca, --keep-empty-dirs, and --service-ca-only apply to tls clean only.

ssh

Subcommands: key.

nu scripts/dockypody.nu ssh key [--force]

ci

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.

docs

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.

Build Command

nu scripts/dockypody.nu build --service <service-name> [options]

Config Plane Flag

--plane <mode>

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 local

Modes:

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/*.nuon only.
  • Tracked CI generation consumes only tracked versions (never local). --plane local is rejected at build --matrix-json, ci workflow, and ci ghcr-purge. ci list-deps always 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 master

Service Selection Flags

--service <string>

Build a specific service. Use this when you are not targeting --all-services:

nu scripts/dockypody.nu build --service revad-base

--all-services

Build all discovered services in dependency order:

nu scripts/dockypody.nu build --all-services

Discovers 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-only or --all-versions instead)
  • Mutually exclusive with --versions (use --latest-only or --all-versions instead)

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 --platform are skipped
  • Default version is built unless --all-versions or --latest-only is specified
  • Dependency graph is constructed per-service and merged with deduplication
  • Continue-on-failure is default (use --fail-fast to 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-order

Version Flags

--version <string>

Build a specific version from the manifest:

nu scripts/dockypody.nu build --service revad-base --version v3.10.1

--all-versions

Build all versions defined in the manifest:

nu scripts/dockypody.nu build --service revad-base --all-versions

--latest-only

Build only versions marked with latest: true:

nu scripts/dockypody.nu build --service revad-base --latest-only

--versions <string>

Build multiple specific versions (comma-separated list):

nu scripts/dockypody.nu build --service revad-base --versions v3.10.1,master

Note: --version (singular) for single version, --versions (plural) for multiple versions.

Platform Flags

--platform <string>

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 debian

Platform Suffix in Version

You 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--debian is 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

CI Matrix Generation

--matrix-json

Output GitHub Actions matrix JSON:

nu scripts/dockypody.nu build --service revad-base --matrix-json

Output format:

Single-Platform

{
  "include": [
    {
      "version": "v1.0.0",
      "platform": "",
      "latest": true
    }
  ]
}

Multi-Platform

{
  "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 explicit platforms.nuon manifest
  • 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)

Cache Busting Flags

--cache-bust <string>

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.

--no-cache

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-cache

This 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.

Dependency Building Flags

--dep-cache <string>

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=strict

Modes:

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-deps

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-deps

Behavior:

  • Only affects dependencies (not target service)
  • Independent of --push flag
  • Can be used with or without --push

--tag-deps

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-deps

Behavior:

  • Propagates both --latest and --extra-tag flags 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 --latest is used, but a dependency's version has latest: false, the latest tag is not applied to that dependency

Build Control Flags

--show-build-order

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-only

Single-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 marked latest: true
  • --platform <string> - Filter to a platform from platforms.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

--fail-fast

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-fast

Default 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-fast flag) - 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

Other Build Flags

--push

Push built images to registry:

nu scripts/dockypody.nu build --service revad-base --version v3.10.1 --push

--progress <string>

Set build progress output format:

nu scripts/dockypody.nu build --service revad-base --all-versions --progress plain

--latest <boolean>

Control latest tag generation:

nu scripts/dockypody.nu build --service revad-base --version master --latest false

Disk Management Flags

--disk-monitor <string>

Control 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=off

Runtime 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-cache-mounts

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-versions

Behavior:

  • Runs docker builder prune -f after 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=cache entries)
  • 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-web with 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.

See Also