NouveauDécouvrir comment
FirstSales
Accueil/Tutoriels/Démarrage rapide de la CLI FirstSales
Développeur & CLI

Démarrage rapide de la CLI FirstSales

Installez la CLI FirstSales, authentifiez-vous avec une clé API et exécutez vos premières commandes sans risque — whoami, découverte org/workspace, dry-run et idempotence.

8 min de lecture·Avancé·7 étapes
  1. 1

    Installez le CLI

    Le CLI FirstSales est un package npm. Installez-le globalement pour obtenir le binaire firstsales :

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

    Authentifiez-vous

    Créez une clé Developer API dans Settings → API, puis fournissez au CLI la clé et l'URL de base. La méthode la plus propre est d'utiliser des variables d'environnement :

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

    Vérifiez avec whoami et doctor

    Avant toute chose, confirmez que la clé pointe vers le bon contexte. whoami affiche votre utilisateur, votre org et votre workspace ; doctor vérifie votre configuration :

    firstsales whoami --json
firstsales doctor
  4. 4

    Comprenez les flags globaux

    Chaque commande partage les mêmes flags — apprenez-les une bonne fois pour toutes :

    • --org <id> / --workspace <id> — portée ciblée (la plupart des commandes ont besoin des deux).
    • --json (par défaut) / --pretty — format de sortie.
    • --data '<json>' / --data-file <path> — corps de la requête.
    • --idempotency-key <key> — nouvelles tentatives sûres sur les créations.
    • --dry-run — prévisualise la requête sans l'envoyer.
    • --confirm — requis pour toute commande destructrice (suppression).
    • --api-key / --base-url / --profile — surcharge l'authentification par appel.
  5. 5

    Découvrez votre org et votre workspace

    La plupart des commandes sont limitées à une org et un workspace. Listez-les, puis réutilisez les IDs :

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

    Effectuez une première mutation en toute sécurité

    Suivez la boucle d'or : inspecter d'abord, muter délibérément, vérifier ensuite. Prévisualisez avec --dry-run, puis créez avec une clé d'idempotence, puis relisez pour confirmer :

    # Preview — no write happens
firstsales contacts create --org ORG_ID --workspace WS_ID \
  --data '{"email":"jane@acme.com","first_name":"Jane"}' --dry-run

# Create for real, idempotently
firstsales contacts create --org ORG_ID --workspace WS_ID \
  --data '{"email":"jane@acme.com","first_name":"Jane"}' \
  --idempotency-key jane-acme-2026-01

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

    Supprimez de façon délibérée

    Les commandes destructrices refusent de s'exécuter sans --confirm — il s'agit d'une friction intentionnelle pour qu'un agent ou une commande mal saisie ne puisse pas effacer des données par accident :

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

Astuces de pro

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

1

Inspecter d'abord, muter délibérément, vérifier ensuite

Le CLI est construit autour de cette boucle. Listez avant de modifier, testez le changement avec --dry-run, exécutez-le, puis relisez pour confirmer. C'est plus lent à taper, mais bien moins coûteux que d'annuler une mauvaise écriture.

2

--json est pour les machines, --pretty pour vous

La sortie est en JSON compact par défaut afin que les scripts et les agents puissent l'analyser. Ajoutez --pretty quand un humain lit la sortie, mais gardez --json dans les pipelines.

3

Ne renvoyez jamais votre clé en clair

Passez l'authentification via FIRSTSALES_API_KEY ou un profil, pas en ligne où elle finirait dans l'historique du shell ou les logs. Le CLI n'affiche jamais les clés brutes — ne défaites pas cette protection en faisant un echo de la variable d'environnement.

4

Les clés d'idempotence sont une assurance gratuite

Toute création susceptible d'être retentée devrait porter --idempotency-key. Une commande rejouée devient un no-op au lieu d'un doublon.

Questions fréquentes

Comment installer le CLI ?

npm install -g @firstsales.io/cli, qui vous donne le binaire firstsales. Il correspond directement à l'API Developer publique /api/v1.

Comment fonctionne l'authentification ?

Définissez FIRSTSALES_API_KEY (et éventuellement FIRSTSALES_BASE_URL) dans votre environnement, ou passez --api-key / --base-url à chaque commande. Vérifiez avec firstsales whoami --json.

Pourquoi les commandes ont-elles besoin de --org et --workspace ?

Les ressources sont rattachées à une organisation et un workspace. Listez-les avec organizations list et workspaces list --org ORG_ID, puis passez les deux IDs sur les commandes concernées.

Que fait --dry-run ?

Il affiche la requête que le CLI enverrait sans réellement l'envoyer — vous pouvez ainsi confirmer le corps et la cible avant une mutation réelle.

Pourquoi ma suppression ne s'exécute-t-elle pas ?

Les commandes destructrices exigent le flag --confirm par conception. Ajoutez --confirm une fois que vous êtes sûr — c'est le garde-fou qui empêche les suppressions accidentelles.

Le CLI est-il différent de l'API ?

C'est une fine couche au-dessus des mêmes endpoints publics /api/v1. Le CLI ajoute du confort — authentification centralisée, JSON stable, gestion de l'idempotence et confirmation des opérations destructrices — afin que les agents et les scripts n'aient pas à les réimplémenter.

Puis-je garder plusieurs comptes configurés ?

Oui — utilisez --profile <name> pour charger un profil local enregistré, ou surchargez --api-key/--base-url par commande pour basculer entre orgs ou environnements.

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