russel is the command-line client. It talks to a control plane, russel-ctrl, over HTTP. Install: Installation.
Commands
ID is the service’s service.name from its Russelfile.
Options for every command
russel init
Writes a Russelfile.toml in DIR (default: the current folder), with every field explained in comments. It won’t overwrite an existing file without --force.
russel login, logout, origin
login saves the control plane’s address and token to ~/.config/russel/config.toml (mode 0600). It reads the token from --token-file (a bare token or a RUSSEL_API_TOKEN=… line), from RUSSEL_API_TOKEN, or by prompting. It never prints the token.
logout deletes the saved file. origin shows the address in use, where the token comes from, and whether the control plane answers. It’s the first thing to run when something doesn’t connect.
russel deploy
Deploys the service named in the Russelfile. Use it for the first deploy, and russel update after that.
Deploying the commit and Russelfile a service already runs does nothing and reports
unchanged. A folder with uncommitted changes, or one outside git, always deploys.
Renaming a service. service.name is the service’s identity. To rename one, change the name, deploy it, then russel destroy the old name.
russel ps, status, logs
ps lists every service with its runtime, status, host port, and uptime. status shows one service in detail, including its restart count. logs prints its recent output. With only one service deployed, status and logs work without an ID.
russel update
Rebuilds and redeploys a running service.
- Without flags, it rebuilds the commit that’s already running. Secrets are read again, so this is how you apply a changed secret.
--refreshbuilds the latest commit: the default branch of a git URL, orHEADof a folder. This is how you ship changes.--repoand--configdeploy from a different source, and imply--refresh. The Russelfile’sservice.namemust still matchID.
russel rollback
Starts an earlier deployment’s recorded build again, with the Russelfile it ran. Without --version, it picks the previous deployment. --rebuild builds that deployment’s commit from source instead; use it when Nix has collected an old build. With --rebuild, a deployment made from uncommitted changes is rebuilt from what its folder holds now.
russel stop and destroy
stop stops the app and removes its route, but keeps its history, so update or rollback can start it again. destroy also removes its ports, files, and history. Destroying an unknown service is an error.
[[volumes]] data on destroy:
Absolute
host = folders are never deleted.
russel secrets
list shows names only. Use a secret with secret://NAME in [service.env].
Output and exit codes
deploy, update, and rollback print each stage as it happens. They exit 0 when the result is deployed or unchanged, and non-zero on failure. A deploy that failed and was rolled back (rolled_back) also exits non-zero, so scripts notice.
russel-ctrl
The control plane. The installer runs it as a systemd service, so you rarely start it by hand.
All settings: Environment reference.