# 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](https://github.com/omne-org/omne-cli/releases) and place the `omne` binary on your PATH.
### From crates.io
```bash
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
```bash
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/image/`, and stamps `MANIFEST.md` with `kernel-source` and `distro-source` for future upgrades.
- `upgrade` reads `kernel-source` / `distro-source` from MANIFEST.md frontmatter and replaces `.omne/core/` or `.omne/image/` with the latest release. `cfg/` and `log/` are untouched.
- `validate` checks volume structure (required dirs, manifest fields, depth rule at max 3 levels), 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:
```bash
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/MANIFEST.md` to add the fields, or re-run `omne init <distro>` in a fresh directory.
## Platforms
- `x86_64-pc-windows-msvc` (Windows)
- `x86_64-unknown-linux-gnu` (Linux)