omne-cli 0.2.1

CLI for managing omne volumes: init, upgrade, and validate kernel and distro releases
Documentation

omne-cli

CLI tool for managing omne volumes. Fetches kernel and distro releases from GitHub, scaffolds volumes, runs validation.

Installation

Prebuilt binaries (recommended)

Download the latest release for your platform from GitHub Releases and place the omne binary on your PATH.

From crates.io

cargo install --locked omne-cli

The --locked flag uses the committed lockfile for exact dependency reproducibility. Without it, cargo re-resolves dependencies against latest semver-compatible versions.

Commands

omne init <distro>           # scaffold a new volume

omne upgrade [kernel|distro] # update to latest release

omne validate                # check volume integrity

How It Works

  • init downloads the latest kernel and distro release tarballs from GitHub Releases, unpacks them into .omne/core/ and .omne/dist/, scaffolds the v2 layout (.omne/lib/{cfg, docs/{raw,inter,wiki}}, .omne/var/, .omne/wt/), seeds the docs baseline, writes .gitignore runtime entries, stamps .omne/omne.md with kernel-source + distro-source, and writes a CLAUDE.md bootloader that imports @.omne/dist/AGENTS.md directly.
  • upgrade reads kernel-source / distro-source from .omne/omne.md frontmatter and replaces .omne/core/ or .omne/dist/ with the latest release. lib/, var/, and wt/ are untouched.
  • validate checks volume structure (required dirs, omne.md frontmatter fields, depth rule on user content), then reads core/manifest.json for the gate_runner path and calls the distro's own validator. If Python is not available, the gate runner is skipped with a warning.

Authentication

Set GITHUB_TOKEN or GH_TOKEN to authenticate with the GitHub API (raises the rate limit from 60 to 5,000 requests/hour). GITHUB_TOKEN takes precedence when both are set.

Troubleshooting

Rate limit errors: Set GITHUB_TOKEN or GH_TOKEN as described above.

Partial init failure: If omne init is interrupted, .omne/ may be left in a partial state. Remove it and retry:

rm -rf .omne/   # Unix

Remove-Item -Recurse -Force .omne  # PowerShell

Corporate CA / TLS errors: Set SSL_CERT_FILE or SSL_CERT_DIR to point at your organization's CA bundle.

Pre-existing volumes missing kernel-source/distro-source: Hand-edit .omne/omne.md to add the fields, or re-run omne init <distro> in a fresh directory.

Pre-v2 volumes (.omne/MANIFEST.md, .omne/image/, .omne/cfg/, .omne/log/): re-run omne init <distro> in a fresh directory. Automatic migration is not in v1 — omne validate flags the legacy layout with a clear error.

Platforms

  • x86_64-pc-windows-msvc (Windows)
  • x86_64-unknown-linux-gnu (Linux)