# 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/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:
```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/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)