All commands

The commands are grouped by what you're doing, and the groups go from everyday to specialised. Most people only ever need the first three groups. In the terminal, `zev help` lists every command, and `zev help <command>` shows how to use one. Press `/` on this page to search. **In the usage lines:** `<name>` means you fill something in, `[name]` means it's optional, and `a | b` means one or the other. ## Quick list | I want to… | Command | |---|---| | start a new project | [`zev init`](#zev-init) | | copy a project from Zaryn | [`zev clone`](#zev-clone) | | see what I changed | [`zev status`](#zev-status), [`zev diff`](#zev-diff) | | choose what to save | [`zev add`](#zev-add) | | save a version | [`zev commit`](#zev-commit) | | see the history | [`zev log`](#zev-log), [`zev show`](#zev-show) | | undo changes to a file | [`zev restore`](#zev-restore) | | delete a file | [`zev rm`](#zev-rm) | | put work aside for a moment | [`zev stash`](#zev-stash) | | work on something separately | [`zev branch`](#zev-branch), [`zev checkout`](#zev-checkout) | | combine branches | [`zev merge`](#zev-merge) | | send my work to Zaryn | [`zev push`](#zev-push) | | get others' work | [`zev pull`](#zev-pull) | | ask for a review | [`zev pr`](#zev-pr) | | check nothing got worse (tests, speed, size, model scores) | [`zev eval`](#zev-eval) | | install packages faster through Zaryn | [`zev mirror`](#zev-mirror) | | use my proxy for every app, or as a VPN | [`zev proxy`](#zev-proxy), [`zev vpn`](#zev-vpn) | ## Start a project ### zev init Makes the current folder (or the folder you name) a zev repository. It creates a hidden `.zev` folder for the history and doesn't touch your files. ```bash zev init zev init my-project ``` ### zev clone Copies a repository to your computer: its full history, its files, and `origin` set to where it came from. The folder is named after the repository unless you give one. ```text zev clone <address> [folder] [--branch <name>] ``` ```bash zev clone someone/project zev clone someone/project my-copy --branch dev zev clone someone/project@dev zev clone https://zaryn.xyz/someone/project zev clone file:///home/me/backups/project ``` Private repositories need you to be [signed in](#zev-login) with access to them. The folder must not exist yet, or be empty. ### zev config Reads and changes this repository's settings. The two you need are your name and email, which go on every commit. ```bash zev config set user.name "Your Name" zev config set user.email "you@example.com" zev config get user.name zev config list ``` ## Everyday work ### zev status Shows where you are: the branch, what's staged for the next commit, what you changed but haven't staged, files you deleted, and new files zev doesn't track yet. Each section says which command to run next. ```bash zev status zev status --json # for scripts ``` ```text On branch main Changes to be committed: new file: notes.md Changes not staged for commit: modified: todo.txt deleted: old.txt Untracked files: draft.txt ``` ### zev add Stages changes, which means picking them for the next commit. It handles new files, changed files and deleted files. ```text zev add <file | folder | .>... ``` ```bash zev add notes.md # one file zev add src # everything in a folder zev add . # everything in the project zev add old.txt # old.txt was deleted: stages the deletion ``` Files matching `.zevignore` are skipped (unless zev already tracks them). Files that haven't changed since the last commit aren't staged, so `zev add .` is always safe to run. ### zev commit Saves everything you staged as a new commit, with a message describing it. ```bash zev commit -m "Fix the login button on small screens" zev commit "Same thing, without -m" ``` If nothing is staged, zev says so and makes no commit. A good message says what changed and why, in a few words. ### zev diff Shows the lines that changed: `+` added, `-` removed, with a little unchanged text around each change. ```text zev diff [file | folder] your changes that aren't staged yet zev diff --staged [file] what the next commit will contain zev diff <commit> [<commit>] [-- file] between commits ``` ```bash zev diff zev diff todo.txt zev diff --staged zev diff HEAD~3 HEAD # what the last three commits changed zev diff v1.0 main -- src # between a tag and a branch, only in src ``` ### zev log Lists commits, newest first: the ID, author, date and message. ```text zev log [--oneline] [-n <count> | --all] [<commit or branch>] ``` ```bash zev log # the last 10 zev log --oneline # one line each zev log -n 30 zev log --all zev log feature # the history of another branch ``` ### zev show Shows one commit and the changes it made. Without a commit it shows the newest one. ```bash zev show zev show 5f7f5e22 # the first characters of an ID are enough zev show HEAD~1 # the commit before the newest zev show v1.0 # a tag ``` **Naming commits.** Everywhere zev asks for a commit, you can write `HEAD` (the commit you're on), `HEAD~2` (two before it), a branch name, a tag name, or the start of a commit ID (at least 4 characters). ### zev restore Undoes changes to files. ```text zev restore <file | folder | .>... throw away your changes: back to the last commit zev restore --staged <file | folder | .>... unstage: keep your changes, leave them out of the next commit ``` ```bash zev restore todo.txt # undo my edits to todo.txt zev restore . # undo all my edits (careful!) zev restore old.txt # bring back a deleted file zev restore --staged notes.md # take notes.md out of the next commit ``` Changes you throw away with `zev restore` were never committed, so they can't be brought back. If you might want them later, use [`zev stash`](#zev-stash) instead. ### zev rm Deletes a tracked file and stages the deletion for the next commit. ```text zev rm [--cached] [--force] <file | folder>... ``` ```bash zev rm old.txt zev rm build # a whole folder zev rm --cached secrets.env # stop tracking it, but keep the file ``` zev refuses to delete a file with changes that aren't committed, so you don't lose work by accident. `--force` deletes it anyway. `--cached` is what you want when you committed something by mistake (add it to `.zevignore` too). ### zev stash Puts your uncommitted changes aside and gives you a clean folder (back to the last commit). Later, you bring them back. ```text zev stash [save [message]] put changes aside zev stash list see them zev stash pop [id] bring back the newest (or that one) and delete it zev stash apply [id] bring it back and keep it zev stash drop [id] delete it ``` ```bash zev stash save "half-done search box" zev checkout main # do something else zev checkout feature zev stash pop ``` Stashes include staged and unstaged changes to tracked files. Untracked files stay where they are. `zev stash pop` won't overwrite a file you changed after stashing; it tells you which file is in the way. ## Branches A branch is a separate line of work. You can try something on a branch without touching `main`, then merge it in when it's ready. See [Branches and merging](/docs/en/branches) for the full story. ### zev branch Lists branches (`*` marks the one you're on), makes one, or deletes one. ```bash zev branch # list zev branch new-search # make it (you stay where you are) zev branch -d new-search # delete it ``` ### zev checkout Switches to another branch and updates your files to match it. ```text zev checkout <branch> [--force] zev checkout -b <new-branch> ``` ```bash zev checkout new-search zev checkout -b new-search # make it and switch to it, bringing your changes along ``` zev never overwrites your uncommitted work: if switching would replace a changed file, it changes nothing and names the file. Commit or [stash](#zev-stash) first. `--force` throws your changes away and switches. ### zev switch The same as `zev checkout`, by the name some people expect. `zev switch -c <new-branch>` makes a branch and switches to it. ### zev merge Brings the commits of another branch into the one you're on. ```text zev merge <branch> zev merge <branch> --resolve when both changed the same lines zev merge --continue | --abort ``` ```bash zev checkout main zev merge new-search ``` If the branches don't overlap, zev combines them by itself. If both changed the same lines, it stops without changing anything and suggests `--resolve`, which marks both versions in the file: ```text <<<<<<< main the line as it is on main ======= the line as it is on new-search >>>>>>> new-search ``` Edit the file to keep what you want, delete the marker lines, then `zev add <file>` and `zev merge --continue`. `zev merge --abort` puts everything back as it was. [Step by step](/docs/en/branches#when-both-changed-the-same-lines). ### zev rebase Replays the commits of the branch you're on on top of another branch, as if you had started from its latest commit. ```bash zev rebase main ``` If it stops because both changed the same lines, run `zev merge main --resolve` instead: it does the same replay and lets you combine the lines by hand. ### zev cherry-pick Copies one commit from anywhere onto the branch you're on. ```bash zev cherry-pick 47bec4f5 ``` ### zev tag Gives a commit a name that doesn't move, usually a release. ```text zev tag [list] list tags zev tag <name> tag the current commit zev tag -a <name> -m <message> a tag with a message and author zev tag -d <name> delete a tag ``` ```bash zev tag v1.0 zev show v1.0 ``` ## Share on Zaryn ### zev login Signs this computer in to Zaryn (or another zev server). You do this once per computer. ```text zev login <server> --register <username> --email <address> make an account (an emailed code confirms it) zev login <server> --register <username> --code <123456> finish, if you closed the terminal zev login <server> --device [--client <name>] approve in your browser (existing accounts, servers, agents) zev login <server> sign in again with this project's identity ``` ```bash zev login zaryn.xyz --register sara --email sara@example.com zev login zaryn.xyz --device ``` The token is saved in `~/.config/zev/credentials`, readable only by you. ### zev whoami Shows the server and account you're signed in as. ### zev logout Forgets the saved sign-in on this computer. The token itself keeps working until you revoke it on Zaryn (Settings → AI agents and tokens). ### zev new Creates the current project on Zaryn and connects it as `origin`. It asks for a name, the kind of project (code, model, dataset, agent or topology), public or private, and a license. ```bash zev new zev push ``` ### zev push Sends your commits to a remote. With nothing after it, it sends the branch you're on to `origin`. ```text zev push [remote] [branch] ``` ```bash zev push zev push origin feature-x zev push me/project main ``` Large files only send the parts that changed. In [encrypted repositories](/docs/en/encrypted-repositories), files are encrypted on your computer before they're sent. ### zev pull Gets new commits from a remote and updates your files to match. ```text zev pull [remote] [branch] ``` ```bash zev pull zev pull origin main ``` If updating would overwrite a file you changed, zev changes no files and names the file. The new commits are still saved; commit or stash, then `zev checkout <branch>`. ### zev remote Manages remotes, the named addresses of other copies of the repository. ```bash zev remote # list zev remote add upstream team/project zev remote show upstream zev remote remove upstream ``` ## Work with others ### zev pr Opens a pull request from the branch you're on. zev drafts the title and description from your commits, shows them, and asks before opening. ```text zev pr [--title <t>] [--desc <d>] [--target <branch>] [--yes] zev pr list | view <number> | merge <number> ``` ```bash zev checkout -b fix-typo zev commit -m "Fix a typo in the README" zev push zev pr ``` See [Collaboration from the terminal](/docs/en/cli-collaboration). ### zev issue Opens and manages issues (bug reports, ideas, tasks). ```text zev issue [--title <t>] [--desc <d>] zev issue list [--all] | view <number> | comment <number> | close <number> ``` ### zev fork-repo Makes your own copy of someone's repository on Zaryn, to change freely and send back with a pull request. ```bash zev fork-repo someone/project --clone ``` `--as <name>` names the copy differently; `--clone` also clones it to your computer. ### zev ci Turns on CI for a repository and shows recent runs. ```bash zev ci enable zev ci status ``` ### zev mcp Runs an MCP server so an AI agent (Claude Code, Codex and others) can use Zaryn through zev. See [Scripting and AI agents](/docs/en/automation-and-agents). ```bash claude mcp add zaryn -- zev mcp ``` ## Find out more ### zev blame Shows, for each line of a file, the commit and author that last changed it. ```bash zev blame src/login.js ``` ### zev bisect Finds the commit that broke something by halving the history: you mark commits good or bad, and zev picks the next one to test. ```bash zev bisect start zev bisect bad # the current commit is broken zev bisect good 5f7f5e22 # this older one worked # test what zev checks out, then mark it: zev bisect good / zev bisect bad zev bisect reset # done ``` ### zev search Searches commits, experiments, metrics, lineage and snapshots. ```bash zev search commits login zev search all "learning rate" ``` ### zev compare Puts two commits, branches, snapshots or experiments side by side. ```bash zev compare branches main feature ``` ## Private networks ### zev net Joins this computer to one of your team's private networks (Premium): devices reach each other directly and privately, through NATs, over WireGuard. See [Private networks](/docs/en/private-networks). ```text sudo zev net up <owner>/<network> join (runs in the background) sudo zev net down [<network>] leave for now (--forget to leave for good) zev net status peers, connections, traffic zev net ls networks you're in zev net map [<owner>/<network>] who reaches whom, and what one failure would cost zev net share <port> [--name web] share an app on this device with the network zev net config <owner>/<network> a config file for WireGuard's own apps (phones) ``` ## Network devices ### zev site Makes this machine the collector of a site: it reads the site's routers and switches over SSH with read-only commands (Cisco IOS / IOS-XE, Huawei VRP, MikroTik RouterOS, FRRouting, VyOS) for config backups and drift, the live map, the address plan and Path Explain, and runs the site's probes. Passwords stay on the collector. See [Network sites](/docs/en/network-sites), [Path Explain and probes](/docs/en/network-paths) and [Digital twin](/docs/en/network-twin). ```text zev site join <token> [--server URL] make this machine the site's collector zev site cred add <name> --user <user> [--key <file>] [--enable] zev site cred ls · zev site cred rm <name> the logins kept on this collector zev site test <address> [--cred <name>] [--vendor cisco|huawei|mikrotik|frr|vyos] [--config] zev site discover <range>… which addresses answer on SSH, and what they are zev site probe ping|tcp|http|dns <target> [--port N] [--expect X] run a probe from here, as the service does zev site diff <owner>/<site> <device>=<file>… [--drills] [--json] what a config change would do, before it's made (exits 1 if traffic would break) sudo zev site install run the collector as a service zev site status this collector and its devices zev site forget-key <address> after a device's SSH key changed on purpose ``` ## Security and trust ### zev encrypt Encrypts a private repository's files on your devices, so Zaryn stores only data it can't read. See [Encrypted repositories](/docs/en/encrypted-repositories). ```text zev encrypt [status | on | share | recovery | unlock | approve <fingerprint> | rotate] ``` ### zev verify-storage Checks, with cryptographic proofs instead of trust, that the server really stores everything from your last push. See [Verified storage](/docs/en/verified-storage). ```bash zev verify-storage ``` ### zev advisory Declares commits compromised (for example a poisoned dataset or a leaked key), so owners of everything built on them are told. See [Advisories and lineage](/docs/en/advisories). ```text zev advisory file | list | show <id> | refresh | withdraw <id> | ack <id> | verify <id> | feed ``` ### zev taint Shows which advisories reach a repository. `zev taint check` is a CI gate: it fails while an unresolved advisory applies. ```bash zev taint zev taint check --fail-on high ``` ### zev identity Shows (and creates the first time) this repository's signing key. ### zev sign `zev sign <cid>` signs an object with your identity; `zev verify <cid>` checks a signature. ### zev notarize Anchors the hash of a snapshot or commit on a blockchain, as public proof that it existed at that time. ```text zev notarize snapshot <name> | commit <id> | verify <record> | list | config ``` ### zev audit Prints a full provenance report for the repository. ## Machine learning `zev eval` catches regressions in any project; the rest tracks the things ML projects care about, next to the code. ### zev eval Runs your tests, builds, benchmarks or eval, finds the numbers (test results, coverage, timings, bundle, binary and firmware sizes, frame times, model scores), records them for this commit on Zaryn and tells you at once whether a pull request into `main` would be blocked. Exits 1 when a metric got worse than its tolerance (in its units or a percentage, like `5%`), so it works as a CI step too. See [Evals and lineage](/docs/en/evals-and-lineage). ```bash zev eval init # once: detects Rust, JS/TS, Go, Zig, C/C++, PlatformIO, Godot, Unity, Python; saves zev-evals.json zev eval init -- python eval.py # or start from your own command zev eval run # before every pull request, or in CI zev eval report junit.xml lcov.info # results files you already have zev eval # this commit next to main zev eval compare main my-branch zev eval badge binary # Markdown for your README ``` ### zev metrics Records numbers (accuracy, loss, latency…) with commits, and compares them. ```bash zev metrics set accuracy 0.913 zev metrics show zev metrics compare <commit-a> <commit-b> ``` ### zev check A regression gate for CI: exits with an error if a metric got worse than the [thresholds](#zev-threshold) allow. ```bash zev check ``` ### zev threshold Sets the limits `zev check` enforces. ```bash zev threshold set accuracy --min 0.9 zev threshold list ``` ### zev history Shows a metric's trend over the commits, as a small chart. ```bash zev history accuracy ``` ### zev sdiff A semantic diff: changed metrics, and structural code changes (renamed functions, changed signatures) instead of only lines. See [Semantic diffing](/docs/en/semantic-diff). ### zev experiment Tracks a hypothesis from start to result. ```text zev experiment start <name> [description] | list | show <name> | complete <name> | abandon <name> | compare <a> <b> ``` ### zev dataset Registers datasets, splits them into shards, and records which shards were used where, so you know what a bad shard affected. ```text zev dataset register <path> --name <n> | split <n> --shards <k> | assign | lineage <n> | impact <n> --shard <i> | list ``` ### zev lineage Records what was made from what: data, scripts, models. ```text zev lineage record <trained_on|fine_tuned_from|evaluated_on|derived_from|uses> <owner/repo[@commit]> zev lineage upstream zev lineage add <id> <type> <description> | link <child> <parent> | show <id> | list | graph | provenance <cid> ``` `record` and `upstream` work on Zaryn: what this repository came from, and whether that changed since. The rest keeps a graph inside this repository only. ### zev context Records whether a change came from a person or an AI model, and with what prompt. ```bash zev context add src/parser.py --model claude --kind llm zev context blame src/parser.py ``` ### zev wdiff Compares model weight files (`.safetensors`, PyTorch, NumPy) tensor by tensor. ```bash zev wdiff base.safetensors tuned.safetensors ``` ### zev merge-weights Merges two checkpoints: average, weighted, SLERP or TIES. ```bash zev merge-weights a.safetensors b.safetensors --output merged.safetensors --strategy slerp --alpha 0.5 ``` ### zev drift Notices when metrics drift away from a baseline. ```text zev drift baseline <snapshot or commit> | config --metric <m> --delta <d> | check | show | history | watch ``` ### zev reproduce Captures a command and its output, and later checks that it reproduces within a tolerance. ### zev snapshot Named snapshots of the repository's state, optionally permanent. ```text zev snapshot create <name> | list | show <name> | restore <name> | diff <a> <b> ``` ### zev suggestions Lists lineage that Zaryn inferred from model weights ("this model looks fine-tuned from that one"), for you to accept or dismiss. ## Advanced These are for special setups and tooling. You won't need them for everyday work. | Command | What it does | |---|---| | `zev hook list \| add <type> <script> \| remove <type>` | run scripts before or after commit, push, merge (`pre-commit`, `post-commit`, `pre-push`, `post-merge`, `commit-msg`) | | `zev gc` | remove objects that nothing refers to any more | | `zev export <file>` / `zev import <file>` / `zev archive-info <file>` | the repository (or a snapshot) as a single archive file | | `zev publish commit \| experiment \| snapshot \| config` | publish to a configured endpoint | | `zev ipfs status \| add \| cat \| pin \| unpin \| block-put \| block-get \| block-stat` | talk to a local IPFS node | | `zev ipns key-gen \| publish \| resolve \| announce` | IPNS names | | `zev peer status \| announce \| listen \| connect \| sync` | sync with peers directly over libp2p | | `zev dag show \| walk \| put \| stat \| query \| export \| import \| get` | the content-addressed graph, directly | | `zev ipld migrate \| log` | IPLD commits | | `zev graft <cid> --as <name>` | link an outside CID under a readable name | | `zev fedmerge --from <file.car>` | merge work from a `.car` file, no server needed | | `zev fork <meta-cid> <folder>` | fork from an IPFS metadata CID | | `zev fetch-range <hash> <start> <len>` | part of a server object, checked against its hash | | `zev cat <cid>` / `zev hash <data>` | read an object / compute a CID | | `zev verify-release <url> <cid>` / `zev verify-sth <url>` | check the server's transparency log | | `zev push-api` / `zev pull-api` / `zev clone-api` | the server versions of push, pull and clone; `zev push`, `zev pull` and `zev clone` pick them for you | ## zev itself ### zev self ```bash zev self update # update zev (the download's signature is checked) zev self update --check # only say whether there's a newer version zev self uninstall ``` If zev came from a package manager (apt, dnf, zypper, pacman), update it there instead; `zev self update` tells you which command to use. ### zev proxy Sends zev's own connections (sign-in, clone, push, pull, updates, private networks) through a proxy of yours, and if you like every app (`share`, `system`, `ssh`, `run`) or the whole computer (`zev vpn`), for networks that block the way to Zaryn: VLESS, VMess, Trojan, Shadowsocks, Hysteria2 and WireGuard (through the Xray engine), SOCKS5 or HTTP, or a provider's subscription. Several servers at once with failover, chains, and routes for what goes direct. See [Using zev through a proxy](/docs/en/proxy). ```text zev proxy start ['<link>'] [--tun] [--kill-switch] everything on in one go (apps, desktop, VPN with --tun) zev proxy stop everything off again zev proxy is it on, and through which server zev proxy add <name> [<link>] [--use] save a proxy (no link: paste it, out of shell history) zev proxy use <name> | off go through it, or directly again zev proxy use <a>,<b> | auto | <sub> a pool: the fastest 3 run, switching when one stops answering zev proxy probe [<name>|auto] time every server at once and rank them zev proxy chain <name> <a> <b> [<c>…] reach <b> through <a>; use it by its name zev proxy route [direct|proxy|rm <route>… | iran | clear] what goes direct (example.com, CIDR, geoip:ir) zev proxy test [<name>] connect through it and time the way to Zaryn zev proxy doctor [<name>] [--no-fix] [--json] find what blocks the way and fix what zev can (per network) zev proxy set [forget | dns|ipv4|fragment|fp …] the network's fixes zev proxy ls | status | rm <name> zev proxy engine install install Xray (needed for all but socks5:// and http://; SHA-256 checked) zev proxy sub add <name> <url> a subscription: all its servers, named <name>-1, -2 … zev proxy sub update [<name>] | ls | rm <name> zev proxy config <name> the Xray config zev runs for it (holds its secrets) zev proxy share on [--port N] [--lan] | off | status one SOCKS5+HTTP port (127.0.0.1:10808) for every app zev proxy system on | off the desktop's proxy setting and new sessions' http_proxy, all_proxy… zev proxy ssh [<host>…] | off SSH (git push to GitHub…) through the proxy zev proxy connect <host> <port> a connection on stdin/stdout (SSH's ProxyCommand) zev proxy run <command…> one command through it (HTTP, HTTPS, SOCKS, git over SSH) zev proxy check where you appear from; DNS and IPv6 leaks zev proxy top [--once] live traffic of the shared port or the VPN ``` ### zev vpn All of this computer's traffic through the proxy you chose with `zev proxy use`: every program, its DNS and IPv6, on Linux. See [the whole computer: zev vpn](/docs/en/proxy#the-whole-computer-zev-vpn). ```text sudo zev vpn on [--kill-switch] [--exclude <name|ip/cidr>,…] start it (a system service) sudo zev vpn off stop it; routes, rules and firewall table removed zev vpn status ``` ### zev mirror Points pip, uv, npm, cargo and rustup at Zaryn's mirrors, which check every file against the hash the tool already knows. See [Mirrors](/docs/en/package-mirrors#all-at-once-zev-mirror). ```text zev mirror what is set up, tool by tool zev mirror on [cargo npm pip uv rustup] switch them to Zaryn (all by default) zev mirror off [...] back to their own servers (only zev's lines are removed) zev mirror zig [--check|--undo] this project's build.zig.zon through the mirror (--check: download and check every dependency now) ``` ### zev version `zev --version` prints the version and the system it was built for. ### zev help `zev help` lists every command; `zev help <command>` shows how to use one. Typos get a suggestion (`zev comit` → did you mean `zev commit`).