ENDE
Back to home

Honeycup 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 CLI comes onto your own computer. CLI means command-line tool, a program you do not 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 Honeycup 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:

honeycup --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: honeycup --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 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:

honeycup 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, honeycup login --site "$WP_AGENT_SITE" --no-open prints an address that you can open yourself. Use honeycup 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 honeycup init for this normal CLI login. For the other route, use the connection file from the connection guide.

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

Diagnostics

honeycup 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 honeycup logout --site "$WP_AGENT_SITE" --force, then honeycup 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 Honeycup 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 Honeycup control center.
  7. Connection: Are your assistant's tools reachable? If this fails while the plugin is active, run the external connection diagnosis on the plugin’s connection page and check its hints about a firewall, CDN, or security plugin.

For an individual check, use honeycup preflight for the bot role and honeycup abilities for the tool list. honeycup login connects the CLI. honeycup 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.