NeuSo funktioniert es
FirstSales
Startseite/Tutorials/FirstSales CLI-Schnellstart
Entwickler & CLI

FirstSales CLI-Schnellstart

Installieren Sie die FirstSales-CLI, authentifizieren Sie sich mit einem API-Schlüssel und führen Sie Ihre ersten sicheren Befehle aus — whoami, Org-/Workspace-Erkennung, Dry-Run und Idempotenz.

8 Min. Lesezeit·Experte·7 Schritte
  1. 1

    Die CLI installieren

    Die FirstSales-CLI ist ein npm-Paket. Installieren Sie sie global, um das Binary firstsales zu erhalten:

    npm install -g @firstsales.io/cli
firstsales --version
  2. 2

    Authentifizieren

    Erstellen Sie einen Developer-API-Key unter Settings → API und übergeben Sie der CLI dann den Key und die Basis-URL. Der sauberste Weg sind Umgebungsvariablen:

    export FIRSTSALES_API_KEY="fs-key-..."
export FIRSTSALES_BASE_URL="https://api.app.firstsales.io"
  3. 3

    Mit whoami und doctor überprüfen

    Bevor Sie irgendetwas tun, bestätigen Sie, dass der Key den richtigen Kontext auflöst. whoami zeigt Ihren Nutzer, Ihre Organisation und Ihren Workspace; doctor prüft Ihr Setup:

    firstsales whoami --json
firstsales doctor
  4. 4

    Die globalen Flags verstehen

    Jeder Befehl teilt sich dieselben Flags — lernen Sie diese einmal:

    • --org <id> / --workspace <id> — Ziel-Scope (die meisten Befehle brauchen beide).
    • --json (Standard) / --pretty — Ausgabeformat.
    • --data '<json>' / --data-file <path> — Request-Body.
    • --idempotency-key <key> — sichere Wiederholungen bei Creates.
    • --dry-run — Vorschau des Requests, ohne ihn zu senden.
    • --confirm — erforderlich für jeden destruktiven (Delete-)Befehl.
    • --api-key / --base-url / --profile — Auth pro Aufruf überschreiben.
  5. 5

    Ihre Organisation und Ihren Workspace ermitteln

    Die meisten Befehle sind auf eine Organisation und einen Workspace eingegrenzt. Listen Sie sie auf und wiederverwenden Sie dann die IDs:

    firstsales organizations list
firstsales workspaces list --org ORG_ID
firstsales campaigns list --org ORG_ID --workspace WS_ID
  6. 6

    Eine sichere erste Änderung vornehmen

    Folgen Sie der goldenen Schleife: zuerst prüfen, bewusst ändern, danach verifizieren. Erst mit --dry-run eine Vorschau erstellen, dann mit einem Idempotency-Key anlegen, dann erneut lesen, um zu bestätigen:

    # Vorschau — es wird nichts geschrieben
firstsales contacts create --org ORG_ID --workspace WS_ID \
  --data '{"email":"jane@acme.com","first_name":"Jane"}' --dry-run

# Tatsächlich erstellen, idempotent
firstsales contacts create --org ORG_ID --workspace WS_ID \
  --data '{"email":"jane@acme.com","first_name":"Jane"}' \
  --idempotency-key jane-acme-2026-01

# Verifizieren
firstsales contacts list --org ORG_ID --workspace WS_ID
  7. 7

    Bewusst löschen

    Destruktive Befehle weigern sich, ohne --confirm auszuführen — das ist beabsichtigte Reibung, damit ein Agent oder ein Vertipper keine Daten versehentlich löschen kann:

    firstsales contacts delete --org ORG_ID --workspace WS_ID \
  --contact CONTACT_ID --confirm

Profi-Tipps

Hart erarbeitete Abkürzungen, damit die Aufwärmung auf Kurs bleibt.

1

Zuerst prüfen, bewusst ändern, danach verifizieren

Die CLI ist um diese Schleife herum gebaut. Auflisten vor dem Ändern, die Änderung mit --dry-run testen, ausführen, dann erneut lesen, um zu bestätigen. Es dauert länger zu tippen, ist aber weit günstiger als eine fehlerhafte Schreibaktion rückgängig zu machen.

2

--json ist für Maschinen, --pretty ist für Sie

Die Ausgabe ist standardmäßig kompaktes JSON, damit Skripte und Agenten es parsen können. Fügen Sie --pretty hinzu, wenn ein Mensch liest, aber behalten Sie --json in Pipelines bei.

3

Ihren Key niemals ausgeben

Übergeben Sie die Authentifizierung über FIRSTSALES_API_KEY oder ein Profil, nicht inline, wo er in der Shell-History oder in Logs landet. Die CLI gibt niemals rohe Keys aus — machen Sie das nicht rückgängig, indem Sie die Umgebungsvariable echoen.

4

Idempotency-Keys sind kostenlose Absicherung

Jedes Create, das wiederholt werden könnte, sollte --idempotency-key mitführen. Ein wiederholter Befehl wird so zu einem No-op statt zu einem Duplikat.

Häufig gestellte Fragen

Wie installiere ich die CLI?

npm install -g @firstsales.io/cli, wodurch Sie das Binary firstsales erhalten. Es bildet direkt auf die öffentliche Developer-API /api/v1 ab.

Wie funktioniert die Authentifizierung?

Setzen Sie FIRSTSALES_API_KEY (und optional FIRSTSALES_BASE_URL) in Ihrer Umgebung, oder übergeben Sie --api-key / --base-url pro Befehl. Überprüfen Sie mit firstsales whoami --json.

Warum benötigen Befehle --org und --workspace?

Ressourcen sind auf eine Organisation und einen Workspace eingegrenzt. Listen Sie sie mit organizations list und workspaces list --org ORG_ID auf und übergeben Sie dann beide IDs bei eingegrenzten Befehlen.

Was macht --dry-run?

Es gibt den Request aus, den die CLI senden würde, ohne ihn tatsächlich zu senden — so können Sie Body und Ziel vor einer echten Mutation bestätigen.

Warum wird mein Delete nicht ausgeführt?

Destruktive Befehle erfordern by Design das Flag --confirm. Fügen Sie --confirm hinzu, sobald Sie sicher sind — es ist die Sicherung, die versehentliche Löschungen stoppt.

Unterscheidet sich die CLI von der API?

Sie ist ein dünner Wrapper über dieselben öffentlichen /api/v1-Endpoints. Die CLI fügt Komfort hinzu — zentralisierte Authentifizierung, stabiles JSON, Idempotency-Handling und Bestätigung destruktiver Operationen — damit Agenten und Skripte das nicht neu implementieren müssen.

Kann ich mehrere Accounts konfiguriert halten?

Ja — nutzen Sie --profile <name>, um ein gespeichertes lokales Profil zu laden, oder überschreiben Sie --api-key/--base-url pro Befehl, um zwischen Organisationen oder Umgebungen zu wechseln.

Bereit, das in die Praxis umzusetzen?

Starten Sie Ihre FirstSales-Testphase und richten Sie in wenigen Minuten ein aufgewärmtes, authentifiziertes Postfach ein.

Für 1 $ starten
Alle Tutorials