La CLI fun

La CLI fun vous permet de gérer Fundamentum depuis votre terminal et vos scripts. Ce guide vous montre comment l'installer, vous connecter, travailler avec plusieurs environnements, utiliser les commandes sélectionnées et appeler n'importe quelle opération de la Public API avec fun api.

Avant de commencer

Vous avez un compte Fundamentum avec accès à au moins un projet. Consultez Authentication.
Vous connaissez l'ID de votre projet. Le Hub l'affiche.
Pour les exemples de scripts, jq est pratique mais facultatif.

1. Installer la CLI

Téléchargez l'archive correspondant à votre plateforme depuis https://cli.fundamentum-iot.com :

Plateforme	Archive
Linux (amd64)	`fundamentum-cli-linux-amd64-<version>.zip`
macOS (Apple silicon, arm64)	`fundamentum-cli-mac-arm64-<version>.zip`
Windows (386)	`fundamentum-cli-windows-386-<version>.zip`

Sous Linux et macOS, extrayez le binaire fun et placez-le dans votre PATH :

unzip fundamentum-cli-mac-arm64-<version>.zip
chmod +x fun
sudo mv fun /usr/local/bin/fun

Sous macOS, Gatekeeper peut bloquer le binaire la première fois que vous l'exécutez, car il a été téléchargé depuis Internet. Autorisez-le dans System Settings → Privacy & Security.

Sous Windows, l'archive contient fun.exe. Extrayez-le dans un dossier de votre PATH.

Vérifiez l'installation :

fun --version

Vérifiez à tout moment la présence d'une version plus récente avec fun check-update. Pour mettre à niveau, téléchargez la nouvelle archive et remplacez le binaire.

Vous pouvez aussi activer la complétion du shell, qui complète également les commandes fun api :

source <(fun completion zsh)

Remplacez zsh par bash, fish ou powershell. Consultez fun completion <shell> --help pour l'installer de façon permanente.

fun login

La CLI vous demande :

un nom de contexte : appuyez sur Entrée pour default ;
le point de terminaison de l'API : appuyez sur Entrée pour https://api.fundamentum-iot.com ;
le point de terminaison OAuth : appuyez sur Entrée pour https://oauth.fundamentum-iot.com.

Votre navigateur s'ouvre sur la page de connexion de Fundamentum, où vous vous connectez comme d'habitude, y compris avec l'authentification unique. La CLI enregistre ensuite votre jeton dans contexts.json, dans son répertoire de configuration. fun config dir affiche son emplacement.

Lorsque le jeton expire, exécutez de nouveau fun login en indiquant le même nom de contexte : la CLI actualise le jeton et conserve vos points de terminaison.

3. Utiliser un contexte par environnement

Un contexte est un ensemble nommé de points de terminaison et d'un jeton. Créez-en un par environnement ou par compte :

fun login                  # answer "staging" to the context prompt, then the staging endpoints
fun config contexts list

Sélectionnez un contexte avec --context sur toute commande qui appelle Fundamentum. Sans cette option, la CLI utilise default :

fun functions list --project <project-id> --context staging

Pour modifier les points de terminaison d'un contexte existant, exécutez fun login --override.

4. Utiliser les commandes sélectionnées

Les commandes sélectionnées couvrent les tâches qui nécessitent plus d'un appel d'API. Leurs noms sont versionnés avec la CLI, ce qui en fait le bon choix pour les scripts qui doivent continuer à fonctionner.

Redirigez un port d'un appareil vers votre machine, par exemple pour accéder à son serveur web sur le port 80 à localhost:8080 :

fun devices port-forward -p <project-id> -r <registry-id> -s <serial-number> -l 8080 -d 80

Appuyez sur une touche pour arrêter la redirection. Consultez Remote terminal and port forwarding.

Envoyez un fichier à un appareil, puis récupérez-en un :

fun devices transfer cloud-to-device -p <project-id> -r <registry-id> -s <serial-number> \
  --file ./config.bin --remote-path /etc/app/config.bin

fun devices transfer device-to-cloud -p <project-id> -r <registry-id> -s <serial-number> \
  --remote-path /var/log/app.log --name app.log

Le fichier local doit être un chemin relatif à l'intérieur du répertoire courant. Consultez File transfers.

Créez, téléversez et invoquez une fonction cloud :

fun functions new decoder --project <project-id> --language go --description "Decode sensor frames"
fun functions upload decoder ./decoder.wasm
echo '{"frame":"0a1b"}' | fun functions invoke --name decoder
fun functions executions list --name decoder

decoder est un nom local que la CLI enregistre dans functions.json, ce qui évite de répéter les ID du projet et de la fonction. Consultez Cloud functions.

5. Appeler n'importe quelle opération de la Public API avec `fun api`

fun api expose chaque opération de la Public API, générée à partir de ses spécifications OpenAPI. Les nouvelles opérations deviennent disponibles sans nouvelle version de la CLI.

Téléchargez les spécifications une fois, puis de nouveau chaque fois que vous avez besoin d'opérations nouvellement publiées :

fun api refresh

Découvrez les opérations, de la version jusqu'à l'opération :

fun api v1 --help
fun api v1 device --help
fun api v1 device get-device --help

Appelez une opération. Les paramètres de chemin sont des options obligatoires, et chaque paramètre est une option en kebab-case :

fun api v1 device get-device --project-id <project-id> --device-id <device-id>

Envoyez un corps en ligne, depuis un fichier ou depuis stdin :

fun api v2 service-accounts create-service-account --project-id <project-id> \
  --body-file service-account.json

Les noms de groupes et d'opérations proviennent de la spécification ; ils peuvent donc changer lorsque les spécifications changent. Utilisez fun api pour l'exploration et les appels ponctuels, et privilégiez les commandes sélectionnées dans les automatisations de longue durée.

6. Automatiser avec la CLI

La CLI réserve stdout au JSON afin que vous puissiez le chaîner avec un tube :

Le JSON de la réponse va sur stdout. Le contexte actif et le statut HTTP vont sur stderr.
--data-only affiche uniquement le champ data de l'enveloppe de la réponse.
--dry-run affiche la requête sans l'envoyer.
Dans un terminal, les listes paginées ouvrent un paginateur interactif. Dans les scripts, utilisez --page <n> ou --data-only.

fun api v2 licenses list-licenses --project-id <project-id> --data-only | jq '.[].id'
fun api v1 device list-devices --project-id <project-id> --page 1 > devices.json
fun api v2 registries create-registry --project-id <project-id> --body-file registry.json --dry-run

En CI, évitez la connexion par navigateur : définissez le contexte avec des variables d'environnement et un jeton de compte de service :

export FUN_CONTEXT_FUNDAMENTUM_IOT_ENDPOINT=https://api.fundamentum-iot.com
export FUN_CONTEXT_API_KEY="$SERVICE_ACCOUNT_TOKEN"
fun functions invoke --project <project-id> --function-id <function-id> --input-file input.json

Stockez le jeton dans le magasin de secrets de votre CI, jamais dans le dépôt. Consultez Authentication pour créer un compte de service et son jeton.

Prochaines étapes

AI agents and skills : laissez un agent piloter la CLI à votre place.
fun CLI reference : chaque commande, option et variable d'environnement.
Public API reference et Conventions.