Zum Inhalt springen
NeuSo funktioniert es

FirstSales in CI/CD & Skripten verwenden

Führen Sie die FirstSales-CLI in Pipelines aus — maskierte Secrets, Fail-Fast-Authentifizierung, Dry-Run bei PRs und Apply auf main, idempotente Schritte und abgesicherte destruktive Aktionen.

Tutorials
Entwickler & CLI
Min. Lesezeit
8 min
Schritte
7 · Experte

  1. Die CLI in Pipelines bevorzugen

    Für CI/CD-Jobs und lokale Skripte empfehlen die Docs die CLI gegenüber rohem HTTP: sie zentralisiert das Credential-Handling, gibt stabiles JSON aus, das Ihre Schritte parsen können, und behält die destruktiven Sicherungen, die Sie in der Automatisierung wollen. Ein Tool, ein Auth-Pfad, konsistente Ausgabe.

  2. Den Key als maskiertes Secret injizieren

    Speichern Sie Ihren Developer-API-Key im Secret-Store Ihres CI-Anbieters (GitHub-Actions-Secrets, GitLab-CI-Variablen usw.) und stellen Sie ihn als FIRSTSALES_API_KEY bereit. Hardcoden Sie ihn niemals in der Workflow-Datei. Die meisten CI-Systeme maskieren Secret-Werte automatisch in Logs: behalten Sie das bei, indem Sie den Key niemals echoen.

    # GitHub Actions job step
- name: FirstSales sync
  env:
    FIRSTSALES_API_KEY: ${{ secrets.FIRSTSALES_API_KEY }}
  run: |
    npm install -g @firstsales.io/cli
    firstsales whoami --json

  3. Bei ungültigem Key sofort fehlschlagen

    Beginnen Sie jeden Job mit whoami, damit die Pipeline sofort stoppt, wenn der Key falsch oder widerrufen ist, statt einen Sync halb auszuführen:

    firstsales whoami --json > /dev/null || {
  echo "FirstSales auth failed"; exit 1;
}

  4. Mit --dry-run planen, dann anwenden

    In der Automatisierung wollen Sie eine Vorschau, bevor Sie schreiben. Sichern Sie echte Mutationen hinter einem Plan-Schritt mit --dry-run ab (z. B. bei Pull Requests) und wenden Sie sie nur auf dem Main-Branch an:

    # PR / plan: preview only
firstsales contacts create --org "$ORG" --workspace "$WS" \
  --data-file ./new-lead.json --dry-run

# main / apply: real write, idempotent
firstsales contacts create --org "$ORG" --workspace "$WS" \
  --data-file ./new-lead.json \
  --idempotency-key "lead-${GITHUB_SHA}"

  5. Wiederholbare Schritte idempotent machen

    CI-Schritte werden wiederholt: durch instabile Runner, durch Menschen, die einen Job erneut ausführen. Leiten Sie einen --idempotency-key aus etwas Stabilem ab (ein Commit-SHA, eine Zeilen-ID, eine Run-Nummer), damit ein erneuter Lauf nicht doppelt anlegt:

    firstsales contact-imports create --org "$ORG" --workspace "$WS" \
  --data-file ./import.json \
  --idempotency-key "import-${CI_PIPELINE_ID}"

  6. Destruktive Schritte absichern

    Deletes erfordern --confirm, was in einer Pipeline genau richtig ist: Ein Cleanup-Job kann Daten nur entfernen, wenn das Flag explizit gesetzt ist. Halten Sie --confirm aus jedem Schritt heraus, der nicht löschen soll, und parsen Sie die --json-Ausgabe, um das Ergebnis zu verifizieren:

    firstsales connectors delete --org "$ORG" --workspace "$WS" \
  --connector "$STALE_ID" --confirm --json | jq -e '.deleted == true'

  7. JSON parsen, nicht scrapen

    Die gesamte Ausgabe ist standardmäßig JSON: leiten Sie sie an jq weiter, um Entscheidungen zu treffen, Job-Outputs zu setzen oder spätere Schritte zu gaten. Scrapen Sie niemals die App-UI oder rufen Sie private Endpoints aus CI auf; wenn ein Befehl unsupported_operation zurückgibt, lassen Sie den Schritt fehlschlagen und melden Sie es, statt einen Workaround zu suchen.

Profi-Tipps

  • whoami als erster Job-Schritt

    Eine einzeilige Auth-Prüfung am Anfang des Jobs verwandelt einen falschen/abgelaufenen Key in einen sofortigen, offensichtlichen Fehler statt in einen teilweisen, verwirrenden.

  • Idempotency-Keys aus CI-Variablen ableiten

    Commit-SHA, Pipeline-ID, Run-Nummer: jeder stabile Wert pro Lauf macht einen wiederholten Schritt zu einem sicheren No-op. Verwenden Sie niemals einen Zeitstempel oder Zufallswert; die untergraben den Zweck.

  • Zweiphasig: dry-run bei PRs, apply auf main

    Spiegelt Infrastructure-as-Code. --dry-run bei Pull Requests zeigt den Diff zur Review; die echte Schreibaktion läuft erst nach dem Merge. Günstige Absicherung für irreversible Aktionen.

  • Auf der JSON-Ausgabe asserten

    Leiten Sie --json an jq -e weiter, damit der Schritt tatsächlich fehlschlägt, wenn das Ergebnis nicht dem erwarteten entspricht, statt mit Exit-Code 0 bei einem stillen Fehler zu enden.

Häufig gestellte Fragen

Sollte CI die CLI oder die API verwenden?

Die CLI. Für CI/CD und Skripte wird sie gegenüber rohem HTTP empfohlen, weil sie das Credential-Handling und die Ausgabe standardisiert und die eingebauten Sicherungen für destruktive Operationen beibehält.

Wie handhabe ich den API-Key in CI?

Legen Sie ihn im Secret-Store Ihres CI-Anbieters ab und stellen Sie ihn als FIRSTSALES_API_KEY bereit. Hardcoden Sie ihn nicht in den Workflow und echoen Sie ihn niemals: die meisten CI-Systeme maskieren Secrets in Logs nur, wenn Sie sie nicht selbst ausgeben.

Wie kann ich eine Änderung vorab ansehen, bevor sie läuft?

Nutzen Sie --dry-run, um den Request auszugeben, ohne ihn zu senden. Ein gängiges Muster ist Dry-Run bei Pull Requests und die echte Schreibaktion nur auf dem Main-Branch.

Wie mache ich einen Schritt sicher wiederholbar?

Übergeben Sie --idempotency-key, abgeleitet aus einem stabilen Wert wie dem Commit-SHA oder der Pipeline-ID. Ein wiederholter Schritt mit demselben Key ist ein No-op statt eines doppelten Schreibvorgangs.

Wie verhindere ich, dass ein Cleanup-Job zu viel löscht?

Deletes erfordern --confirm, sodass ein Schritt nur Daten entfernen kann, wenn das Flag explizit gesetzt ist. Halten Sie es aus nicht-destruktiven Schritten heraus und asserten Sie mit jq -e auf dem --json-Ergebnis.

Kann ich Entscheidungen aus der Ausgabe treffen?

Ja: die Ausgabe ist standardmäßig JSON. Leiten Sie sie an jq weiter, um spätere Schritte zu gaten oder Job-Outputs zu setzen. Scrapen Sie nicht die UI; melden Sie den Schritt bei unsupported_operation als fehlgeschlagen.

Entwickler & CLI

Akquise, die weiterläuft, wenn du offline bist.Leads, E-Mails, Follow-ups und Antworten, erledigt.

Verbinde unbegrenzte Postfächer und lass KI-Agenten Leads finden, jede E-Mail schreiben und nachfassen. Oder sende deine eigenen Vorlagen im manuellen Modus. Ab $29/Monat.

Starte deine $1-Testphase Preise ansehen

$1 für 3 Tage · Jederzeit kündbar · Kein Vertrag

Mit KI installieren

Dein Coding-Agent richtet die FirstSales CLI und Skills für dich ein.

Prompt für Claude Code

I'm setting up FirstSales (https://firstsales.io), an AI outbound sales platform: campaigns, contacts, a reply inbox, deliverability and lead signals. Help me get my workspace sending real, good emails end to end, from Claude Code.

Read these first so you know how FirstSales works:
- Developer docs and API: https://developer.firstsales.io
- CLI: https://www.npmjs.com/package/@firstsales.io/cli
- Skills for coding agents: https://github.com/firstsalesio/firstsales-skills (read README.md and GUIDE.md)

Setup
1. Install the CLI: npm install -g @firstsales.io/cli
2. Install the FirstSales skills:
   claude plugin marketplace add firstsalesio/firstsales-skills
   claude plugin install firstsales@firstsales
3. Ask me if I already have a FirstSales account. If not, send me to https://app.firstsales.io to sign up.
4. Ask me to create an API key under Settings → API → API Keys, with only the scopes we need.
   Never ask me to paste the key into this chat. Tell me to run this in my own terminal, so the key stays hidden:
   read -rs FS_KEY && firstsales auth login --api-key "$FS_KEY"; unset FS_KEY
5. Run `firstsales whoami` and tell me which workspace and organisation we are connected to.

Then ask me about my business: what I sell, who I sell to (roles, company size, countries), my best customers, and what I use today for outbound (tools, lists, mailboxes). Walk me through:
1. Teaching FirstSales my business: website, offer, proof points and case studies in the knowledge base, so the AI writes like someone who knows the product.
2. Connecting my sending mailboxes and checking my sending domain: SPF, DKIM, DMARC and warm-up. If anything is unhealthy, tell me the exact DNS record to add.
3. Bringing in contacts: import my CSV or CRM export into a clean list, remove duplicates and bad emails, and block domains I must never email (customers, competitors, my own).
4. Building my first campaign: the right list, senders, steps and timing. Write the sequence with me, show me the drafts, and do not launch until I say yes.
5. Setting up Signals if it fits: find people engaging with LinkedIn posts about topics my buyers care about, and turn them into leads.
6. Inviting my team and giving each person the right access.

Once campaigns run, show me how to work the reply inbox from here: which replies need an answer, draft responses in my voice, and move good conversations into deals. If I use Cal.com, connect it so follow-ups can offer my booking link (not the first email).

Throughout, as you learn about my business, proactively suggest and help create:
- Reply templates for the questions and objections my prospects are likely to raise, based on my product, site and codebase if you can see them.
- Campaign ideas and segments worth testing, with the reason for each.

Safety rules:
- Show every change as a dry run (--dry-run) first and wait for my yes. Never send emails, launch campaigns or delete anything without my yes.
- Tell me before anything that spends credits, and how many.

Be opinionated. If the docs give a sensible default, just use it. Don't make me choose between five options.
Developer docs ↗npm: @firstsales.io/cli ↗GitHub: firstsales-skills ↗