Authentification

SenseCraft CLI s’authentifie avec une clé d’accès. Une seule clé couvre SenseCraft Data, SenseCraft AI et CodeCraft Hub.

Choisissez l’une ou l’autre méthode d’autorisation, puis vérifiez le profil actif :

Méthode	Fonctionnement	À choisir pour
1. Autorisation dans le navigateur — auth init	Connectez-vous et approuvez l’accès dans votre navigateur, puis sélectionnez ou créez une clé	La première configuration, y compris avec un agent IA
2. Importer une clé d’accès — auth add	Créez ou retrouvez une clé dans le centre de comptes, puis importez-la dans le CLI	Réutiliser une clé précise, des scripts ou la CI

Les deux méthodes enregistrent un profil de clé d’accès actif sur la machine qui exécute le CLI. Les commandes suivantes réutilisent ce profil.

Avant de commencer : comptes et sites

Le CLI ne crée pas de comptes. Pour vous authentifier, il vous faut un compte Seeed existant sur le site visé :

• Global (international) — créez un compte sur sensecap.seeed.cc ou sensecraft.seeed.cc.
• China — le système de comptes domestique.

Le site se choisit par profil et est stocké dans le fichier de configuration. Une clé créée sur un site ne fonctionne pas sur l’autre — une clé Global associée à un profil China est la cause classique d’une erreur de clé invalide.

Attention

Le site China ne prend en charge que SenseCraft Data. Les commandes SenseCraft AI et CodeCraft Hub nécessitent le site Global (international) — choisissez Global au moment de créer la clé et au moment de l’importer.

Méthode 1 : autorisation dans le navigateur

Utilisez auth init pour vous connecter via votre navigateur et sélectionner ou créer une clé d’accès sans en copier le secret.

Avec un agent IA

Le CLI actuel gère l’autorisation en plusieurs commandes distinctes. Chaque étape affiche du JSON et se termine, ce qui permet à l’agent de mener la configuration sans terminal interactif. Passez au CLI 0.4.3 pour les instructions de skills décrites ici.

1. Vérifiez le profil actuel avec sensecraft-cli auth info. Réutilisez le site et l’organisation attendus quand des identifiants sont déjà configurés.

2. Démarrez l’autorisation :

   bash

   sensecraft-cli auth init --site Global --no-wait

   L’agent conserve le device_code renvoyé, vous montre verification_url et attend que vous vous connectiez et approuviez l’accès dans votre navigateur. Dites à l’agent quand vous avez approuvé ; il doit présenter le lien avant d’interroger le service.

3. Lisez les clés disponibles après l’approbation dans le navigateur :

   bash

   sensecraft-cli auth init --device-code <device_code>

   La réponse contient le compte, l’organisation, ainsi que les ID, libellés et permissions des clés disponibles. Les secrets des clés d’accès ne sont pas affichés.

4. Enregistrez la clé choisie, ou créez une clé étiquetée avec les permissions nécessaires à la tâche :

   bash

   sensecraft-cli auth init --device-code <device_code> --key-id <access_id>

   Pour créer une nouvelle clé à la place :

   bash

   sensecraft-cli auth init --device-code <device_code> --label <name> --access-level read-write

   --access-level accepte read-write et only-read. L’agent pose dans le chat les questions encore ouvertes sur le compte ou les permissions et laisse le CLI enregistrer le secret localement.

5. Vérifiez le profil enregistré avec sensecraft-cli auth info avant de poursuivre avec les commandes cloud.

Assistant interactif

Quand vous utilisez le CLI directement dans un terminal interactif, démarrez l’assistant :

bash

sensecraft-cli auth init

Étape	Ce qui se passe
1	Choisir le site — Global (International) ou China
2	Demander un code d’appareil — le CLI le récupère auprès du centre utilisateur
3	Approuver dans le navigateur — il affiche un lien avec le code à usage unique déjà intégré, plus le code seul sur sa propre ligne
4	Attendre — il interroge le service et continue tout seul dès votre approbation
5	Choisir une clé — il liste les clés d’accès de votre compte ; choisissez-en une, ou créez-en une nouvelle avec un libellé et un droit lecture/écriture ; le profil est enregistré comme actif

Le terminal ressemble à ceci :

Plain Text

[3/5] Complete authorization in the browser

Copy the link below into your browser and authorize with the primary account:

  https://account.seeed.cc/device?user_code=ABCD-2345

  Verification code: ABCD-2345

The CLI will continue automatically after you complete browser authorization.

Conditions de connexion

• Le lien est portable. Ouvrez-le sur n’importe quel appareil disposant d’un navigateur. Terminez les étapes restantes du CLI sur la machine où l’autorisation a démarré.
• Seul l’assistant a besoin d’un terminal interactif. Les agents utilisent --no-wait puis --device-code. Laissez l’assistant tourner si vous avez choisi le parcours interactif.
• Les deux parcours navigateur peuvent créer une clé. Un passage séparé par le centre de comptes est facultatif ; la méthode 2 couvre l’import d’une clé.
• Le code expire (quelques minutes ; la durée vient du service de comptes). Si vous êtes trop lent, le CLI se termine avec context deadline exceeded et n’enregistre rien — relancez-le pour obtenir un nouveau code.
• --sandbox simule tout le parcours sans requête réseau, et peut tout de même écrire une configuration simulée — pointez SENSECRAFT_CONFIG_FILE vers un fichier jetable si cela pose problème.

Méthode 2 : importer une clé d’accès

Utilisez auth add pour importer une clé d’accès précise. Cette méthode commence dans le centre de comptes et vérifie la clé via OpenAPI avant de l’enregistrer.

1. Créer ou retrouver une clé d’accès

Les clés d’accès se créent et se gèrent dans le centre de comptes Seeed, sous Access Keys. Ouvrez la page de votre site :

Site	Page
Global (International)	account.seeed.cc/account/access-keys
China	account.seeed.cn/account/access-keys

La page des clés d’accès du site sélectionné (données de démonstration). Choisissez Create key.

Connectez-vous avec le compte principal — les sous-comptes ne peuvent ni consulter ni gérer les clés d’accès ; la page affiche un avertissement de permission au lieu de la liste. Utilisez une clé existante, ou créez-en une :

1. Choisissez Create key.
2. Donnez-lui un libellé que vous reconnaîtrez plus tard (facultatif, jusqu’à 64 caractères ; par ex. laptop-cli).
3. Choisissez une permission :
   • Read — lister les appareils, lire la télémétrie, chercher des applications et des modèles. Suffisant pour la supervision et les workflows d’agent en lecture seule.
   • Write — tout ce que permet Read, plus les créations, mises à jour, publications, suppressions, téléversements, déploiements et liaisons.
4. Copiez les deux valeurs de la ligne de la nouvelle clé :
   • Access ID — l’identifiant public ; le CLI l’appelle le Key ID (--key-id).
   • Access Key — le secret (--access-key). Révélez-le avec l’icône en forme d’œil, puis copiez-le.

Donnez à la clé un libellé et choisissez Read ou Write.

Copiez l’Access ID ; révélez l’Access Key, puis copiez-le.

Dans la boîte de dialogue de création, la permission vaut Write par défaut ; choisissez Read quand le workflow ne fait que lire. Une clé en Read s’authentifie sans problème, mais toute commande d’écriture échoue avec une erreur de permission — c’est le niveau de la clé, pas un bug du CLI.

Le secret reste consultable sur cette page (révéler puis copier) : traitez-le comme un mot de passe, non comme un affichage unique. Vous pouvez changer le libellé ou la permission avec Edit, et utiliser Disable quand la clé doit cesser de fonctionner. Il n’y a pas de bouton Delete sur cette page ; Disable est l’interrupteur de révocation, et Enable l’annule.

2. Importer la clé

Importez la clé dans le CLI :

bash

sensecraft-cli auth add \
  --key-id <Access ID> \
  --access-key <Access Key> \
  --site Global

--site accepte Global (par défaut) et China. Choisissez le site qui a émis la clé : account.seeed.cc → --site Global, account.seeed.cn → --site China. La vérification appelle l’OpenAPI de ce site, donc une clé de l’autre site échoue.

Dans un terminal interactif, toute valeur manquante est demandée au lieu de faire échouer la commande. L’invite de site n’apparaît que si une valeur de clé a aussi été demandée — si vous passez à la fois --key-id et --access-key mais omettez --site, le CLI utilise Global en silence. Passez --site explicitement quand cela compte.

Plain Text

Key ID: K1234567890
Access Key: <paste the Access Key>
Select the SenseCAP site to connect to
  1) Global (International)
  2) China (China site)
Enter number [1]:

L’invite affiche ce que vous tapez ; lancez-la dans un terminal privé. La forme avec l’option --access-key reste visible dans l’historique du shell et dans la liste des processus : ne collez donc pas de clé dans des journaux partagés, des captures d’écran ou des transcriptions d’agent.

3. Confirmer l’import

Le CLI vérifie la clé avec un appel view_organization, résout l’ID de votre organisation, enregistre le profil et l’active :

Plain Text

Verifying Access Key against OpenAPI ...
✓ Access Key verified
  Site: Global
  Organization ID: 12345
  Key ID: K1234567890

✓ Access config saved and set as active
  Config file: ~/.config/sensecraft-cli/sensecraft.json

auth add ne fait qu’importer une clé existante — il n’en crée, n’en renouvelle et n’en supprime jamais. En cas d’échec de vérification, rien n’est écrit dans le fichier de configuration.

auth info — inspecter les identifiants

Après l’une ou l’autre méthode, vérifiez le profil actif avec :

bash

sensecraft-cli auth info

Affiche (lisible par un humain, pas du JSON) le chemin du fichier de configuration utilisé, ainsi que le site, l’ID de l’organisation, l’Access ID actif (affiché comme Key ID) et la date de création. Le secret n’est jamais affiché. Quand rien n’est encore configuré, la commande affiche No profiles configured yet. et suggère auth init. Cette commande lit la configuration locale ; elle n’émet aucune requête API pour valider la clé enregistrée.

Lancez-la dès que vous ne savez pas quel environnement une commande va atteindre — voir aussi Configuration.

Profils multiples et changement de profil

Le fichier de configuration peut contenir plusieurs profils de clé d’accès (voir Configuration pour le schéma du fichier). Un pointeur décide lequel est actif :

• use_api — l’Access ID actif

Chaque auth add / auth init réussi écrit son profil et le rend actif. Pour revenir à un profil antérieur, relancez auth add pour cette clé et ce site (il revérifie et réactive le profil existant), ou modifiez use_api directement dans le fichier de configuration. Il n’y a volontairement pas de repli du type « la première entrée gagne » — un pointeur non défini est une erreur, pas une supposition.

Supprimer les identifiants

Il n’y a pas de commande auth remove — la suppression d’identifiants est une opération sur un fichier local, faite délibérément.

Empêcher la clé de fonctionner

Ouvrez la page des clés d’accès et utilisez Disable. Les appels API qui utilisent cette clé échouent jusqu’à ce que vous utilisiez Enable. La désactivation est réversible, et la clé reste dans la liste. Pour invalider l’identifiant partout où il sert, c’est l’étape à faire — supprimer un profil local ne l’oublie que sur cette machine.

Tout supprimer (déconnexion complète)

Supprimez le répertoire de configuration (son emplacement dépend de votre mode d’installation ; voir Configuration) :

bash

rm -rf ~/.config/sensecraft-cli
  # Windows: Remove-Item -Recurse "$env:APPDATA\sensecraft-cli"

Cela efface toutes les clés d’accès, les jetons et les pointeurs de profil stockés sur cette machine.

Supprimer un profil

Ouvrez sensecraft.json et supprimez l’entrée de app_config_list. Si vous avez supprimé le profil actuellement actif, pointez aussi use_api vers une entrée restante, ou videz-le et relancez auth add / auth init. Gardez les permissions du fichier à 0600 — le CLI l’écrit de façon atomique avec ces permissions.

Notes de sécurité

• Le fichier de configuration est écrit avec des permissions 0600 via un fichier temporaire renommé de façon atomique, si bien qu’une écriture partielle ne le corrompt jamais. Le secret y est stocké en clair — protégez le fichier, pas seulement la clé.
• Ne versionnez jamais sensecraft.json ; si vous en gardez une copie dans un dépôt pour la CI, limitez la clé à ce dont le pipeline a réellement besoin (en lecture seule si possible).
• Une clé en Read fait échouer toutes les commandes d’écriture avec une erreur de permission — c’est le niveau de la clé, pas un bug du CLI.
• Pendant une configuration par IA, l’agent lance auth init --no-wait et attend votre approbation dans le navigateur. Gardez les mots de passe, les jetons et les clés d’accès brutes hors du chat et des journaux d’agent ; voir Confirmations et sécurité.

Note sur les versions

La version publique de @seeed-studio/sensecraft-cli prend en charge à la fois auth init (recommandé) et auth add pour une clé d’accès unique, avec les sites Global et China. Les clés d’accès n’expirent pas et ne sont jamais renouvelées : il n’y a donc ni commande auth refresh, ni option --kind. Rappelez-vous que le site China ne couvre que SenseCraft Data.