---
title: "Documentation"
html_title: "Enroll Documentation"
description: "Current user documentation for Enroll harvest, manifest, diff, explain, validate, SOPS, remote mode, and Ansible output."
---
<header class="py-5 hero">
  <div class="container py-3">
    <div class="kicker mb-3"><i class="bi bi-journal-text"></i> Documentation</div>
    <h1 class="display-6 fw-bold mb-2">Current Enroll behavior</h1>
    <p class="lead mb-0">This page describes how the 0.7 beta CLI works today: what it captures, how it renders Ansible, and where the trust boundaries are.</p>
  </div>
</header>

<main class="py-5">
  <div class="container">
    <div class="row g-4">
      <aside class="col-lg-3">
        <div class="callout p-4 position-sticky" style="top: 96px;">
          <div class="fw-semibold mb-2">On this page</div>
          <ul class="small mb-0">
            <li><a href="#mental-model">Mental model</a></li>
            <li><a href="#harvest">Harvest</a></li>
            <li><a href="#manifest">Manifest</a></li>
            <li><a href="#modes">Single-site vs multi-site</a></li>
            <li><a href="#diff">Diff</a></li>
            <li><a href="#explain-validate">Explain and validate</a></li>
            <li><a href="#config">Configuration file</a></li>
            <li><a href="#install">Install</a></li>
          </ul>
        </div>
      </aside>

      <div class="col-lg-9">
        <section id="mental-model" class="scroll-mt-nav">
          <div class="feature-card p-4">
            <h2 class="h3 fw-bold mb-3">Mental model</h2>
            <p>Enroll has two main phases:</p>
            <ol>
              <li><strong>Harvest</strong> collects host facts and selected files into a harvest bundle containing <code>state.json</code> and <code>artifacts/</code>.</li>
              <li><strong>Manifest</strong> converts that bundle into Ansible configuration-management output.</li>
            </ol>
            <p class="mb-0">Additional commands help you compare harvests (<code>diff</code>), explain why things were included or skipped (<code>explain</code>), and validate bundle structure (<code>validate</code>).</p>
          </div>
        </section>

        <section id="harvest" class="scroll-mt-nav mt-4">
          <div class="feature-card p-4">
            <h2 class="h3 fw-bold mb-3"><code>enroll harvest</code></h2>
            <p>Harvest writes a local bundle. If <code>--out</code> is omitted, Enroll creates a private randomized cache directory under the user’s Enroll cache. If <code>--out</code> is supplied for plaintext output, the final output directory must be new and safe; Enroll creates it with private permissions.</p>
            <h3 class="h5 fw-bold mt-4">High-level capture scope</h3>
            <div class="row g-3">
              <div class="col-md-6"><ul class="mb-0"><li>Manual packages and installed package inventory</li><li>Enabled systemd services and relevant package ownership</li><li>Modified package-owned config where the backend can prove drift</li><li>Service-relevant unowned files under matching <code>/etc</code> trees</li><li>Central cron and logrotate snippets</li></ul></div>
              <div class="col-md-6"><ul class="mb-0"><li>Non-system users and SSH public/authorized key material</li><li>Package-manager config: <code>apt_config</code> or <code>dnf_config</code></li><li>Miscellaneous <code>/etc</code> and <code>/usr/local</code> custom files</li><li>Runtime sysctl and firewall fallback state where appropriate</li><li>Flatpak, Snap, Docker, and Podman image evidence</li></ul></div>
            </div>
            <h3 class="h5 fw-bold mt-4">Path selection</h3>
            <p><code>--include-path</code> adds extra files or directories to the <code>extra_paths</code> role. <code>--exclude-path</code> removes matching paths from all harvesting, including defaults. Excludes win over includes.</p>
            <div class="terminal"><pre class="mb-0"><code>enroll harvest --out ./harvest \
  --include-path '/home/*/.profile' \
  --exclude-path '/home/*/.ssh/**' \
  --exclude-path 're:^/var/cache/myapp/.*$'</code></pre></div>
            <p class="small text-secondary mt-3 mb-0">Pattern styles are plain paths, inferred or explicit globs such as <code>glob:/path/**/*.conf</code>, and regexes prefixed with <code>re:</code> or <code>regex:</code>. Include expansion ignores symlinks, respects caps, and reports unmatched/capped paths as notes.</p>
          </div>
        </section>

        <section id="remote" class="scroll-mt-nav mt-4">
          <div class="feature-card p-4">
            <h2 class="h3 fw-bold mb-3">Remote harvesting</h2>
            <p>Remote mode runs the harvest over SSH and stores the bundle locally. The remote host does not need Enroll installed in the same way you would for local operation.</p>
            <div class="terminal"><pre class="mb-0"><code>enroll harvest --remote-host app01.example.net --remote-user mig --out ./harvest-app01</code></pre></div>
            <ul class="mt-3 mb-0">
              <li><code>--remote-ssh-config [path]</code> reads OpenSSH-style settings. With no value, it defaults to <code>~/.ssh/config</code>.</li>
              <li>Supported ssh config fields include <code>HostName</code>, <code>User</code>, <code>Port</code>, <code>IdentityFile</code>, <code>ProxyCommand</code>, and <code>HostKeyAlias</code> where supported.</li>
              <li><code>-K</code> / <code>--ask-become-pass</code> prompts for remote sudo. <code>--no-sudo</code> avoids sudo and produces a more limited harvest.</li>
              <li><code>--ask-key-passphrase</code> prompts for an encrypted SSH key. <code>--ssh-key-passphrase-env ENV_VAR</code> reads it from an environment variable for CI.</li>
            </ul>
          </div>
        </section>

        <section id="manifest" class="scroll-mt-nav mt-4">
          <div class="feature-card p-4">
            <h2 class="h3 fw-bold mb-3"><code>enroll manifest</code></h2>
            <p>Manifest validates the harvest, freezes directory bundles into a private temporary copy, prints the semantic-safety warning, and writes Ansible output.</p>
            <div class="terminal"><pre class="mb-0"><code>enroll validate ./harvest
enroll manifest --harvest ./harvest --out ./ansible
cd ./ansible
ansible-galaxy collection install -r requirements.yml
ansible-playbook -i localhost, -c local playbook.yml --check --diff</code></pre></div>
            <h3 class="h5 fw-bold mt-4">Output contents</h3>
            <ul>
              <li><code>playbook.yml</code> in single-site mode, or <code>playbooks/&lt;fqdn&gt;.yml</code> plus inventory in multi-site mode.</li>
              <li><code>roles/&lt;role&gt;/tasks/main.yml</code>, with handlers where needed.</li>
              <li>Harvested files in role <code>files/</code>, generated templates in role <code>templates/</code>, and variables in <code>defaults/main.yml</code> or host vars.</li>
              <li><code>requirements.yml</code> for Ansible collections such as container/Flatpak/Snap support when required.</li>
              <li>A generated <code>README.md</code> summarising layout, roles, excluded paths, notes, and dry-run commands.</li>
            </ul>
            <p class="mb-0">Every generated role has a tag named <code>role_&lt;role_name&gt;</code>. Use tags to dry-run or apply a narrow slice, for example <code>--tags role_users,role_services</code>.</p>
          </div>
        </section>

        <section id="modes" class="scroll-mt-nav mt-4">
          <div class="feature-card p-4">
            <h2 class="h3 fw-bold mb-3">Output modes</h2>
            <div class="row g-3">
              <div class="col-md-6"><div class="callout p-3 h-100"><h3 class="h5 fw-bold">Single-site: default</h3><p class="small text-secondary mb-0">Use this for one server or a “golden” role set. Roles are more self-contained; files live under the role; variables live in role defaults.</p></div></div>
              <div class="col-md-6"><div class="callout p-3 h-100"><h3 class="h5 fw-bold">Multi-site: <code>--fqdn</code></h3><p class="small text-secondary mb-0">Use this for several existing servers. Generic shared roles read host-specific variables and per-host files under <code>inventory/host_vars/&lt;fqdn&gt;</code>.</p></div></div>
            </div>
            <p class="mt-3 mb-0">By default, Enroll groups many package and systemd-unit roles into common Debian Section/RPM Group roles. <code>--no-common-roles</code> preserves one generated role per package/unit. <code>--fqdn</code> implies this behavior to avoid cross-host coupling.</p>
          </div>
        </section>

        <section id="sops" class="scroll-mt-nav mt-4">
          <div class="feature-card p-4">
            <h2 class="h3 fw-bold mb-3">SOPS encrypted bundles</h2>
            <p><code>--sops &lt;GPG_FINGERPRINT...&gt;</code> writes a single encrypted binary tarball instead of a plaintext directory. This is storage-at-rest encryption for harvest/manifest bundles, not an Ansible inventory-vault workflow.</p>
            <div class="terminal"><pre class="mb-0"><code>enroll harvest --out ./harvest --dangerous --sops 54A91143AE0AB4F7743B01FE888ED1B423A3BC99
enroll manifest --harvest ./harvest/harvest.tar.gz.sops \
  --out ./ansible-secure --sops 54A91143AE0AB4F7743B01FE888ED1B423A3BC99
cd ./ansible-secure
sops -d manifest.tar.gz.sops | tar -xzvf -
cd manifest</code></pre></div>
            <p class="small text-secondary mt-3 mb-0">When manifest output is encrypted, decrypt and extract it before running <code>ansible-playbook</code>.</p>
          </div>
        </section>

        <section id="diff" class="scroll-mt-nav mt-4">
          <div class="feature-card p-4">
            <h2 class="h3 fw-bold mb-3"><code>enroll diff</code></h2>
            <p>Diff compares two harvests and reports package, service, user, and managed-file drift. Inputs may be directories, <code>state.json</code> paths, tarballs, or SOPS bundles when <code>--sops</code> is set.</p>
            <div class="terminal"><pre class="mb-0"><code>enroll diff --old ./harvest-a --new ./harvest-b --format markdown \
  --ignore-package-versions --exclude-path /var/anacron --exit-code</code></pre></div>
            <p class="mt-3">Notification options include <code>--webhook</code>, <code>--webhook-format json|text|markdown</code>, repeated <code>--webhook-header 'K: V'</code>, repeated <code>--email-to</code>, SMTP settings, and <code>--notify-always</code>.</p>
            <p class="mb-0"><code>--exit-code</code> returns status 2 when differences are detected, which is useful for cron, CI, or monitoring wrappers.</p>
          </div>
        </section>

        <section id="explain-validate" class="scroll-mt-nav mt-4">
          <div class="feature-card p-4">
            <h2 class="h3 fw-bold mb-3">Explain and validate</h2>
            <div class="row g-3">
              <div class="col-md-6"><div class="callout p-3 h-100"><h3 class="h5 fw-bold"><code>enroll explain</code></h3><p class="small text-secondary">Summarises inventory, roles, included reasons, excluded reasons, and examples. Supports <code>--format text|json</code>, <code>--max-examples</code>, tarballs, directories, <code>state.json</code>, and SOPS bundles.</p><pre class="terminal small mb-0"><code>enroll explain ./harvest --format json --max-examples 20</code></pre></div></div>
              <div class="col-md-6"><div class="callout p-3 h-100"><h3 class="h5 fw-bold"><code>enroll validate</code></h3><p class="small text-secondary">Checks JSON validity, schema compliance, missing referenced artifacts, and orphaned artifact files. Supports <code>--schema</code>, <code>--allow-remote-schema</code>, <code>--no-schema</code>, <code>--fail-on-warnings</code>, JSON output, and report files.</p><pre class="terminal small mb-0"><code>enroll validate ./harvest --format json --out validate.json</code></pre></div></div>
            </div>
          </div>
        </section>

        <section id="config" class="scroll-mt-nav mt-4">
          <div class="feature-card p-4">
            <h2 class="h3 fw-bold mb-3">Configuration file</h2>
            <p>Enroll can read INI-style defaults from an explicit <code>--config</code> path, <code>ENROLL_CONFIG</code>, <code>$XDG_CONFIG_HOME/enroll/enroll.ini</code>, or <code>~/.config/enroll/enroll.ini</code>. It no longer reads <code>.enroll.ini</code> from the current working directory.</p>
            <p>Precedence is: explicit CLI flags, subcommand/global INI defaults, then argparse defaults. Use underscores for INI keys that are hyphenated on the CLI.</p>
            <div class="terminal"><pre class="mb-0"><code>[harvest]
include_path =
  /home/*/.bashrc
  /home/*/.profile
exclude_path = /usr/local/bin/docker-*, /usr/local/bin/some-tool

[manifest]
no_jinjaturtle = true

[diff]
exclude_path = /var/anacron
ignore_package_versions = true</code></pre></div>
          </div>
        </section>

        <section id="install" class="scroll-mt-nav mt-4">
          <div class="feature-card p-4">
            <h2 class="h3 fw-bold mb-3">Install</h2>
            <p>Enroll requires Python 3.10 or newer. The project’s README documents Debian/Ubuntu and Fedora repositories, AppImage, pip/pipx, and Poetry development installs.</p>
            <div class="row g-3">
              <div class="col-md-6"><div class="callout p-3 h-100"><div class="fw-semibold mb-2">pip / pipx</div><pre class="terminal small mb-0"><code>pip install enroll
# or
pipx install enroll</code></pre></div></div>
              <div class="col-md-6"><div class="callout p-3 h-100"><div class="fw-semibold mb-2">development checkout</div><pre class="terminal small mb-0"><code>poetry install
poetry run enroll --help</code></pre></div></div>
            </div>
            <p class="small text-secondary mt-3 mb-0">For a beta release, your package manager may require an explicit pre-release opt-in depending on how you install and what stable version is already available.</p>
          </div>
        </section>
      </div>
    </div>
  </div>
</main>