Autenticación

SenseCraft CLI se autentica con una clave de acceso. Una clave cubre SenseCraft Data, SenseCraft AI y CodeCraft Hub.

Elige cualquiera de los dos métodos de autorización y luego consulta el perfil activo:

Método	Cómo funciona	Elígelo para
1. Autorización en el navegador — `auth init`	Inicia sesión y aprueba el acceso en tu navegador, y luego elige o crea una clave	La configuración inicial, incluida la que haces con un agente de IA
2. Importar una clave de acceso — `auth add`	Crea o localiza una clave en el centro de cuentas y luego impórtala en la CLI	Reutilizar una clave concreta, scripts o CI

Ambos métodos guardan un perfil de clave de acceso activo en la máquina donde se ejecuta la CLI. Las órdenes posteriores reutilizan ese perfil.

Antes de empezar: cuentas y sitios

La CLI no crea cuentas. Para autenticarte necesitas una cuenta de Seeed existente en el sitio al que te diriges:

Global (internacional) — regístrate en sensecap.seeed.cc o sensecraft.seeed.cc.
China — el sistema de cuentas nacional.

El sitio se elige por perfil y se guarda en el archivo de configuración. Una clave creada en un sitio no funciona en otro — una clave Global contra un perfil de China es la causa clásica de un error de clave no válida.

Método 1: autorización en el navegador

Usa auth init para iniciar sesión a través del navegador y elegir o crear una clave de acceso sin copiar su secreto.

Con un agente de IA

La CLI actual admite la autorización en órdenes separadas. Cada paso imprime JSON y termina, así que el agente puede encargarse de la configuración sin una terminal interactiva. Actualiza a la CLI 0.4.3 para las instrucciones de skills que se describen aquí.

Comprueba el perfil actual con sensecraft-cli auth info. Reutiliza el sitio y la organización esperados cuando ya haya credenciales configuradas.
Inicia la autorización:
bash
```
sensecraft-cli auth init --site Global --no-wait
```
El agente conserva el device_code devuelto, te muestra verification_url y espera a que inicies sesión y apruebes el acceso en tu navegador. Avísale cuando hayas aprobado; debería mostrarte el enlace antes de consultar el estado.
Lee las claves disponibles después de la aprobación en el navegador:
bash
```
sensecraft-cli auth init --device-code <device_code>
```
Devuelve la cuenta, la organización y los ID de clave disponibles, con sus etiquetas y permisos. Los secretos de las claves de acceso no se imprimen.
Guarda la clave elegida o crea una clave con etiqueta y los permisos que necesite la tarea:
bash
```
sensecraft-cli auth init --device-code <device_code> --key-id <access_id>
```
Para crear en su lugar una clave nueva:
bash
```
sensecraft-cli auth init --device-code <device_code> --label <name> --access-level read-write
```
--access-level acepta read-write y only-read. El agente pregunta en el chat por las decisiones de cuenta o de permisos que sigan sin resolver y deja que la CLI guarde el secreto en local.
Comprueba el perfil guardado con sensecraft-cli auth info antes de seguir con órdenes en la nube.

Asistente interactivo

Cuando uses la CLI directamente en una terminal interactiva, arranca el asistente:

sensecraft-cli auth init

Paso	Qué ocurre
1	Elige el sitio — Global (International) o China
2	Solicita un código de dispositivo — la CLI lo obtiene del centro de usuarios
3	Aprueba en el navegador — imprime un enlace con el código de un solo uso ya incluido, además del código en su propia línea
4	Espera — consulta el estado y continúa sola en cuanto apruebas
5	Elige una clave — lista las claves de acceso de tu cuenta; elige una o crea una nueva con una etiqueta y un nivel de lectura/escritura; el perfil se guarda como activo

La terminal se ve así:

[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.

Requisitos de conexión

El enlace es portable. Ábrelo en cualquier dispositivo con navegador. Completa los pasos restantes de la CLI en la máquina donde empezó la autorización.
Solo el asistente necesita una terminal interactiva. Los agentes usan --no-wait y después --device-code. Mantén el asistente en marcha si elegiste el flujo interactivo.
Ambos flujos de navegador pueden crear una clave. La visita aparte al centro de cuentas es opcional; el Método 2 cubre la importación de claves.
El código caduca (unos minutos; el tiempo de vida lo marca el servicio de cuentas). Si tardas demasiado, la CLI sale con context deadline exceeded y no guarda nada — vuelve a ejecutarla para obtener un código nuevo.
--sandbox simula todo el flujo sin peticiones de red, y aun así puede escribir una configuración simulada — apunta SENSECRAFT_CONFIG_FILE a un archivo desechable si eso te importa.

Método 2: importar una clave de acceso

Usa auth add para importar una clave de acceso concreta. Este método empieza en el centro de cuentas y verifica la clave a través de OpenAPI antes de guardarla.

1. Crear o localizar una clave de acceso

Las claves de acceso se crean y se gestionan en el centro de cuentas de Seeed, en Access Keys. Abre la página de tu sitio:

Sitio	Página
Global (International)	account.seeed.cc/account/access-keys
China	account.seeed.cn/account/access-keys

Página de claves de acceso del centro de cuentas de Seeed, con el botón «Create key» resaltado

La página de claves de acceso del sitio seleccionado (datos de demostración). Elige Create key.

Inicia sesión con la cuenta principal — las subcuentas no pueden ver ni gestionar claves de acceso; la página muestra un aviso de permisos en lugar de la lista. Usa una clave existente o crea una:

Elige Create key.
Ponle una etiqueta que reconozcas después (opcional, hasta 64 caracteres; p. ej., laptop-cli).
Elige un permiso:
- Read — listar dispositivos, leer telemetría, buscar apps y modelos. Suficiente para monitorización y flujos de agente de solo lectura.
- Write — todo lo que permite Read y además: crear, actualizar, publicar, eliminar, subir, desplegar y vincular.
Copia los dos valores de la fila de la clave nueva:
- Access ID — el identificador público; la CLI lo llama Key ID (--key-id).
- Access Key — el secreto (--access-key). Muéstralo con el icono del ojo y cópialo.

Diálogo «Create Access Key» con los campos de etiqueta y permiso

Ponle a la clave una etiqueta y elige Read o Write.

Access ID y Access Key en una fila de clave

Copia el Access ID; muestra la Access Key y cópiala.

El permiso del diálogo de creación es Write por defecto; elige Read cuando el flujo solo lee. Una clave con permiso Read se autentica sin problema, pero todas las órdenes de escritura fallan con un error de permisos — es el nivel de la clave, no un fallo de la CLI.

El secreto sigue disponible en esta página (mostrar y copiar), así que trátalo como una contraseña y no como algo que se muestra una sola vez. Puedes cambiar la etiqueta o el permiso con Editar, y desactivar la clave cuando deba dejar de funcionar. En esta página no hay botón de borrado; desactivar es el interruptor de revocación y activar lo revierte.

2. Importar la clave

Importa la clave en la CLI:

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

--site acepta Global (por defecto) y China. Elige el sitio que emitió la clave: account.seeed.cc → --site Global, account.seeed.cn → --site China. La verificación llama al OpenAPI de ese sitio, así que una clave del otro sitio falla.

En una terminal interactiva, cualquier valor que falte se pide en lugar de fallar. El prompt del sitio aparece solo cuando también se preguntó algún valor de la clave — si pasas --key-id y --access-key pero omites --site, la CLI usa Global en silencio. Pasa --site de forma explícita cuando importe.

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

El prompt repite lo que escribes; ejecútalo en una terminal privada. La forma con el flag --access-key también queda visible en el historial del shell y en los listados de procesos, así que no pegues una clave en registros compartidos, capturas de pantalla ni transcripciones de agentes.

3. Confirmar la importación

La CLI verifica la clave con una llamada view_organization, resuelve el ID de tu organización, guarda el perfil y lo deja activo:

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 solo importa una clave existente — nunca crea, rota ni elimina una. Si la verificación falla, no se escribe nada en el archivo de configuración.

auth info — inspeccionar las credenciales

Después de cualquiera de los dos métodos, comprueba el perfil activo con:

sensecraft-cli auth info

Imprime (en formato legible, no JSON) la ruta del archivo de configuración en uso, además del sitio, el ID de organización, el Access ID activo (impreso como Key ID) y la hora de creación. El secreto nunca se imprime. Cuando todavía no hay nada configurado, imprime No profiles configured yet. y sugiere auth init. Esta orden lee la configuración local; no hace ninguna petición a la API para validar la clave guardada.

Ejecútala siempre que no tengas claro sobre qué entorno actuará una orden — consulta también Configuración.

Varios perfiles y cambio entre ellos

El archivo de configuración puede contener varios perfiles de clave de acceso (consulta Configuración para el esquema del archivo). Un puntero decide cuál está activo:

use_api — el Access ID activo

Cada auth add / auth init correcto escribe su perfil y lo deja activo. Para volver a un perfil anterior, ejecuta auth add otra vez para esa clave y ese sitio (vuelve a verificar y reactiva el perfil existente) o edita use_api directamente en el archivo de configuración. A propósito no hay un respaldo del tipo «gana la primera entrada» — un puntero sin definir es un error, no una suposición.

Eliminar credenciales

No hay una orden auth remove — eliminar credenciales es una operación sobre archivos locales, hecha a propósito.

Hacer que la clave deje de funcionar

Abre la página de claves de acceso y desactiva la clave. Las llamadas a la API que la usen fallan hasta que vuelvas a activarla. Desactivar es reversible, y la clave sigue en la lista. Para invalidar la credencial en todos los lugares donde se usa, este es el paso — borrar un perfil local solo la olvida en esa máquina.

Eliminarlo todo (cerrar sesión por completo)

Borra el directorio de configuración (su ubicación depende de cómo lo instalaras; consulta Configuración):

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

Esto borra todas las claves de acceso, tokens y punteros de perfil guardados en esa máquina.

Eliminar un solo perfil

Abre sensecraft.json y borra la entrada de app_config_list. Si has borrado el perfil activo, apunta use_api a una entrada que quede, o bórralo y ejecuta auth add / auth init de nuevo. Mantén los permisos del archivo en 0600 — la CLI lo escribe de forma atómica con esos permisos.

Notas de seguridad

El archivo de configuración se escribe con permisos 0600 mediante un archivo temporal y un renombrado atómicos, así que una escritura parcial nunca lo corrompe. El secreto se guarda en texto plano en ese archivo — protege el archivo, no solo la clave.
No hagas nunca commit de sensecraft.json; si guardas una copia en un repositorio para CI, limita la clave a lo que la pipeline necesita de verdad (solo lectura cuando sea posible).
Una clave con permiso Read hace que todas las órdenes de escritura fallen con un error de permisos — es el nivel de la clave, no un fallo de la CLI.
Durante la configuración con IA, el agente lanza auth init --no-wait y espera tu aprobación en el navegador. Mantén las contraseñas, los tokens y las claves de acceso sin procesar fuera del chat y de los registros del agente; consulta Confirmaciones y seguridad.

Nota sobre la versión

La compilación pública de @seeed-studio/sensecraft-cli admite tanto auth init (recomendado) como auth add para una sola clave de acceso, con los sitios Global y China. Las claves de acceso no caducan y nunca se renuevan, así que no hay orden auth refresh ni flag --kind. Recuerda que el sitio China solo sirve para SenseCraft Data.