Cord-CLI

Melden Sie sich über den Browser an, richten Sie Ihr Konto ein, integrieren Sie Ihr Projekt und testen Sie Webhooks auf Ihrem localhost.

@flouviahq/cli ist ein Entwicklungswerkzeug: Es akzeptiert nur Testschlüssel (sk_test_ oder rk_test_), sodass nichts, was Sie damit tun, echte Daten berührt. Die Ausnahme ist cord setup: Es schlägt die Konfiguration Ihres echten Kontos vor und wendet nichts ohne Ihre Freigabe an.

Installation

Ohne Installation verwenden:

npx @flouviahq/cli

Oder global installieren, um den Befehl cord zu erhalten:

npm install -g @flouviahq/cli
cord --version

Die Beispiele auf dieser Seite verwenden cord; mit npx funktioniert es genauso, wenn Sie npx @flouviahq/cli voranstellen.

Befehle

Befehl	Funktion
`cord`	Ohne Befehl und in einem interaktiven Terminal öffnet sich der Assistent. Außerhalb eines Terminals wird die Hilfe ausgegeben.
`cord wizard`	Öffnet den Assistenten ausdrücklich.
`cord login`	Meldet Sie über den Browser an und speichert einen Testschlüssel.
`cord whoami`	Zeigt Organisation, Modus, Berechtigung und den verwendeten Schlüssel.
`cord logout`	Löscht den auf Ihrem Rechner gespeicherten Schlüssel.
`cord setup`	Schlägt die Konfiguration Ihres Kontos mit KI vor; Sie geben sie frei.
`cord init`	Erkennt Ihr Framework und richtet die Integration ein.
`cord listen`	Leitet Test-Webhooks an Ihren lokalen Server weiter.
`cord trigger`	Löst einen Test-Webhook aus.
`cord simulate`	Erzwingt das Ergebnis der nächsten steuerlichen Ausstellung oder simuliert den Kunden oder das Verstreichen von Zeit.
`cord events tail`	Zeigt Ereignisse an, sobald sie eintreten.
`cord help`	Die Hilfe. Auch `--help` oder `-h`.

Globale Optionen und Variablen

Option	Variable	Details
`--api-key <Schlüssel>`	`CORD_API_KEY`	Der zu verwendende Testschlüssel. Hat Vorrang vor dem gespeicherten.
`--base-url <url>`	`CORD_BASE_URL`	Ursprung von Cord. Standard `https://cordhq.app`.
`--version`, `-v`	—	Gibt die Version aus.
`--help`, `-h`	—	Gibt die Hilfe aus.

Der Schlüssel wird in dieser Reihenfolge gesucht: --api-key, CORD_API_KEY und der von cord login gespeicherte in ~/.config/cord/config.json (oder $XDG_CONFIG_HOME/cord/config.json), mit den Berechtigungen 0600. Ein Live-Schlüssel (sk_live_, rk_live_) oder ein öffentlicher Schlüssel (pk_) wird abgelehnt, bevor Cord aufgerufen wird.

Die Optionen akzeptieren sowohl --option wert als auch --option=wert.

Der Assistent

npx @flouviahq/cli

Verbinden Sie Ihr Terminal. Gibt es keine gültige Sitzung, öffnet sich die Anmeldung im Browser. Soll der Assistent Ihr Projekt integrieren, können Sie auf demselben Bildschirm einen geheimen Testschlüssel dafür erstellen.
Wählen Sie, was zu tun ist, mit den Pfeiltasten und der Leertaste: Ihr Konto mit KI einrichten, Cord in das Projekt integrieren und Webhooks auf Ihrem localhost testen.
Jeder Schritt läuft wie sein eigenständiger Befehl (setup, init, listen), und am Ende sehen Sie eine Zusammenfassung dessen, was bereit ist, und den nächsten Schritt.

Der Assistent benötigt ein interaktives Terminal. Verwenden Sie in Skripten und in der CI die eigenständigen Befehle.

`cord login`

cord login

Öffnet Ihren Browser mit einem Bestätigungscode (zum Beispiel WXYZ-2346). Prüfen Sie, ob er mit dem im Terminal übereinstimmt, und autorisieren Sie mit Ihrer Cord-Sitzung: Das Terminal erhält den Schlüssel selbstständig, und Sie müssen nichts kopieren.

Der Schlüssel ist eingeschränkt und für Tests bestimmt: Er kann nur die Simulatoren verwenden (test_helpers, Schreiben), Ereignisse lesen (eventos, Lesen) und Konfigurationen vorschlagen (setup, Schreiben).
Er läuft nach 90 Tagen ab und erscheint unter Entwickler › Schlüssel als CLI · <Name Ihres Rechners>, wo Sie ihn widerrufen können. Wenn Sie denselben Rechner erneut verbinden, wird der vorherige Schlüssel widerrufen.
Der Code läuft nach 10 Minuten ab, und der Schlüssel wird nur einmal übergeben.
Die CLI öffnet im Browser nur Adressen mit demselben Ursprung wie --base-url.

Variante	Funktion
`cord login --no-browser`	Gibt die Adresse aus, damit Sie sie auf einem anderen Rechner öffnen können (zum Beispiel auf einem Server per SSH).
`cord login --api-key`	Fordert Sie auf, einen eigenen Testschlüssel einzufügen, und prüft ihn vor dem Speichern.
`cord login --api-key sk_test_...`	Speichert diesen Schlüssel ohne Rückfrage, nachdem er geprüft wurde.

Für cord listen und cord init funktioniert auch ein normaler geheimer Testschlüssel: Hinterlegen Sie ihn in CORD_API_KEY.

`cord whoami` und `cord logout`

cord whoami

Empresa  Aceros del Norte
Modo     prueba
Permiso  write
Llave    sk_test_…9f2a

Die Oberfläche der CLI ist auf Spanisch. cord logout löscht die Konfigurationsdatei. Der Schlüssel wird dabei in Cord nicht widerrufen: Widerrufen Sie ihn dafür unter Entwickler › Schlüssel.

`cord setup`

cord setup --sitio materialesdelvalle.mx --descripcion "Building materials on 30-day credit" --archivo prices.xlsx

Option	Details
`--sitio <url>`	Ihre Website: Name, Marke und Kontaktdaten.
`--descripcion <text>`	Womit sich das Unternehmen beschäftigt, wie es Zahlungen erhält und welche Steuern es anwendet.
`--archivo <pfad>`	Preisliste: `.csv`, `.xlsx`, `.pdf` oder Foto, bis zu 3 MB.

Ohne Optionen fragt der Befehl dieselben Angaben Schritt für Schritt ab. Cord erstellt den Vorschlag, öffnet ihn in Ihrem Browser und wartet auf Ihre Freigabe (bis zu 30 Minuten; Enter beendet das Warten). Nichts wird angewendet, bevor Sie es freigeben. Der Vorschlag konfiguriert immer Ihr echtes Konto, auch mit einem Testschlüssel, und zählt zum Limit von 6 Vorschlägen pro Tag. Details unter Assistierte Einrichtung.

`cord init`

cord init

Erkennt das Framework im aktuellen Ordner, sagt Ihnen genau, was es tun wird, und führt es aus, wenn Sie zustimmen. Eine bestehende Datei wird nie überschrieben.

Framework	Installiert	Erstellt oder schlägt vor	Umgebungsdatei
Next.js (App Router)	`@flouviahq/node` und `@flouviahq/elements`	`app/api/webhooks/cord/route.ts` und den Proxy `app/api/cord/[...path]/route.ts` (unter `src/`, wenn `src/app` existiert)	`.env.local`
Astro	`@flouviahq/node` und `@flouviahq/elements`	`src/pages/api/webhooks/cord.ts`	`.env.local`
Next.js (Pages Router), Express	`@flouviahq/node` und `@flouviahq/elements`	Zeigt Ihnen die Webhook-Route zum Einfügen	`.env`
Laravel, Django, Flask, FastAPI	Nichts: Die SDKs für PHP und Python sind noch nicht veröffentlicht	Zeigt Ihnen eine Route, die die Signatur ohne Abhängigkeiten prüft	`.env`

Installiert wird mit dem Paketmanager Ihres Projekts, je nach Lockfile: pnpm, yarn, bun oder npm.
CORD_SECRET_KEY wird nur in eine Umgebungsdatei geschrieben, die Ihre .gitignore ignoriert. Gibt es keine, werden keine Schlüssel geschrieben, und Sie werden darauf hingewiesen.
Die erzeugte Route prüft die Signatur mit CORD_WEBHOOK_SECRET.

`cord listen`

cord listen --forward-to http://localhost:3000/api/webhooks/cord --env-file .env.local

Option	Details
`--forward-to <url>`	Pflichtangabe. `http://`- oder `https://`-URL Ihres lokalen Servers.
`--events <liste>`	Nur diese Ereignisse, durch Komma getrennt: `--events quote.paid,invoice.paid`. Ohne Angabe alle.
`--env-file <datei>`	Speichert dort das Secret der Sitzung als `CORD_WEBHOOK_SECRET`, ohne die übrigen Zeilen zu verändern.
`--allow-remote`	Erlaubt die Weiterleitung an einen Host, der nicht Ihr Rechner ist.

Cord kann keine Anfragen an Ihren Rechner senden, deshalb öffnet die CLI eine Empfangssitzung in Ihrer Testumgebung und fragt sie alle anderthalb Sekunden ab. Die Ereignisse durchlaufen dieselbe Engine wie in der Produktion (Signatur, API-Version, Verlauf), und die CLI leitet sie mit den echten Signatur-Headern weiter. Prüfen Sie mit constructEvent und dem Secret der Sitzung, genau wie in der Produktion.

│  17:04:12  200  quote.sent                 evt_9d2a6c4e1f8b3a5d7c0e2f4a6b8d1c3e  41 ms

Standardmäßig wird nur an localhost, 127.0.0.1, ::1 und Hosts *.localhost weitergeleitet. Die URL darf weder Benutzername noch Passwort enthalten, und einer Weiterleitung (Redirect) Ihres Servers wird nicht gefolgt.
Die Sitzung läuft nach 24 Stunden ab, Strg+C beendet sie. Pro Schlüssel können bis zu 3 Sitzungen geöffnet sein.
Das Secret der Sitzung ändert sich jedes Mal und gilt nur für diese Sitzung.
Ein Ereignis gilt als zugestellt, sobald die CLI es abholt. Antwortet Ihr Server nicht, zeigt die CLI das an und versucht es nicht erneut: Lösen Sie es mit cord trigger erneut aus.

`cord trigger`

cord trigger invoice.paid
cord trigger quote.approved --objeto 8b0c6f0e-2d55-4c1e-9a43-6a2f1c7d9e10

Löst eines der 41 Ereignisse des Katalogs an Ihre Test-Endpoints und Ihre Sitzungen von cord listen aus. Ohne --objeto mit Beispieldaten; mit der UUID eines Testangebots oder einer Testrechnung mit deren echten Daten. Die Zustellung läuft über die echte Engine: Signatur, Wiederholungsversuche und Verlauf in der Workbench.

`cord simulate`

cord simulate fiscal pac_caido
cord simulate quote 8b0c6f0e-2d55-4c1e-9a43-6a2f1c7d9e10 vista
cord simulate quote 8b0c6f0e-2d55-4c1e-9a43-6a2f1c7d9e10 vencer

Form	Wirkung
`simulate fiscal <ergebnis>`	Die nächste steuerliche Testausstellung ergibt `exito`, `pac_caido`, `receptor_invalido`, `certificado_vencido` oder `timbre_duplicado`.
`simulate quote <id> vista`	Der Kunde öffnet den Link: löst `quote.viewed` aus.
`simulate quote <id> vencer`	Das Angebot läuft ab: löst `quote.expired` aus. Nur bei einem gesendeten oder angesehenen Angebot.

Es sind dieselben Simulatoren wie in der API.

`cord events tail`

cord events tail --type quote.paid

Fragt den Ereignisverlauf alle 2 Sekunden ab und zeigt neue Ereignisse an, sobald sie eintreten, ab dem Moment, in dem Sie den Befehl starten. --type filtert nach einem Typ. Strg+C zum Beenden.

Häufige Fehler

Die Meldungen der CLI sind auf Spanisch.

Meldung	Was zu tun ist
`No hay sesión. Corre cord login…`	Es gibt keinen Schlüssel in `--api-key`, `CORD_API_KEY` oder in der Konfiguration.
`Esa es una llave en vivo…`	Die CLI verwendet nur Testschlüssel. Erstellen Sie einen `sk_test_`-Schlüssel oder verwenden Sie `cord login`.
`Falta --forward-to…`	`cord listen` benötigt die URL Ihres Servers.
`--forward-to apunta a <host>…`	Um außerhalb Ihres Rechners weiterzuleiten, ergänzen Sie `--allow-remote`.
`Ya hay 3 sesiones de escucha abiertas con esta llave…`	Schließen Sie eine mit Strg+C oder warten Sie, bis sie abläuft.

API-Fehler enthalten die request_id in Klammern: Suchen Sie sie unter Entwickler › Protokolle.

Installation

Befehle

Globale Optionen und Variablen

Der Assistent

cord login

cord whoami und cord logout

cord setup

cord init

cord listen

cord trigger

cord simulate

cord events tail