CLI Overview
Every unisrv command, grouped by what it does.
The CLI is declarative: you describe a project in unisrv.hcl and apply it.
unisrv up # apply unisrv.hcl to an environment
unisrv status # see what is running
unisrv destroy # tear the environment downEverything else is setup (hosts, registry credentials) or inspection (status, logs).
Environments
Every command that touches running resources works against one environment, resolved from project in your unisrv.hcl and prompted when ambiguous. Pin it with --env <name>:
unisrv up --env stagingThe same file applied to a different environment gives an independent copy — that is how per-PR and per-agent environments work.
Session
| Command | What it does |
|---|---|
unisrv login | Log in with username and password. Credentials go to the system keystore. |
unisrv logout | Forget the stored session on this machine. |
unisrv auth token | Print an access token to stdout, for scripts and docker login. |
Project
| Command | What it does |
|---|---|
unisrv up | Apply unisrv.hcl from the current directory. Shows a plan first. |
unisrv status | What is running across this project's environments, with per-service traffic. --json for scripts. |
unisrv destroy | Delete an environment and everything in it. |
up takes --var KEY=VALUE and --var-file FILE (both repeatable) for interpolation. Both up and destroy take -y to skip confirmation, required when no terminal is attached, as in CI.
Some changes are destructive: renaming a service or network, changing a network's iprange, or moving a deployment between services recreates the affected resources. unisrv up tells you before it does it.
Hosts
| Command | What it does |
|---|---|
unisrv host claim <hostname> | Claim a domain and provision a TLS certificate for it. |
unisrv host list | List claimed hosts. |
A host must be claimed before a service can list it in hosts. Claiming is per account, and a host binds to one service globally. You do not need this to get a URL — every service is always reachable at a derived {service}-{environment-slug}.unisrv.dev.
DNS for custom domains
Point the domain at the Unisrv edge before claiming it, or certificate provisioning fails.
| Type | Record | Value |
|---|---|---|
| CNAME / ALIAS | app.example.com | srvedge.net |
| A | app.example.com | 70.34.214.14 |
| AAAA | app.example.com | 2a05:f480:2000:16fd::1 |
For subdomains, a CNAME to srvedge.net is simplest. DNS forbids a CNAME at a zone apex, so for apex domains use an ALIAS or CNAME-flattening record if your provider has one (Cloudflare and others do), otherwise the A and AAAA records.
Registries
Public images need no setup. Private ones need a credential, stored on your account rather than this machine, so the platform can pull on your behalf. The console manages the same credentials.
| Command | What it does |
|---|---|
unisrv registry add <hostname> | Add a credential, e.g. unisrv registry add ghcr.io -u <username>. |
unisrv registry list | List configured registries. --json for scripts. |
unisrv registry update <hostname> | Replace the credentials for a registry. |
unisrv registry delete <hostname> | Remove a credential. |
unisrv registry test <hostname> | Check the stored credentials still work upstream. |
add validates upstream before saving (--no-validate to skip) and prompts for the password, or reads it from stdin:
echo $GITHUB_TOKEN | unisrv registry add ghcr.io -u <username> --password-stdinInstances
unisrv up creates instances; these commands inspect them, plus run for one-shot containers. Instances are referenced by UUID, name, or UUID prefix.
| Command | What it does |
|---|---|
unisrv instance list | Instances in the environment. -a includes stopped ones, --json for scripts. |
unisrv instance logs <name> | Print logs. -f follows until the instance stops. |
unisrv instance run <image> [cmd...] | Start a one-shot instance and follow it until it exits. |
unisrv instance rm <name> | Stop and remove an instance. -t <secs> for a graceful shutdown. |
Use instance run for one-off work: a migration, a shell, a check that an image boots. It takes -e KEY=VALUE, --env-file, --cpus, -m/--memory, --name, --network, -d to detach, and --rm to clean up on exit.
unisrv instance run alpine echo hello
unisrv instance run --network internal -e PGPASSWORD=... --rm migrate:latestAn instance started with run is not managed by unisrv.hcl. unisrv up will not touch it, and it will not come back if it dies.