ENDE
Back to home

WPAgently documentation

CLI and everyday reference

The CLI is a small dependency-free Node program. This page covers the commands you actually need at the start. Every input and output is documented in the separate abilities reference.

Step 3: install the CLI (about 2 minutes)

Now the small WPAgently program comes onto your own computer. It's called a CLI (command-line tool), a program you don't click but start by typing a command in your terminal. This CLI is the remote control you'll use to set everything up and check it.

The wp-agent CLI ships as a Node package in the delivered archive wp-agent-<version>.tgz (<version> stands for the version number, which appears in the file name of your download). Install it globally directly from this archive:

npm install -g wp-agent-<version>.tgz

Then verify the installation:

wp-agent --help

The output must list the available commands, including login, logout, preflight, abilities, doctor, article, and landing. If you see this list, the CLI is installed.

On Windows, the CLI automatically recognizes a native wp.exe and the usual WP-CLI or Local wp.bat and wp.cmd launchers. It never executes batch files through cmd.exe. When the official adjacent wp-cli.phar exists, WPAgently launches PHP and the PHAR directly. If WP-CLI or PHP is not on PATH, set their absolute paths in PowerShell:

$env:WP_AGENT_WP_CLI_BIN = "C:\path\to\wp.bat"
$env:WP_AGENT_PHP_BIN = "C:\path\to\php.exe"

WP_AGENT_WP_CLI_BIN may point to wp.exe or wp-cli.phar instead. These variables apply only to local backup and restore runs that use WP_AGENT_WP_PATH. Remote backups and normal REST or MCP connections do not require a local WP-CLI installation.

By default, the CLI's own output (help text, error messages, prompts) is in German. To get English output instead, pass --locale en (alias --lang en) on any command, or export WP_AGENT_LOCALE=en in your shell so it applies to every invocation. A CLI flag always wins over the environment variable, and both fall back to German (de) if unset. This setting controls only the CLI's own messages, not the language of the content an agent generates through the pipelines.

Done when: wp-agent --help shows the command list instead of an error like "command not found".

Step 4: connect the CLI through the browser (about 3 minutes)

First, store only the base address of your site in the shell. Do not include /wp-json or a trailing slash:

export WP_AGENT_SITE="https://your-domain.tld"

Then start the login:

wp-agent login --site "$WP_AGENT_SITE"

The CLI registers its own public OAuth client, opens your browser, and waits locally for the response. Sign in to the WordPress backend, select the Editor from step 2, and approve access. The CLI then stores a short-lived access token and a rotating refresh token in your private local configuration directory. On macOS and Linux, only your user can read the directory and file. Neither your WordPress password nor the Editor's password is given to or stored by the CLI.

By default, a site stores at most 200 OAuth clients, pending sign-ins, and active connections. Large installations can adjust this server-side through wpagent_companion_oauth_max_clients. Valid values are integers from 1 through 10,000. Invalid values fall back to 200. Increasing the limit grows option storage and should be done only for a concrete capacity need.

If the browser cannot open automatically, wp-agent login --site "$WP_AGENT_SITE" --no-open prints the consent URL for manual opening. wp-agent logout --site "$WP_AGENT_SITE" revokes server access and removes the local record. Use --force only if the server is permanently unreachable. It removes the local record without claiming to have revoked the server grant.

Application Passwords remain available as a fallback. Set WP_AGENT_USER and WP_AGENT_APP_PASSWORD, or pass --user and --app-password. Explicit password credentials take precedence over stored OAuth credentials. Credential flags can be visible in process lists and shell history. The CLI does not load a .env file automatically.

wp-agent init is not required for normal CLI login. By default, it creates static MCP connection files for Claude Code, Codex, Cursor, Windsurf, Visual Studio Code, Gemini CLI, OpenCode, Cline, Roo Code, Kilo Code, Zed, GitHub Copilot, Amazon Q, and Antigravity and requires a separate username and Application Password for that purpose. Claude Code and Codex additionally support the user-wide OAuth registration in step 6, which needs no WordPress password. In this guided flow, you already downloaded the appropriate client file directly from WordPress in step 2.

Done when: wp-agent login reports a successful connection. The CLI automatically renews expiring tokens from then on.

Diagnostics

You can also run an external connection diagnosis under WPAgently > Connect agent. Without sending credentials, WordPress requests its public REST API, MCP endpoint, and OAuth metadata through the normal website address. This reveals many CDN, firewall, and security-plugin blocks that a purely internal check cannot see. Detected intermediaries and known active security plugins are shown as hints, not automatically blamed as the cause. If a connection that was used successfully later loses authentication, WPAgently also warns administrators and links directly to this diagnosis.

The seven checks of wp-agent doctor (see step 5) in detail. The command runs through them in order and reports OK or ERROR per check with a plain-text hint. If one comes back red, here's the cause:

  1. Reachability: is the site reachable at WP_AGENT_SITE, and does the technical interface at /wp-json respond with the expected data (JSON)? Most common beginner mistake: with "Plain" permalinks, /wp-json/ returns the homepage as HTML instead of the expected data. This check detects that and gives you a permalink hint instead of falsely showing green. Fix: enable pretty permalinks (Settings > Permalinks).
  2. Auth: does the stored OAuth grant sign in the selected Editor correctly? The CLI refreshes a token before it expires. A failure usually means the server grant was revoked. Run wp-agent logout --site "$WP_AGENT_SITE" --force, then wp-agent login --site "$WP_AGENT_SITE". With the password fallback, check the username and Application Password instead.
  3. Bot role: does the bot carry the Editor role and not Administrator? This is the same check as wp-agent preflight; admin rights are a hard stop, and that's deliberate.
  4. License: is the local license proof valid and within the permitted offline grace period?
  5. Control: are the master switch, domain lock, and ability profile valid, with no failed server-side diagnostics?
  6. Abilities: are all abilities enabled by the control center registered? If any are missing, inspect the profile and master switch under WPAgently > Overview.
  7. MCP: does the server at <site>/wp-json/wp-agent/mcp respond cleanly, and does tools/list contain the tools for every ability enabled by the control center? If the server is missing despite the plugin being active, the plugin was shipped incompletely and needs to be rebuilt.

For a targeted individual check, wp-agent preflight (check 3) and wp-agent abilities (check 6) repeat the same aspect in isolation. wp-agent login establishes CLI access but is not one of the seven Doctor checks. wp-agent init also tests nothing. It only writes optional static connection files (see step 4).

The overall architecture is described in the architecture documentation.