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.
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 chatDonnez à 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-keysur toute création susceptible d'être retentée. - N'utiliser
--confirmque pour une suppression intentionnelle demandée par l'utilisateur. - Ne jamais afficher les clés API en clair.
- Démarrer chaque session avec
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 --jsonMutations : 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":"[email protected]","first_name":"Sam"}' --dry-run firstsales contacts create --org ORG_ID --workspace WS_ID \ --data '{"email":"[email protected]","first_name":"Sam"}' \ --idempotency-key sam-acme-2026-01 firstsales contacts list --org ORG_ID --workspace WS_ID --jsonApprouvez 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_IDRespectez 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
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.