# 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)
