Authentifizierung

SenseCraft CLI authentifiziert sich mit einem Zugangsschlüssel. Ein Schlüssel deckt SenseCraft Data, SenseCraft AI und CodeCraft Hub ab.

Wählen Sie eine der beiden Autorisierungsmethoden und prüfen Sie danach das aktive Profil:

Methode	So funktioniert es	Dafür wählen
1. Browser-Autorisierung — auth init	Im Browser anmelden und Zugriff bestätigen, dann einen Schlüssel auswählen oder anlegen	Die Ersteinrichtung, auch die Einrichtung mit einem KI-Agenten
2. Zugangsschlüssel importieren — auth add	Einen Schlüssel im Account-Center anlegen oder finden und ihn dann in die CLI importieren	Einen bestimmten Schlüssel wiederverwenden, Skripte oder CI

Beide Methoden speichern ein aktives Zugangsschlüssel-Profil auf dem Rechner, auf dem die CLI läuft. Spätere Befehle verwenden dieses Profil erneut.

Vorab: Konten und Sites

Die CLI legt keine Konten an. Zum Autorisieren brauchen Sie ein bestehendes Seeed-Konto auf der Site, die Sie nutzen möchten:

• Global (International) — registrieren Sie sich unter sensecap.seeed.cc oder sensecraft.seeed.cc.
• China — das chinesische Kontosystem.

Die Site wird pro Profil gewählt und in der Konfigurationsdatei gespeichert. Ein Schlüssel, der auf einer Site ausgestellt wurde, funktioniert auf einer anderen nicht — ein Global-Schlüssel gegen ein China-Profil ist die klassische Ursache für einen Fehler wegen eines ungültigen Schlüssels.

Achtung

Die China-Site unterstützt nur SenseCraft Data. Befehle für SenseCraft AI und CodeCraft Hub brauchen die Global-Site (international) — wählen Sie Global, wenn Sie den Schlüssel anlegen, und ebenso beim Import.

Methode 1: Browser-Autorisierung

Verwenden Sie auth init, um sich über Ihren Browser anzumelden und einen Zugangsschlüssel auszuwählen oder anzulegen, ohne dessen Secret zu kopieren.

Mit einem KI-Agenten

Die aktuelle CLI unterstützt die Autorisierung über getrennte Befehle. Jeder Schritt gibt JSON aus und beendet sich, sodass der Agent die Einrichtung ohne interaktives Terminal erledigen kann. Aktualisieren Sie auf CLI 0.4.3 für die hier beschriebenen Skill-Anweisungen.

1. Prüfen Sie das aktuelle Profil mit sensecraft-cli auth info. Wenn bereits Zugangsdaten konfiguriert sind, verwenden Sie die erwartete Site und Organisation weiter.

2. Starten Sie die Autorisierung:

   bash

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

   Der Agent behält den zurückgegebenen device_code, zeigt Ihnen die verification_url und wartet darauf, dass Sie sich anmelden und den Zugriff im Browser bestätigen. Sagen Sie dem Agenten, sobald Sie bestätigt haben; er sollte den Link vor dem Polling anzeigen.

3. Lesen Sie die verfügbaren Schlüssel nach der Bestätigung im Browser aus:

   bash

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

   Das liefert Konto, Organisation sowie die verfügbaren Key IDs, Labels und Berechtigungen. Secrets von Zugangsschlüsseln werden nicht ausgegeben.

4. Speichern Sie den ausgewählten Schlüssel, oder legen Sie einen benannten Schlüssel mit den für die Aufgabe nötigen Berechtigungen an:

   bash

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

   Um stattdessen einen neuen Schlüssel anzulegen:

   bash

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

   --access-level akzeptiert read-write und only-read. Der Agent klärt offene Fragen zu Konto oder Berechtigungen im Chat und lässt die CLI das Secret lokal speichern.

5. Prüfen Sie das gespeicherte Profil mit sensecraft-cli auth info, bevor Sie mit Cloud-Befehlen fortfahren.

Interaktiver Assistent

Wenn Sie die CLI direkt in einem interaktiven Terminal verwenden, starten Sie den Assistenten:

bash

sensecraft-cli auth init

Schritt	Was passiert
1	Site wählen — Global (International) oder China
2	Device-Code anfordern — die CLI holt ihn vom User-Center ab
3	Im Browser bestätigen — ausgegeben wird ein Link, in dem der Einmalcode bereits steckt, plus der Code in einer eigenen Zeile
4	Warten — die CLI pollt und fährt von selbst fort, sobald Sie bestätigen
5	Schlüssel wählen — die Zugangsschlüssel Ihres Kontos werden aufgelistet; wählen Sie einen aus oder legen Sie einen neuen an, mit Label und Stufe Read/Write; das Profil wird als aktiv gespeichert

Das Terminal sieht so aus:

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.

Anforderungen an die Verbindung

• Der Link ist übertragbar. Öffnen Sie ihn auf einem beliebigen Gerät mit Browser. Die restlichen CLI-Schritte erledigen Sie auf dem Rechner, auf dem die Autorisierung gestartet wurde.
• Nur der Assistent braucht ein interaktives Terminal. Agenten verwenden --no-wait und danach --device-code. Lassen Sie den Assistenten laufen, wenn Sie den interaktiven Ablauf gewählt haben.
• Beide Abläufe im Browser können einen Schlüssel anlegen. Ein zusätzlicher Besuch im Account-Center ist optional; Methode 2 behandelt den Schlüsselimport.
• Der Code läuft ab (wenige Minuten; die Laufzeit kommt vom Kontodienst). Wenn Sie zu langsam sind, beendet sich die CLI mit context deadline exceeded und speichert nichts — starten Sie sie erneut für einen frischen Code.
• --sandbox simuliert den gesamten Ablauf ohne Netzwerkanfragen und schreibt möglicherweise trotzdem eine simulierte Konfiguration — richten Sie SENSECRAFT_CONFIG_FILE auf eine Wegwerfdatei, wenn das eine Rolle spielt.

Methode 2: Zugangsschlüssel importieren

Verwenden Sie auth add, um einen bestimmten Zugangsschlüssel zu importieren. Diese Methode beginnt im Account-Center und prüft den Schlüssel über OpenAPI, bevor sie ihn speichert.

1. Zugangsschlüssel anlegen oder finden

Zugangsschlüssel werden im Seeed Account-Center unter Access Keys angelegt und verwaltet. Öffnen Sie die Seite für Ihre Site:

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

Die Access-Keys-Seite für die gewählte Site (Demodaten). Wählen Sie Create key.

Melden Sie sich mit dem Hauptkonto an — Unterkonten können Zugangsschlüssel weder sehen noch verwalten; die Seite zeigt statt der Liste einen Berechtigungshinweis. Verwenden Sie einen vorhandenen Schlüssel, oder legen Sie einen an:

1. Wählen Sie Create key.
2. Vergeben Sie ein Label, das Sie später wiedererkennen (optional, bis zu 64 Zeichen; z. B. laptop-cli).
3. Wählen Sie eine Permission:
   • Read — Geräte auflisten, Telemetrie lesen, Apps und Modelle durchsuchen. Ausreichend für Monitoring und rein lesende Agent-Workflows.
   • Write — alles, was Read erlaubt, plus Anlegen, Aktualisieren, Veröffentlichen, Löschen, Hochladen, Deployen und Binden.
4. Kopieren Sie beide Werte aus der Zeile des neuen Schlüssels:
   • Access ID — der öffentliche Bezeichner; die CLI nennt ihn Key ID (--key-id).
   • Access Key — das Secret (--access-key). Blenden Sie es über das Augensymbol ein und kopieren Sie es dann.

Vergeben Sie ein Label und wählen Sie Read oder Write.

Kopieren Sie die Access ID; blenden Sie den Access Key ein und kopieren Sie ihn.

Die Permission im Anlege-Dialog steht standardmäßig auf Write; wählen Sie Read, wenn der Workflow nur liest. Ein Schlüssel mit Read-Berechtigung authentifiziert sich einwandfrei, aber jeder Schreibbefehl scheitert mit einem Berechtigungsfehler — das ist die Stufe des Schlüssels, kein CLI-Fehler.

Das Secret bleibt auf dieser Seite verfügbar (einblenden und kopieren), behandeln Sie es also wie ein Passwort und nicht wie eine einmalige Anzeige. Label und Permission lassen sich mit Edit ändern, und den Schlüssel können Sie mit Disable deaktivieren, wenn er nicht mehr funktionieren soll. Auf dieser Seite gibt es keine Schaltfläche zum Löschen; Disable ist der Schalter zum Widerrufen, und Enable macht ihn rückgängig.

2. Schlüssel importieren

Importieren Sie den Schlüssel in die CLI:

bash

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

--site akzeptiert Global (Standard) und China. Wählen Sie die Site, die den Schlüssel ausgestellt hat: account.seeed.cc → --site Global, account.seeed.cn → --site China. Die Verifikation ruft die OpenAPI dieser Site auf, deshalb scheitert ein Schlüssel der anderen Site.

In einem interaktiven Terminal wird jeder fehlende Wert abgefragt, statt abzubrechen. Die Site-Abfrage erscheint nur, wenn auch ein Schlüsselwert abgefragt wurde — wenn Sie --key-id und --access-key übergeben, --site aber weglassen, verwendet die CLI stillschweigend Global. Geben Sie --site ausdrücklich an, wenn es darauf ankommt.

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]:

Die Abfrage zeigt wieder, was Sie eintippen; führen Sie sie in einem privaten Terminal aus. Auch die Form mit dem Flag --access-key ist in der Shell-Historie und in Prozesslisten sichtbar, fügen Sie einen Schlüssel also nicht in geteilte Logs, Screenshots oder Agent-Transkripte ein.

3. Import bestätigen

Die CLI prüft den Schlüssel mit einem view_organization-Aufruf, ermittelt Ihre Organisation-ID, speichert das Profil und setzt es als aktiv:

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 importiert nur einen vorhandenen Schlüssel — es legt keinen an, rotiert keinen und löscht keinen. Bei einer fehlgeschlagenen Verifikation wird nichts in die Konfigurationsdatei geschrieben.

auth info — Zugangsdaten prüfen

Prüfen Sie nach beiden Methoden das aktive Profil mit:

bash

sensecraft-cli auth info

Ausgegeben wird (menschenlesbar, nicht JSON) der verwendete Pfad der Konfigurationsdatei sowie die Site, die Organisation-ID, die aktive Access ID (angezeigt als Key ID) und der Erstellungszeitpunkt. Das Secret wird nie ausgegeben. Ist noch nichts konfiguriert, erscheint No profiles configured yet. und der Hinweis auf auth init. Dieser Befehl liest die lokale Konfiguration; er stellt keine API-Anfrage, um den gespeicherten Schlüssel zu prüfen.

Führen Sie ihn immer aus, wenn Sie unsicher sind, welche Umgebung ein Befehl trifft — siehe auch Konfiguration.

Mehrere Profile und Umschalten

Die Konfigurationsdatei kann mehrere Zugangsschlüssel-Profile halten (das Dateischema steht in Konfiguration). Ein Zeiger entscheidet, welches aktiv ist:

• use_api — die aktive Access ID

Jedes erfolgreiche auth add / auth init schreibt sein Profil und setzt es aktiv. Um zu einem früheren Profil zurückzukehren, führen Sie auth add für diesen Schlüssel bzw. diese Site erneut aus (das vorhandene Profil wird erneut geprüft und aktiviert), oder bearbeiten Sie use_api direkt in der Konfigurationsdatei. Es gibt bewusst keinen Fallback im Sinne von „der erste Eintrag gewinnt“ — ein nicht gesetzter Zeiger ist ein Fehler, keine Vermutung.

Zugangsdaten entfernen

Es gibt keinen Befehl auth remove — das Entfernen von Zugangsdaten ist eine lokale Dateioperation, die bewusst erfolgt.

Schlüssel unwirksam machen

Öffnen Sie die Access-Keys-Seite und deaktivieren Sie den Schlüssel (Disable). API-Aufrufe damit scheitern, bis Sie ihn wieder aktivieren (Enable). Das Deaktivieren ist umkehrbar, und der Schlüssel bleibt in der Liste. Wenn Sie die Zugangsdaten überall ungültig machen wollen, ist das der richtige Schritt — das Löschen eines lokalen Profils vergisst sie nur auf dieser Maschine.

Alles entfernen (vollständig abmelden)

Löschen Sie das Konfigurationsverzeichnis (der Ort hängt davon ab, wie Sie installiert haben; siehe Konfiguration):

bash

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

Damit werden alle auf dieser Maschine gespeicherten Zugangsschlüssel, Tokens und Profilzeiger gelöscht.

Einzelnes Profil entfernen

Öffnen Sie sensecraft.json und löschen Sie den Eintrag aus app_config_list. Wenn Sie das aktuell aktive Profil entfernt haben, richten Sie use_api zusätzlich auf einen verbleibenden Eintrag, oder leeren Sie den Zeiger und führen Sie auth add / auth init erneut aus. Belassen Sie die Dateirechte bei 0600 — die CLI schreibt die Datei atomar mit diesen Rechten.

Sicherheitshinweise

• Die Konfigurationsdatei wird mit Rechten 0600 geschrieben, atomar über eine temporäre Datei und ein Rename, sodass ein abgebrochener Schreibvorgang sie nie beschädigt. Das Secret liegt im Klartext in dieser Datei — schützen Sie die Datei, nicht nur den Schlüssel.
• Committen Sie sensecraft.json nie; wenn Sie für CI eine Kopie im Repository halten, beschränken Sie den Schlüssel auf das, was die Pipeline tatsächlich braucht (möglichst nur Lesen).
• Ein Schlüssel mit Read-Berechtigung lässt alle Schreibbefehle mit einem Berechtigungsfehler scheitern — das ist die Stufe des Schlüssels, kein CLI-Fehler.
• Beim Einrichten durch eine KI startet der Agent auth init --no-wait und wartet auf Ihre Bestätigung im Browser. Halten Sie Passwörter, Tokens und rohe Zugangsschlüssel aus Chats und Agent-Logs heraus; siehe Bestätigungen und Sicherheit.

Hinweis zur Version

Der öffentliche Build von @seeed-studio/sensecraft-cli unterstützt sowohl auth init (empfohlen) als auch auth add für einen einzelnen Zugangsschlüssel, mit den Sites Global und China. Zugangsschlüssel laufen nicht ab und werden nie erneuert, daher gibt es keinen Befehl auth refresh und kein Flag --kind. Denken Sie daran, dass die China-Site nur SenseCraft Data umfasst.