cli

The xvii binary: every service's commands, sign-in, contexts, server installation and the MCP bridge. Repo cli. Stage 1 (skeleton and pages commands), grows with each service. Conventions: conventions/cli.md.

Top level

xvii login | logout | whoami | status           device flow against id, per context
xvii context add <domain> | use | list | rm      several instances
xvii open [service]                              the panel in the browser
xvii update                                      self-update from the instance
xvii completion [--install]                      bash, zsh, fish
xvii mcp                                         stdio MCP server exposing every service's tools
xvii server install | update | status | add-node | restore | doctor
<service> …                                      xvii pages deploy, xvii apps logs, xvii ai usage, …

`xvii server install`

xvii server install [USER@HOST] runs against a server over SSH, or on the machine itself without a host. The wizard (or --domain --email --user --yes, the token from XVII_CLOUDFLARE_TOKEN) asks for the domain, the ACME e-mail, an optional Cloudflare token (one wildcard certificate over DNS-01; without it a certificate per name over HTTP-01) and the first superuser's name, and shows whether <domain> and id.<domain> point at the server. On the server it downloads xvii-node from the release store (--source, default https://xvii.network/releases, checked against SHA256SUMS) and runs xvii-node setup with the answers on stdin: PostgreSQL, Caddy with the Cloudflare module, the instance settings, the newest id and home from the store, then xvii-node as a service. It prints the link (and a QR code) that creates the first passkey. Idempotent: running it again repairs.

Later: checks for ports 80/443 held by something else and for the clock, choosing services to enable, saving the instance as a context.

Stage 1 state

xvii login DOMAIN signs in to that instance's pages (the browser approval pages already has) and saves the token in a context; stage 2 switches it to the device flow at id. Builds are published by make publish into pages' /cli/ (served with latest.json); stage 2 moves them to home's /releases/cli/. Completion is dynamic: the scripts call xvii __complete WORDS…, so nested commands and names from the server complete without regenerating anything.

`xvii mcp`

A stdio MCP server for AI clients (claude mcp add xvii -- xvii mcp): it asks home's catalog which services run, collects their tools from <service>/mcp and forwards calls with the CLI's sign-in (or XVII_TOKEN), so the client can do what the user can. CI jobs sign in by themselves: XVII_ID_TOKEN (GitLab id_tokens) or GitHub Actions' OIDC token is traded at id under a trust rule.

Distribution

curl -fsSL https://<d>/install.sh | sh installs the CLI from the instance; binaries for linux/darwin × amd64/arm64; self-update with checksum verification (from pages).