Command reference
Every wor command, its flags, what it does, and the output you should expect.
Exit code is 0 on success and 1 on any error, unless a section says otherwise. wor help prints a flag summary.
Example outputs on this page come from real runs of wor on macOS. Machine-specific values (tool versions, disk sizes, dates, file names) have been replaced with typical ones and long paths shortened, so your numbers will differ. On Linux, paths and a few platform-specific checks differ.
All commands
| Group | Commands |
|---|---|
| General | version upgrade setup doctor env clean reset create |
| Domain | domain add domain remove |
| Service | service add remove start stop restart reload status logs chown |
| Run | run |
| Host | host add remove list test reload logs |
| Database | database add remove backup |
| Source | source clone pull backup |
| Deploy | deploy rollback |
| SSL | ssl issue redirect sync renew status remove install |
| Inspect | info health diagnose |
| Navigate | path shell-init goto |
| Global flags | --json --non-interactive |
General
wor version / --version --json
Prints the product name, version and build number. A binary built without the build stamp shows no build number. Needs no initialised workspace and no lock.
wor upgrade [--yes]
Asks the download site which release is current, shows installed against published, and installs the newer one after you confirm. Compares build numbers only when the version numbers match; a local build that is newer than the published one gets a warning before it offers to continue. Does not need an initialised workspace or the lock. Setup: Install: upgrading.
wor setup
The first-time wizard. Safe to re-run: earlier answers become the defaults. Steps and effects are in Install & first run. Always the way a workspace becomes initialised, so it is exempt from the initialised-workspace gate.
wor doctor --json
Read-only machine check: is this machine ready? A ✓ / ⚠ / ✗ checklist in four groups.
- Environment: OS,
WOR_ENV,WOR_HOME, config file, host provider, and one line saying whether the workspace is initialised. - Runtimes: PHP, PHP-FPM, Node.js, Python, Go. Missing is ✗ immediately; there is no "is anything using it?" exception. nginx and Apache are both shown with
(active)on the configured one, and ✗ only if the active one is missing. - Database: MySQL client/server, MariaDB, PostgreSQL, Redis, SQLite. Always optional (⚠ at most).
- Other tools: git, zip, gzip. Always optional.
It ends with a Security section, which only ever warns and never changes the exit code: group- or other-readable .env files under WOR_HOME (with a copy-pasteable find ... -exec chmod 600); whether the web server user can traverse into WOR_HOME and into every static/php service's public/ (full check on Debian family with exact setfacl commands; other Linux families get a broad warning to also check SELinux; skipped on macOS); a WOR_HOME owned by root while you are not (this blocks ssl sync); and Let's Encrypt certificates with no renewal schedule on the machine (no systemd timer, launchd job or cron entry). It reports and shows the command; it never installs a schedule.
Exit code 1 when something required is missing: a core runtime, a configured-but-absent host provider, or an uninitialised workspace. It takes the workspace lock because it can refresh the default vhost.
Abridged output:
$ wor doctor
WOR Doctor
==========
Environment
OS : macOS
WOR_ENV : development
WOR_HOME : ~/wor
Config : ~/.wor/config
Host Provider : nginx
✓ Workspace initialized
Runtimes
✓ Nginx (active) nginx/1.24.0
✓ PHP 8.3.6 (cli) (NTS)
✓ PHP-FPM per-service pools available: 8.3, 8.2
✓ Node.js v20.11.1
✓ Python 3.12.3
Database
✓ MySQL Client /usr/bin/mysql Ver 8.0.36
⚠ MariaDB not installed
✓ SQLite 3.45.1
Security
✓ Service tree is owned by a single account (you)
✓ No world-readable .env files found under WOR_HOME
wor env
Prints the configuration values in effect (WOR_ENV, WOR_HOME, config file and the resolved settings).
wor clean
Removes orphans: host configs, PM2 processes, systemd units and /etc/hosts entries that no domain or service references any more. Never touches anything still tied to a registered service.
wor reset
Wipes everything wor created back to a clean state: PM2 processes prefixed wor_, units wor_*.service, vhosts wor__*.conf, wor's /etc/hosts block, and the domains, backups, logs and ssl folders. Host configs that are not wor's are left alone. You must type RESET; there is no flag that skips this.
Output:
$ wor env
WOR Environment
---------------
OS : macOS
WOR_ENV : development
CONFIG_FILE : ~/.wor/config
WOR_HOME : ~/wor
WOR_DOMAINS : ~/wor/domains
WOR_BACKUPS : ~/wor/backups
HOST_PROVIDER : nginx
NGINX_BIN : /usr/local/bin/nginx
NGINX_AVAILABLE : /opt/homebrew/etc/nginx/servers
NGINX_ENABLED : /opt/homebrew/etc/nginx/servers
NGINX_LOG_DIR : /opt/homebrew/var/log/nginx
PHP_FPM_ENDPOINT : not configured
wor create [host]
Interactive only. Accepts the optional positional host and no flags (any --flag is a usage error pointing at the automation surface). Walks through service type, domain id override, domain type (local or public) and the hosts-file entry, then creates the domain, service, scaffold, vhost, and optionally the certificate. For automation use domain add, service add and host add.
Domain
wor domain add <domain-id>
wor domain remove <domain-id>
add creates the domain's folders and config files, including its backup and log folders.
remove has no --cascade or force flag. It blocks at once if the domain still has any service, even a stopped one, and lists the exact wor service remove commands to run first. When none remain it asks, in this order, with [Y/n] defaulting to yes: Backups, Logs, Web Data. The first two only record the decision and say whether they will keep or delete. Web Data, asked last, is the confirmation for the whole set: "n" cancels everything (nothing is deleted); "y" performs all three as chosen.
Output:
$ wor domain add com-example
[OK] Domain ready: com-example
Service
wor service add <domain>/<service> [--host=<host>] [--port=<port>] [--entry=<entry-point>]
[--service-type=static|node|go|python|php]
[--php-version=<version>] [--no-php-pool] [--no-start]
wor service remove <domain>/<service> [--cascade] [--yes]
wor service start|stop|restart|reload <domain>/<service>
wor service status
wor service logs <domain>/<service> [--lines=100]
wor service chown <domain>/<service> [<user>]
service add
| Flag | Meaning |
|---|---|
--service-type= | static, node, go, python or php. (Renamed from --template=.) |
--host= | Hostname to bind. Optional. |
--port= | Port for node, go and python. When omitted, wor picks a free one starting at 3000 by trying to listen on it. |
--entry= | Entry point file or binary name, overriding the default (app.js, app, app.py, public/index.php). |
--php-version= | Pick the PHP-FPM version when several are installed. |
--no-php-pool | Use the host-wide PHP_FPM_ENDPOINT instead of a dedicated pool. |
--no-start | Do not start node/go/python after creation. Use it to set up env or secrets first. |
- Blocks immediately if the template's runtime is not installed. There is no "set it up now?" prompt;
wor doctorsays what is missing. - A
phpservice gets its own pool automatically when exactly one PHP-FPM version is detected. See Per-service pools. goservices are built (go build) at creation.- node, go and python start automatically. If that start fails, it only warns; the config, ecosystem file and unit already exist, so run
wor service startyourself.
Output (a static service; node, go and python also report their port and start the service):
$ wor service add com-example/myapp --service-type=static --host=myapp.example.com --no-start
[OK] Service ready: com-example/myapp (static)
service remove
Blocks if any host still references the service, unless --cascade (which also deletes those host configs). Deletes the service's whole directory, so run wor source backup first. --yes skips the confirmation. With --cascade it also deletes the hosts' SSL records and wor's copies of their certificates; for a Let's Encrypt host it then prints sudo certbot delete --cert-name <host> (see SSL: removing a host).
start / stop / restart / logs
Route to the right provider (PM2, systemd, or nothing). They fail immediately if the domain or service does not exist; they no longer fall back to a no-op static service. start and restart then wait for the service to answer, the same way a deploy does (the readiness gate), and fail if it does not. They never revert anything. logs reads through pm2 logs or journalctl, can follow indefinitely, and therefore takes no lock.
service reload
For a php service with its own pool only. Re-renders the pool from .wor/php.ini and .wor/php-fpm.ini, validates it with php-fpm -t, reloads php-fpm, and prints the settings now in force. Configuration only: restarting a process is service restart, re-rendering a vhost is host reload. Unlike deploy it never skips an unchanged pool, because someone who typed it means it. It is also the only way to apply those files when the source is not a git repository. A service with no pool gets an error naming the command that does apply, not a silent no-op.
service status
Every service from every domain (disabled ones too), grouped by real provider: PM2 (node), SYSTEMD (go/python), PHP-FPM (php), STATIC (no process). One pm2 jlist and one batched systemctl sample serve the whole group. Columns: status, pid, uptime, CPU, memory.
wor health.Output:
$ wor service status
STATIC (no process)
[on] com-example/myapp n/a served by web server
[on] default/web n/a served by web server
(process status only -- for end-to-end health: wor health)
service chown <domain>/<service> [<user>]
Hands the service's files to the operator account, or to <user>. Needs elevation. It changes the owner only, never the group, and re-grants the php-fpm pool afterwards from the group recorded for that pool (so a src/.env at 0640 keeps the group the pool user was granted against). It repairs; it does not record. Nothing is written to services.config.json, and there is deliberately no per-service owner: a service owned by someone else would be swept back by the next wor setup. Use it for a tree left behind by a root-run command, a CI rsync, or an admin who is not the operator.
Run
wor run
Brings the machine to the desired state: every enabled service, plus the runtimes and web server it needs, running. Named run rather than start or up because it is one-way, like terraform apply; there is no wor down.
- Once, before the loop. Start the active web server if it is not running. Start the PM2 daemon if any service needs it. If
pm2 startupwas never registered (nothing in wor ever did, so PM2 services never came back after a reboot), offer to register it. wor runspm2 startupto obtain the suggested command, always shows you the full command first, then runs it through the same confirm-once sudo gate. - For each enabled service. Start the runtime it needs (php-fpm for a pooled php service), then the service itself if it is not running.
A failed service is skipped; the command carries on and ends with a one-line count of successes and failures.
Host
wor host add <host> [--target=<domain>/<service>] [--server=nginx|apache] [--replace]
[--domain-type=local|public] [--add-hosts|--no-hosts]
wor host remove <host> [--yes]
wor host list
wor host test
wor host reload
wor host logs <host> [access|error] [--lines=100]
host addgenerates the vhost from the embedded template for the service's type, enables it, validates and reloads.--domain-type=local|publicand--add-hosts/--no-hostsanswer its questions without prompting. Without a terminal,--domain-typeis required: wor does not guess it from the name (a.testname is only a suggestion, and the answer decides whether wor edits/etc/hosts).host removedeletes the vhost, the entry inservices.config.json, the/etc/hostsentry and the recorded SSL state inssl/hosts/<host>/, in one command.host listis one table: ✓ enabled / ✗ disabled (comparing sites-available with sites-enabled; enabled rows first), the target, the port, and a plainsslor-. Whole rows are not coloured green because the list reports configuration, not health: a certificate existing does not mean it works.wor diagnose <host>is the real check.host testandhost reloadrun the web server's own config test or reload by hand.host logsshows the access or error log of one host with a hand-written tail-and-follow loop (notailbinary involved). Takes no lock.
Output of host add and host list:
$ wor host add myapp.example.com --target=com-example/myapp --domain-type=public --no-hosts
[INFO] Public domain selected. Make sure DNS points to this server.
[OK] Host ready: myapp.example.com -> com-example/myapp
Domain Type: public
DNS Note : Make sure DNS points to this server.
$ wor host list
WOR Hosts nginx (nginx/1.24.0)
[on] api.example.com -> com-example/api :3100 -
[on] myapp.example.com -> com-example/myapp n/a ssl
host add, create and every wor ssl write follow one sequence: snapshot the current files, write, make sure the host is enabled, run the server's config test, and reload only if it passes. A configuration the server rejects is rolled back and never reloaded. This matters because nginx -t and apachectl configtest validate the whole machine: one bad vhost fails the test for every site, and reloading anyway would take them all down. The worst case is now "this one host did not change".Database
wor database add <domain>/<profile> [--label="Label"]
wor database remove <domain>/<profile>
wor database backup <domain>/<profile>[/database]
Backup only. There is no restore, drop or migrate, deliberately and as in v1. Engines: mysql, mariadb, postgresql, sqlserver, sqlite. A profile is a KEY=value file at $WOR_HOME/configs/database/<profile>.env (engine, host, port, name, user, password, charset, plus engine-specific keys such as SQLite path, PostgreSQL sslmode, SQL Server encrypt). Dumps are compressed with Go's own gzip and written to backups/<domain>/database/<profile>/<yyyymmdd>/.
adderrors if the domain does not exist (it no longer creates it). A duplicate profile only warns and leaves the existing label and.envuntouched.removeerrors if the domain does not exist or the profile is not registered, and deletes both the config entry and the profile's.env(it used to forget the file).
Output of database backup (a SQLite profile):
$ wor database backup com-example/main
[INFO] Backing up sqlite database: shop
[OK] ~/wor/backups/com-example/database/main/20260101/shop_120000.sqlite.gz
Source
wor source clone <domain>[/<service>] <git-url> [--branch=<name>] [--depth=<n>]
[--ssh-key=<file>] [--ca-cert=<file>] [--env=...] [--wor=...] [--yes]
wor source pull <domain>[/<service>] [--stash]
wor source status <domain>[/<service>] [--fetch]
wor source backup <domain>[/<service>] [--gitignore=enable|disable]
wor works with any git remote. It does not care whether the server is a hosted service or one you run yourself: a hosted service, a self-hosted Gitea or Forgejo, GitLab on your own network, a bare repository on another machine, or a directory on the same disk are all just an address and a way to prove who you are.
source clone
| Address | Example |
|---|---|
| https | https://git.example.com/org/myapp.git |
| ssh | ssh://[email protected]:2222/org/myapp.git or [email protected]:org/myapp.git |
| git, file, local path | git://git.example.com/org/myapp.git, file:///srv/git/myapp.git, /srv/git/myapp.git |
Anything else is refused, including addresses that start with - and git's helper::address forms, because those make git run something other than a clone.
| Flag | Meaning |
|---|---|
--branch=<name> | Clone this branch or tag instead of the remote's default. |
--depth=<n> | Shallow clone of the last n commits. Smaller and faster; older commits are not available locally, so rollback --to cannot reach them. (Git ignores it for a plain local path; use file://.) |
--ssh-key=<file> | The private key of an SSH deploy key. It is the only identity offered, and it is recorded in the clone, so source pull, deploy and plain git in that folder keep using it. The file must not be readable by other accounts (chmod 600). ssh addresses only. |
--ca-cert=<file> | A CA certificate for a server whose TLS certificate is signed by a private CA, which is common for a self-hosted server. Recorded in the clone the same way. https addresses only. wor has no switch to turn certificate verification off, deliberately. |
--env=keep-both|overwrite|replace--wor=keep|delete | The answers to the two questions below. replace and delete also need --yes. |
Proving who you are
For a private repository, use one of these. None of them needs a password typed into wor.
- An SSH deploy key (recommended for servers): add the public key to the repository on the git server, then pass
--ssh-key=. - A git credential helper already configured for the account that runs wor, with an https address.
- A token in the address (
https://[email protected]/org/myapp.git) works, but git stores it in plain text in the clone's.git/config. wor warns when you do this, hides it in everything it prints, andsource statuskeeps warning while it is there.
When git fails, wor adds advice based on what git said (a refused key, an untrusted certificate, a name that does not resolve, a branch that does not exist), the same whichever server answered. Under --non-interactive git is told never to ask for a username, password or passphrase, and ssh runs in batch mode, so a missing credential is an error instead of a hang:
$ wor source clone com-example/myapp https://git.example.invalid/o/r.git
[INFO] Cloning https://git.example.invalid/o/r.git
fatal: unable to access 'https://git.example.invalid/o/r.git/': Could not resolve host: git.example.invalid
[INFO] The server's name does not resolve from this machine. Check the address and this machine's DNS.
ERROR: git clone failed: exit status 128
When the target already has source
It is always backed up with source backup and replaced; no --replace flag (an old script that still passes it is ignored, not rejected). The old tree is moved aside first and only discarded after the new tree is in place; if the move fails the old tree is moved back.
Replacing the tree would also take .env and .wor with it, and the backup zip may not contain them because it filters by .gitignore. So it asks, or you answer with the flags:
| File | Choices |
|---|---|
.env | --env=keep-both (default when asked: the old one stays in use, the repo's copy becomes .env.new), --env=overwrite (old stays, repo copy discarded), or --env=replace (use the repo's, discard the old; needs --yes). |
.wor | --wor=keep (default when asked: the current one carries into the new tree, the repo's becomes .wor.new) or --wor=delete (take the repo's copy, or none; needs --yes). wor cannot know which of two hand-written configs is wanted, so it never picks silently. |
Without a terminal both flags are required when the target has that file, and wor says so before it touches the network. Afterwards, for a registered service it asks whether to deploy now (deploy --no-pull --force), since a fresh clone has no node_modules, build output or Go binary; without a terminal that question is skipped and the clone still succeeds.
Output:
$ wor source clone com-example/myapp https://git.example.com/org/myapp.git --env=keep-both --wor=keep
[INFO] Cloning https://git.example.com/org/myapp.git
[INFO] .wor in ~/wor/domains/com-example/myapp kept (--wor=keep).
[OK] Cloned: com-example/myapp
[INFO] A fresh clone has no installed dependencies or build output (node_modules, go binary, ...).
Deploy com-example/myapp now (install deps + build + restart)? [y/N]:
(no answer -- skipped)
[INFO] Skipped. Run `wor deploy com-example/myapp --no-pull --force` before starting the service.
source pull
Fast-forward only. wor never makes a merge commit on a server: when the tree has commits the remote does not (or the remote's history was rewritten), the pull fails, says so, and points at wor rollback to discard the local commits. --stash sets uncommitted changes aside for the pull and restores them afterwards; a failed pull leaves the stash in place rather than layering a conflict on a conflict.
source status
Read-only. Where the tree came from and where it stands: the remote (credentials hidden), branch, last commit, how far ahead or behind its remote, uncommitted changes, stashes, and whether the clone is shallow or uses a recorded SSH key or CA certificate. It makes no network call unless you pass --fetch, so without it "behind" means behind as of the last fetch. It takes no workspace lock.
$ wor source status com-example/myapp --fetch
WOR Source
----------
Target : com-example/myapp
Path : ~/wor/domains/com-example/myapp
Remote : origin https://git.example.com/org/myapp.git
Branch : main
Commit : a1b2c3d Fix cache headers (2 days ago)
Sync : up to date with origin/main
Changes : clean
Stashes : 0
source backup
Writes a .zip to backups/<domain>/source/ using archive/zip (no zip program needed). By default files are also filtered through the .gitignore at the root of that tree, in addition to the exclude list in backup.config.json. --gitignore=enable|disable overrides for one run. The matcher supports comments, blank lines, ! negation, leading or middle / anchoring, trailing / for directories, and * ? [...] **, last match winning as in git. Nested .gitignore files are not read.
Output of source backup:
$ wor source backup com-example/myapp
[OK] ~/wor/backups/com-example/source/com-example_myapp_20260101_120000.zip
Deploy and rollback
wor deploy <host|domain/service> [--pull-only] [--no-pull] [--no-restart] [--force] [--stash] [--no-revert] [--no-hooks]
wor rollback <domain>/<service> [--to=<commit|tag>] [--yes]
deploy
.wor settingsgit pull (fast-forward only)- Dependencies:
npm ci(ornpm installwithout a lockfile) andpip install -r requirements.txtrun whenpackage.jsonorrequirements.txtchanged. - Build: node runs
npm run buildif the script exists; go builds every time a pull brought new commits (editing a.gofile with no dependency change still needs a rebuild, so there is no node-style heuristic). - Restart via the service's provider, then wait until the service really answers (next paragraph). A node service can be reloaded instead of restarted, one worker at a time, so requests are not refused: see PM2 cluster mode and reload.
- PHP pool: for a pooled php service,
.wor/php.iniand.wor/php-fpm.iniare validated right after the pull, before anything is installed, built or restarted (a typo stops the deploy there; it is the file in the new tree that counts, so the commit that fixes a broken one can deploy), and the pool is re-rendered after the build. Either failure fails the deploy. If the rendered pool is byte-for-byte what is already on disk, the write, the config test and the reload are all skipped, because reloading the shared master cycles the workers of every other service under it. --forceskips every "did the manifest change?" check and always installs, builds and restarts. It is howrollbackandsource clonecall deploy (--no-pull --force), because there the commit has not moved yet the dependencies are exactly what is stale.--pull-only,--no-pull,--no-restartand--stashdo what they say. Deploy requires a git repository.
The readiness gate
A process manager saying "started" does not mean the service serves. After the restart, a service that has a port is not reported deployed until it accepts connections, optionally answers a URL you name, and then stays up for a few seconds (which catches the commonest failure: an app that opens its port and crashes a moment later). If it does not, the deploy fails with exit code 1, the last lines of the service's log, and a pointer to wor diagnose. It waits up to 30 seconds by default.
Tune it, or turn it off, per service in .wor/deploy.ini; see Deploy settings. wor service start and wor service restart wait the same way, and fail the same way. A deploy.ini that does not parse stops a deploy after the pull but before anything is installed, built or restarted (it is the file in the new tree that counts, so the commit that fixes a broken one can deploy), but is ignored with a warning by start and restart, so a typo can never block an emergency restart.
Static and php services have no process of their own, so they are only checked when ready.path is set, through the web server.
$ wor deploy api.example.com
...
[INFO] Waiting for com-example/api to accept connections on port 3000 (up to 30s)...
[OK] Ready: com-example/api (3.8s)
[OK] Deploy completed: com-example/api
When the app never starts listening:
[INFO] Waiting for com-example/api to accept connections on port 3000 (up to 30s)...
Last lines of the service's log:
fatal: cannot find config
[INFO] Investigate with: wor diagnose com-example/api
[INFO] To change how long wor waits, or to turn the check off: .wor/deploy.ini (see .wor/deploy.ini.example)
ERROR: com-example/api did not become ready within 30s: nothing is accepting connections on port 3000 (connection refused)
When it opens the port and then dies:
ERROR: com-example/api answered but did not stay up: the supervisor restarted it 1 time(s) since the deploy
When it never opens the port because it keeps crashing, the supervisor's restart count gives it away, and wor stops at once instead of waiting out the timeout:
ERROR: com-example/api is crash-looping: the supervisor has restarted it 2 time(s) since the deploy and it is still not ready (nothing is accepting connections on port 3000 (connection refused))
Deploy hooks
Two optional executable files in the service's own tree carry the application's own steps, so they do not have to be built into wor:
| File | Runs | If it fails |
|---|---|---|
.wor/hooks/pre-restart | after dependencies and build, before the restart. The place for a database migration. | The deploy stops. The running version is untouched and keeps serving. |
.wor/hooks/post-deploy | after the service answered its readiness check. Cache warming, a notification. | A warning only. The deploy had already succeeded. |
- They are part of your repository, so a hook always belongs to the commit that needs it: wor reads them from the tree as it is after the pull. Commit them with
chmod +x. - Run as the account that runs wor, never elevated. wor adds no
sudo. The working directory is the service folder and stdin is closed, so a hook that asks a question gets end of input instead of hanging the deploy. - A curated environment, not yours:
PATH,HOME,USER,LANG,TZ,TMPDIRandPM2_HOMEfrom the account running wor; the service's ownenvfromservices.config.json; and these facts:WOR_HOOK,WOR_DOMAIN,WOR_SERVICE,WOR_SERVICE_DIR,WOR_SERVICE_TYPE,WOR_PORT(when it has one),WOR_COMMIT(the commit now checked out, in full) andWOR_PREVIOUS_COMMIT. Nothing else from the deploying account's environment reaches a hook (anAWS_*key, an agent socket). A service's ownenvcannot override theWOR_*facts. - A time limit:
hooks.timeoutin.wor/deploy.ini, 300 seconds by default. When it runs out the whole process group is stopped (first politely, then withSIGKILL), so a hook that started other programs does not leave them behind. - A hook that is present but cannot run is an error, never a skipped step (not executable, writable by every account, a link pointing outside the service folder). It stops the deploy after the pull, before anything is installed, built or restarted. A migration that quietly did not run is the failure this exists to prevent.
- Once a
pre-restarthook has run, a failed readiness check is not reverted automatically (see below): the migration may already have changed the database, and the previous code may not work with it. wor deploy --no-hooksskips both hooks, for an emergency. With--no-restartthey are skipped too, since they belong to the restart.wor infolists the hooks a service has.
If pre-restart fails, the files on disk are already at the new commit, which the running process has not loaded. wor says so and gives the command to put the previous code back:
[INFO] Running the pre-restart hook (.wor/hooks/pre-restart)...
migration 7 failed: column already exists
[INFO] The deploy stopped before the restart: com-example/api is still running what it was running before.
[WARN] The files on disk are at a1b2c3d, though, which the running process has not loaded. To put the previous code back: wor rollback com-example/api --to=9f8e7d6
ERROR: pre-restart hook failed: exit status 1
[INFO] Running the post-deploy hook (.wor/hooks/post-deploy)...
cache server unreachable
[WARN] post-deploy hook failed: exit status 2. The deploy itself succeeded; com-example/api is running the new version.
[OK] Deploy completed: com-example/api
Automatic revert
If the service fails that check after a deploy that moved the code, wor puts the previous commit back and applies it: it resets the tree to the commit that was running before the deploy, reinstalls dependencies and rebuilds for it, restarts, and waits again. The deploy is still reported as failed (exit code 1), because the deploy you asked for did not happen, even though the service is running the previous version again. The next wor deploy will pull the same failing commit again unless it has been fixed on the remote.
It only does this when going back is safe, and says why when it is not:
- No pre-restart hook ran in this deploy (it may have migrated a database).
- The tree had no uncommitted changes to tracked files. Resetting would destroy them. (Untracked files, such as
.woror build output, are never touched.) --stashwas not used, since going back would discard the changes that were stashed and restored.- The code actually moved: not for
--no-pull, nor--forceon an unchanged commit. --no-revertwas not given, andrevertis notnoin.wor/deploy.ini.
It acts only on a failed readiness check. A build or install that fails stops the deploy before the restart, so the old process is still running, and that error is reported as it is. When it does not revert, the output gives the way back by hand, wor rollback <target> --to=<commit>. If reinstating the previous version fails its own check, the output says plainly that the service is probably down and points at wor diagnose.
[WARN] com-example/api did not become ready after deploying a1b2c3d "v2 crashes after listening".
[INFO] Reverting to 9f8e7d6 "v1 good", the commit that was running before this deploy...
HEAD is now at 9f8e7d6 v1 good
[INFO] Waiting for com-example/api to accept connections on port 3000 (up to 30s)...
[OK] Ready: com-example/api (3.7s)
[WARN] Reverted: com-example/api is running 9f8e7d6 again.
[INFO] The next `wor deploy` will pull a1b2c3d again unless it is fixed on the remote.
ERROR: deploy of a1b2c3d failed and was reverted to 9f8e7d6: com-example/api answered but did not stay up: the supervisor restarted it 1 time(s) since the deploy
And when it must not:
[WARN] Not reverting: the tree had uncommitted changes to tracked files, which `git reset --hard` would destroy.
[INFO] To go back by hand: wor rollback com-example/api --to=9f8e7d6
Output of deploy for a static service:
$ wor deploy myapp.example.com
Already up to date.
[INFO] static service deployed. Reloading host provider.
[OK] Deploy completed: com-example/myapp
rollback
Backs up with source backup, then hard-resets the source and discards all uncommitted local changes. Accepts only domain/service, never a bare domain. Offers a deploy afterwards (skipped when non-interactive).
- It never deletes
.woror.env. Rollback resets tracked files and removes other untracked files, but those two (your web-server snippets, PHP and deploy settings, and secrets) are untracked in almost every service and are kept. Earlier versions removed them unless they were gitignored. - Without
--toit resets to the branch's own upstream: whichever remote the branch tracks, whatever that remote is called (origin/mainin the common case). --to=<commit|tag>resets to that commit or tag instead, which is how you go back to a known-good version. The name is fetched and checked first: one that does not exist stops the command with the tree untouched, and a name that could be read as an option is refused. A shallow clone may not have the commit; deepen it withgit fetch --unshallowin the service folder.- After
--tothe tree is behind its branch, so a laterdeployorsource pullmoves it forward again. To deploy exactly the commit you rolled back to, usewor deploy <target> --no-pull.
SSL
wor ssl issue <host> [--provider=letsencrypt|self-signed|custom|none]
[--preferred=<host>] [--redirect|--no-redirect]
wor ssl redirect <host> on|off
wor ssl sync <host> [--skip-if-busy]
wor ssl hook <host>
wor ssl renew <host>
wor ssl status <host> [--json]
wor ssl remove <host> [--yes]
wor ssl install <host> --cert=/path/fullchain.pem --key=/path/privkey.pem
The behaviour behind these, including why wor keeps its own certificate copy, is on the SSL & certificates page. In short:
issueobtains a certificate, copies it intossl/hosts/<host>/, asks about the HTTP to HTTPS redirect, and rewrites the vhost through the validated pipeline.--preferrednames the canonical host for alias redirects (it applies to that run only; it is not remembered).redirect on|offchanges the redirect later without reissuing.syncrefreshes wor's copy from certbot's store and reloads; idempotent. It is the one command allowed undersudo.--skip-if-busyis for the hook wor registers; typed by hand it is pointless.renewrunscertbot renewand lets the hook write. It is the one ssl action that takes no lock.statusshows provider, files, expiry, redirect setting (marking one inherited from the old behaviour) and the last sync result.removeclears the state first, regenerates and reloads the SSL-free vhost, and only then deletes the certificate files.installtakes your own certificate and key.
Output of ssl issue, ssl redirect and ssl status:
$ wor ssl issue myapp.example.com --provider=self-signed --no-redirect
[OK] Self-signed SSL installed: myapp.example.com
[INFO] HTTP -> HTTPS redirect: off (change it with `wor ssl redirect myapp.example.com on|off`)
$ wor ssl redirect myapp.example.com on
[OK] HTTPS redirect for myapp.example.com is now on.
$ wor ssl status myapp.example.com
SSL Enabled : true
Current Provider : self-signed
Certificate File : ~/wor/ssl/hosts/myapp.example.com/fullchain.pem
Private Key File : ~/wor/ssl/hosts/myapp.example.com/privkey.pem
Certificate Expiration: Jan 1 00:00:00 2029 GMT
Auto Renew Status : unsupported
HTTP -> HTTPS Redirect: on
Inspect
wor info <host|domain/service>
One summary: type, enabled, source path, bound hosts with per-host SSL status, real process status through that service's provider (pm2 describe, systemctl status, or pool socket, version and group), whether the web server user can reach WOR_HOME and the docroot (Debian family, static and php only), host and service CPU and memory, and git status if the source is a repository. For a pooled php service it lists the settings .wor/php.ini asks for and marks them NOT APPLIED when the running pool differs.
Output:
$ wor info myapp.example.com
WOR Info
--------
Target : myapp.example.com
Domain : com-example
Service : myapp
Type : static
Enabled : true
Source : ~/wor/domains/com-example/myapp
Hosts :
- myapp.example.com [ssl: none]
Process:
static -- served directly by the web server, no process
Reachability:
not checked (only auto-detected on Debian/Ubuntu)
wor health --json
Fleet-wide: are my services actually serving? Read-only, exit 1 when a problem is found. Full description on Operations.
wor diagnose <host|domain/service>
Read-only root-cause analysis for one broken target, ending in a single root cause, evidence and copy-pasteable fix commands. Exit 1 when a problem is found. Full description on Operations.
Output of health and diagnose is shown on Operations.
Navigate
wor path [.|./<path>|<domain>[/<service>]]
wor shell-init
wor goto [same target] # shell function installed by shell-init
pathprints the bare absolute path on one line, socd "$(wor path myapp/backend)"works. Errors go to stderr with exit 1..isWOR_HOME;./<path>is any subtree of it (./logs,./backups/myapp), checked withfilepath.Cleanand rejected if it escapes. A domain or service only has to exist on disk; it need not be registered.- With no argument,
pathandgotoshow a numbered menu (WOR_HOMEfirst, then every domain and domain/service) on stderr, read the number from stdin, and print only the choice on stdout. Enter on an empty line cancels with exit 1, never 0, or the shell would runcd "". shell-initprints the function. It is exempt from the initialised-workspace gate: if it printed an error, that error would beeval'd as a command in every new terminal.
Output:
$ wor path com-example/myapp
~/wor/domains/com-example/myapp
Global flags
--json
Accepted by exactly four read-only reports: version, doctor, health, ssl status. Prints one JSON document on stdout instead of the text. Anywhere else it is a usage error that names the four. The full contract is on Operations.
--non-interactive
Accepted by every command, anywhere on the line (or WOR_NONINTERACTIVE=1). Any question ends the command with an error naming it, and sudo runs as sudo -n. Details on Operations.