Buy

CLI (wd)

Free & Premium

wd is WebDonkey's command line. You start services, create sites, back up databases, read logs, run scheduled tasks and workflows and work with your servers, straight from any terminal. Almost every page of the app has its commands in wd.

wd manages nothing itself. It talks to the running app over a local socket and calls the same functions as the window. Whatever you change with wd shows in the app at once, and the other way round. Free and Premium limits apply exactly as in the window.

What you do here

How wd gets onto your Mac

There is nothing to install. The app brings wd along and puts it into ~/Library/Application Support/WebDonkey/shims/ on every start, the same folder through which php and node reach your shell. After an app update, the new version is there automatically. For the folder to be on your PATH, Tools in the terminal has to be on (Settings › Sites & services).

  1. Open the page Tools › Terminal.
  2. Read the state in the WebDonkey CLI card.
  3. Open a new terminal window and type wd --help.

The WebDonkey CLI card

The card sits at the top of the Shell & SSH tab and asks a fresh shell whether it finds wd.

Display or button Meaning
Found on your PATH all set, next to it the path under which your shell finds wd
Not on your PATH with the reason: Tools in the terminal is off, or your shell has not loaded the folder yet, or this build does not include the CLI
Turn on “Tools in the terminal” appears when the setting is off and switches it on
Check again repeats the test, for example after opening a new terminal window
Command reference opens these docs at the CLI chapter
Briefing for AI agents opens the Briefing for AI agents
Copy icon copies wd --help to the clipboard

Below it stand four examples: wd --help, wd, wd services start mysql and wd open toolbox.

Good to know

  • You may abbreviate names. wd start my finds mysql, wd sites open shop your shop site. If several match, wd asks with a picker in the terminal. If you leave the name out, the picker opens straight away.
  • If the app is closed, wd asks whether to start it. With -y it starts it without asking, with --no-launch never. wd open always starts the app, because that is what the command is for.
  • Confirmations: commands that delete or overwrite something ask first. In scripts without a terminal they need -y, otherwise they stop with exit code 2 instead of silently saying yes.
  • Language: if the app runs in German, wd answers in German, otherwise in English. The environment variable WD_LANG=en or WD_LANG=de sets the language yourself. Commands and options are the same in every language, the help texts (--help) are English.
  • For scripts every command has --json, errors included. The exit code tells success, failure, wrong usage, unreachable app and Premium apart. See Options and exit codes.
  • wd only reaches the WebDonkey of the same user on the same Mac. It opens no network port.

Free and Premium

wd itself is free. Every command has the same limits as the page it belongs to:

Area Free Premium
Services, sites, databases, logs, certificates, mail, proxy, app yes, with the app's limits (for example 6 running services, 3 sites with HTTPS) no limits
Scheduled tasks 3 tasks any number
Project backups, Remote, notes, own logs no yes
Monitor, subscriptions, workflows with the pages' Free limits no limits
SEO with the SEO package with the SEO package

When a command hits a limit, it ends with exit code 4 and names the limit. Prices are at webdonkey.io/pricing.

Core commands Free & Premium

The core commands of wd cover everyday work: the overview, services, sites, the front proxy, busy ports, the app itself and the WebDonkey Editor. Wherever a <name> appears, you may abbreviate. Leave it out and a picker opens in the terminal. wd <command> --help shows the help for every command.

Where to find it

In the terminal: wd --help lists every command. In the app, Command reference on the WebDonkey CLI card of the page Tools › Terminal opens these docs.

How to do it

Get a PHP project going:

  1. wd status shows what is running.
  2. wd sites create shop.test --path ~/Sites/shop --php 8.3 creates the site and starts what it needs.
  3. wd sites open shop opens it in the browser.
  4. If something does not load, wd doctor shows the cause together with the command that fixes it.

Overview and diagnosis

Command Meaning
wd overview: Free or Premium, version, front proxy, running services and sites. Same as wd status
wd status the same overview, machine-readable with --json
wd doctor checks PATH, app, versions, crashed services, every site (PHP and web server running?) and the front proxy. Every problem comes with the command that fixes it. Exit code 1 when a check fails
wd open <page> brings the app to the front on a page, for example wd open toolbox or wd open "toolbox?tool=json". Without a page: picker
wd completions <shell> prints tab completion for zsh, bash, fish, elvish or powershell. For zsh: source <(wd completions zsh) in ~/.zshrc

wd open knows these pages: dashboard, sites, certificates, services, configuration, databases, remote-databases, mail, remote-mail, logs, custom-logs, remote-logs, docs, legal, remote, notes, backups, remote-backups, cron, remote-cron, monitor, subscriptions, api-client, workflows, toolbox, ai, claude, terminal, vms, changelog, premium, themes and settings. Plus the short forms home, config, configs, db, certs, ssl, tasks, scheduled-tasks, api, ki, help and manual. If the name is no page but a site, wd open opens the site in the browser and points you to wd sites open.

Services

Command Meaning
wd services installed services with version, status and uptime, running ones first. Short form wd ls, also wd service
wd services start <name…> start services, name@version for a specific installed version. Short form wd start
wd services stop <name…> stop services. Short form wd stop
wd services stop --all stop every running service
wd services restart <name…> restart services. Short form wd restart
wd services install <name[@version]…> install services: without a version the newest stable one, otherwise exactly that one. Can take minutes because of the download
wd services use <name@version> set the version a service starts with and new terminal windows use, for example php@8.3. Without a version: show the active and the installed versions

wd services start php starts the version that is active in the app. Running services keep their version after wd services use until you restart them.

Sites

Command Meaning
wd sites every site with domain, on or off, web server, PHP and path. Also wd site
wd sites info <site> everything about one site: URL, name, aliases, document root, project folder, web server, PHP, Node, own process, SSL, certificate, environment variables
wd sites start <site> switch a site on and start what it needs: PHP, web server, databases
wd sites stop <site> switch a site off. The domain is released, services other sites use keep running
wd sites open <site> open a site in the browser
wd sites create <domain> create a site for a folder and start it right away (options below)
wd sites delete <site> delete a site: configuration, certificate and logs. The project folder stays. Asks first
wd sites php <site> <version> pin the site to an installed PHP version, for example wd sites php shop 8.4
wd sites node <site> <version> the same for Node, for example wd sites node app 22
wd sites diagnose <site> the checks of the Sites page: folder, vhost, certificate, PHP, web server. Exit code 1 when one fails
wd sites packages [package] the site packages (Shopware, WordPress and more) with what they need. With a package name: its settings with default and allowed values

Options of wd sites create

Option Meaning Default
--path <folder> project folder that is served. ~/ is allowed the current folder
--name <name> display name in the app the domain
--webserver <kind> nginx, caddy or apache nginx
--php <version> PHP version, for example 8.3 none, so a static site
--no-ssl HTTP instead of HTTPS HTTPS
--package <package> install a site package into the folder (Premium) none
--set KEY=VALUE a setting of the package, repeatable the package's default
--overwrite the package may replace files that are already in the folder off

If the new site does not start, it stays created but switched off. wd names the reason and the command wd sites start <domain> for the next attempt.

With --package, wd works like the form on the Sites page: it first checks that everything the package needs is there, then creates the site, installs the package and shows every step. If the install fails, the site stays, and you start the install again in the app.

Proxy, ports and app

Command Meaning
wd proxy is the front proxy running on ports 80 and 443? Same as wd proxy status
wd proxy start, wd proxy stop start or stop the front proxy. Without it your sites do not answer on their domains
wd free-port <port> stop the process that holds a port, for example wd free-port 3306. Asks first
wd app is the app running? Works while it is closed too. Same as wd app status
wd app start start the app and wait until it answers
wd app stop quit the app. It stops its services first

WebDonkey Editor

Command Meaning
wd edit [path…] open files or folders in the WebDonkey Editor. path:line or path:line:column jumps there. Without a path: the current folder. Starts the editor when it is not running
wd edit -w <file> waits until you close the file in the editor again. Meant for $EDITOR, git commit or Ctrl+G in Claude Code. Long form: --wait
wd edit --diff <a> <b> compare two files side by side
wd edit --terminal [folder] open a terminal in the editor, in the given or the current folder

Removing WebDonkey

Command Meaning
wd uninstall removes what WebDonkey set up outside its data folder: sudoers rules, helper programs, scheduling daemons, DNS files, hosts entries, the trust in the local CA, the PATH block, the Claude statusline, shell aliases, SSH hosts and the prompt. Shows the list and asks first, macOS asks once for the administrator password, then the app quits
wd uninstall --delete-data also deletes WebDonkey's data (sites, databases, settings) once the app has quit

wd uninstall never touches project folders. Use it only when you really want to remove WebDonkey, not as a repair.

Examples

wd services start mysql redis
wd start php@8.3
wd services use php@8.4
wd sites create shop.test --php 8.3
wd sites create blog.test --path ~/Sites/blog --package wordpress --set site_title=Blog
wd sites diagnose shop
wd edit src/Checkout.php:42
wd status --json

Free and Premium

  • On the Free plan, at most 6 services run at once. Further starts end with exit code 4 and the hint wd services stop <name>.
  • On the Free plan, at most 3 sites have HTTPS. wd sites create then ends with exit code 4 and the hint --no-ssl.
  • wd sites create --package needs Premium, wd sites packages lists the packages without it too.

Troubleshooting

What you see Why What you do
Message with PORT_IN_USE:<port> and the hint wd free-port <port> Another program holds the port, often a second MySQL or web server Check what it is, then wd free-port <port>
Port … is held by a system process The process belongs to another user or to macOS itself Quit that program yourself, WebDonkey cannot
Site does not load It is off, or PHP or the web server is not running wd sites (is it on?), then wd sites diagnose <site>
Message that the version is not installed, with wd services install php@… wd sites php only takes installed versions Run the command named, then try again
Ambiguous name in a script Without a terminal wd cannot ask Write the name more specifically, the message lists the candidates

See also

Databases Free

With wd db you work with WebDonkey's local database servers: MySQL, MariaDB, PostgreSQL and MongoDB. You list servers and databases, open the client, create and rename databases, back them up, restore dumps and manage users and their rights. These are the same actions as on the Databases page.

Where to find it

In the terminal: wd db --help and wd db users --help. wd databases is another spelling of wd db.

How to do it

Create a database for a new project, set up a user for it and restore a dump:

  1. wd db shows which servers are running. If none is, start one with wd services start mysql.
  2. wd db create mysql shop creates the database shop.
  3. printf '%s' "$PW" | wd db users add mysql shop_user --database shop --password-stdin creates the user shop_user and gives it all rights on shop.
  4. wd db restore mysql shop ~/Downloads/shop.sql.gz restores the dump. The current content of shop is backed up first, wd asks before it starts.

Commands

Command Meaning
wd db database servers with version, port and status, their databases below. Databases only show while their server runs. Same as wd db list
wd db shell [server] [database] opens the server's client (mysql, psql, mongosh), already logged in as root. If only one server runs, you may leave it out. Flags for the client go after --, for example wd db shell mysql shop -- -e "SHOW TABLES"
wd db create <server> <name> new database on a running server
wd db drop <server> <name> delete a database with all its data. Asks first, the name has to be exact
wd db rename <server> <name> <new-name> rename a database
wd db backup <server> <database> back up a database into a file. Format, file name and folder as last chosen in the app's backup dialog
wd db restore <server> <database> <file> restore a backup into a database. The current content is backed up first, then replaced. Asks first

<server> is mysql, mariadb, postgres or mongodb and may be abbreviated. The server has to be running. Backup and restore work for MySQL, MariaDB and PostgreSQL.

Options of wd db backup

Option Meaning
--format <format> sql (SQL, gzip-compressed), sql_plain (SQL without compression), pg_custom (PostgreSQL archive) or csv
--folder <folder> folder for the file. Without it: the one last chosen, otherwise the app's backup folder

What you pass with --format and --folder is remembered by the app like a choice in the dialog.

Options of wd db restore

Option Meaning
--accept-version-jump also restore a dump from another major version of the server
--rewrite-definers rewrite DEFINER clauses in views, routines and triggers to the local user

The file may be SQL, gzip-compressed SQL or a PostgreSQL archive. If the restore needs one of these decisions, wd stops and names the matching option.

Users and rights

Command Meaning
wd db users [server] users of every running server (or of one) with hosts, rights per database and the sites that log in with them. Same as wd db users list
wd db users add <server> <user> --password-stdin create a user. Options: --database <db> gives it rights on it right away, --level sets them, --host (MySQL and MariaDB only) says where it may log in from: localhost (default), % for anywhere or a host
wd db users grant <server> <user> <database> give a user rights on a database. Replaces what it had there before. --level as above, default all
wd db users revoke <server> <user> <database> take the rights on a database away. Asks first
wd db users password <server> <user> --password-stdin set a new password
wd db users delete <server> <user> delete a user. Asks first, sites that log in with it stop working

--level has three steps: all (every right), readwrite (read and write) and readonly (read only).

Passwords only through stdin. wd never takes a password as an argument, so it lands neither in the shell history nor in the process list. Pass it in the first line of stdin with --password-stdin, for example printf '%s' "$PW" | wd db users password mysql shop_user --password-stdin.

You cannot change the server's own accounts (root, postgres and similar) with wd, the app logs in with them.

What happens in the background

  • wd db shell replaces itself with the server's client. That is why it does not work with --json.
  • The app runs wd db backup and wd db restore with the same checks as the dialogs of the Databases page. wd waits until they are done, even if that takes a while.
  • Before wd db restore, the app stores a backup of the current content in the backup folder.

Free and Premium

Every command on this page is free.

Troubleshooting

What you see Why What you do
No database server is running No server has been started wd services start mysql (or postgres, mariadb)
Message with remote_db_restore_version_jump and the hint --accept-version-jump The dump comes from another major version Check that this is wanted, then repeat with --accept-version-jump
Message with remote_db_restore_definer and the hint --rewrite-definers Views or routines run under an account that does not exist locally Repeat with --rewrite-definers
Message with db_system_account You tried to change one of the server's own accounts Create a user of your own and change that one
The password comes from stdin only The password is missing or came as an argument Pass it with --password-stdin and a pipe
db_not_listed The database does not exist on this server Check the name with wd db, it has to be exact

See also

Tasks, backups and logs Free & Premium

These commands belong to the app's Scheduled tasks, Backups, Logs, SSL certificates and Mail pages. With wd cron you create and run scheduled tasks, with wd backup you control project backups, with wd logs you read logs, with wd ssl you look after local certificates, and with wd mail you read the mail Mailpit has caught.

Where to find it

In the terminal: wd cron --help, wd backup --help, wd logs --help, wd ssl --help, wd mail --help. Other spellings: wd tasks for wd cron, wd backups for wd backup, wd certs and wd certificates for wd ssl, wd mails for wd mail.

How to do it

Create a nightly task and test it once right away:

  1. wd cron add cleanup --schedule "0 3 * * *" --command "php bin/console app:cleanup" --dir ~/Sites/shop
  2. wd cron run cleanup runs it now and shows its output.
  3. wd cron shows it with schedule, last and next run.

Scheduled tasks (wd cron)

Command Meaning
wd cron scheduled tasks with schedule, last and next run. Same as wd cron list
wd cron run <task> run a task now, wait and show its output. Exit code 1 when the command fails
wd cron enable <task> switch a task on, the schedule runs it again
wd cron disable <task> pause a task
wd cron add <name> --schedule <cron> --command <command> new task
wd cron edit <task> change a task, only what you pass changes. On or paused stays as it was
wd cron delete <task> delete a task. Asks first
Option Meaning Default
--schedule <cron> schedule as a cron expression with five fields (minute, hour, day, month, weekday), for example "*/15 * * * *" required for add
--command <command> shell command, runs through sh -c required for add
--dir <folder> folder the command runs in. Relative means: from the current folder. With edit, "" resets it to your home folder your home folder
--paused create the task paused (add only) off
--name <name> new name (edit only)

Project backups (wd backup)

Command Meaning
wd backup backup sets with schedule, last run and size. Same as wd backup list
wd backup run <set> run a backup set now. Can take minutes. Exit code 1 when it does not fully succeed
wd backup runs <set> the archives of a set with date, size and status
wd backup add <name> new backup set (options below)
wd backup edit <set> change a set, only what you pass changes
wd backup delete <set> delete a set. Asks first. The archives stay unless you pass --archives
Option Meaning Default
--path <path> folder or file to back up. Repeatable none
--exclude <pattern> what is left out in every path, a folder name like node_modules or a sub-path like var/cache. Repeatable none
--db [server:]database database dumped along, server mysql, mariadb or postgres. You may leave the server out when only one has the database. Repeatable none
--folder <folder> folder for the archives WebDonkey's backup folder
--default-folder archives into WebDonkey's backup folder again
--schedule <plan> off (by hand only), hourly, daily, weekly or custom off
--at HH:MM time for daily and weekly 02:00
--weekday <day> day for weekly: mon, tue, wed, thu, fri, sat or sun mon
--cron <expression> your own cron expression, sets the plan to custom
--keep <n> how many complete backups stay, 1 means only the newest 10

With edit, a list you pass (--path, --db, --exclude) replaces the old one. A single '' empties it. Without options a new set backs up nothing, runs only by hand and keeps 10 backups.

Logs (wd logs)

Command Meaning
wd logs every log WebDonkey knows, with its file. Same as wd logs list
wd logs tail <name> print the end of a log. Short form wd logs <name>
wd logs custom your own logs with their file
wd logs custom add <name> <file> add a log file under a name
wd logs custom tail <name> print the end of an own log
wd logs custom clear <name> empty an own log file. Asks first
wd logs custom remove <name> take an own log off the list. The file stays

-n <number> sets how many lines tail prints (default 100). -f keeps following the file until you stop with Ctrl+C. If the file is emptied or rotated meanwhile, wd reads on from the top.

Certificates (wd ssl)

Command Meaning
wd ssl whether the local CA is trusted, then every certificate with domain, days left and further names. Fewer than 14 days are marked yellow. Same as wd ssl list
wd ssl renew <site> issue a site's certificate again
wd ssl trust trust WebDonkey's local CA in the keychain. macOS asks for your password

Mail (wd mail)

Command Meaning
wd mail the newest mails Mailpit has caught, with number, sender, subject and age, below them the total and the unread count. Same as wd mail list
wd mail list -n <number> show that many mails (default 20)
wd mail show <number> one mail with from, to, subject, date and text. 1 is the newest. The mail's ID works instead of the number too

If a mail only has an HTML part, wd mail show points you to wd open mail. That is a quick way to check whether your site really sent a mail.

Free and Premium

Commands Free Premium
wd cron 3 tasks. Listing and running existing tasks is never limited any number
wd backup only wd backup delete, for sets from an earlier Premium time every command
wd logs, wd logs tail yes yes
wd logs custom the list only every command
wd ssl, wd mail yes yes

After a switch from Premium to Free, tasks above the limit are kept but locked. On a locked task you can only change the name. When a limit is reached, the command ends with exit code 4.

Troubleshooting

What you see Why What you do
wd cron run ends with exit code 1 The task's command failed Read the output above it, it comes from the command itself
wd backup run reports partial Part of it could not be backed up Check wd backup runs <set> and the message
Message with mailpit_not_running The Mailpit service is not running wd services start mailpit
Nothing to change edit was called without an option Pass at least one option
wd logs tail -f does not end That is the point, -f follows the file Ctrl+C, in scripts -n with a fixed number of lines

See also

Servers (Remote) Premium

With wd remote you work with the servers you saved on the SFTP / SSH page: open an SSH session, test the login, fetch and upload files over SFTP, back up and restore databases on the server, read logs, look into mailboxes and control the servers' cron jobs and backups. Everything runs through the same connections and with the same checks as in the app. wd remote needs Premium.

Where to find it

In the terminal: wd remote --help, for the areas wd remote sftp --help, wd remote db --help and so on. wd servers is another spelling of wd remote.

How to do it

Fetch a file from the server and run a command there:

  1. wd remote shows your saved connections.
  2. wd remote test prod logs in once and shows the start folder.
  3. wd remote sftp ls prod www lists the folder www in the start folder.
  4. wd remote sftp get prod www/.env ./env-prod fetches the file to your Mac.
  5. wd remote ssh prod -- uptime runs uptime on the server.

Connections

Command Meaning
wd remote saved connections with host, user and kind of login. Same as wd remote list
wd remote ssh <name> open an SSH session. Flags and commands for ssh go after --, for example wd remote ssh prod -- uptime
wd remote test <name> log in once and report the start folder. On first contact WebDonkey remembers the server's fingerprint
wd remote add <name> --host <host> --user <user> save a new connection (options below)
wd remote delete <name> delete a connection together with its stored secret. Asks first. Refused while active tasks, backups or sync pairs use it
Option of add Meaning Default
--host <host> host name or IP required
--user <user> login user required
--port <port> SSH port 22
--key <file> log in with this private key file
--agent log in through the SSH agent
--password-stdin read the password (or the key's passphrase) from the first line of stdin

Without --key and --agent the connection logs in with a password. Never pass a password as an argument, only through --password-stdin.

Files over SFTP (wd remote sftp)

Command Meaning
wd remote sftp ls <server> [path] list a folder on the server, with permissions, size and age. Without a path: the start folder. Relative paths start there
wd remote sftp get <server> <remote> [local] download a file or folder, a folder comes whole. Without a target: the same name in the current folder. If the target is an existing folder, it lands inside. Asks before overwriting something here
wd remote sftp put <server> <local> [remote] upload a file or folder. Without a target: the same name in the start folder. A target ending in / means "into this folder". Asks before overwriting something on the server

Databases on the server (wd remote db)

Command Meaning
wd remote db the entries of the Remote › Databases page with kind, server, address and default database
wd remote db databases <entry> the databases an entry reaches, with size and number of tables
wd remote db backup <entry> [database] back up a database into a file on your Mac. Format, file name and folder as last chosen in the dialog. Short form dump
wd remote db restore <entry> <database> <file> restore a file into a database on the server. The current content is backed up first, then replaced. Asks first. Short form import

backup knows --format (sql, sql_plain, pg_custom, csv, json) and --folder. Without a database, backup takes the entry's own, otherwise it asks. restore knows --accept-version-jump and --rewrite-definers, as with the local databases.

Logs on the server (wd remote logs)

Command Meaning
wd remote logs your remote logs with server, file, schedule and last read
wd remote logs tail <log> read the log over SSH now and print the end, -n lines (default 100). With -f, wd reads again every 5 seconds until you stop it

Mailboxes (wd remote mail)

Read only: wd sends and deletes nothing here.

Command Meaning
wd remote mail your mailboxes with protocol, login and server
wd remote mail folders <mailbox> the folders of a mailbox with their number of mails. With POP3 only the inbox
wd remote mail messages <mailbox> the newest mails of a folder with number, sender, subject and age. Options: --folder (default INBOX), -n (default 20), --search <text>
wd remote mail show <mailbox> <number> one mail with headers and text. 1 is the newest. With --id you pass the ID from the --json output instead of the number, --folder as above

Cron jobs on servers (wd remote cron)

Command Meaning
wd remote cron tasks on your servers with server, schedule and next run
wd remote cron run <task> run a task on its server now and show the end of its log. Exit code 1 when it fails
wd remote cron add <name> --server <connection> --schedule <cron> --command <command> new task. Instead of --command, --file <script> runs a script on the server
wd remote cron edit <task> change it, only what you pass: --name, --schedule, --command, --file, --run-by
wd remote cron delete <task> delete a task. A line in the server's crontab goes too. Asks first

--run-by sets who starts the task: webdonkey (your Mac over SSH, the default) or server (a line in the server's crontab). --paused creates it paused. If the same task name exists on several servers, write name (server).

Backups of servers (wd remote backup)

Command Meaning
wd remote backup your server backups with server, schedule and last run
wd remote backup run <backup> back up now. If the space check fails, it stops, --force backs up anyway
wd remote backup add <name> --server <connection> new server backup (options below)
wd remote backup edit <backup> change it, only what you pass. A list you pass replaces the old one
wd remote backup delete <backup> delete it. Asks first. The archives on your Mac stay unless you pass --archives
Option Meaning Default
--path <path> folder or file on the server, relative to the start folder. Repeatable
--db [entry:]database database to dump. You may leave the entry out when the server has only one. Repeatable
--exclude <pattern> what is left out, relative to every path, for example var/cache
--to <target> local (your Mac) or remote (a folder on the server, with --dest-path) local
--folder <folder> folder on your Mac for --to local WebDonkey's folder for this server
--schedule <plan> off, hourly, daily, weekly or custom off
--at HH:MM time for daily and weekly 03:00
--weekday <day> mon to sun for weekly mon
--cron <expression> your own cron expression, sets the plan to custom
--keep <n> how many archives stay 10
--name-pattern <pattern> file name of the archive without its ending, with {name}, {server}, {date} and {time}

Free and Premium

Every command under wd remote needs Premium, like the app's Remote pages. On the Free plan they end with exit code 4.

Troubleshooting

What you see Why What you do
wd remote ssh asks for a password The connection logs in with a password Enter the password or store a key on the SFTP / SSH page
Message with remote_conn_has_ when deleting Active tasks, backups or sync pairs still use the connection Delete them first or switch them to another connection
Message with remote_backup_space and the hint --force The space check before the backup failed, space is missing Make room or repeat on purpose with --force
Ambiguous task name The same task has the same name on several servers Pass name (server)
Nothing to change edit was called without an option Pass at least one option

See also

Monitor and SEO Free & Premium

With wd monitor you control the Monitor page: list monitored addresses, check them now, add, change and delete them, set the Check automatically switch and start Lighthouse measurements. wd seo belongs to the SEO page and starts an audit's website check and crawl.

Where to find it

In the terminal: wd monitor --help and wd seo --help.

How to do it

Monitor an address and measure it right away:

  1. wd monitor add https://shop.example.com --label Shop --interval 5 adds the address, checked every 5 minutes.
  2. wd monitor check Shop checks it now and shows status, response time and certificate expiry.
  3. wd monitor lighthouse Shop --profile mobile measures the page with Lighthouse and prints the scores.

Monitor (wd monitor)

Command Meaning
wd monitor monitored addresses with project, URL, status, response time, certificate expiry and last check. Same as wd monitor list
wd monitor check [address] check one address now. Without a name: all of them
wd monitor add <url> monitor an address (options below)
wd monitor edit <address> change an address, only what you pass
wd monitor delete <address> stop monitoring and delete the history. Asks first
wd monitor auto [on|off] set the Check automatically switch for every project and address. Without a value: show the state
wd monitor lighthouse [address] start a Lighthouse measurement, wait and print the scores for performance, accessibility, best practices and SEO
Option Meaning Default
--label <name> name in the list the address's host name, such as shop.example.com
--project <project> project the address belongs to. With edit: move it to another project the first project. If there is none yet, wd creates one
--interval <minutes> time between two checks 15
--keyword <text> text the page has to contain. With edit, "" removes it none
--url <url> new address (edit only)
--profile <profile> mobile, desktop or both (lighthouse only) both
--detach start Lighthouse and return at once (lighthouse only) off

A new address follows its project's switch: if Check automatically is off there, it is off for the address too.

SEO (wd seo)

Command Meaning
wd seo your SEO audits with address and last check. Same as wd seo list
wd seo check [audit] run the audit's website check now and print every result: passed, warning, failed or note, with code, group and value
wd seo crawl [audit] start the audit's crawl, like Run audit on the SEO page. wd waits and shows the progress. With --detach it returns at once

At the end of wd seo crawl stand the number of crawled pages and of findings. The evaluation is in the app on the SEO page.

You create audits in the app, not with wd.

Free and Premium

  • Monitor: on the Free plan one project with up to three addresses, with every feature including Lighthouse. Premium lifts the limit. wd monitor add ends with exit code 4 at the limit.
  • SEO: needs the SEO package. Without it, wd seo check and wd seo crawl end with exit code 4 and the message that a WebDonkey add-on package is needed.

Troubleshooting

What you see Why What you do
No result, the app shows why Lighthouse could not measure the page Read the message on the Monitor page in the app
Exit code 4 with wd monitor add The Free limit is reached Delete an address or activate Premium
Exit code 4 with wd seo The SEO package is missing See SEO package
Ambiguous name Several addresses match the abbreviation Give the name from wd monitor more fully

See also

More tools Free & Premium

These commands belong to the pages in the Tools group and to the settings: run workflows, read and write notes, control virtual machines, manage AI chats and CLI configurations, switch MCP servers, keep subscriptions, change themes, set settings and ask for the state of Claude Code.

Where to find it

In the terminal: wd workflows --help, wd notes --help, wd vms --help, wd ai --help, wd mcp --help, wd subscriptions --help, wd themes --help, wd settings --help, wd claude --help.

How to do it

Start a workflow from a Git hook or a script and use the result:

  1. wd workflows shows your workflows with status, last and next run.
  2. wd workflows run deploy --data '{"branch":"main"}' starts it through its manual start and passes the input fields.
  3. wd waits, shows every step and ends with exit code 1 when the run fails.

Workflows (wd workflows)

Workflows are a beta feature. Other spellings: wd workflow, wd wf.

Command Meaning
wd workflows workflows with on or off, last run and next scheduled run. A note names workflows past the Free limit or with Premium nodes
wd workflows run <workflow> run the workflow through its manual start (otherwise its first trigger), wait and show its steps. Exit code 1 when the run fails
wd workflows runs <workflow> the last runs with status, start, duration, trigger and error. -n sets the number (default 10)
wd workflows enable <workflow> switch it on, its triggers start it again
wd workflows disable <workflow> switch it off

run knows --data '<json>' for the input fields of the manual start, for example '{"name":"x"}', and --detach to return at once with the run's id. Creating and editing workflows only works in the app.

Notes (wd notes)

The commands work in the active vault of the Notes page. Other spelling: wd note.

Command Meaning
wd notes every note of the active vault with its path
wd notes show <note> print a note
wd notes new <path> [text] create a note, wd adds .md itself, for example wd notes new projects/shop "First line"
wd notes append <note> [text] append a line at the end of a note

If the text is missing as an argument, wd reads it from a pipe, for example echo "- check the contact form" | wd notes append projects/shop.

Virtual machines (wd vms)

Virtual machines are a beta feature. Other spelling: wd vm.

Command Meaning
wd vms virtual machines with system, CPUs, memory, disk and SSH port, running ones with a green dot
wd vms start <vm>, wd vms stop <vm> start or stop a VM
wd vms create <name> create a VM, its disk is made at once
wd vms edit <vm> change name, image, system, architecture, CPUs, memory or SSH port, only while the VM is stopped
wd vms delete <vm> delete a stopped VM together with its disk. Asks first
Option Meaning Default
--iso <file> installer image (.iso) on your Mac. With edit, "" ejects it none
--os <system> linux, windows or bsd linux
--arch <arch> aarch64 or x86_64 your Mac's
--cpus <n> number of CPUs 2
--ram <gb> memory in GB 4
--disk <gb> disk size in GB, fixed once created (create only) 32
--ssh-port <port> port on your Mac for SSH into the VM, 0 means none 0

AI (wd ai)

Command Meaning
wd ai your AI chats with model and last change. Same as wd ai chats
wd ai rename <chat> <new title> rename a chat, for example wd ai rename "New chat" Shop checkout
wd ai configs the chat configurations (model, memory, specialist) and the CLI configurations (CLI, model, memory, folder)
wd ai cli-add <name> --model <model> create a CLI configuration for the CLI tab of the AI page
wd ai cli-delete <configuration> delete a CLI configuration. Asks first, running terminals keep going
wd ai models the installed models of the local Ollama with size and your notes. If Ollama is not running, wd says so

cli-add knows --cli (aider as default, qwen-code, codex-cli, goose, opencode, crush), --model (a model from wd ai models, required), --memory (memory for model and context in GB, at least 1, or auto as default) and --folder (working folder, default the current one). Chatting with a model only works in the app.

MCP (wd mcp)

Command Meaning
wd mcp the configured MCP servers of your AI clients with client, scope, transport and state, running ones with a green dot
wd mcp clients the AI clients WebDonkey knows, whether they are on this Mac and how many servers they have
wd mcp enable <server>, wd mcp disable <server> switch a server on or off. The entry stays. wd says whether it takes effect after a restart of the client or in a new session

If several clients have a server of that name, you name it as name · client, for example "github · Claude Code". Adding and editing servers only works in the app. Some entries are managed by their client itself and cannot be switched here.

Subscriptions (wd subscriptions)

Command Meaning
wd subscriptions your subscriptions with amount per period, next charge and cancel-by date, below them the totals per month and year
wd subscriptions add <name> --price <amount> add a subscription
wd subscriptions delete <subscription> delete a subscription. Asks first
Option of add Meaning Default
--price <amount> amount per period, for example 9.99 or 9,99 required
--currency <code> currency code EUR
--every <period> day, week, month, quarter or year month
--start <date> first charge as YYYY-MM-DD, the next ones follow from it today
--url <address> website of the service
--notice-days <days> notice period in days, from which the cancel-by date follows

Themes and settings (wd themes, wd settings)

Command Meaning
wd themes built-in themes (System, Arctic, Aurora), presets and your own. The active one is marked
wd themes use <theme> wear a theme: system, arctic, aurora, a preset or one of your own by its name
wd settings the main settings with their values
wd settings get <key> the value of one setting
wd settings set <key> <value> change a setting, for example wd settings set language en
Key Allowed values
language cs, da, de, en, es, fr, fr-BE, it, ja, ko, nl, nl-BE, pl, ru, uk, zh
default_editor webdonkey-editor, vscode, cursor, phpstorm, webstorm, zed, sublime, nova, system
default_sites_root an absolute folder path
terminal_open auto, editor, webdonkey, system
folder_open auto, editor, code, finder
code_open auto, editor, code
db_open auto, editor, webdonkey
remote_notices on, off
theme as with wd themes use

You may write - instead of _, so default-editor is the same as default_editor. A value the setting does not know ends with a message that lists the allowed ones.

Claude Code (wd claude)

Command Meaning
wd claude whether Claude Code is installed, which account you are logged in with, your plan's live limits and the running instances. Same as wd claude status
wd claude sessions the running Claude instances with PID, name, kind, status, folder, model and context use
wd claude usage tokens per day, estimated from the local transcripts, with the approximate API value. --days <n> sets the range (default 30, today included)

The live limits only appear once you installed the statusline bridge on the Claude page (Show live limits (install statusline bridge)). None of these commands uses tokens.

Free and Premium

Commands Free Premium
wd workflows 3 workflows from the free nodes every workflow and node
wd notes no yes
wd vms yes yes
wd ai everything except cli-add everything
wd mcp list and clients plus enable and disable
wd subscriptions 6 subscriptions any number
wd themes use System, Arctic and Aurora plus the presets and your own themes
wd settings yes yes
wd claude status and sessions plus usage

When a limit is reached or Premium is missing, the command ends with exit code 4.

Troubleshooting

What you see Why What you do
wd workflows run reports an error about --data The text is not valid JSON Put the JSON in single quotes: --data '{"name":"x"}'
Nothing to add wd notes append without text and without a pipe Pass text or pipe it in
Ollama is not running The Ollama service is off wd services start ollama
Message that an MCP server cannot be switched here Its client manages the entry itself Change the server in the client or on the MCP page
Message unknown setting The key is not one of the main settings wd settings shows the known keys

See also

Options and exit codes Free

Some options apply to every wd command, whether you write them before or after the command. On top come the exit codes, from which scripts tell how a command went, and the JSON format for errors.

Where to find it

In the terminal: wd --help shows the options and, at the end of the help, the exit codes. wd <command> --help shows the options of one command.

How to do it

Use wd safely in a script:

  1. Pass --json when you evaluate the output. The text output is for people and may change.
  2. Pass -y when the command would ask, for example when deleting.
  3. Pass --no-launch when the app should not start by itself.
  4. Decide by the exit code, then read the message.
if ! out=$(wd sites start shop --json -y --no-launch); then
  echo "$out" | jq -r '.error.message'
fi

Options for every command

Option Meaning
--json exactly one JSON document on stdout: the result or the error. Questions go to stderr, stdout is kept for the JSON. The one exception: wd logs tail -f --json prints one object { "line": "…" } per line
-y, --yes answer confirmations with yes: start the app, free a port, delete a site, drop a database, remove WebDonkey
--no-launch never start the app automatically. If it is closed, the command ends with exit code 3
--no-color no colours. Also applies when NO_COLOR is set or the output does not go to a console
-h, --help help for the command
-V, --version version of the app this wd belongs to

Single commands have their own options, such as -n and -f for wd logs tail. They are on the pages of the commands.

Exit codes

Code Meaning
0 success
1 the command ran and failed, for example a service did not start or a task ended with an error. Also: the running app is older than wd
2 wrong usage: typo, missing argument, ambiguous name without a terminal or missing -y for a confirmation
3 the app is not reachable: it is not running and was not started, because of --no-launch or because without a terminal nobody can answer the question
4 the feature needs WebDonkey Premium or an add-on package, or a Free limit is reached

Some commands report their full result even when they fail, such as wd cron run with the task's exit code and output. The exit code is still 1 then.

Errors as JSON

With --json an error looks like this:

{ "ok": false, "error": { "kind": "failed", "code": 1, "message": "…" } }
kind Exit code Meaning
failed 1 the command failed
app_outdated 1 the app is older than wd, an app update helps
usage 2 wrong usage, message lists the candidates for an ambiguous name
unreachable 3 the app is not running
premium 4 Premium, add-on package or Free limit. detail names the limit, such as premium_service_limit:6/6

Two extra fields help with the fix: hint names a command, such as wd free-port 3306 for a busy port or --no-ssl at the HTTPS limit. detail is present with premium and app_outdated.

Questions, pickers and names

  • Abbreviating names: almost everywhere you may abbreviate names. If exactly one matches, wd takes it. If several match, a picker opens in the terminal. Without a terminal the command ends with exit code 2 and lists the candidates.
  • Leaving a name out: in the terminal the picker opens. In a script, always give the name.
  • No match: wd says so and suggests a similar name where it can ("did you mean …?").
  • Confirmations before final actions are answered with yes or no in the terminal. Without a terminal and without -y, wd stops with exit code 2 instead of saying yes silently or hanging.

What happens in the background

wd talks to the app through a Unix socket file in WebDonkey's folder: ~/Library/Application Support/WebDonkey/runtime/control.sock, readable only by your user. There is no network port and no token. Whatever you do with wd, you do with your own rights.

Normal commands wait up to 10 minutes for the app's answer. Commands that can take long, such as backups, installs, scheduled tasks or uploads over SFTP, wait up to 6 hours.

Troubleshooting

What you see Why What you do
WebDonkey is not running and exit code 3 The app is closed and wd was not allowed to start it wd app start or repeat the command with -y
The running WebDonkey app is too old for this command wd is newer than the running app, for example right after an update Restart or update the app
Exit code 2 with the hint to confirm with -y The command wants to ask, but there is no terminal Pass -y if you really want the action
wd logs tail -f never returns -f follows the file until you stop it In scripts use -n with a fixed number of lines

See also

Briefing for AI agents Free

If you work with Claude Code, Cursor, Codex or another AI agent, it can drive WebDonkey itself: start services, create sites, read logs, spot port conflicts, back up databases. It just needs to know how. The block below is exactly that knowledge: every command, the JSON shapes with examples, the exit codes and, just as important, what wd cannot do. Without that last part agents invent commands that do not exist.

Where to find it

Sidebar Tools › Terminal, card WebDonkey CLI, button Briefing for AI agents. It opens this page in the app's docs. The briefing is further down this page as a block.

How to do it

  1. Copy the block below. In the app, use the Copy code button at the top right of the block.
  2. Put it into your agent's context file: CLAUDE.md, AGENTS.md, .cursorrules or the system prompt.
  3. From then on the agent knows how to handle your environment. Ask it, for example: "Why does shop.test not load?"

The text is in English on purpose, even when the app runs in another language. It is read by the model, not by you, and coding agents follow English instructions more reliably.

For Claude Code: keep the agent up to date

With Claude Code it works without copying and stays current with every update:

  1. Open the page Tools › Claude, tab Hooks.
  2. Switch on Keep the WebDonkey agent up to date.

At the start of every new Claude session, WebDonkey then writes the agent webdonkey-cli to ~/.claude/agents/webdonkey-cli.md, with this briefing and every command of the installed version together with its options. New commands arrive with each update that way. The hook prints nothing into the session, Claude reads the full agent only when it hands it a task.

What happens in the background

  • The switch adds a session start hook to your Claude settings that calls wd claude refresh-agent. Switching it off removes the hook again.
  • If CLAUDE_CONFIG_DIR is set, the agent lands in the agents folder there instead of ~/.claude/agents.
  • The file carries a marker line from WebDonkey. Only a file with this line is overwritten. Delete the line and your own version stays. WebDonkey never touches a webdonkey-cli.md of your own without the line.
  • If the text is already current, WebDonkey does not rewrite the file.

What it states explicitly

  • A crashed service does not count as healthy: status has six values, not two.
  • Before actions that touch running work or data, the agent asks, for example before wd free-port, wd db drop or wd sites delete.
  • wd uninstall is never a repair.
  • Passwords only go through --password-stdin, never as an argument and never through the chat.
  • What only works in the app, such as editing workflows or chatting with an AI model.

Free and Premium

The briefing is free. The switch Keep the WebDonkey agent up to date on the Claude page needs Premium.

The block

# WebDonkey, briefing for AI agents

## Purpose

WebDonkey is a local web development environment for macOS. It runs services
(PHP-FPM, MySQL, MariaDB, PostgreSQL, Redis, nginx, Apache, Caddy, Node,
Mailpit, …), serves local sites on real domains with HTTPS through a front
proxy on ports 80/443, and runs scheduled tasks and project backups. It also
manages remote servers (tasks, backups), monitored
addresses, workflows, notes and virtual machines.

You control it with the `wd` command. `wd` manages nothing itself: it talks
to the running WebDonkey app over a local socket and calls the same functions
as the app's UI. Whatever you change is immediately visible in the app, and
the other way round.

## Rules

1. **Check first, then act.** Read the state (`wd status --json`) before you
   start, stop or switch anything.
2. **Always pass `--json` when you read output.** The text output is for
   people and may change; the JSON shapes below are stable. Fields may be
   added, existing ones do not disappear.
3. **Pass `-y` on commands that would ask.** Without a terminal there is no
   one to answer a question, so `wd` refuses instead of guessing (exit 2),
   or does not launch the app (exit 3).
4. **Decide by exit code, then read the message.** 0 is success; everything
   else carries a JSON error (see *Errors*).
5. **Only use the commands listed here.** If something is not listed, it does
   not exist, say so instead of inventing it. `wd --help` and
   `wd <command> --help` show the real list.
6. **Ask before destructive actions**: `wd free-port`, `wd services stop --all`,
   `wd sites stop`, `wd sites delete`, `wd db drop`, `wd db restore`,
   `wd remote delete`, `wd vms stop`, `wd vms delete`, `wd monitor delete`,
   `wd proxy stop`, `wd app stop`. They
   affect the user's running work or data. **Never run `wd uninstall`** unless the
   user explicitly asks to remove WebDonkey from the Mac, it is not a fix
   for anything. The same goes for `wd db users delete|revoke|password`,
   `wd logs custom clear`, `wd subscriptions delete`, `wd mcp disable`,
   `wd sites create --package` and `wd settings set`: only when the user asks.
7. **When something does not work, start with `wd doctor --json`.** It checks
   PATH, app, versions, crashed services, sites and the front proxy, and names
   the fix for every problem it finds.

## Is WebDonkey available?

```bash
command -v wd                 # is the CLI installed?
wd app status --json          # is the app running?
```

```json
{ "running": true, "app_version": "<version>" }
```

- `command -v wd` prints nothing → WebDonkey is not installed, or its
  terminal integration ("Tools in the terminal" in the app's settings) is
  off. Tell the user; do not try to install anything yourself.
- `wd app status` exits with 3 and prints `{ "running": false }` → the app
  is closed. Start it with `wd app start --json` (it waits until the app
  answers), then continue.

## Options on every command

| Option | Effect |
|---|---|
| `--json` | exactly one JSON document on stdout: the result, or the error |
| `-y`, `--yes` | answer confirmations with yes: starting the app, freeing a port, deleting a site, uninstalling |
| `--no-launch` | never start the app; exit 3 when it is closed |
| `--no-color` | no colours (also honours `NO_COLOR` and non-terminals) |
| `-h`, `--help` | help for the command, e.g. `wd sites create --help` |
| `-V`, `--version` | version of the app this `wd` belongs to |

## Commands

Names may be abbreviated (`my` finds `mysql`). Without a terminal, an
ambiguous name is an error that lists the candidates, use a more specific
name then. Leaving a name out opens a picker in a terminal; you have none, so
always name the service, site, log, task or connection.

Aliases that work too: `wd ls` and `wd service` (= `wd services`), `wd site`,
`wd databases` (= `wd db`), `wd tasks` (= `wd cron`), `wd backups`,
`wd servers` (= `wd remote`), `wd certs` (= `wd ssl`),
`wd wf` (= `wd workflows`), `wd note`, `wd vm`, `wd mails`.

### Overview

```bash
wd status --json
```

```json
{
  "app_version": "<version>",
  "premium": false,
  "proxy": { "running": true, "last_error": null },
  "services_total": 3,
  "services_running": [{ "package_id": "mysql", "version": "<version>" }],
  "sites": [{ "domain": "shop.test", "ssl": true, "webserver": "nginx" }]
}
```

### Services

```bash
wd services --json                      # installed services, running first
wd services start mysql redis --json    # start one or more
wd services start php@<version> --json  # a specific installed version
wd services stop mysql --json
wd services restart php --json
wd services stop --all --json           # everything, ask first
wd services install redis --json        # newest stable version
wd services install php@<version> --json
wd services use php@<version> --json    # the version new shells and plain starts use
wd services use php --json              # without a version: show the active and the installed ones
```

`wd services --json` returns a list:

```json
[{ "package_id": "mysql", "name": "MySQL", "version": "<version>",
   "status": "Running", "uptime_seconds": 5400, "installed": true }]
```

`status` is one of `Running`, `Starting`, `Stopping`, `Stopped`,
`Crashed`, `Unknown`. Treat a service as usable only when it is
`Running`, never test for `!= "Stopped"`, a crashed service would pass.

start/stop/restart return the state afterwards:

```json
{ "ok": true, "action": "start",
  "services": [{ "package_id": "mysql", "version": "<version>", "status": "Running", "...": "…" }] }
```

`wd services install` returns `{ "ok": true, "action": "install", "installed":
[{ "package_id", "version" }] }` and can take minutes (downloads).

`wd services use php --json` (no version) returns
`{ "package_id": "php", "active": "<version>", "installed": ["<version>", "…"] }`;
`active` is null when the newest installed version is used. With a version it
switches: new terminal windows use it at once, running services keep theirs
until they are restarted. A version that is not installed is an error that
lists the installed ones.

`wd start`, `wd stop`, `wd restart` and `wd ls` are short forms of the same
commands. `wd services start php` starts the version marked active in the
app; name a version only when the project needs a different one.

### Sites

```bash
wd sites --json               # every site
wd sites start shop --json    # switch on + start what it needs (PHP, webserver, databases)
wd sites stop shop --json     # switch off: the domain is released, ask first
wd sites open shop            # open in the user's browser
wd sites create shop.test --path /abs/project --php <version> --json
                              # new site for a folder, started right away; HTTPS unless --no-ssl
wd sites create shop.test --name "Shop" --webserver caddy --no-ssl --json
                              # display name, nginx (default) | caddy | apache, plain HTTP
wd sites delete shop -y --json
                              # configuration, certificate, logs, the folder stays; ask first
wd sites info shop --json     # one site with every field
wd sites php shop <version> --json
                              # pin the site to an installed PHP version (Node: wd sites node)
wd sites diagnose shop --json # the Sites page's checks; exit 1 if one fails
wd sites packages --json      # site packages: id, name, description, requires
wd sites packages wordpress --json
                              # one package with its settings (key, default, options)
wd sites create blog.test --path /abs/blog --package wordpress --set site_title=Blog --json
                              # site + package install (Premium); waits, { "ok", "site", "steps" }
```

`wd sites create` without options: the current folder, the domain as name,
nginx, no PHP (a static site), HTTPS. `--path` may start with `~/`. It
starts what the site needs, like `wd sites start`; when that fails, the site
is still created but switched off, `started` is `false` and
`site.start_error` says why. Results: start/stop
`{ "ok": true, "action": "start", "site": { … } }`, create
`{ "ok": true, "action": "create", "started": true, "site": { … } }`, delete
`{ "ok": true, "action": "delete", "id": "…", "domain": "shop.test" }`.

Each site in `wd sites --json`: `id`, `name`, `domain`, `aliases`,
`path`, `webserver`, `php_version`, `node_version`, `ssl_enabled`,
`enabled`, `serve_command`, `serve_port`, `env`, … . `enabled: false`
means the site exists but is switched off and will not answer, a common
reason for "my site does not load". `wd sites start <site>` fixes exactly
that. `wd sites diagnose` returns `{ "ok", "domain", "items": [{ "label",
"ok", "detail" }] }`; a version that is not installed is an error naming
`wd services install php@<version>`.

`--package` works like the Sites form: every setting at the package's
default (the database name from the domain), `--set KEY=VALUE` over it, the
newest installed PHP/Node the package accepts unless `--php` names one. It
stops before creating anything with `site_package_requirements: …` (install
what it names), `site_package_db_not_empty: …` (another `--set db_name=…`) or
`site_package_files: …` (files it would replace, ask the user, then repeat
with `--overwrite`). A failed install exits 1 with its `steps`; the site stays.

### Certificates

```bash
wd ssl --json                 # { "ca_trusted", "certificates": [{ "site_domain", "days_left", "not_after", "sans", … }] }
wd ssl renew shop --json      # issue the site's certificate again
wd ssl trust                  # trust the local CA, macOS asks the user for a password; only on request
```

### Databases

```bash
wd db --json
```

```json
[{ "kind": "mysql", "display": "MySQL", "version": "<version>", "port": 3306,
   "running": true, "databases": ["shop"], "users": ["root"] }]
```

Databases are listed only while their server runs.

```bash
wd db shell mysql shop -- -e "SHOW TABLES"    # run SQL, logged in as root
wd db shell postgres appdb -- -c "SELECT 1"
```

`wd db shell` starts the engine's own client (mysql, psql, mongosh) already
logged in; everything after `--` goes to that client, so a query runs and
returns. Without client flags it opens an interactive session, not useful to
you. Its output is the client's own text, not JSON.

```bash
wd db create mysql shop --json                 # new database on a running server
wd db rename mysql shop shop_old --json
wd db drop mysql shop_old -y --json            # deletes all its data, ask first
wd db backup mysql shop --json                 # { "ok", "path", "size_bytes", "note" }
wd db backup postgres app --format pg_custom --folder /abs/dir --json
wd db restore mysql shop /abs/dump.sql.gz -y --json
                                               # the current content is backed up first, ask first
```

`wd db backup` uses the format, file name and folder last chosen in the app
(`--format`: `sql` = gzip-compressed SQL, `sql_plain`, `pg_custom`, `csv`).
A restore that needs an answer fails with `remote_db_restore_version_jump…`
(dump from another major version) or `remote_db_restore_definer…`: ask the
user, then repeat with `--accept-version-jump` or `--rewrite-definers`.

Database users and their rights:

```bash
wd db users --json            # per running server: { "kind", "users": [{ "name", "hosts", "system", "global_level", "sites" }], "grants": [{ "user", "database", "level" }] }
wd db users list mysql --json
printf '%s' "$PW" | wd db users add mysql shop_user --database shop --password-stdin --json
wd db users grant mysql shop_user shop --level readonly --json   # all | readwrite | readonly
wd db users revoke mysql shop_user shop -y --json
printf '%s' "$PW" | wd db users password mysql shop_user --password-stdin --json
wd db users delete mysql shop_user -y --json
```

A password only ever comes from stdin. The engine's own accounts (root,
postgres …) are refused with `db_system_account: …`, the app logs in with them.

### Logs

```bash
wd logs --json                        # [{ "id", "label", "path" }]
wd logs tail nginx -n 100 --json      # { "id", "label", "path", "lines": [...] }
wd logs nginx -n 100 --json           # the same, short form
```

Without `-n` you get the last 100 lines.

`wd logs tail <name> -f` follows the file and never returns (with `--json`
it prints one `{ "line": "…" }` per line). Avoid it in an agent context;
read a fixed number of lines with `-n` instead.

The user's own log files (Logs page, Premium except the list):

```bash
wd logs custom --json                       # [{ "id", "name", "path" }]
wd logs custom tail app -n 100 --json       # { "id", "name", "path", "lines": [...] }
wd logs custom add app /abs/storage/logs/laravel.log --json
wd logs custom clear app -y --json          # empties the file, ask first
wd logs custom remove app --json            # off the list; the file stays
```

### Scheduled tasks

```bash
wd cron --json                # tasks: name, cron_expr, enabled, last_run_at, last_exit_code, next_due_at
wd cron run cleanup --json    # run now; waits until it is done
wd cron disable cleanup --json   # pause it; wd cron enable switches it on again
wd cron add cleanup --schedule "0 3 * * *" --command "php bin/console app:cleanup" --dir . --json
                              # --dir: the folder it runs in (relative = from here; default: home); --paused
wd cron edit cleanup --schedule "30 3 * * *" --json
                              # only what is given changes: --name, --schedule, --command, --dir ("" = home)
wd cron delete cleanup -y --json   # ask first
```

```json
{ "ok": true, "id": "…", "name": "cleanup", "exit_code": 0, "output": "…" }
```

If the task's command fails, `ok` is false and `wd` exits with 1, the
result still carries `exit_code` and `output`.

`add` and `edit` save like the page's form and answer
`{ "ok": true, "action": "add", "task": { … } }` with the saved task. The
Free plan's task limit answers with exit 4, and a task over the limit after
Premium ended only takes a new name. `edit` keeps the task on or paused.

### Project backups (Premium)

```bash
wd backup --json              # backup sets
wd backup run nightly --json  # run now; can take minutes
wd backup runs nightly --json # its archives: archive_path, size_bytes, status, created_at
wd backup add nightly --path . --db shop --schedule daily --at 02:30 --json
                              # --path, --db [server:]database (server mysql|mariadb|postgres) and
                              # --exclude (node_modules, var/cache) repeat; --folder /abs/dir or
                              # --default-folder, --weekday mon…sun, --cron EXPR, --keep N (1 = newest only)
wd backup edit nightly --keep 14 --json
                              # only what is given changes; a list given (--path, --db, --exclude) replaces
                              # the old one, '' alone empties it
wd backup delete nightly -y --json
                              # its archives stay unless --archives, ask first
```

```json
{ "ok": true, "name": "nightly", "status": "ok", "archive_path": "…", "size_bytes": 123456 }
```

`status` is `ok`, `partial` or `failed`; anything but `ok` exits with 1.
On the Free plan both commands exit with 4.

`add` and `edit` save like the page's form (Premium) and answer
`{ "ok": true, "action": "add", "set": { … } }`; without options a new set
backs up nothing, runs only by hand and keeps 10 backups. `delete` works on
the Free plan too, for sets left over from Premium.

### Remote servers (Premium)

```bash
wd remote --json                  # saved connections: name, host, port, username, auth_kind
wd remote ssh prod -- uptime      # run a command on the server
```

Key-based connections run non-interactively. With password login, ssh asks for
the password, you cannot answer that; tell the user instead.

```bash
wd remote test prod --json        # { "ok", "home" }, one login
wd remote add prod --host example.com --user deploy --key ~/.ssh/id_ed25519 --json
wd remote delete prod -y --json   # refused while tasks or backups use it, ask first
wd remote cron --json             # tasks on servers: name, connection_name, cron_expr, enabled, next_due_at
wd remote cron run cleanup --json # run on the server now: { "ok", "last_exit", "log_tail" }
wd remote backup --json           # server backups
wd remote backup run nightly --json
                                  # { "ok", "status", "path", "size_bytes", "message" }
wd remote cron add cleanup --server prod --schedule "0 3 * * *" --command "php bin/console app:cleanup" --json
                                  # also --file <script>, --run-by webdonkey|server, --paused
wd remote cron edit cleanup --schedule "30 3 * * *" --json
                                  # only what is given changes: --name, --schedule, --command, --file, --run-by
wd remote cron delete cleanup -y --json
                                  # a crontab line on the server goes too, ask first
wd remote backup add nightly --server prod --path www --db shop --schedule daily --at 02:30 --json
                                  # --exclude, --to local|remote, --dest-path, --folder, --weekday, --cron, --keep, --name-pattern
wd remote backup edit nightly --keep 14 --json
                                  # only what is given changes; a list given (--path, --db, --exclude) replaces the old one
wd remote backup delete nightly -y --json
                                  # its archives stay unless --archives, ask first
```

Files, databases, logs and mailboxes on the servers (Premium). Relative
server paths start in the login folder:

```bash
wd remote sftp ls prod www --json # { "path", "entries": [{ "name", "path", "is_dir", "size", "mtime" }] }
wd remote sftp get prod www/.env ./env-prod --json
wd remote sftp put prod ./dist www/ --json
                                  # a target ending in / means "into that folder"; overwriting asks (-y), ask first
wd remote db --json               # entries of Remote databases: name, kind, connection_name, host, port, database
wd remote db databases shop --json
wd remote db backup shop --json   # a dump into a file on this Mac (alias dump); --format, --folder
wd remote db restore shop shop_live ./shop.sql.gz -y --json
                                  # backs the database up first, then replaces it (alias import), ask first
wd remote logs --json             # remote logs: name, connection_name, path
wd remote logs tail error-log -n 50 --json
                                  # reads over SSH now: { "lines" }; -f keeps reading every few seconds
wd remote mail --json             # mailboxes
wd remote mail folders info --json
wd remote mail messages info --json
                                  # newest mails: id, from_name, from_address, subject, date, seen (--folder, -n, --search)
wd remote mail show info 1 --json # one mail with headers, text and attachments; --id takes the id instead
```

A password or key passphrase goes in only through `--password-stdin` (first
line of stdin), never put one into an argument, and never ask the user for
one in the chat. A server backup refused with `remote_backup_space:…` lacks
space; `--force` runs it anyway, ask first.

### Monitor and SEO

```bash
wd monitor --json                 # { "projects", "targets", "online" }: last_status, last_latency_ms, ssl_expires_at
wd monitor check --json           # check every address now
wd monitor check shop --json      # one address
wd seo --json                     # SEO audits (add-on)
wd seo check shop --json          # website check: { "final_url", "checks": [{ "code", "group", "state", "value" }] }
wd seo crawl shop --json          # the audit's crawl; waits: { "status", "crawled", "found" } (--detach)
wd monitor add https://shop.example.com --label Shop --interval 5 --json
                                  # --project, --keyword; a new address follows its project's switch
wd monitor edit Shop --keyword "Add to cart" --json   # --url, --label, --project, --interval
wd monitor delete Shop -y --json  # deletes its history, ask first
wd monitor auto off --json        # "check automatically" for every project and address; without on/off: the state
wd monitor lighthouse Shop --profile mobile --json    # waits; scores lh_* (mobile), lhd_* (desktop); --detach
```

`state` is `pass`, `warn`, `fail`, `info` or `unknown`.

### Workflows

```bash
wd workflows --json                              # name, enabled, last_status, next_run_at, locked_by_quota
wd workflows run deploy --json                   # waits; { "ok", "run": { "status", "error" }, "steps": [...] }
wd workflows run deploy --data '{"branch":"main"}' --json
                                                 # input fields of the manual start
wd workflows run deploy --detach --json          # { "ok", "run_id" } at once
wd workflows runs deploy -n 5 --json
wd workflows disable deploy --json               # wd workflows enable switches it on
```

A run that ends in `error` or `cancelled` exits with 1.

### Notes (Premium)

```bash
wd notes --json                                  # [{ "rel_path", "name" }] of the active vault
wd notes show projects/shop --json               # { "path", "content" }
wd notes new projects/shop "First line" --json   # .md is added
echo "- check the contact form" | wd notes append projects/shop --json
```

### Virtual machines

```bash
wd vms --json                 # name, os_family, cpus, ram_mb, disk_gb, ssh_port, running
wd vms start ubuntu --json
wd vms stop ubuntu --json     # ask first
wd vms create ubuntu --iso ~/Downloads/ubuntu.iso --cpus 4 --ram 8 --disk 64 --ssh-port 2222 --json
                              # --os linux|windows|bsd, --arch aarch64|x86_64 (default: this Mac's)
wd vms edit ubuntu --ram 4 --json       # only while stopped; --name, --iso ("" ejects), --os, --arch, --cpus, --ssh-port
wd vms delete ubuntu -y --json          # deletes its disk, ask first
```

### Mail (Mailpit)

```bash
wd mail --json                # newest 20: { "total", "unread", "messages": [{ "ID", "From", "To", "Subject", "Created", "Read" }] }
wd mail list -n 5 --json
wd mail show 1 --json         # the newest mail: From, To, Subject, Date, Text, HTML
```

Use it to check that a site really sent a mail. `mailpit_not_running` →
`wd services start mailpit`.

### AI

```bash
wd ai --json                  # chats: id, title, model, specialist_id, ctx_budget_gb, updated_at
wd ai rename "New chat" Shop checkout --json
wd ai configs --json          # { "configs": [{ "id", "name", "model", "ctx_budget_gb", "specialist_id" }], "specialists": [{ "id", "name" }],
                              #   "cli_configs": [{ "id", "name", "cli_id", "model", "ctx_budget_gb", "cwd" }] }
wd ai cli-add Shop --cli qwen-code --model qwen3:8b --memory 16 --folder ~/Sites/shop --json
                              # a CLI configuration of the CLI tab; --cli aider (default), qwen-code, codex-cli,
                              # goose, opencode, crush; --memory auto (default) or GB; --folder defaults to the current one
wd ai cli-delete Shop --json  # ask first
wd ai models --json           # { "ollama_running", "installed": [the local Ollama's models], "notes": [...] }
```

A CLI configuration needs Premium, like the CLI tab: on Free `cli-add` exits 4.

### MCP

```bash
wd mcp --json                 # configured servers: id, name, client, client_name, scope, project, transport, state, running, can
wd mcp clients --json         # the AI clients: id, name, present, processes, sources
wd mcp disable "github · Claude Code" --json
                              # wd mcp enable switches it on again; the result's "reload" says when it takes effect
```

Name a server as `<name> · <client>` when several clients have one of that name.

### Subscriptions

```bash
wd subscriptions --json       # { "subscriptions": [{ "name", "price_cents", "currency", "interval_unit", "next_due_at", "cancel_by", "status", … }], "totals": [...] }
wd subscriptions add Hosting --price 12 --every month --start 2026-01-15 --notice-days 30 --json
wd subscriptions delete Hosting -y --json
```

Free keeps a limited number of subscriptions: over it, `add` exits 4.

### Themes and settings

```bash
wd themes --json              # { "active", "builtin", "presets", "custom": [{ "id", "name", "base", … }] }
wd themes use aurora --json   # system | arctic | aurora | a preset (Premium) | an own theme by name
wd settings --json            # language, theme, default_editor, default_sites_root, terminal_open, folder_open, code_open, db_open, remote_notices
wd settings get language --json
wd settings set language en --json
```

A value the setting does not take fails with the allowed ones in `message`.

### Claude Code

```bash
wd claude --json                  # installed, login, plan limits, running instances
wd claude sessions --json         # running Claude instances: pid, name, cwd, kind, status, model, ctx_used_pct
wd claude usage --days 7 --json   # tokens per day, estimated from local transcripts (Premium)
```

Plan limits (`limits.five_hour` / `limits.seven_day`: `used_pct`, `resets_at` in
ms) exist only after the user switched on the statusline bridge on the app's
Claude page; `limits` is null otherwise. None of these commands costs tokens.
`wd claude statusline` and `wd claude notify` are called by Claude itself,
do not run them.

### WebDonkey Editor

```bash
wd edit src/Checkout.php:42       # open a file at a line in the WebDonkey Editor
wd edit src/Checkout.php:42:7     # … and column
wd edit .                         # open the current folder as the editor's project
wd edit --diff a.php b.php        # compare two files
wd edit --wait notes.md           # blocks until the tab is closed (-w)
wd edit --terminal                # a terminal in the editor, in the current folder
wd edit --terminal /abs/project   # … in that folder
```

The editor is a separate app; `wd edit` starts it when it is not running and
answers `{"ok": true, "action": "edit" | "diff" | "terminal", ...}` with
`--json`. `--wait` holds until the user closes the tab, never use it for a
file you only want to show; it is meant for `$EDITOR`/`$VISUAL`.

### Diagnosis

```bash
wd doctor --json
```

```json
{ "ok": false, "checks": [
  { "name": "Site shop.test", "ok": false, "detail": "not running: nginx", "hint": "wd sites start shop.test" }
] }
```

Exit 1 when a check fails. Every failed check carries a `hint`, the command
that fixes it (ask before destructive ones).

### App pages

```bash
wd open services --json       # bring the app to the front on a page
wd open "toolbox?tool=json"   # a page with a query
```

Also accepted: home, config/configs, db, certs/ssl, tasks/scheduled-tasks,
api, ki, help/manual. Without a page a picker opens (terminal only).

Pages: dashboard, sites, certificates, services, configuration, databases,
remote-databases, mail, remote-mail, logs, custom-logs, remote-logs, docs,
legal, remote, notes, backups, remote-backups, cron, remote-cron, monitor,
subscriptions, api-client, workflows, toolbox, ai, claude, terminal, vms,
changelog, premium, themes, settings. Use this to show the user something, it does not change
anything.

### Front proxy, ports, the app

```bash
wd proxy --json               # { "running": true, "last_error": null }
wd proxy start --json
wd proxy stop --json          # sites stop answering on 80/443, ask first
wd free-port 3306 -y --json   # stops a FOREIGN process on that port, ask first
wd app start --json           # { "running": true, "app_version": "<version>", "launched": true }
wd app stop --json            # quits the app and its services, ask first
```

### Shell completion

```bash
wd completions zsh    # zsh, bash, fish, elvish or powershell
```

Prints a completion script for the user's shell configuration
(`source <(wd completions zsh)` in `~/.zshrc`). No `--json` (exit 2). Only
when the user asks for it.

### Removing WebDonkey from the Mac

```bash
wd uninstall -y --json                # system parts only; sites, databases and settings stay
wd uninstall --delete-data -y --json  # also delete WebDonkey's data once the app has quit
```

Removes what WebDonkey set up outside its data folder: sudoers rules, root
helpers, scheduling daemons, DNS resolver files, hosts entries, the trusted
root CA, the PATH block, the Claude statusline bridge, shell aliases, SSH
hosts and the prompt of the Terminal page. Project folders are never touched.
macOS asks the user for an administrator password once, on the Mac; then the
app quits. Without a terminal it needs `-y` (exit 2 otherwise).

```json
{ "removed": [{ "kind": "sudoers_rule", "path": "…", "privileged": true }],
  "remaining": [], "errors": [] }
```

Exit 1 when something remains (`remaining` names it) or the password dialog
was cancelled (nothing changed then). **Only on the user's explicit request to
remove WebDonkey**: never to fix a problem.

## Errors

With `--json`, a failure prints exactly one object on stdout:

```json
{ "ok": false, "error": { "kind": "failed", "code": 1, "message": "…" } }
```

| Exit | kind | Meaning | What to do |
|---|---|---|---|
| 0 | none | success | continue |
| 1 | `failed` | the command ran and failed | read `message`; do not retry blindly |
| 1 | `app_outdated` | the app is older than this `wd` | tell the user to update WebDonkey |
| 2 | `usage` | wrong arguments, ambiguous name, missing `-y` | fix the call; `message` lists the candidates |
| 3 | `unreachable` | the app is not running | `wd app start`, then retry once |
| 4 | `premium` | needs WebDonkey Premium or an add-on, or a Free limit is reached | tell the user; `detail` says which (`addon_required:<package>`) |

Common patterns:

- **Port conflict**: a start fails with a message containing
  `PORT_IN_USE:<port>:<process>` and `"hint": "wd free-port <port>"`.
  Another program holds the port, often a second MySQL or web server the
  user needs. Ask before running the hint.
- **Free limit**: `kind: "premium"` with `detail` like
  `premium_service_limit:…`: the Free plan runs a limited number of
  services at once. Stop one (ask which) or tell the user.
- **Site does not load**: check `wd sites --json` (is it `enabled`?), then
  `wd services --json` (are its PHP and webserver `Running`?), then
  `wd logs tail <webserver> -n 100 --json`.

## Typical flows

Bring a PHP project up:

```bash
wd status --json
wd sites start shop --json       # starts PHP, webserver and databases for it
wd proxy --json                  # must be running for https://shop.test
```

Check a service before relying on it:

```bash
wd services --json | jq -r '.[] | select(.package_id=="mysql") | .status'
```

Investigate a failing site:

```bash
wd sites --json | jq '.[] | select(.domain=="shop.test") | {enabled, webserver, php_version}'
wd logs tail nginx -n 100 --json
wd logs tail php -n 100 --json
```

## Limits: do not work around these

- **Editing sites** (domain, aliases, environment), **uninstalling**
  packages, editing configuration files: app UI only.
- **Creating and editing** workflows and SEO audits: app UI only. Listing,
  running and switching them on or off works with `wd`. Tasks, backup
  sets, monitored addresses and virtual machines can be
  created and edited with `wd`, and so can tasks and backups on servers
  (`wd remote cron add`, `wd remote backup add` …).
- **The toolbox, the API client, chatting with an AI model, adding or editing
  MCP servers**: app UI only.
- `wd` only reaches the WebDonkey of the **same user on the same Mac**.

## Security

`wd` talks to a Unix socket inside the user's WebDonkey folder
(`~/Library/Application Support/WebDonkey/runtime/control.sock`, mode 0600):
no network port, no token. Everything you do with `wd` you do as the user,
so ask before anything that stops their work or kills a process.

See also

Cookie preferences

This website uses cookies to ensure the best experience possible. Your choice applies to webdonkey.io and the shop at shop.webdonkey.io. More information...

Technically required

Cookies required for this website to function:

Always on
WebDonkey
WebDonkey
Provider: BuI Hinsche GmbH, Neumarkt 7, 06712 Zeitz, Germany
Purpose: Your consent, colour scheme and language for website and shop, price switches; with wd_debug in the address, the measurement events in the developer console for troubleshooting
Cookies and storage: Cookie wd_consent on .webdonkey.io, shared with shop.webdonkey.io (12 months); cookies wd_theme and wd_lang on .webdonkey.io, shared with shop.webdonkey.io, only when you switch colour scheme or language yourself (365 days); localStorage wd:consent, wd:theme, wd:lang; sessionStorage wd:acc, wd:term, wd:debug (only with wd_debug in the address; until the tab closes)

Statistics

Shows us which pages and products people look at on webdonkey.io and in the shop, where visitors come from and how they get to a purchase (with order number, amount and products, without name or email address). Provider: Google. Transfer to the USA possible (EU-US Data Privacy Framework). Your choice applies to webdonkey.io and the shop together.

Google Tag Manager, Google Analytics 4
Google Tag Manager
Provider: Google Ireland Limited, Gordon House, Barrow Street, Dublin 4, Ireland
Purpose: Loads the services you agreed to, here and in the shop. Sets no cookies of its own.
Cookies and storage: none
Privacy policy
Google Analytics 4
Provider: Google Ireland Limited, Gordon House, Barrow Street, Dublin 4, Ireland
Purpose: Usage statistics: page views, clicks, scroll depth, sources, devices, load times; in the shop also basket, checkout, purchases, registration and sign-in
Cookies and storage: _ga, _ga_<ID> (2 years)
Privacy policy

Marketing

Measures whether our ads on Facebook, Instagram and TikTok lead to visits and downloads on webdonkey.io and to registrations and purchases in the shop, and builds audiences for ads. Providers: Meta and TikTok, with whom we are jointly responsible for this. With this consent Google may also set advertising cookies (_gcl_…). Transfer to the USA and other countries outside the EU possible. Your choice applies to webdonkey.io and the shop together.

Google Tag Manager, Meta Pixel (Facebook, Instagram), TikTok Pixel
Google Tag Manager
Provider: Google Ireland Limited, Gordon House, Barrow Street, Dublin 4, Ireland
Purpose: Loads the services you agreed to, here and in the shop. Sets no cookies of its own.
Cookies and storage: none
Privacy policy
Meta Pixel (Facebook, Instagram)
Provider: Meta Platforms Ireland Limited, Merrion Road, Dublin 4, D04 X2K5, Ireland
Purpose: Ad measurement and target groups on Facebook and Instagram, also in the shop (basket, checkout, purchases, registration)
Cookies and storage: _fbp (3 months), _fbc (3 months, only if you arrive through an ad), fr on facebook.com (3 months)
Privacy policy
TikTok Pixel
Provider: TikTok Technology Limited, 10 Earlsfort Terrace, Dublin, D02 T380, Ireland
Purpose: Ad measurement and target groups on TikTok, also in the shop (basket, checkout, purchases, registration)
Cookies and storage: _ttp, _tt_enable_cookie (13 months)
Privacy policy