AI-Entwicklung

Wie die Cloudflare-cf-CLI JSON nutzt, damit ein KI-Agent Befehle sucht und eine API aufruft (2026)

Ca. 15 Min.

Ein Agent muss nicht mehr als 2.900 Befehle auswendig lernen. Er sucht mit einem Satz, liest die API-Felder, die der Befehl senden wird, und führt ihn erst dann aus. Das Ergebnis ist eingerücktes JSON auf der Standardausgabe. Fortschritt und Fehler gehen auf die Standardfehlerausgabe. Das Modell füllt nur Argumente. cf ruft die Cloudflare-API auf.

Kurz vor dem Lesen

Objekt Öffentliche Fakten bis 2026-10-13 So nutzt es der Agent
cf Öffentliche Beta am 28. September. Deckt die ganze API ab. Doku: mehr als 2.900 Befehle. Installation über npm JSON ist Standard. Kein --json nötig
cf cli search Lokale Suche. Kein Login. Der ganze Satz in Anführungszeichen. Höchstens fünf Treffer, der beste zuerst Nur command und summary nehmen. Noch nicht ausführen
cf schema Beschreibt das HTTP eines generierten Befehls: Methode, Pfad, Parameter, Body-Felder Pflichtfelder zuerst. deploy und Ähnliches über --help
Ergebnis Doku vom 29. September: JSON ist immer eingerückt. Ein nicht-interaktives Löschen ohne --force kann Aborted. auf stderr schreiben und trotzdem mit 0 enden Zuerst das JSON auf stdout, dann den Exit-Code

Der Starttext sagte: hübsch für Menschen, komprimiert für Agenten. Die Doku vom 29. September sagt: JSON ist eingerückt, egal ob stdout ein Terminal ist. Eine öffentliche Prüfung von 1.0.0-beta.5 am 8. Oktober sah ebenfalls keine komprimierte Ausgabe. Parser folgen der Doku. orders.example.test ist erfunden.

Ein Agent steuert Cloudflare in drei JSON-Schritten, nicht durch Auswendiglernen

Cloudflare hat cf am 28. September veröffentlicht. Der Starttext nennt für März etwa ein Viertel der Wrangler-Nutzung durch Agenten und 48 Prozent in der Woche vor dem Start. Wrangler hatte rund 280 von Hand gebaute Befehle und deckte die API nicht ab. Die neue CLI entsteht aus OpenAPI. Die Doku vom 29. September nennt mehr als 2.900 Befehle. Installation: npm install --global cf. cf auth login braucht eine Person, die eine Browserseite freigibt. Unbeaufsichtigte Läufe setzen CLOUDFLARE_API_TOKEN, das einen gespeicherten Login überstimmt. Den Token nicht ins Repository schreiben. Der Platzhalter lautet sk_demo_not_real.

  • Suchen: cf cli search "create D1 database". Die Anführungszeichen bleiben. Die Suche läuft lokal und berührt das Konto nicht.
  • Prüfen: cf schema d1 create listet die HTTP-Felder, die gesendet werden. Vor einer echten Änderung --dry-run. Ein Probelauf braucht keine Zugangsdaten.
  • Ausführen: Die Standardausgabe ist nur das JSON-Ergebnis. Die gewählte Zone, Fehler und Aborted. gehen auf die Standardfehlerausgabe.

Das ist kein Agent, der Seiten anklickt. Wie ein Plugin-Verzeichnis einen MCP-Server in mcp.json ablegt: Verzeichnisvertrag von Agent Plugins 1.0.0. Wie ein MCP-tools/call aussieht: Wie ein Coding Agent MCP aufruft. Hier geht es nur um das JSON, das cf an den Agenten gibt.

Suchergebnisse sind ein Array mit höchstens fünf Objekten

Die Doku vom 29. September zeigt die ersten beiden Treffer in dieser Form. Die einzigen Felder sind command und summary:

[
  {
    "command": "cf d1 create",
    "summary": "Create D1 Database"
  },
  {
    "command": "cf d1 update",
    "summary": "Update D1 Database"
  }
]

Ohne Anführungszeichen gilt jedes Wort nach dem ersten als unbekannter Befehl. --help an der Wurzel und an Gruppen verweist zuerst auf die Suche. Das eigene --help eines Befehls ist Klartext, nicht dieses Array. Fehlt der Befehl, listet die CLI ähnliche Namen. Das ist kein Suchergebnis.

Zuerst die Anfrage lesen, die gesendet wird, danach die eine zurückgekommene Seite

cf schema gilt nur für generierte API-Befehle. cf deploy braucht --help. Die dokumentierten Schlüssel sind operationId, httpMethod, path, pathParams, queryParams, hasRequestBody und requestBodyFields. Parameter nutzen API-Namen wie account_id. Body-Felder nutzen Optionsnamen plus Beschreibung. Ist die Liste unvollständig, den ganzen Body mit --body übergeben. Unten dieselben Schlüssel als Beispiel, der Hostname ist erfunden und kein Mitschnitt aus der Produktion:

{
  "operationId": "dns-records-create",
  "httpMethod": "POST",
  "path": "/zones/{zone_id}/dns_records",
  "pathParams": [
    { "name": "zone_id", "type": "string", "required": true }
  ],
  "queryParams": [],
  "hasRequestBody": true,
  "requestBodyFields": [
    { "name": "type", "type": "string", "required": true, "description": "Record type" },
    { "name": "name", "type": "string", "required": true, "description": "Record name" },
    { "name": "content", "type": "string", "required": true, "description": "Record content" }
  ]
}

Pflichtfelder passieren das Tor vor dem Lauf. Warum das Tor nicht nur im Prompt stehen kann: Warum KI JSON Schema braucht. Die Standardausgabe eines Listenbefehls ist ein JSON-Array mit einer Seite. Die Blätter-Flags unterscheiden sich je Befehl. Änderungen ohne Daten lassen stdout leer. Rohe R2-Objekte oder Modellbilder gehen unverändert auf stdout, nicht als Objekt. Eine erfundene DNS-Seite:

[
  {
    "id": "rec_demo_1042",
    "type": "TXT",
    "name": "orders.example.test",
    "content": "demo-pass"
  }
]

Feldnamen hängen vom Befehl ab. Der Parser prüft zuerst, dass es ein Array ist, und nimmt dann id oder name aus dem Schema dieses Befehls. Nicht jede Seite hat eine Hülle namens success.

Standardausgabe, Standardfehler und Exit-Code nicht zu einem Erfolg zusammenziehen

Ein Agent fasst drei Signale leicht zu einem zusammen:

Was sichtbar ist Was es bedeutet
Eingerücktes JSON auf stdout Das ist das Ergebnis. Die Doku sagt: eingerückt, ob stdout ein Terminal ist oder nicht. Den Startsatz über komprimierte Agenten-Ausgabe nicht als aktuellen Vertrag nehmen.
Gewählte Zone, Fehler, Aborted. Auf stderr. Ein zerstörerischer Befehl ohne --force kann in einer nicht-interaktiven Sitzung nur Aborted. drucken und trotzdem mit Code 0 enden.
cf workers delete --force Bei manchen Befehlen ist --force auch ein API-Parameter. Er kann einen Worker löschen, auf den andere noch verweisen. Vor der Freigabe das Schema lesen.
Repository nur mit wrangler.jsonc Solange keine cloudflare.config.ts da ist, darf der Agent cf dev, cf build und cf deploy nicht starten. Zuerst cf migrate --dry-run.

Projekte mit Wrangler-Konfiguration bleiben bei Wrangler. Andere Cloudflare-Aufgaben gehen über cf. Der Satz gehört in AGENTS.md oder CLAUDE.md. --local gilt nur für einige KV-, D1- und R2-Befehle. cf d1 query hat kein lokales Gegenstück und gibt einen Fehler zurück, statt still die Live-API zu rufen.

Sechs Schritte, bevor ein Agent eine Live-Ressource ändert

Nicht damit anfangen, den Token in den Prompt zu kleben:

  1. Eine Person schließt cf auth login ab. Nur unbeaufsichtigt CLOUDFLARE_API_TOKEN setzen. Den Token nicht ins Befehls-JSON schreiben.
  2. Mit Anführungszeichen suchen. Der ganze Satz ist ein Argument. Zuerst die höchstens fünf Werte in command lesen.
  3. cf schema ausführen. Auf required achten. Ist die Liste unvollständig, auf --body und die API-Doku wechseln.
  4. Zuerst --dry-run. Es druckt das Anfrage-JSON, sendet nichts und braucht keine Zugangsdaten. Prüfen, dass der Pfad einen Demowert wie zone_demo_1042 enthält.
  5. Nur stdout parsen. Leere Ausgabe heißt: diese Änderung liefert keine Daten. Bei zerstörerischen Befehlen auf Aborted. in stderr achten.
  6. Wrangler-Projekte zuerst umziehen. Ohne cloudflare.config.ts nicht deployen. Bleibt TODO(@cloudflare) in einer generierten Datei, schlägt der Build fehl.

Nach der öffentlichen Beta bleibt Wrangler noch 18 Monate in Wartung. Beide können nebeneinander stehen. Im selben Projekt darf der Agent die alte Konfiguration nicht mit cf deploy überdecken.

Vor einer Schreibfreigabe drei JSON-Stücke aufklappen

Die meisten Fehler sind eine Suche ohne Anführungszeichen, ein Schema, das nicht zum Ergebnis passt, oder Exit-Code 0 als bereits erfolgte Löschung.

  • Such-Array und Schema Formatieren und mit Schema-Prüfung prüfen, ob jedes required: true in requestBodyFields vorhanden ist.
  • Mit JSONPath-Extraktion $[0].command, $.httpMethod und $.path ziehen.
  • Die --dry-run-Anfrage und die zurückgekommene Seite mit JSON-Diff vergleichen. Fehlende Felder füllen, bevor der Prompt geändert wird.
  • Steht Aborted. auf stderr, ist die Löschung nicht passiert.
  • Zone, Token und Konto-ID nicht in einen öffentlichen Formatierer kleben. JSONSort läuft lokal im Browser.

Stimmen die drei Stücke überein, ruft der Agent eine API auf und rät nicht an einem Befehl. Die Einrückung selbst ist kein Fehler.

Häufige Fehler

  • Wegen des Starttexts auf komprimiertes JSON warten. Die aktuelle Doku sagt: immer eingerückt. Die Prüfung von beta.5 am 8. Oktober sah keine kürzere Ausgabe, nur weil ein Agent erkannt wurde.
  • Die Suche nicht in Anführungszeichen setzen. Das zweite Wort wird ein unbekannter Befehl. Suchergebnis und Liste ähnlicher Namen sind nicht dasselbe JSON.
  • Exit-Code 0 als erfolgreiche Löschung lesen. Ohne --force kann ein nicht-interaktiver Lauf nur abgebrochen worden sein. stderr mitlesen.
  • cf deploy in einem Repository starten, das nur wrangler.jsonc hat. Es kann eine neue Konfiguration erzeugen und die alte ungenutzt lassen. Die Migration zuerst mit dry-run prüfen.
  • Den API-Token in den Prompt oder in JSON schreiben, das committet wird. Unbeaufsichtigt nur die Umgebungsvariable. Im Beispiel keinen echten Token verwenden.
  • cf als Agent beschreiben, der selbst den Browser anklickt. Den Login gibt eine Person frei. Danach sind die API-Aufrufe JSON der CLI, keine Seitenklicks.

FAQ

Muss ein Agent bei jedem Befehl noch --json setzen?

Nein. Ergebnisse von cf sind standardmäßig JSON auf stdout. --json und Tabellen gehören zu Wrangler. Nach der Doku vom 29. September ist dieses JSON eingerückt. Auf ein komprimiertes Format warten lohnt nicht.

Nutzt cf cli search mein Konto?

Nein. Die Suche ist lokal und braucht keine Zugangsdaten. Sie liefert höchstens fünf Objekte, jedes mit command und summary. Ressourcen ändert erst der folgende Befehl.

Ist fehlendes JSON ein Fehler?

Nicht immer. Änderungen ohne Rückgabedaten lassen stdout leer. Ein Fehler ist ein Exit-Code ungleich null, die Meldung steht auf stderr. Eine abgebrochene Löschung zeigt Aborted. auf stderr und kann trotzdem mit 0 enden.

Muss ein Wrangler-Projekt heute auf cf umgestellt werden?

Deploy muss nicht am selben Tag wechseln. Solange wrangler.jsonc oder wrangler.toml vorliegt, bleiben Entwicklung, Build und Deploy bei Wrangler. Der Umzug nach cloudflare.config.ts läuft über cf migrate, zuerst mit --dry-run. Nach der öffentlichen Beta bleibt Wrangler 18 Monate in Wartung.

Was tun, wenn requestBodyFields unvollständig ist?

Die Doku sagt, dass requestBodyFields bei manchen Befehlen unvollständig oder leer ist. Dann den ganzen Body mit --body senden und mit der API-Doku abgleichen. Eine leere Liste heißt nicht, dass die API keinen Body hat.

Fazit

cf ist der Weg, auf dem ein KI-Agent die Cloudflare-API über JSON aufruft. Die Suche liefert den Befehlsnamen, schema die Felder, die gesendet werden, stdout eine Ergebnisseite. Eingerücktes JSON parsen und stderr vom Exit-Code trennen.

Zuerst prüfen, dass cf d1 create aus dem Such-Array kommt, zone_id aus dem Schema und orders.example.test nur im Demo-Ergebnis steht. Stimmen die drei Stellen, darf die Live-Ressource geändert werden.

Weiterlesen

Änderungen: Erstveröffentlichung