Installation

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.

   go version
   git --version

2. Install zever plus the matching zever-lsp with the pinned installer (never main).

   Linux

   curl -fsSL https://raw.githubusercontent.com/zenta-dev/zever/main/install.sh | sh

   macOS

   curl -fsSL https://raw.githubusercontent.com/zenta-dev/zever/main/install.sh | sh

   Windows

   irm https://raw.githubusercontent.com/zenta-dev/zever/main/install.ps1 | iex

   PATH

   The installer puts both binaries in ~/.local/bin. If zever is not found, add that directory to your PATH.

   Windows execution policy

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

Re-running the installer upgrades in place

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

Checksum verification is mandatory

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 <binary> --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.

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

`go install` for the CLI

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.

main.go

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

go build ./... && go test ./... && go run .

Expected output:

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: files use snake_case keys, and env vars are <SERVICE>_<FIELD> with no prefix (DB_ADAPTER, DB_MAXCONNS).

Upgrade

Re-run the pinned installer, or self-update from the CLI itself:

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

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

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

QuickstartGo from an empty folder to a running API.

Project layoutWhere every package lives.

ConfigurationLayered config, env mapping, redaction.

UpgradeVersion bumps and breaking changes.