ENDE
Zur Startseite

WPAgently-Dokumentation

CLI und Referenz für den Alltag

Die CLI ist ein kleines, dependency-freies Node-Programm. Diese Seite hält die Befehle fest, die du am Anfang wirklich brauchst. Alle Eingaben und Ausgaben findest du in der separaten Abilities-Referenz.

Schritt 3: CLI installieren (etwa 2 Minuten)

Jetzt kommt das kleine WPAgently-Programm auf deinen eigenen Rechner. Es heißt CLI (Command-Line-Tool), also ein Programm, das du nicht anklickst, sondern durch Tippen eines Befehls im Terminal startest. Diese CLI ist die Fernbedienung, mit der du gleich alles einrichtest und prüfst.

Die wp-agent-CLI kommt als Node-Paket im gelieferten Archiv wp-agent-<version>.tgz (<version> steht für die Versionsnummer, die im Dateinamen deines Downloads steht). Installiere sie global direkt aus diesem Archiv:

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

Prüfe danach die Installation:

wp-agent --help

Die Ausgabe muss die verfügbaren Befehle auflisten, unter anderem login, logout, preflight, abilities, doctor, article und landing. Wenn du diese Liste siehst, ist die CLI installiert.

Unter Windows erkennt die CLI ein natives wp.exe sowie die üblichen wp.bat- und wp.cmd-Launcher von WP-CLI und Local automatisch. Batchdateien werden aus Sicherheitsgründen nicht über cmd.exe ausgeführt. Liegt wie bei der offiziellen Installation wp-cli.phar daneben, startet WPAgently stattdessen PHP und das PHAR direkt. Falls WP-CLI oder PHP nicht im Suchpfad liegt, setze in PowerShell die absoluten Pfade:

$env:WP_AGENT_WP_CLI_BIN = "C:\Pfad\zu\wp.bat"
$env:WP_AGENT_PHP_BIN = "C:\Pfad\zu\php.exe"

WP_AGENT_WP_CLI_BIN akzeptiert alternativ wp.exe oder wp-cli.phar. Diese Variablen betreffen nur lokale Backup- und Restore-Läufe mit WP_AGENT_WP_PATH. Remote-Backups und normale REST- oder MCP-Verbindungen benötigen kein lokales WP-CLI.

Geschafft, wenn: wp-agent --help die Befehlsliste zeigt, statt einer Fehlermeldung wie „command not found“.

Schritt 4: CLI per Browser verbinden (etwa 3 Minuten)

Speichere zuerst nur die Basisadresse deiner Website in der Shell. Die Adresse enthält weder /wp-json noch einen abschließenden Slash:

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

Starte danach die Anmeldung:

wp-agent login --site "$WP_AGENT_SITE"

Die CLI registriert einen eigenen öffentlichen OAuth-Client, öffnet deinen Browser und wartet lokal auf die Antwort. Melde dich im WordPress-Backend an, wähle den Redakteur aus Schritt 2 und bestätige den Zugriff. Danach speichert die CLI kurzlebige Zugriffstokens und ein rotierendes Refresh-Token in deinem privaten lokalen Konfigurationsordner. Unter macOS und Linux sind Ordner und Datei nur für deinen Benutzer lesbar. Dein WordPress-Passwort und das Passwort des Redakteurs werden weder an die CLI übergeben noch gespeichert.

Standardmäßig speichert eine Site höchstens 200 OAuth-Clients, offene Anmeldungen und aktive Verbindungen. Große Installationen können diese Grenze serverseitig über wpagent_companion_oauth_max_clients anpassen. Erlaubt sind Ganzzahlen von 1 bis 10.000. Ungültige Werte fallen auf 200 zurück. Eine Erhöhung vergrößert den Optionsspeicher und sollte nur mit einem konkreten Kapazitätsbedarf erfolgen.

Falls kein Browser geöffnet werden kann, zeigt wp-agent login --site "$WP_AGENT_SITE" --no-open die Freigabeadresse zum manuellen Öffnen an. Mit wp-agent logout --site "$WP_AGENT_SITE" widerrufst du den Serverzugang und entfernst den lokalen Eintrag. --force ist nur für den Sonderfall gedacht, dass der Server dauerhaft nicht mehr erreichbar ist. Dann wird ausschließlich der lokale Eintrag entfernt.

Application Passwords bleiben als Fallback erhalten. Setze dafür WP_AGENT_USER und WP_AGENT_APP_PASSWORD oder übergib --user und --app-password. Ein ausdrücklich gesetzter Passwortzugang hat Vorrang vor dem gespeicherten OAuth-Zugang. Flags mit Zugangsdaten können in Prozesslisten und im Shell-Verlauf sichtbar sein. Die CLI lädt keine .env-Datei automatisch.

wp-agent init ist für die normale CLI-Anmeldung nicht erforderlich. Standardmäßig erzeugt der Befehl statische MCP-Verbindungsdateien für Claude Code, Codex, Cursor, Windsurf, Visual Studio Code, Gemini CLI, OpenCode, Cline, Roo Code, Kilo Code, Zed, GitHub Copilot, Amazon Q und Antigravity und benötigt dafür einen getrennten Benutzernamen und ein Application Password. Für Claude Code und Codex gibt es zusätzlich die benutzerweite OAuth-Registrierung aus Schritt 6. Sie benötigt kein WordPress-Passwort. Im geführten Ablauf hast du die passende Clientdatei bereits in Schritt 2 direkt aus WordPress heruntergeladen.

Geschafft, wenn: wp-agent login die erfolgreiche Verbindung meldet. Ab dann erneuert die CLI ablaufende Tokens automatisch.

Diagnose

Die sieben Checks von wp-agent doctor (siehe Schritt 5) im Detail. Der Befehl läuft sie der Reihe nach durch und meldet je Check OK oder FEHLER mit einem Klartext-Hinweis. Falls einer rot ist, findest du hier die Ursache:

  1. Erreichbarkeit: Ist die Seite unter WP_AGENT_SITE erreichbar, und antwortet die technische Schnittstelle unter /wp-json mit den erwarteten Daten (JSON)? Häufigster Anfängerfehler: Bei „Einfach“-Permalinks liefert /wp-json/ die Startseite als HTML statt der erwarteten Daten. Dieser Check erkennt das und gibt dir einen Permalink-Hinweis, statt fälschlich grün zu sein. Abhilfe: Pretty-Permalinks aktivieren (Einstellungen > Permalinks).
  2. Auth: Meldet der gespeicherte OAuth-Zugang den ausgewählten Redakteur korrekt an? Die CLI erneuert ein bald ablaufendes Token automatisch. Ein Fehler bedeutet meist, dass der Zugang serverseitig widerrufen wurde. Führe dann wp-agent logout --site "$WP_AGENT_SITE" --force und anschließend wp-agent login --site "$WP_AGENT_SITE" aus. Beim Passwort-Fallback prüfst du stattdessen Benutzername und Application Password.
  3. Bot-Rolle: Trägt der Bot die Rolle Editor und nicht Administrator? Das ist dieselbe Prüfung wie wp-agent preflight; Admin-Rechte sind ein harter Stopp und Absicht.
  4. Lizenz: Ist die lokale Lizenzbestätigung gültig und innerhalb der erlaubten Offline-Frist?
  5. Steuerung: Sind der zentrale Schalter, der Domain Lock und das Ability-Profil gültig, und melden die serverseitigen Diagnosen keinen Fehler?
  6. Abilities: Sind alle laut Kontrollzentrum aktivierten Abilities angemeldet? Fehlen welche, prüfe das Profil und den Companion-Schalter unter WPAgently > Übersicht.
  7. MCP: Antwortet der Server unter <site>/wp-json/wp-agent/mcp sauber, und enthält tools/list die Werkzeuge für alle laut Kontrollzentrum aktivierten Abilities? Fehlt der Server trotz aktivem Plugin, ist das Plugin unvollständig ausgeliefert und muss neu gebaut werden.

Für eine gezielte Einzelprüfung wiederholen wp-agent preflight (Check 3) und wp-agent abilities (Check 6) denselben Aspekt isoliert. wp-agent login richtet den CLI-Zugang ein, gehört aber nicht zu den sieben Doctor-Checks. wp-agent init testet ebenfalls nichts. Der Befehl schreibt nur optionale statische Verbindungsdateien (siehe Schritt 4).

Die Gesamtarchitektur der installierbaren Bausteine beschreibt die Architektur-Dokumentation.