Collaboration from the Terminal

Everything you would normally do in a web UI — creating a repository, opening issues, reviewing and merging pull requests, forking — works directly from the zev CLI. You sign in once, and every server command after that needs no URLs or tokens. ## Sign in once ```bash zev init zev login zaryn.xyz --register alice --email alice@example.com ``` `zev login` signs a one-time challenge with this repository's identity (`.zev/identity`), exchanges it for a personal access token, and saves the server URL and token to `~/.config/zev/credentials`, readable only by you. The first time, `--register <username> --email <address>` creates an account for this identity once you confirm the emailed code; afterwards plain `zev login <url>` is enough. The server can be written as its website (`zaryn.xyz`, `example.com`), as `http://host:port`, as a bare `host:port`, or as any repository address on it — only the server part is used. ```bash zev whoami zev logout ``` `zev whoami` shows the saved server, user, and a masked token. `zev logout` deletes the saved credentials from this machine; the token itself stays valid on the server until it is revoked there. ### Where credentials come from Every server command resolves credentials in this order: 1. `--server` and `--token` flags 2. The `ZEV_SERVER` and `ZEV_TOKEN` environment variables 3. The login saved by `zev login` So flags always win, environment variables suit CI and automation, and a saved login covers everyday use. ## Create a connected repository ```bash zev new ``` An interactive wizard asks for the repository name, type (code, model, dataset, agent, topology), main language, visibility, and license. It creates the repository on the server, writes a `.zevignore` suited to the language, and connects the local project as the `origin` remote. ## The everyday loop ```bash zev add . zev commit "Describe the change" zev push ``` With no arguments, `zev push` pushes the current branch to `origin`, and `zev pull` pulls the current branch from `origin`. Both accept an explicit remote name or URL and branch when you need them: ```bash zev push upstream feature-x zev pull alice/project main ``` `zev add .` stages a whole directory tree recursively, skipping `.zev/` and anything matched by `.zevignore`. ## Issues ```bash zev issue --title "Login button misaligned" --desc "Overflows on narrow screens" zev issue list zev issue list --all zev issue view 1 zev issue comment 1 --body "Reproduced on a 360px viewport." zev issue close 1 ``` Plain `zev issue` creates an issue, prompting for anything you did not pass as a flag. `list` shows open issues, and `--all` includes closed ones. `view` shows the description and the full comment thread. `comment` prompts for the text if `--body` is omitted. `close` asks for confirmation first, because issues cannot be reopened from the CLI yet. Issue numbers can be written as `3` or `#3`. ## Pull requests ```bash zev branch fix-login-button zev checkout fix-login-button zev add . zev commit "Fix login button overflow" zev push zev pr ``` `zev pr` detects the source branch from your checkout and asks for the target branch, defaulting to `main`. It drafts the title from your latest commit message and, when the branch has more than one commit, drafts the description as a list of every commit on your branch that the target does not have yet. Press Enter to accept each draft, or type your own. `zev pr --yes` accepts all the drafts without prompting. ```bash zev pr list zev pr list --all zev pr view 1 zev pr merge 1 ``` `merge` checks that the pull request is still open, asks for confirmation, and then merges it on the server. Afterwards, bring your local copy up to date: ```bash zev checkout main zev pull ``` ### On the website Open **Pull requests → New pull request** in the repository. Pick the branch with your changes and the branch to merge into: the page shows the commits and the files your branch changed, and whether the target has moved on since. Write a title and a description (a template is filled in), tick the issues it closes (they close when it merges), add labels, ask the owner or collaborators to review, and open it, ready or as a draft. Reviewers approve, ask for changes, or comment. A pull request merges when it isn't a draft, nobody's request for changes is outstanding, and its branch holds every commit of the target, so merging never drops anyone's work. ### When the target branch has moved on If someone merged into `main` after you branched, bring their commits into your branch, then push it: ```bash zev pull origin main zev checkout fix-login-button zev merge main zev push ``` `zev merge main` replays your commits on top of `main`, combining each file line by line. When both sides changed the same lines it changes nothing and says which files; then run `zev merge main --resolve`: your branch is put on top of `main` and those files get both versions between `<<<<<<<` and `>>>>>>>` markers. Keep what you want, remove the markers, and run `zev merge --continue` (or `zev merge --abort` to go back). ## Working with other repositories ```bash zev fork-repo alice/project --clone zev clone alice/project project --branch main ``` `zev fork-repo` copies a repository, with all its branches, into your account; `--as <name>` gives the fork a different name, and `--clone` clones it locally as well. `zev clone` clones a repository into a new directory. In both cases the clone is ready to use immediately: files are checked out and `origin` is set, so `zev pull` and `zev push` work with no arguments. `list`, `view`, `comment`, `close`, and `merge` accept `--repo owner/name`, so you can work with any repository from any directory — including outside a repository entirely. ## Your working files are safe zev never silently overwrites uncommitted work. - `zev pull` on your current branch updates your files automatically, but only when that is safe. If you have staged changes, modified or deleted tracked files, or an untracked file that the update would overwrite, it changes nothing, names the file responsible, and tells you what to do. The branch itself is still updated, so nothing is lost. - `zev pull` for a branch you are not on never touches your working files. - `zev checkout` refuses to switch branches in the same situations, and changes nothing when it does. `zev checkout --force <branch>` switches anyway and discards your local changes. - When switching or pulling, files that exist only in the old version are removed, so your working tree always matches the branch you are on. `zev status` shows the current branch and lists staged, modified, deleted, and untracked files, including those inside subdirectories.