Accueil/Tutoriels/Utiliser FirstSales avec Claude Code

Développeur & CLI

Utiliser FirstSales avec Claude Code

Pilotez FirstSales depuis Claude Code via la CLI — installez, authentifiez-vous, inspectez avant de modifier et n'exposez jamais votre clé API dans la sortie de l'agent.

8 min de lecture·Avancé·7 étapes

1
Pourquoi le CLI pour Claude Code
Claude Code a accès au shell, il devrait donc piloter FirstSales via le CLI, pas du HTTP brut. Le CLI centralise l'authentification, renvoie un JSON stable que l'agent peut parser, gère les en-têtes d'idempotence, et impose une confirmation sur les opérations destructrices — tout ce que vous devriez sinon demander à l'agent de faire correctement à chaque fois.
Règle empirique tirée de la documentation : les agents devraient privilégier le CLI dès lors qu'un accès shell existe.
2
Installez et exposez la clé
Installez le CLI une fois, et donnez à Claude Code la clé via l'environnement afin qu'elle n'apparaisse jamais dans un prompt ou une transcription :
```
npm install -g @firstsales.io/cli
export FIRSTSALES_API_KEY="fs-key-..."   # set in your shell, not in the chat
```
3
Donnez à l'agent ses règles de fonctionnement
Collez un court contrat opérationnel dans Claude Code (ou un fichier de règles projet) afin qu'il se comporte de manière sûre :
- Démarrer chaque session avec firstsales whoami --json ; confirmer l'org et le workspace avant d'agir.
- Inspecter d'abord, muter délibérément, vérifier ensuite.
- Utiliser --idempotency-key sur toute création susceptible d'être retentée.
- N'utiliser --confirm que pour une suppression intentionnelle demandée par l'utilisateur.
- Ne jamais afficher les clés API en clair.

L'exploration en lecture seule est toujours sans risque

Encouragez l'agent à explorer librement avec les commandes list/get — elles ne peuvent rien endommager :

firstsales campaigns list --org ORG_ID --workspace WS_ID --json
firstsales contacts list --org ORG_ID --workspace WS_ID --json
firstsales billing overview --org ORG_ID --json

Mutations : prévisualiser, agir, vérifier

Pour tout ce qui écrit, demandez à Claude Code de suivre la boucle jusqu'au bout — --dry-run, puis l'appel réel avec une clé d'idempotence, puis une relecture :

firstsales contacts create --org ORG_ID --workspace WS_ID \
  --data '{"email":"lead@acme.com","first_name":"Sam"}' --dry-run

firstsales contacts create --org ORG_ID --workspace WS_ID \
  --data '{"email":"lead@acme.com","first_name":"Sam"}' \
  --idempotency-key sam-acme-2026-01

firstsales contacts list --org ORG_ID --workspace WS_ID --json

Approuvez ou rejetez les brouillons IA depuis le terminal

Une boucle Claude Code utile : passer en revue les réponses IA en attente et agir dessus sans ouvrir l'app. Listez les threads, lisez-en un, puis approuvez ou rejetez le brouillon :

firstsales inbox threads --org ORG_ID --workspace WS_ID
firstsales inbox thread --org ORG_ID --workspace WS_ID --thread THREAD_ID
firstsales inbox approve-draft --org ORG_ID --workspace WS_ID \
  --email EMAIL_ID --idempotency-key approve-EMAIL_ID

7
Respectez la surface publique
Indiquez à l'agent de rester sur les commandes publiques du CLI. Si une commande renvoie unsupported_operation, il doit s'arrêter et le signaler — sans tenter d'appeler des routes privées de l'app, des callbacks de fournisseur, des pixels de tracking, des gestionnaires de désabonnement ou des endpoints cron internes pour forcer le résultat.

Astuces de pro

Des raccourcis chèrement acquis pour garder le préchauffage sur la bonne voie.

Placez les règles de fonctionnement dans un fichier de règles projet

Plutôt que de recoller le contrat de sécurité à chaque session, déposez-le dans votre fichier de règles projet Claude Code afin que chaque run démarre par whoami et la boucle inspecter-muter-vérifier.

La clé dans l'environnement, jamais dans le chat

Exportez FIRSTSALES_API_KEY dans le shell où Claude Code s'exécute. Si la clé est dans un prompt, elle finit dans la transcription — le CLI la garde hors de la sortie, ne l'y remettez pas.

Laissez-le lire librement, verrouillez les écritures

Les commandes list/get/analytics sont sûres à exécuter sans supervision. Réservez votre relecture à tout ce qui implique create/update/delete ou --confirm.

unsupported_operation signifie s'arrêter

Entraînez l'agent à traiter unsupported_operation comme un mur, pas comme un puzzle. Le CLI public est toute la surface autorisée ; aucun contournement astucieux ne vaut le risque.

Questions fréquentes

Claude Code doit-il utiliser le CLI ou l'API ?

Le CLI. Comme Claude Code dispose d'un accès shell, le CLI est privilégié — il centralise l'authentification, produit un JSON stable, et impose l'idempotence et la confirmation des opérations destructrices afin que l'agent n'ait pas à les réimplémenter.

Comment garder ma clé API hors de la transcription ?

Exportez FIRSTSALES_API_KEY dans le shell avant de démarrer Claude Code, et demandez-lui de ne jamais afficher les clés en clair. Le CLI lit la variable d'environnement et ne l'affiche jamais dans la sortie.

Quel est le flux de travail sûr pour les modifications ?

Vérifiez l'identité avec whoami, confirmez l'org/workspace, inspectez l'état actuel, effectuez le changement minimal avec --dry-run puis --idempotency-key, n'utilisez --confirm que pour des suppressions voulues, et relisez pour valider.

Peut-il gérer la boîte de réception ?

Oui — inbox threads, inbox thread, et inbox approve-draft / reject-draft permettent à Claude Code de trier et d'agir sur les réponses écrites par l'IA depuis le terminal.

Que se passe-t-il si une commande n'est pas prise en charge ?

Si le CLI renvoie unsupported_operation, l'agent doit s'arrêter et le signaler. Il ne doit pas se rabattre sur des routes privées de l'app, des callbacks, des pixels ou des endpoints cron — ceux-ci sont hors limites et casseront.

Comment empêcher les suppressions accidentelles ?

Les commandes destructrices exigent --confirm. Tant que l'agent n'ajoute --confirm que pour des suppressions explicitement demandées par l'utilisateur, une suppression accidentelle ne peut pas se produire silencieusement.

Prêt à passer à la pratique ?

Démarrez votre essai FirstSales et lancez une boîte mail préchauffée et authentifiée en quelques minutes.

Commencer pour 1 $

Tous les tutoriels