nullforge 0.2.0__tar.gz → 0.3.1__tar.gz

{nullforge-0.2.0 → nullforge-0.3.1}/.github/CONTRIBUTING.md

@@ -85,6 +85,40 @@ If any hooks fail, please fix the issues before committing. You can manually run
 prek run --all-files
 ```
 
+### Tasks (via poe)
+
+Every routine check, build and test step is a [poe](https://poethepoet.natn.io/) task.
+Tasks run through poe's `uv` executor, so they resolve their own environment - no `uv run --group ...` prefix needed.
+The bare name is the variant CI runs; a colon suffix selects a mode (`:fix` for auto-fix, `:dev` for the local loop):
+
+```bash
+uv sync                    # create the environment
+uv run poe check           # format + lint + typecheck + lint-imports + deptry (what CI runs)
+uv run poe format          # ruff format --check
+uv run poe format:fix      # ruff format
+uv run poe lint            # ruff check
+uv run poe lint:fix        # ruff check --fix
+uv run poe lint:md         # markdownlint over all Markdown (via prek)
+uv run poe typecheck       # ty check
+uv run poe lint-imports    # import-linter layer contracts
+uv run poe deptry          # dependency hygiene
+uv run poe tests           # pytest with coverage
+uv run poe docs            # strict docs site build (what docs CI runs)
+uv run poe docs:dev        # serve the docs site with live reload
+```
+
+Run `uv run poe check` and `uv run poe tests` before pushing - they are the same checks the pull request runs.
+Markdown is not in `poe check` - the prek hook lints it on every commit and in CI; `uv run poe lint:md` runs it on demand.
+`poe check` does not build the documentation site either, so run `uv run poe docs` when the change touches `docs/`.
+
+### Tests
+
+`uv run poe tests` runs the suite; CI runs it on Python 3.13, 3.14 and 3.15.
+`tests/conftest.py` patches the pyinfra context so rune and operation calls are no-ops - molds, smithy helpers, runes, and templates unit-test without a real target.
+End-to-end correctness is still validated by deploying to a real host.
+
+The suite also enforces the [conventions](https://wlix13.github.io/NullForge/contributing/conventions/).
+
 ## Commits
 
 All commits are expected to follow the conventional commits specification.
@@ -113,8 +147,7 @@ message — please replace that with something descriptive. Examples:
 - `Improve CI/CD caching and test matrix`
 - `Fix swap sizing on small hosts`
 
-A good title reads cleanly in the PR list and the project history. The individual
-**commits** inside the PR still follow Conventional Commits (see [Commits](#commits));
+The individual **commits** inside the PR still follow Conventional Commits (see [Commits](#commits));
 because PRs are merged with a merge/rebase strategy, those commit messages — not the
 title — drive the release changelog, so the title itself does not need a `type:` prefix.
 

{nullforge-0.2.0 → nullforge-0.3.1}/.github/dependabot.yml

@@ -3,7 +3,8 @@ updates:
   - package-ecosystem: "github-actions"
     directory: "/"
     schedule:
-      interval: "weekly"
+      interval: "cron"
+      cronjob: "0 6 1,15 * *" # twice a month, closest dependabot gets to every two weeks
     commit-message:
       prefix: "chore"
       include: "scope"
@@ -17,7 +18,8 @@ updates:
   - package-ecosystem: "uv"
     directory: "/"
     schedule:
-      interval: "weekly"
+      interval: "cron"
+      cronjob: "0 6 1,15 * *" # twice a month, closest dependabot gets to every two weeks
     commit-message:
       prefix: "chore"
       include: "scope"
@@ -31,7 +33,8 @@ updates:
   - package-ecosystem: "pre-commit"
     directory: "/"
     schedule:
-      interval: "weekly"
+      interval: "cron"
+      cronjob: "0 6 1,15 * *" # twice a month, closest dependabot gets to every two weeks
     commit-message:
       prefix: "chore"
       include: "scope"

{nullforge-0.2.0 → nullforge-0.3.1}/.github/labeler.yaml

@@ -19,9 +19,11 @@ labels:
     files:
       - '^README\.md$'
       - "^docs/"
+      - '^zensical\.toml$'
   - label: "ci-cd"
     files:
       - '^\.github/'
+      - '^\.markdownlint-cli2\.jsonc$'
   - label: "tests"
     files:
       - "^tests/"

{nullforge-0.2.0 → nullforge-0.3.1}/.github/workflows/ci-code-quality.yaml

@@ -25,21 +25,13 @@ jobs:
         with:
           persist-credentials: false
 
-      - uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+      - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
         with:
           enable-cache: true
           cache-dependency-glob: uv.lock
 
-      - run: uv sync --all-groups
-
-      - name: Check formatting
-        run: uv run ruff format --check .
-
-      - name: Lint code
-        run: uv run ruff check .
-
-      - name: Type check
-        run: uv run ty check
+      - name: Run quality checks
+        run: uv run poe check
 
   hooks:
     name: 🪝 prek hooks
@@ -50,7 +42,7 @@ jobs:
         with:
           persist-credentials: false
 
-      - uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+      - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
         with:
           enable-cache: true
           cache-dependency-glob: uv.lock

nullforge-0.3.1/.github/workflows/ci-docs.yaml

@@ -0,0 +1,37 @@
+name: 📚 Docs build check
+
+on:
+  pull_request:
+    branches:
+      - main
+    paths:
+      - "docs/**"
+      - "zensical.toml"
+      - "pyproject.toml"
+      - "uv.lock"
+      - ".github/workflows/ci-docs.yaml"
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    name: 📚 Build documentation
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+
+      - name: Build documentation
+        run: uv run poe docs

{nullforge-0.2.0 → nullforge-0.3.1}/.github/workflows/ci-tests.yaml

@@ -17,22 +17,27 @@ concurrency:
 
 jobs:
   tests:
-    name: 🧪 Tests
+    name: 🧪 Tests (py${{ matrix.python-version }})
     runs-on: ubuntu-latest
     timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.13", "3.14", "3.15"]
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
 
-      - uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+      - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
         with:
           enable-cache: true
           cache-dependency-glob: uv.lock
-          python-version: "3.13"
+          cache-suffix: py${{ matrix.python-version }}
+          python-version: ${{ matrix.python-version }}
 
-      - name: Run tests with coverage
-        run: uv run --group tests pytest
+      - name: Run tests
+        run: uv run poe tests
 
   build:
     name: 📦 Package build check
@@ -43,7 +48,7 @@ jobs:
         with:
           persist-credentials: false
 
-      - uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+      - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
         with:
           enable-cache: true
           cache-dependency-glob: uv.lock

nullforge-0.3.1/.github/workflows/deploy-docs.yaml

@@ -0,0 +1,62 @@
+name: 📚 Deploy documentation
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - "docs/**"
+      - "zensical.toml"
+      - "pyproject.toml"
+      - "uv.lock"
+      - ".github/workflows/deploy-docs.yaml"
+  workflow_dispatch:
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: 📚 Build documentation
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+      pages: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+
+      - name: Build documentation
+        run: uv run poe docs
+
+      - uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0
+
+      - uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
+        with:
+          path: site
+
+  deploy:
+    name: 🚀 Deploy to GitHub Pages
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5.0.1

{nullforge-0.2.0 → nullforge-0.3.1}/.github/workflows/release-please.yaml

@@ -52,7 +52,7 @@ jobs:
         with:
           persist-credentials: false
 
-      - uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+      - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
         with:
           enable-cache: false
 
@@ -95,7 +95,7 @@ jobs:
           path: dist/
 
       - name: Generate artifact attestations
-        uses: actions/attest-build-provenance@0f67c3f4856b2e3261c31976d6725780e5e4c373 # v4.1.1
+        uses: actions/attest-build-provenance@4d101475d8b20a2381f78447822ac1eab6504dd8 # v4.2.2
         with:
           subject-path: dist/*
 
@@ -111,7 +111,9 @@ jobs:
     permissions:
       id-token: write
     steps:
-      - uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+      - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+        with:
+          enable-cache: false
 
       - name: Download distribution artifacts
         uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
@@ -122,6 +124,38 @@ jobs:
       - name: Publish to PyPI
         run: uv publish --trusted-publishing always
 
+  publish-photon:
+    name: 📤 Publish to photon-manifest
+    needs: [release-please, build, attest-artifacts]
+    if: needs.release-please.outputs.release_created == 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment:
+      name: photon
+      url: https://py.wlix13.dev/simple/nullforge/
+    permissions:
+      contents: read
+    steps:
+      - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+        with:
+          enable-cache: false
+
+      - name: Download distribution artifacts
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish to photon-manifest
+        env:
+          UV_PUBLISH_TOKEN: ${{ secrets.PHOTON_PUBLISH_TOKEN }}
+        run: |
+          uv auth login https://py.wlix13.dev/simple/ --token "$UV_PUBLISH_TOKEN"
+          uv publish \
+            --publish-url https://py.wlix13.dev/legacy/ \
+            --check-url https://py.wlix13.dev/simple/ \
+            --no-attestations
+
   finalize-release:
     name: 🚀 Attach assets and publish
     needs: [release-please, build, attest-artifacts, publish-pypi]

nullforge-0.3.1/.markdownlint-cli2.jsonc

@@ -0,0 +1,25 @@
+{
+  "gitignore": true,
+
+  // Generated, boilerplate and vendored - not authored to this style.
+  "ignores": [
+    "CHANGELOG.md",
+    ".github/PULL_REQUEST_TEMPLATE.md",
+    ".github/ISSUE_TEMPLATE/**",
+  ],
+
+  "config": {
+    "default": true,
+
+    // Prose is one sentence per line; tables pad cells but not the delimiter row.
+    "MD013": false,
+    "MD060": false,
+
+    "MD046": false,
+
+    // mkdocs admonition blocks
+    "MD033": {
+      "allowed_elements": ["div"],
+    },
+  },
+}

{nullforge-0.2.0 → nullforge-0.3.1}/.pre-commit-config.yaml

@@ -5,7 +5,7 @@ default_install_hook_types:
   - post-rewrite
 repos:
   - repo: https://github.com/tox-dev/pyproject-fmt
-    rev: v2.25.3
+    rev: v2.29.4
     hooks:
       - id: pyproject-fmt
 
@@ -19,12 +19,12 @@ repos:
       - id: end-of-file-fixer
 
   - repo: https://github.com/astral-sh/uv-pre-commit
-    rev: 0.11.32
+    rev: 0.12.14
     hooks:
       - id: uv-lock
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.16.0
+    rev: v0.16.7
     hooks:
       - id: ruff-check
         args: [--fix]
@@ -40,3 +40,8 @@ repos:
       - id: python-no-log-warn
       - id: python-use-type-annotations
       - id: text-unicode-replacement-char
+
+  - repo: https://github.com/DavidAnson/markdownlint-cli2
+    rev: v0.23.2
+    hooks:
+      - id: markdownlint-cli2

nullforge-0.3.1/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.3.1"
+}

{nullforge-0.2.0 → nullforge-0.3.1}/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## [0.3.1](https://github.com/wlix13/NullForge/compare/v0.3.0...v0.3.1) (2026-09-18)
+
+
+### Features
+
+* **runes:** enhance Podman support with rootless prerequisites and auto-updater ([9c02ab7](https://github.com/wlix13/NullForge/commit/9c02ab7de2196149c500ac6aa3ddd457896af31b))
+
+
+### Bug Fixes
+
+* **docs:** cut repeated and internal detail from docs and contributing guide ([21741ef](https://github.com/wlix13/NullForge/commit/21741efe1a785fc5c3fe3b22b58aaefff43f8e70))
+* **inventories:** keep example presets out of pyinfra group discovery ([73578d6](https://github.com/wlix13/NullForge/commit/73578d65f7ceef892491905cc1c670c2e92f7a04))
+
+## [0.3.0](https://github.com/wlix13/NullForge/compare/v0.2.0...v0.3.0) (2026-08-28)
+
+
+### ⚠ BREAKING CHANGES
+
+* **molds:** deploy warp before other features
+* **smithy:** fall back to WARP interface for filtered downloads
+
+### Features
+
+* **molds:** deploy warp before other features ([a97cbfe](https://github.com/wlix13/NullForge/commit/a97cbfe9020bf0708acec4adf370cfa7113ea964))
+* **smithy:** fall back to WARP interface for filtered downloads ([25f0b28](https://github.com/wlix13/NullForge/commit/25f0b28cb7d0efb89cf7710aa922d52a9651c985))
+
+
+### Documentation
+
+* describe WARP download fallback ([8b57441](https://github.com/wlix13/NullForge/commit/8b57441c8ecc234db4f9131e5ab9a603e3384b4c))
+* **site:** add documentation ([d6b8575](https://github.com/wlix13/NullForge/commit/d6b857541d8ed35a5fe8fa3a32cdef95d8d8bf8c))
+
 ## [0.2.0](https://github.com/wlix13/NullForge/compare/v0.1.0...v0.2.0) (2026-07-25)
 
 

nullforge-0.3.1/PKG-INFO

@@ -0,0 +1,48 @@
+Metadata-Version: 2.5
+Name: nullforge
+Version: 0.3.1
+Summary: Forge the server's baseline from null
+Author-email: wlix13 <github@wlix13.dev>
+Maintainer-email: wlix13 <github@wlix13.dev>
+License-File: LICENSE
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Requires-Python: >=3.13
+Requires-Dist: click
+Requires-Dist: pydantic
+Requires-Dist: pyinfra
+Requires-Dist: rich
+Requires-Dist: rich-click
+Description-Content-Type: text/markdown
+
+# NullForge
+
+[![PyPI](https://img.shields.io/pypi/v/nullforge?logo=pypi&logoColor=white)](https://pypi.org/project/nullforge/)
+![Python](https://img.shields.io/badge/python-3.13%20%7C%203.14%20%7C%203.15-blue?logo=python&logoColor=white)
+![Build](https://img.shields.io/github/actions/workflow/status/wlix13/NullForge/ci-tests.yaml?label=build&logo=github)
+![Lint](https://img.shields.io/github/actions/workflow/status/wlix13/NullForge/ci-code-quality.yaml?label=lint&logo=github)
+![License](https://img.shields.io/badge/license-MIT-green)
+![uv](https://img.shields.io/badge/package%20manager-uv-blueviolet?logo=astral)
+![Ruff](https://img.shields.io/badge/linter-ruff-orange?logo=ruff)
+[![Docs](https://img.shields.io/badge/docs-GitHub%20Pages-0075ca?logo=materialformkdocs&logoColor=white)](https://wlix13.github.io/NullForge/)
+
+Forge the server's baseline from null - an infrastructure-as-code framework built on [pyinfra](https://pyinfra.com), themed around a blacksmith's forge: **inventories** define hosts, **molds** shape the configuration, **runes** are idempotent operation sets, the **foundry** casts them onto targets, and the **smithy** holds cross-distro helpers.
+
+> [!WARNING]
+> **NullForge is in active development.** Until the `v1.0.0` release, the CLI, mold schemas and deploy behaviour may change at any time - breaking changes can land in **any** release, including patch versions. Pin an exact version (e.g. `nullforge==0.2.0`) and check the [release notes](https://github.com/wlix13/NullForge/releases) before upgrading.
+
+## Install
+
+```bash
+uv tool install nullforge
+```
+
+## Documentation
+
+Everything else - getting started, concepts, the full feature reference, and guides - lives at **[wlix13.github.io/NullForge](https://wlix13.github.io/NullForge/)**.
+
+## Contributing
+
+See [CONTRIBUTING.md](.github/CONTRIBUTING.md) for the full setup, commit conventions and pull request flow.

nullforge-0.3.1/README.md

@@ -0,0 +1,29 @@
+# NullForge
+
+[![PyPI](https://img.shields.io/pypi/v/nullforge?logo=pypi&logoColor=white)](https://pypi.org/project/nullforge/)
+![Python](https://img.shields.io/badge/python-3.13%20%7C%203.14%20%7C%203.15-blue?logo=python&logoColor=white)
+![Build](https://img.shields.io/github/actions/workflow/status/wlix13/NullForge/ci-tests.yaml?label=build&logo=github)
+![Lint](https://img.shields.io/github/actions/workflow/status/wlix13/NullForge/ci-code-quality.yaml?label=lint&logo=github)
+![License](https://img.shields.io/badge/license-MIT-green)
+![uv](https://img.shields.io/badge/package%20manager-uv-blueviolet?logo=astral)
+![Ruff](https://img.shields.io/badge/linter-ruff-orange?logo=ruff)
+[![Docs](https://img.shields.io/badge/docs-GitHub%20Pages-0075ca?logo=materialformkdocs&logoColor=white)](https://wlix13.github.io/NullForge/)
+
+Forge the server's baseline from null - an infrastructure-as-code framework built on [pyinfra](https://pyinfra.com), themed around a blacksmith's forge: **inventories** define hosts, **molds** shape the configuration, **runes** are idempotent operation sets, the **foundry** casts them onto targets, and the **smithy** holds cross-distro helpers.
+
+> [!WARNING]
+> **NullForge is in active development.** Until the `v1.0.0` release, the CLI, mold schemas and deploy behaviour may change at any time - breaking changes can land in **any** release, including patch versions. Pin an exact version (e.g. `nullforge==0.2.0`) and check the [release notes](https://github.com/wlix13/NullForge/releases) before upgrading.
+
+## Install
+
+```bash
+uv tool install nullforge
+```
+
+## Documentation
+
+Everything else - getting started, concepts, the full feature reference, and guides - lives at **[wlix13.github.io/NullForge](https://wlix13.github.io/NullForge/)**.
+
+## Contributing
+
+See [CONTRIBUTING.md](.github/CONTRIBUTING.md) for the full setup, commit conventions and pull request flow.

nullforge-0.3.1/docs/concepts/architecture.md

@@ -0,0 +1,61 @@
+# Architecture
+
+NullForge is a thin, opinionated layer over pyinfra.
+Every layer has one job, and imports only flow downward.
+
+## Data flow
+
+```mermaid
+flowchart TB
+    subgraph plan [Control node]
+        CLI[cli - nullforge cast] --> FY["foundry - full_cast.py / cast.py"]
+        INV[inventories] --> FY
+        FY --> RN["runes/*.py"]
+        RN --> SM[smithy]
+        RN --> TP["templates (Jinja2)"]
+        MD["molds (Pydantic)"] --> INV
+        MD --> RN
+        ML["models (domain types)"] --> MD
+    end
+    RN -->|pyinfra operations over SSH| HOSTS[(Target hosts)]
+```
+
+1. **Inventories** define hosts and attach `system` and `features` data, built by [merging layers](inventories.md) over the defaults.
+2. The **foundry** is the deploy entry point.
+   `full_cast.py` coerces inventory data through the molds, always includes `prepare` then `base`, and then includes the rune of every active feature.
+   `cast.py` is the selective variant used by `nullforge cast -r ...`.
+3. **Runes** are self-contained pyinfra operation sets - one file per concern.
+   They read validated configuration from `host.data` and emit idempotent operations.
+4. **Molds** are Pydantic schemas for all configuration; [`FeaturesMold`](molds.md) composes the per-feature sub-molds.
+5. **Models** hold pure domain types and constants consumed by molds.
+6. The **smithy** provides cross-distro abstractions: package-name mapping (apt/dnf), release-binary installs with checksum verification, version pinning, networking facts, swap, service users.
+7. **Templates** are Jinja2 files for systemd units, service configs, and shell profiles.
+
+## Layer contracts
+
+The layering is enforced by import contracts:
+
+| Contract | Meaning |
+| --- | --- |
+| Deploy spine | `cli` -> `foundry` -> `runes` -> `smithy` -> `molds`/`templates` -> `models`; a layer may import only layers below it |
+| Models are pure | `models` imports no other NullForge package |
+| Templates are a leaf | `templates` imports no other NullForge package, `models` included - its spine position only says which layers may import *it* |
+| Molds describe, never provision | `molds` cannot import runes, smithy, or templates |
+| Runes are independent | no rune imports another rune |
+
+Why rune independence matters - and how runes coordinate without it - is covered in [Runes](runes.md#independence).
+
+## Execution model
+
+pyinfra runs in two phases:
+
+1. **Plan** - fact gathering and operation collection on the control node.
+   Python-level branching (`if host.get_fact(...)`) happens here.
+2. **Execute** - the collected operations run against each host, in a deterministic order shared by all hosts.
+
+The [conventions](../contributing/conventions.md) around `host.loop` and change detection exist to keep that shared ordering stable.
+
+## The CLI wrapper
+
+`nullforge cast` is a thin planner around pyinfra: it resolves the [cast stages](../getting-started/cli.md#stages) and hands them to pyinfra.
+Everything else is stock pyinfra, which is why unknown CLI options are proxied through verbatim.