# Installation Install Go 1.27, the Zever CLI, and the modules you need, then verify with a smoke test. Install the `zever` CLI with the one-line installer, then add the Zever modules to your project with `go get`. A fresh install needs no config file and no database server. | Requirement | Version | Notes | |---|---|---| | Go | 1.27.0+ | `go 1.27.0` in `go.mod`; required but not installed by the script | | Git | any recent | needed for `go get` and scaffolding | | Node.js | 18+ | docs site only (`docs/`), not needed for backend work | ## Install the CLI with the one-line installer 1. Check your toolchain. The installer does not install Go: you need `go1.27` or newer, otherwise install it from [go.dev/dl](https://go.dev/dl/). ```sh go version git --version ``` 2. Install `zever` plus the matching `zever-lsp` with the pinned installer (never `main`). ```sh curl -fsSL https://raw.githubusercontent.com/zenta-dev/zever/main/install.sh | sh ``` ```sh curl -fsSL https://raw.githubusercontent.com/zenta-dev/zever/main/install.sh | sh ``` ```powershell irm https://raw.githubusercontent.com/zenta-dev/zever/main/install.ps1 | iex ``` The installer puts both binaries in `~/.local/bin`. If `zever` is not found, add that directory to your `PATH`. If PowerShell blocks the script, download it first, then run `Unblock-File install.ps1` or invoke it with `powershell -ExecutionPolicy Bypass -File install.ps1`. 3. Run `zever --help`. It prints the grouped command map (Scaffolding, Inspection, Runtime, Database, Operations). If `zever` already exists, `install.sh` upgrades it in place: older installs ask for confirmation, re-running the same version skips, and downgrading from a newer install asks for confirmation. Non-interactive shells need `--yes`. Output is colourised on a terminal; pass `--quiet` (`-Quiet` on Windows) for errors only, or `--no-color` (`-NoColor`) / set `NO_COLOR` to disable colour. `zever-lsp` is always matched to the CLI version (it has no version flag). Every binary is verified against the release's `SHA256SUMS.txt` before installation. If no SHA-256 tool (`sha256sum`/`shasum`) is available, or hashing fails, the installer aborts instead of installing unverified binaries. To proceed unverified (unsafe), pass `--insecure-skip-verify` (`-InsecureSkipVerify` on Windows) or set `ZEVER_INSTALL_INSECURE=1`. When `gh` is not installed, the installer prints the manual provenance check: `gh attestation verify --repo zenta-dev/zever`. ## Add the modules to your project Create a module and fetch the Zever modules you need at the same pinned version. ```sh go mod init example.com/myapp go get github.com/zenta-dev/zever/config@v0.8.0 github.com/zenta-dev/zever/container@v0.8.0 github.com/zenta-dev/zever/adapters/db/sqlite@v0.8.0 ``` From v0.7.2 on, `go install github.com/zenta-dev/zever/cmd/zever@vX.Y.Z` builds the CLI from source. It does not work for v0.7.1 or earlier tags (their `cmd/zever/go.mod` commits `replace` directives), and it is only supported for the CLI module; other zever modules are libraries you `go get`. Otherwise use the installer above or a prebuilt release binary. ## Verify with a smoke test Build one container from `config.Default()` and resolve the database. The default `db` adapter is `sqlite`, so the check imports that adapter and calls its `Register()`. An unregistered adapter fails with `UnknownAdapterError`. ```go title="main.go" check package main import ( "fmt" "github.com/zenta-dev/zever/adapters/db/sqlite" "github.com/zenta-dev/zever/config" "github.com/zenta-dev/zever/container" ) func main() { sqlite.Register() c := container.New(config.Default()) db, err := c.DB() if err != nil { panic(err) } fmt.Println("db resolved:", db != nil) } ``` ```sh go build ./... && go test ./... && go run . ``` Expected output: ```text db resolved: true ``` If that line prints, fetch, build, and default resolution all work. `container.New(nil)` is valid too and closes cleanly. When you add a config file later, see the [configuration guide](https://zenta-dev.github.io/zever/guides/operate/configuration/): files use snake_case keys, and env vars are `_` with no prefix (`DB_ADAPTER`, `DB_MAXCONNS`). ## Upgrade Re-run the pinned installer, or self-update from the CLI itself: ```sh zever upgrade ``` Use `zever upgrade --check` to see whether a newer release exists without installing it, and `zever upgrade --version vX.Y.Z` to pin the target instead of latest. ## Uninstall ```sh zever uninstall ``` It removes both the `zever` and `zever-lsp` binaries. Pass `--keep-lsp` to leave the language server behind, or `--dry-run` to preview what would be removed. ## Production notes - Pin the CLI to the same version as the modules so the TUI and backend behave alike. - Never log raw option maps. Print `config.RedactedServices(cfg)` instead. - `Default()` ships a deterministic dev crypto key. Never let it reach production: supply real secrets through a file or env. - Close every container you open (`c.Close(ctx)` with a timeout parent), even in smoke tests. ## Work on Zever itself If you contribute to the Zever repository, these `make` targets exist only in a checkout of Zever, not in a scaffolded project.
Make targets and focused test commands | Target | What it does | |---|---| | `make setup` | Install the pinned lint and vuln tools (once) | | `make build` / `make test` | `go build ./...` / `go test ./...` | | `make test-race` | `go test -race ./...` (run by `make check`, not the PR fast gate) | | `make fmt` / `make fmt-fix` | Check / write `gofmt` formatting | | `make lint` / `make lint-fix` | `golangci-lint run` with `.golangci.yml` | | `make vet` | `go vet` (a separate CI step, since `go test` runs with `-vet=off -count=1`) | | `make vulncheck` | `govulncheck` scan | | `make tidy-check` | `go mod tidy -diff` | | `make generate` | `go run ./tools/gengrammar` after touching `token.Keywords` or `resolver.ScalarTypeNames` | | `make check` | Full local CI mirror: download, fmt, vet, tidy-check, lint, test-race, vulncheck, build | ```sh go test ./orm/... go test ./container/... -run TestName -v go test -race ./config/... ```
## Troubleshooting
`go version` reports older than 1.27 Cause: a stale toolchain is first on `PATH`. Fix: install Go 1.27+ from go.dev/dl and run `go version` again.
`go get` fails with a network or proxy error Cause: an offline sandbox or a blocked `GOPROXY`. Fix: set `GOPROXY` per your site policy, run `go mod download`, then retry `go get`.
`make setup` fails while installing the lint tools Cause: the pinned tool download was blocked or partial. Fix: re-run `make setup`, check the binaries are on `PATH`, then run `make build`.
`zever` is not found or prints nothing useful Cause: the binaries landed in a directory outside `PATH`. Fix: add `~/.local/bin` to `PATH`, or re-run `curl -fsSL https://raw.githubusercontent.com/zenta-dev/zever/main/install.sh | sh`.
`go install ...@version` fails with a replace-directive error Cause: the tag predates v0.7.2 (v0.7.1 and earlier commit `replace` directives in `cmd/zever/go.mod`), or you are installing a module other than `cmd/zever`. Fix: install `github.com/zenta-dev/zever/cmd/zever@v0.8.0` or later, or use the installer above or a prebuilt release binary.
The smoke test panics resolving `DB()` Cause: broken local state or edited defaults. Fix: remove any config file and env overrides so `config.Default()` applies, run `go run .`, then layer config back in.
## Related - [Quickstart](https://zenta-dev.github.io/zever/start/quickstart/): Go from an empty folder to a running API. - [Project layout](https://zenta-dev.github.io/zever/start/project-layout/): Where every package lives. - [Configuration](https://zenta-dev.github.io/zever/guides/operate/configuration/): Layered config, env mapping, redaction. - [Upgrade](https://zenta-dev.github.io/zever/guides/operate/upgrade/): Version bumps and breaking changes.