ENDE
Back to home

WPAgently documentation

CLI and everyday reference

The CLI is the program you run with commands in a terminal and is included with Paid. You do not need it for your first draft. This page covers installation, sign-in, and checks for repeatable workflows.

Step 3: install the CLI (about 2 minutes)

This and the next two CLI steps belong to Paid. With Free, use the method from the connection guide instead. The first safe task is in the quickstart.

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, you do not need a local WordPress setup for the normal connection. The following settings are only needed for a local backup or restore when WP-CLI or PHP cannot be found. Skip this block unless that is exactly your situation:

$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 settings apply only to local backups and restores using WP_AGENT_WP_PATH. You do not need a local WP-CLI installation for the normal connection.

The CLI uses German for its own messages by default. If you want English messages, add --locale en to a command or set WP_AGENT_LOCALE=en in your terminal. This changes only CLI messages, not the language of content an assistant creates.

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)

This browser OAuth route through the WPAgently CLI belongs to Paid. First install the CLI as described in the CLI guide. With Free, use the method from the connection guide.

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 opens your browser and waits for your approval. Sign in to WordPress there, select the Editor from the connection guide, and approve access. The CLI can then renew the connection on your own computer. Your regular WordPress password and the Editor password are not passed to or stored by the CLI.

If the browser cannot open automatically, wp-agent login --site "$WP_AGENT_SITE" --no-open prints an address that you can open yourself. Use wp-agent logout --site "$WP_AGENT_SITE" to disconnect later. Use --force only when your site is permanently unreachable. It then removes only the local record.

An Application Password remains the technical fallback. Use it only when browser OAuth is not possible, and never enter credentials in a shared terminal or shared file. You do not need wp-agent init for this normal CLI login. For the other route, use the connection file from the connection guide.

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

Diagnostics

wp-agent doctor shows a clear hint for every check. If one fails, solve that exact hint first. This overview helps you understand what each check asks:

  1. Reachability: Is your website reachable? Check the permalinks first. On a new site that is not yet public, you can select “Post name” under Settings > Permalinks and save. If your website is already public, do not change its permalink structure without a redirect plan. Ask the person responsible for your website or your hosting provider for help.
  2. Sign-in: Can the stored connection sign in as your Editor? If access was revoked, run wp-agent logout --site "$WP_AGENT_SITE" --force, then wp-agent login --site "$WP_AGENT_SITE".
  3. Bot role: Does the bot have the Editor role rather than Administrator? Administrator rights are deliberately a hard stop.
  4. Licence: Is your licence valid?
  5. Control: Is WPAgently correctly activated on this website?
  6. Abilities: are all abilities enabled by the control center registered? If any are missing, check the feature profile and Companion switch in the WPAgently control center.
  7. Connection: Are your assistant's tools reachable? If this fails while the plugin is active, run the external connection diagnosis under WPAgently > Connect agent and check its hints about a firewall, CDN, or security plugin.

For an individual check, use wp-agent preflight for the bot role and wp-agent abilities for the tool list. wp-agent login connects the CLI. wp-agent init writes connection files or registers Claude Code or Codex with --scope user --i-approve. It does not replace sign-in or the connection check with doctor.

The overall architecture is described in the architecture documentation.