CLI reference
TARGET in pages commands is a deploy id (eight hex characters) or an alias name. Flags can come before or
after arguments. --json prints JSON wherever a command lists data.
Account
xvii login
xvii login [DOMAIN]
Signs in to an instance through the browser: shows a code, opens id, where you allow this machine with your
passkey. Creates or updates a context for DOMAIN.
| Flag |
|
--name NAME |
call the context NAME (default: the domain) |
--no-browser |
print a link and a QR code instead of opening a browser |
xvii logout
Signs this machine out of the current instance.
xvii whoami
Who you are on the current instance, your teams and how you signed in. Also xvii me. --json.
xvii tokens
| Command |
|
tokens list [--team TEAM] |
your tokens, or a team's (admins) |
tokens create NAME [--scope read|deploy|write] [--team TEAM] [--ttl 90d] |
a token; the secret is printed once, on stdout |
tokens revoke ID |
revoke a token |
xvii tokens create gitlab-ci
xvii tokens create deploy-bot --team frontend --ttl never
Workspace
xvii teams
| Command |
|
teams list |
the teams you are in, with your role |
teams create NAME |
a new team, with you as its owner |
teams members TEAM |
who is in a team (slug or id) |
teams invite TEAM USER [--role developer] |
invite someone with an account: viewer, developer, admin or owner |
xvii projects
| Command |
|
projects list [--team TEAM] |
every project you can see |
projects create NAME [--team TEAM] [--description …] [--repository URL] |
a project with production and preview environments |
pages
xvii pages deploy
xvii pages deploy [DIR]
Packs the folder (default: dist, build, out or public), uploads it and prints the deploy's address;
with --name the alias's too. Git details are recorded inside a repository.
| Flag |
|
--name NAME |
also point the alias NAME at the deploy |
--ttl 12h|3d|2w|never |
lifetime (default: the server's) |
--keep |
never delete automatically |
--spa |
serve index.html for unknown paths |
--password PASSWORD |
protect with a password |
--public |
open even if the server has a default password |
--team SLUG, --project ID, --env NAME |
where it belongs |
--message TEXT |
a note shown in the panel (default: the last commit subject) |
--qr |
print a QR code of the address |
--watch |
deploy again on every change, until Ctrl-C |
--json |
print the deploy as JSON |
Other pages commands
| Command |
|
pages list [--mine] [-n N] [--team SLUG] |
deploys, newest first (also ls) |
pages open TARGET [--qr] |
open a deploy or alias in the browser |
pages qr TARGET |
a QR code of a site's address |
pages files TARGET [--filter TEXT] |
the files of a deploy |
pages diff TARGET [OTHER] |
files added, removed and changed; without OTHER, against one rollback ago |
pages rm ID… [--yes] |
delete deploys; aliases move to their previous deploy (also delete) |
pages keep ID [--off] |
exempt a deploy from cleanup |
pages ttl ID LIFETIME |
a new lifetime, counted from now |
pages password TARGET [PASSWORD] [--off] [--public] |
protect, unprotect or open |
pages aliases |
aliases and where they point |
pages alias NAME ID |
point an alias at a deploy (creates it) |
pages rollback NAME |
point an alias back at its previous deploy |
pages unalias NAME [--yes] |
remove an alias; its deploys stay |
pages domains ALIAS [add|check|rm|records DOMAIN] [--zone] |
custom domains of an alias |
pages status |
who you are, your teams' quotas, recent deploys (also whoami) |
pages log [-n 30] [--filter TEXT] |
recent activity (also activity) |
apps
xvii apps create
xvii apps create NAME
| Flag |
|
--project SLUG, --env ENVIRONMENT |
where (default environment: production) |
--kind web|worker|bot|cron |
default web |
--port PORT |
the port a web app listens on (default 8080) |
--health PATH |
a path that answers 200 when ready |
--memory MB |
memory limit (default 256) |
--schedule "0 3 * * *" |
a cron app's schedule (UTC) |
--image IMAGE |
deploy this image now |
xvii apps deploy
xvii apps deploy APP
Deploys an image, or a folder built on the app's node (its Dockerfile, else Railpack). Waits until the
release is live or failed.
| Flag |
|
--dir FOLDER |
build and deploy this folder |
--dockerfile PATH |
the Dockerfile's path in the folder |
--image IMAGE |
deploy this image |
--preview NAME |
deploy to a preview (made when missing) |
--ttl 7d |
how long a preview lives without a deploy |
--link URL |
the merge request a preview belongs to |
--message TEXT |
what changed (default: the last commit's subject) |
--dotenv FILE |
write APPS_URL=<address> into FILE once live |
--project SLUG, --env NAME |
when app names repeat |
--detach |
don't wait |
Other apps commands
| Command |
|
apps ls |
your teams' apps |
apps logs APP [-n 200] [-f] [--since 10m] |
an app's last log lines |
apps rollback APP [NUMBER] |
deploy an earlier release again |
apps stop APP, apps start APP |
stop or start an app |
apps previews APP [--rm NAME] |
an app's previews, or remove one |
apps templates |
the templates catalog |
apps install TEMPLATE --project SLUG [--env …] [--name …] |
install a template |
apps import --compose FILE --project SLUG [--env …] [--deploy] |
turn a compose project into apps |
apps registries [--team NAME] [--add HOST --user NAME] [--rm HOST] |
sign-ins to private registries; the password from the terminal, stdin or XVII_REGISTRY_PASSWORD |
apps nodes |
the nodes your teams run on |
apps move NODE --project SLUG [--env …] |
move a project environment to another node |
env
| Command |
|
env ls |
the sets of your teams |
env set NAME=VALUE… [--plain] |
set variables (secret unless --plain) |
env unset NAME… |
remove variables |
env run -- COMMAND [ARGS…] |
run a command with the variables; files in a private temporary folder |
env pull [--out .env] [--files] [--force] |
write the variables into a file, and files and SSH keys with --files |
env export [--format dotenv|json|shell] |
print the variables |
All take --project ID|SLUG (default XVII_PROJECT), --env NAME (default XVII_ENV, then
CI_ENVIRONMENT_NAME) and --team SLUG when project slugs repeat across teams.
eval "$(xvii env export --format shell)"
xvii env run --project api --env preview -- go test ./...
notify
| Command |
|
notify events [-n 20] [--service S] [--severity warning|critical] [--team SLUG] [--type 'deploy.*'] |
recent events (also ls) |
notify ack SEQ |
acknowledge an event |
notify send TOPIC [MESSAGE] [--title …] [--priority low|default|high|urgent] [--link URL] [--tags a,b] |
post to a topic; the message from stdin when not given |
notify topics |
topics of your teams |
notify topic NAME --team SLUG [--description …] [--project ID] |
create a topic |
notify channels |
where your notifications go |
tunnel
xvii tunnel PORT|URL
Opens https://<name>.tunnel.xvii.network for a local port or address until Ctrl-C.
| Flag |
|
--name NAME |
a reserved name or any free one (default: random) |
--team ID |
the team it belongs to |
--password PASSWORD |
ask visitors for a password |
--inspect |
print every request as it comes |
| Command |
|
tunnel ls |
your teams' live tunnels |
tunnel names [--reserve NAME] [--release NAME] [--team ID] |
reserved names |
hooks
| Command |
|
hooks ls |
your teams' endpoints |
hooks create [--name NAME] [--verify telegram|github|gitlab|stripe] [--secret SECRET] [--team ID] |
make an endpoint |
hooks rm ENDPOINT |
delete an endpoint and what it caught |
hooks listen ENDPOINT [--forward PORT|URL] |
pass its requests to this machine; the answer goes back |
hooks requests ENDPOINT [-n 20] |
what an endpoint caught |
hooks replay REQUEST [--to listener|forwards|URL] |
send a caught request again |
ai
| Command |
|
ai keys create [--name NAME] [--own] [--models 'claude-*'] [--daily N] [--budget DOLLARS] [--team ID] |
make a key, shown once |
ai keys rm KEY |
delete a key |
ai usage [--days 30] |
calls, tokens and cost by model and key |
ai quota [KEY] |
what a key may still spend (the key from AI_KEY or the argument) |
ai accounts add PROVIDER |
sign in a subscription account (superusers) |
share
xvii share FILE…
Uploads files and prints https://share.xvii.network/<code> with a QR code.
| Flag |
|
--ttl 12h|7d|2w|never |
lifetime (default 7d) |
--password PASSWORD |
ask for a password first |
--downloads N |
remove after N downloads |
--e2e |
encrypt end to end; the key only in the link's fragment |
--title TITLE, --team ID |
|
| Command |
|
share paste [FILE] [--lang go] [--e2e] [--ttl …] [--password …] |
share text from a file or stdin |
share link URL [--name NAME] [--ttl never] |
a short link |
share ls |
what your teams shared |
share rm CODE |
delete a drop |
config
| Command |
|
config flags [--project SLUG] |
a project's flags and where they are on |
config set FLAG VALUE [--env production] [--project SLUG] |
on, off, or a value of the flag's kind |
server
xvii server install
xvii server install [USER@HOST]
Turns a fresh server into an instance over SSH (or the machine it runs on, as root). Running it again is
safe.
| Flag |
|
--domain DOMAIN |
the instance's domain |
--email EMAIL |
for Let's Encrypt |
--user NAME |
the first superuser's name |
--source URL |
the release store to install from (default https://xvii.network/releases) |
--yes |
take the flags and go |
The Cloudflare token comes from the prompt or XVII_CLOUDFLARE_TOKEN.
xvii server restore
xvii server restore [USER@HOST] --kit FILE
Brings an instance back on a fresh server from its backups, with the recovery kit from the backups panel.
--source for versions the backup doesn't carry, --yes not to ask.
This CLI
| Command |
|
context [list|use NAME|add DOMAIN|rm NAME] |
the instances this CLI talks to (also contexts, ctx) |
completion bash|zsh|fish [--install] |
shell completion |
update [--check] [--force] |
install the version the instance offers (also upgrade, self-update) |
mcp |
serve every service's tools to an AI client over stdio |
version |
print the version |
help [COMMAND…] |
the overview, or a command's flags and examples |
The server's agent: xvii-node
On the control plane and nodes, as root:
| Command |
|
xvii-node status |
services, versions, health |
xvii-node install SERVICE [VERSION] |
install or update a service (default: the newest in the store) |
xvii-node import DIR VERSION |
add a release (manifest, binaries, SHA256SUMS) to the store |
xvii-node logs SERVICE [LINES] |
a service's journal |
xvii-node host SERVICE [LABEL] |
serve a service at <LABEL>.<domain> |
xvii-node recover USER |
a sign-in link from id, when nobody can sign in |
xvii-node token USER NAME [SCOPE] [LIFETIME] |
an API token for automation |
xvii-node join URL TOKEN [NAME] [MODE] |
join apps as a node (edge or relay) |
xvii-node leave |
forget the node's credential |
xvii-node dns URL TOKEN |
answer for domains' own zones on port 53 |
xvii-node edge CONTROL_PLANE_IP |
relay mail ports to the control plane |
xvii-node serve |
the daemon (run by systemd) |