OAPI CLI : premiers pas et commandes essentielles

OAPI CLI vous permet de gérer vos ressources Outscale depuis le terminal. En 3 commandes, vous saurez si tout fonctionne : installer, se connecter, lister vos ressources. Ce guide vous accompagne pas à pas, du premier oapi-cli --help jusqu'à l'automatisation de vos tâches quotidiennes.

Ce que vous allez apprendre

Niveau : Débutant · Prérequis : savoir utiliser un terminal

À la fin de ce guide, vous saurez :

Installer OAPI CLI et configurer vos identifiants
Vérifier votre identité
Éviter les erreurs de débutant (mauvaise région, mauvais profil)
Lister vos ressources : VMs, volumes, images, ...
Filtrer les résultats pour n'afficher que l'essentiel

TL;DR, Votre première session OAPI CLI

Voici le chemin le plus court entre un poste vierge et une première commande qui répond. Comptez une dizaine de minutes. L'ordre compte : la dépendance FUSE se règle avant le téléchargement, sinon l'AppImage refuse de démarrer avec un message trompeur sur libfuse.so.2. Les étapes suivantes détaillent chacun de ces points.

Installer FUSE (Linux) : sudo apt-get install -y libfuse2 (Ubuntu/Debian)
Installer OAPI CLI : télécharger dans ~/.local/bin et rendre exécutable
Configurer : créer ~/.osc/config.json avec vos clés d'accès
Vérifier : oapi-cli ReadAccounts --color doit renvoyer votre compte
Lister : oapi-cli ReadVms --color pour voir vos machines virtuelles
Explorer : oapi-cli --list-calls pour découvrir les appels disponibles

Étape 1, Installer OAPI CLI

L'installation se fait en deux temps sous Linux : d'abord la dépendance système FUSE, ensuite le binaire lui-même. Sous macOS et Windows, seule la seconde partie s'applique. Comptez cinq minutes, sans droits administrateur si vous installez dans ~/.local/bin.

Prérequis : installer FUSE (Linux uniquement)

Les AppImages nécessitent FUSE (Filesystem in Userspace) pour fonctionner. Installez-le selon votre distribution :

sudo apt-get update
sudo apt-get install -y libfuse2

# Fedora
sudo dnf install -y fuse-libs

# RHEL/CentOS 7
sudo yum install -y fuse-libs

# RHEL/CentOS 8+
sudo dnf install -y fuse-libs

sudo pacman -S fuse2

sudo zypper install -y libfuse2

Installation de OAPI CLI

Outscale ne publie pas de paquet .deb ou .rpm : la distribution passe par une AppImage sous Linux, une formule Homebrew sous macOS et une archive zip sous Windows. Chaque release ne contient que deux fichiers, oapi-cli-x86_64.AppImage et oapi-cli-x86_64.zip, et aucun fichier de sommes de contrôle : la vérification d'intégrité se limite donc à télécharger depuis le dépôt officiel en HTTPS, puis à confirmer le résultat avec oapi-cli --version. Choisissez l'onglet correspondant à votre poste.

Installation dans ~/.local/bin (accessible sans sudo) :

# Créer le répertoire si nécessaire
mkdir -p ~/.local/bin

# Télécharger OAPI CLI
curl -L https://github.com/outscale/oapi-cli/releases/latest/download/oapi-cli-x86_64.AppImage \
  -o ~/.local/bin/oapi-cli

# Rendre exécutable
chmod +x ~/.local/bin/oapi-cli

Vérifier que ~/.local/bin est dans votre PATH :

echo $PATH | grep -q "$HOME/.local/bin" && echo "PATH OK" || echo "A faire : ajouter ~/.local/bin au PATH"

Si ~/.local/bin n'est pas dans votre PATH, ajoutez-le :

# Bash
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# Zsh
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Pour rendre oapi-cli accessible à tous les utilisateurs :

# Télécharger
curl -LO https://github.com/outscale/oapi-cli/releases/latest/download/oapi-cli-x86_64.AppImage

# Installer globalement (nécessite sudo)
sudo mv oapi-cli-x86_64.AppImage /usr/local/bin/oapi-cli
sudo chmod +x /usr/local/bin/oapi-cli

Si vous voyez toujours une erreur libfuse.so.2, utilisez l'option --appimage-extract-and-run :

oapi-cli --appimage-extract-and-run ReadRegions --color

Créer un alias pour ne pas taper l'option à chaque fois :

echo 'alias oapi-cli="$HOME/.local/bin/oapi-cli --appimage-extract-and-run"' >> ~/.bashrc
source ~/.bashrc

Cette méthode est beaucoup plus lente : l'AppImage est décompressée dans /tmp à chaque exécution. Préférez installer FUSE si possible.

# Via Homebrew
brew tap outscale/tap
brew install outscale/tap/oapi-cli

Ou installation manuelle :

git clone https://github.com/outscale/homebrew-tap
cd homebrew-tap
brew install Formula/oapi-cli.rb

Téléchargez oapi-cli-x86_64.zip depuis Releases
Extrayez l'archive
Lancez oapi-cli.exe depuis PowerShell ou cmd

Vérifiez l'installation :

oapi-cli --version

oapi-cli version: 0.15.0
osc-sdk-c version: 00.21.00
based on osc-api: 1.41.0

Trois numéros apparaissent, ne les confondez pas. Le premier est la version de la CLI elle-même, celle qui vous intéresse pour comparer avec la page Releases. Le deuxième désigne le SDK C embarqué. Le troisième indique la version de la spécification osc-api à partir de laquelle les appels ont été générés : c'est lui qui détermine quels appels et quels paramètres sont disponibles, indépendamment de la version de la CLI.

Activer l'autocomplétion (recommandé)

L'autocomplétion vous fait gagner du temps : tapez oapi-cli Read puis Tab, et OAPI CLI complète automatiquement en ReadVms, ReadVolumes, ReadRegions...

Bash
Zsh

# Générer le script de complétion
oapi-cli --bash-completion > ~/.oapi-cli-completion.bash

# Activer l'autocomplétion
echo 'source ~/.oapi-cli-completion.bash' >> ~/.bashrc

# Recharger la configuration
source ~/.bashrc

Tester : tapez oapi-cli Read puis Tab → vous devriez voir ReadVms, ReadVolumes, ReadRegions...

# Activer le support des complétions Bash
echo 'autoload bashcompinit && bashcompinit' >> ~/.zshrc

# Générer et sourcer le script
oapi-cli --bash-completion > ~/.oapi-cli-completion.bash
echo 'source ~/.oapi-cli-completion.bash' >> ~/.zshrc

# Recharger
source ~/.zshrc

Tester : tapez oapi-cli Read puis Tab → vous devriez voir les suggestions.

L'autocomplétion fonctionne également pour les paramètres :

oapi-cli ReadVms --Filters.<Tab>
# Affiche : --Filters.VmStateNames[] --Filters.VmIds[] --Filters.TagKeys[] ...

Étape 2, Se connecter à son compte Outscale

Deux façons de fournir vos identifiants coexistent : un fichier de configuration sur le disque, ou des variables d'environnement. Le fichier convient au poste de travail, les variables aux pipelines CI/CD où l'on ne veut rien écrire sur le disque. Les deux acceptent la notion de profil, ce qui permet de basculer entre plusieurs comptes sans réécrire quoi que ce soit.

Créer le fichier de configuration

OAPI CLI utilise un fichier JSON pour stocker vos identifiants. Il n'existe pas d'assistant interactif comparable à aws configure : le fichier se crée à la main, et sa syntaxe JSON doit être valide, sans virgule en trop après le dernier profil.

Créer le répertoire de configuration (Linux/macOS uniquement)
Fenêtre de terminal
```
mkdir -p ~/.osc
```

Créer le fichier config.json

Linux/macOS
Windows

cat > ~/.osc/config.json << 'EOF'
{
    "default": {
        "access_key": "VOTRE_ACCESS_KEY",
        "secret_key": "VOTRE_SECRET_KEY",
        "region": "eu-west-2"
    }
}
EOF

Créez config.json dans le même répertoire que oapi-cli.exe :

{
    "default": {
        "access_key": "VOTRE_ACCESS_KEY",
        "secret_key": "VOTRE_SECRET_KEY",
        "region": "eu-west-2"
    }
}

Remplacer les valeurs

Champ	Où le trouver	Exemple
`access_key`	Console Outscale → Cockpit → Mon Compte → Clés d'accès	`AKIA...`
`secret_key`	Affiché UNE SEULE fois à la création	`wJalr...`
`region`	`eu-west-2` (commerciale, France) ou `cloudgouv-eu-west-1` (SecNumCloud, France)	`eu-west-2`

Méthode alternative : variables d'environnement

Au lieu du fichier config.json, vous pouvez utiliser des variables d'environnement :

# Authentification par clés
export OSC_ACCESS_KEY="VOTRE_ACCESS_KEY"
export OSC_SECRET_KEY="VOTRE_SECRET_KEY"
export OSC_REGION="eu-west-2"

# Vérifier
oapi-cli ReadAccounts --color

Cette méthode est utile pour les scripts CI/CD ou les environnements temporaires : les identifiants restent hors du disque et disparaissent avec le shell. Attention toutefois, ces variables ne s'appliquent que si aucun profil n'est nommé par --profile= ou OSC_PROFILE ; dans le cas contraire, elles sont ignorées au profit des clés du profil.

Étape 3, Vérifier son identité (le "whoami" Outscale)

Avant toute commande potentiellement destructrice, vérifiez que vous êtes connecté au bon compte. L'appel qui remplit ce rôle avec des clés d'accès est ReadAccounts : il renvoie les informations du compte auquel appartient la clé utilisée.

oapi-cli ReadAccounts --color

Une réponse contenant un bloc Accounts signifie deux choses : le fichier de configuration est lu, et la paire clé d'accès / clé secrète est acceptée par l'API. Vous voyez au passage l'adresse e-mail rattachée au compte, ce qui permet de repérer immédiatement une erreur de profil.

Malgré son nom, CheckAuthentication ne teste pas une paire clé d'accès / clé secrète. Ses paramètres Login et Password sont obligatoires. Lancé sans eux, il retourne :

{"Errors":[{"Details":"One or more required parameters are missing: 'Login / Password'.","Type":"MissingParameter","Code":"7000"}]}

Cet appel sert au scénario d'authentification par e-mail et mot de passe, décrit en annexe, pas à la validation d'une installation.

ReadRegions est parfois proposé comme test de connexion. C'est un faux test : la liste des régions est renvoyée même avec des clés totalement invalides. Comparez les deux comportements avec une clé bidon :

# Renvoie la liste des régions même avec des clés fausses : ne prouve rien
oapi-cli ReadRegions

# Renvoie une erreur si les clés sont mauvaises : c'est le vrai test
oapi-cli ReadAccounts

Avec des clés invalides, ReadAccounts et ReadVms répondent InvalidParameterValue avec le code 4120. Si vous voyez ce code, reprenez votre config.json : la clé d'accès ou la clé secrète est erronée, ou le profil sélectionné n'est pas celui que vous croyez.

Checklist avant commande dangereuse

Trois vérifications à enchaîner avant toute suppression. Elles répondent à trois questions différentes, et les faire dans cet ordre a son importance : la première interroge l'API, les deux suivantes votre environnement local. Une variable OSC_ACCESS_KEY oubliée dans un shell l'emporte sur le fichier de configuration et fait viser un tout autre compte, sans aucun message d'avertissement.

# 1. À quel compte mes clés donnent-elles accès ?
oapi-cli ReadAccounts --color

# 2. Quel profil est actif ?
echo $OSC_PROFILE

# 3. Y a-t-il des variables d'environnement qui prennent le dessus ?
env | grep OSC_

Étape 4, Vos premières commandes (lister des ressources)

Maintenant que vous êtes connecté, explorons vos ressources. Vous allez lancer 4 commandes qui vous permettront de comprendre comment OAPI CLI fonctionne.

Comment fonctionne OAPI CLI ?

Avant de commencer, comprenons la logique. OAPI CLI utilise des appels d'API directs : chaque commande correspond à un endpoint de l'API Outscale (CreateVms, ReadVms, DeleteVms...).

🧠 Modèle mental — oapi-cli = un appel API direct

OAPI CLI appelle directement l'API Outscale. Contrairement à AWS CLI (aws service action), ici vous appelez directement l'action (ReadVms, CreateVolume...). La réponse arrive en JSON par défaut.

Structure d'une commande Oapi CLI : oapi-cli + action + options

Points clés

Appel API direct : ReadVms = GET /api/latest/ReadVms
Le JSON est retourné directement (--color pour le formatter)
Chaque commande cible UNE région (eu-west-2 par défaut)

Règles d'or

Toujours vérifier la connexion avant une action oapi-cli ReadAccounts affiche le compte réellement visé

Ne jamais mettre ses clés dans le code Les credentials dans Git = compte compromis en quelques minutes

Vocabulaire essentiel

Région: Zone géographique Outscale (eu-west-2 = Paris)
Profil: Configuration nommée dans config.json
Vm: Virtual Machine (équivalent EC2 chez AWS)

Syntaxe complète

Trois formes suffisent à se repérer dans l'outil. La première exécute un appel, les deux autres servent à explorer l'API sans quitter le terminal. Elles sont votre meilleure source de vérité : la documentation en ligne décrit l'API Outscale dans son ensemble, tandis que --list-calls et --help reflètent exactement ce que votre binaire sait faire, selon la version d'osc-api sur laquelle il a été généré.

oapi-cli <Action> [--options]
oapi-cli --help [Action]              # Aide sur une action
oapi-cli --list-calls                 # Lister toutes les actions disponibles

Options globales principales :

Option	Description	Exemple
`--profile=NOM`	Utilise un profil spécifique	`oapi-cli --profile=production ReadVms`
`--color`	Colorise et formate le JSON	`oapi-cli ReadVms --color`
`--raw-print`	Sortie brute sans formatting	`oapi-cli ReadVms --raw-print`
`--verbose`	Mode debug avec requêtes curl	`oapi-cli ReadVms --verbose`
`--config=PATH`	Chemin du fichier de config	`oapi-cli --config=./custom.json ReadVms`

Le choix du profil peut aussi se faire via la variable d'environnement OSC_PROFILE (utile pour fixer le profil actif sur toute la session shell).

Formes courantes :

# Forme minimale : action seule
oapi-cli ReadRegions

# Avec filtres (syntaxe JSON)
oapi-cli ReadVms --Filters.VmStateNames[] running --color

# Avec variables (chaînage)
oapi-cli CreateVms --ImageId ami-xxx --set-var vm_id=Vms.0.VmId \
  CreateTags --ResourceIds[] --var vm_id --Tags.0.Key Name --Tags.0.Value "MaVM"

# Depuis un fichier JSON
echo '{"VolumeId": "vol-12345678"}' > params.json
oapi-cli DeleteVolume --file params.json

# Avec un profil donné (flag ou variable d'environnement)
oapi-cli --profile=production ReadVms --color
OSC_PROFILE=production oapi-cli ReadVms --color

Les 3 parties d'une commande OAPI CLI

La commande oapi-cli suit toujours la même logique :

Partie	Question	Exemples	Obligatoire ?
Action	Quel appel API effectuer ?	`ReadVms`, `CreateVolume`, `DeleteSnapshot`	Oui
Paramètres	Quels arguments passer ?	`--Filters.VmIds[] i-xxx`, `--Size 10`	Non (selon l'API)
Options	Comment formater la sortie ?	`--color`, `--raw-print`, `--profile`, `--config`	Non (valeurs par défaut)

Action : l'appel d'API Outscale que vous voulez effectuer. Suit la convention CRUD : Create*, Read*, Update*, Delete*.

Paramètres : les arguments de l'API (filtres, IDs, tailles...). La syntaxe suit la structure JSON de l'API.

Options (optionnelles), Modifient le comportement de la CLI : coloriser le JSON, changer de profil, mode debug.

Exemple concret :

# Action=ReadVms, Paramètre=--Filters.VmStateNames[], Option=--color
oapi-cli ReadVms '--Filters.VmStateNames[]' running --color
#        ↑       ↑                              ↑
#      action   paramètres                   options

Commande 1 : Lister les régions Outscale

Objectif : Découvrir les régions servies par l'endpoint que vous interrogez.

oapi-cli ReadRegions

Ce que vous verrez :

{
  "ResponseContext": {
    "RequestId": "150d2d16-0c18-4a3f-94b8-ebd975a68d18"
  },
  "Regions": [
    {
      "RegionName": "eu-west-2",
      "Endpoint": "api.eu-west-2.outscale.com"
    },
    {
      "RegionName": "us-east-2",
      "Endpoint": "api.us-east-2.outscale.com"
    },
    {
      "RegionName": "us-west-1",
      "Endpoint": "api.us-west-1.outscale.com"
    }
  ]
}

Pourquoi c'est important :

La réponse liste les régions du cloud commercial. La région SecNumCloud cloudgouv-eu-west-1 dispose de son propre endpoint et n'apparaît pas dans cette liste : elle se sélectionne explicitement dans le profil.
Ce parcours OUTSCALE se concentre sur les régions européennes : eu-west-2 (commerciale, France) et cloudgouv-eu-west-1 (SecNumCloud, France).
Chaque région est isolée : une ressource créée dans une région n'est pas visible depuis une autre.
Le choix se fait selon le niveau de qualification requis (RGPD seul ou SecNumCloud) et la localisation des utilisateurs.

Commande 2 : Lister vos machines virtuelles

Objectif : Voir toutes vos VMs (équivalent aws ec2 describe-instances).

oapi-cli ReadVms

Deux cas possibles :

Vous n'avez pas de VMs : "Vms": [] (tableau vide)
Vous avez des VMs : vous verrez la liste complète avec ID, état, type, réseau...

{
  "ResponseContext": {
    "RequestId": "5d143c09-ef80-4d00-b87c-cad2e39185b4"
  },
  "Vms": [
    {
      "VmId": "i-935b34c8",
      "VmType": "tinav6.c2r4p1",
      "State": "running",
      "ImageId": "ami-0016b8a0",
      "PublicIp": "148.253.90.33",
      "PrivateIp": "10.20.1.36",
      "SubregionName": "eu-west-2a",
      "Tags": [
        {"Key": "Name", "Value": "production-bastion"},
        {"Key": "Role", "Value": "Bastion"}
      ]
    }
  ]
}

Filtrer pour n'afficher que les VMs en cours d'exécution :

# Syntaxe JSON (recommandée)
oapi-cli ReadVms --Filters.VmStateNames '["running"]'

# Compter le nombre de VMs actives
oapi-cli ReadVms --Filters.VmStateNames '["running"]' | jq '.Vms | length'
# Résultat : 10

Commande 3 : Lister vos volumes de stockage

Objectif : Voir vos volumes BSU (Block Storage Unit, équivalent EBS).

oapi-cli ReadVolumes

Trois champs méritent votre attention dans la réponse. State distingue un volume in-use, rattaché à une VM, d'un volume available qui n'est attaché à rien : ces derniers continuent d'être facturés et constituent la première source de dépense oubliée sur un compte cloud. SubregionName conditionne l'attachement, un volume ne peut être monté que sur une VM de la même sous-région. Iops varie avec le type et la taille, et explique les écarts de performance entre deux volumes d'apparence identique.

Ce que vous verrez :

{
  "Volumes": [
    {
      "VolumeId": "vol-c8356578",
      "Size": 50,
      "VolumeType": "gp2",
      "State": "available",
      "Iops": 150,
      "SubregionName": "eu-west-2c",
      "CreationDate": "2025-11-29T12:16:02.613Z",
      "Tags": [
        {"Key": "CSIVolumeName", "Value": "pvc-75bcb119-4382-49d5-afd2-99c8f85315b6"}
      ]
    },
    {
      "VolumeId": "vol-453dc569",
      "Size": 1,
      "VolumeType": "gp2",
      "State": "available",
      "Iops": 100,
      "SubregionName": "eu-west-2a",
      "CreationDate": "2025-11-29T12:16:02.648Z"
    }
  ]
}

Commande 4 : Lister vos images (OMI)

Objectif : Voir les images disponibles pour créer des VMs.

# Lister toutes les images
oapi-cli ReadImages | jq '.Images | length'
# Résultat : 446 images

# Lister VOS images uniquement (celles de votre compte)
oapi-cli ReadImages | jq '.Images[] | select(.AccountAlias != null) | {ImageId, ImageName, State}'

# Extraire les 5 premières images avec leur nom
oapi-cli ReadImages | jq -r '.Images[0:5] | .[] | "\(.ImageId)\t\(.ImageName)"'

Pour chercher des images spécifiques :

# Chercher les images Ubuntu
oapi-cli ReadImages | jq '.Images[] | select(.ImageName | test("Ubuntu"; "i")) | {ImageId, ImageName}' | head -20

# Chercher avec jq les images contenant "official" dans le nom
oapi-cli ReadImages | jq -r '.Images[] | select(.ImageName | test("official"; "i")) | "\(.ImageId)\t\(.ImageName)"'

Récap de vos 4 premières commandes :

Commande	Action	Ce qu'on apprend
`oapi-cli ReadRegions`	Lister régions	Comprendre la géographie Outscale
`oapi-cli ReadVms`	Lister VMs	Voir ses machines virtuelles
`oapi-cli ReadVolumes`	Lister volumes	Voir ses disques de stockage
`oapi-cli ReadImages`	Lister images	Voir les templates de VMs

Vous venez de valider que votre configuration fonctionne sur trois ressources majeures (VMs, volumes, images).

Découvrir les autres actions par vous-même

OAPI CLI expose 235 actions en version 0.15.0 (CreateVms, DeleteVolume, CreateSnapshot, ReadSubnets...), dont 73 commençant par Read. Il est impossible de toutes les documenter dans un seul guide. Mais la bonne nouvelle, c'est que vous savez déjà chercher.

Trois techniques pour explorer une nouvelle action :

Lister toutes les actions disponibles
Fenêtre de terminal
```
oapi-cli --list-calls
```
Vous verrez toutes les actions classées alphabétiquement : CreateVms, ReadVms, UpdateVm, DeleteVms...
Consulter l'aide d'une action spécifique
Fenêtre de terminal
```
oapi-cli --help ReadVms
```
Affiche :
- La description de l'action
- Les paramètres requis et optionnels
- Les types de chaque paramètre
Utiliser l'autocomplétion

Si vous avez activé l'autocomplétion, tapez oapi-cli Read puis Tab Tab pour voir toutes les actions Read* :
Fenêtre de terminal
```
oapi-cli Read<Tab><Tab>
# Affiche : ReadVms, ReadVolumes, ReadImages, ReadRegions...
```

Pour apprendre une nouvelle action :

oapi-cli --list-calls | grep ACTION → trouver l'action exacte
oapi-cli --help ACTION → voir les paramètres requis
oapi-cli ACTION --color → tester sans paramètres (lecture seule)
oapi-cli ACTION --file params.json → passer des params complexes

Exemple avec les snapshots (sauvegardes de volumes) :

# 1. Trouver l'action
oapi-cli --list-calls | grep Snapshot

# 2. Lire l'aide
oapi-cli --help ReadSnapshots

# 3. Lister les snapshots
oapi-cli ReadSnapshots --color

# 4. Créer un snapshot
oapi-cli CreateSnapshot --VolumeId vol-12345678 --color

Règle d'or : sur OAPI CLI, 90% des actions suivent les mêmes conventions :

Read* pour lire (ReadVms, ReadVolumes, ReadImages)
Create* pour créer (CreateVms, CreateVolume, CreateSnapshot)
Delete* pour supprimer (DeleteVolume, DeleteSnapshot)
Update* pour modifier (UpdateVm, UpdateVolume)

Maintenant que vous savez explorer, passons au filtrage pour rendre ces sorties exploitables.

Étape 5, Filtrer les résultats

OAPI CLI retourne du JSON brut. Pour n'afficher que l'essentiel, deux méthodes.

Méthode 1 : jq (post-traitement)

jq filtre les résultats après réception. Idéal pour extraire des champs précis :

# Extraire uniquement les IDs des VMs
oapi-cli ReadVms | jq -r '.Vms[].VmId'

# Format tabulaire : ID + État + Type + Nom
oapi-cli ReadVms | jq -r '.Vms[] | "\(.VmId)\t\(.State)\t\(.VmType)\t\(.Tags[]? | select(.Key=="Name") | .Value)"'

Notez les guillemets doubles non échappés autour de "Name". Le programme jq est délimité par des quotes simples, donc les doubles y passent telles quelles. Les écrire \"Name\" produit syntax error, unexpected INVALID_CHARACTER, une erreur fréquente quand on recopie un exemple prévu pour un autre shell.

Résultat :

i-935b34c8       running tinav6.c2r4p1   production-bastion
i-3b64ecf1       running tinav6.c2r4p1   production-monitoring
i-cb0491b4       running tinav6.c4r8p1   production-k8s-master-2
i-777755b4       running tinav6.c4r8p1   production-k8s-master-1

# Compter le nombre de VMs
oapi-cli ReadVms | jq '.Vms | length'
# Résultat : 10

# Extraire uniquement les VMs avec un tag Name
oapi-cli ReadVms | jq '.Vms[] | select(.Tags[]? | .Key == "Name") | {VmId, Name: (.Tags[] | select(.Key=="Name") | .Value)}'

Méthode 2 : --Filters (côté serveur)

Les filtres --Filters.* sont traités par l'API Outscale avant l'envoi des données. Plus rapide pour les gros listings :

Syntaxe importante : Les filtres acceptent des tableaux JSON. Utilisez la syntaxe '["valeur"]' avec des quotes :

# Uniquement les VMs en cours d'exécution
oapi-cli ReadVms --Filters.VmStateNames '["running"]'

# VMs avec un type spécifique
oapi-cli ReadVms --Filters.VmTypes '["tinav6.c4r8p1"]'

# Volumes dans une sous-région
oapi-cli ReadVolumes --Filters.SubregionNames '["eu-west-2a"]'

# Images appartenant à un compte donné
oapi-cli ReadImages --Filters.AccountIds '["123456789012"]'

Les filtres attendent un tableau JSON, pas une valeur nue :

# Refusé par l'API
oapi-cli ReadVms --Filters.VmStateNames running

# Accepté
oapi-cli ReadVms --Filters.VmStateNames '["running"]'

# Plusieurs valeurs
oapi-cli ReadVms --Filters.VmStateNames '["running", "pending"]'

La première forme ne provoque pas une erreur locale mais un rejet côté serveur : InvalidParameter, code 3003, avec le détail « The request body must be a valid JSON object. » Voir ce code doit vous faire relire vos quotes avant toute autre chose.

Une variante existe, l'ajout élément par élément : oapi-cli ReadVms '--Filters.VmStateNames[]' running. Sous Zsh, les crochets sont interprétés par le shell et déclenchent « no matches found » : entourez alors l'option de quotes simples, comme ci-dessus.

Filtres courants

Ces neuf filtres couvrent l'essentiel des besoins de listage. Deux principes de lecture : le nom du filtre est toujours au pluriel parce qu'il attend un tableau, et il est spécifique à l'action (VolumeStates n'existe que sur ReadVolumes). En cas de doute, oapi-cli --help ReadVolumes affiche la structure de filtre attendue par l'appel.

Ressource	Filtre	Exemple
VMs	État	`--Filters.VmStateNames '["running"]'`
VMs	Type	`--Filters.VmTypes '["tinav6.c4r8p1"]'`
VMs	Tag (clé)	`--Filters.TagKeys '["Environment"]'`
VMs	Tag (valeur)	`--Filters.TagValues '["production"]'`
Volumes	Taille	`--Filters.VolumeSizes '[100]'`
Volumes	Type	`--Filters.VolumeTypes '["gp2"]'`
Volumes	État	`--Filters.VolumeStates '["available"]'`
Images	Compte	`--Filters.AccountIds '["123456789012"]'`
Images	Nom	`--Filters.ImageNames '["Ubuntu*"]'`

Combiner filtres et jq

La combinaison gagnante consiste à réduire d'abord le volume côté serveur avec --Filters, puis à mettre en forme côté client avec jq. Faire l'inverse fonctionne mais transfère l'intégralité du listing sur le réseau, ce qui devient sensible sur les comptes chargés, notamment avec ReadImages qui retourne plusieurs centaines d'entrées.

# Filtrer côté serveur PUIS extraire avec jq
oapi-cli ReadVms --Filters.VmStateNames '["running"]' | jq '.Vms | length'
# Résultat : 10 (nombre de VMs actives)

# Lister uniquement les IDs des VMs arrêtées
oapi-cli ReadVms --Filters.VmStateNames '["stopped"]' | jq -r '.Vms[].VmId'

# Volumes disponibles avec leur taille
oapi-cli ReadVolumes --Filters.VolumeStates '["available"]' | \
  jq -r '.Volumes[] | "\(.VolumeId)\t\(.Size) GB\t\(.VolumeType)"'
# Résultat : 9 volumes disponibles avec vol-xxx  50 GB  gp2

Étape 6, Gérer plusieurs comptes (profils)

Si vous travaillez avec plusieurs comptes Outscale (dev, staging, prod), créez des profils séparés dans config.json.

Créer plusieurs profils

Éditez ~/.osc/config.json (ou .\config.json sur Windows) :

{
    "default": {
        "access_key": "AK_DEV",
        "secret_key": "SK_DEV",
        "region": "eu-west-2"
    },
    "production": {
        "access_key": "AK_PROD",
        "secret_key": "SK_PROD",
        "region": "eu-west-2"
    },
    "secnumcloud": {
        "access_key": "AK_GOUV",
        "secret_key": "SK_GOUV",
        "region": "cloudgouv-eu-west-1"
    }
}

Utiliser un profil

oapi-cli accepte deux formes pour sélectionner le profil :

# Flag pour une commande ponctuelle
oapi-cli --profile=production ReadVms --color

# Variable d'environnement pour toute la session
export OSC_PROFILE=production
oapi-cli ReadVms --color  # utilise automatiquement "production"

Vérifier quel profil est actif

Aucune commande n'affiche directement le profil courant : il faut inspecter l'environnement. La règle observée sur la version 0.15.0 tient en une phrase : dès qu'un profil est nommé, par le flag --profile= ou par la variable OSC_PROFILE, ce sont les clés de ce profil qui signent la requête, et les variables OSC_ACCESS_KEY / OSC_SECRET_KEY sont ignorées. Ces variables ne l'emportent que lorsqu'aucun profil n'est nommé, auquel cas elles remplacent le profil default. Un env | grep OSC_ qui remonte une clé oubliée dans le shell explique la majorité des « je ne comprends pas, je vois les ressources d'un autre compte ».

# Variable d'environnement
echo $OSC_PROFILE

# Ou vérifier toutes les variables OSC_*
env | grep OSC_

Le seul contrôle qui ne ment pas reste oapi-cli ReadAccounts --color : il interroge l'API avec la configuration réellement appliquée et retourne le compte qui répond.

Recettes du quotidien

Ces commandes couvrent les opérations les plus fréquentes avec OAPI CLI : vérifier sa connexion, lister ses ressources, créer une VM ou un volume, et explorer la documentation intégrée.

Vérifier la connexion

Confirmer l'authentification avant toute action, le réflexe de sécurité de base. La réponse contient l'adresse e-mail du compte : lisez-la, c'est elle qui vous dit si vous visez la production.

oapi-cli ReadAccounts --color
# Exemple
oapi-cli --profile=production ReadAccounts --color

Lister les VMs

Voir toutes les machines virtuelles du compte courant.

oapi-cli ReadVms
# Filtrer sur les VMs en cours d'exécution
oapi-cli ReadVms --Filters.VmStateNames '["running"]'

Lister les volumes

Voir tous les volumes de stockage BSU. Filtrer sur l'état available est le réflexe le plus rentable : ce sont les volumes détachés, facturés sans rien servir.

oapi-cli ReadVolumes
# Filtrer sur un type de volume
oapi-cli ReadVolumes --Filters.VolumeTypes '["gp2"]'

Lister les régions

Voir les régions Outscale disponibles. Rappel utile : cet appel répond même avec des clés invalides, il renseigne sur l'endpoint joint, pas sur votre authentification.

oapi-cli ReadRegions
# Extraire uniquement les noms de régions
oapi-cli ReadRegions | jq -r '.Regions[].RegionName'

Lister les images disponibles

Voir toutes les images (OMI) utilisables pour créer des VMs.

oapi-cli ReadImages
# Compter le nombre d'images
oapi-cli ReadImages | jq '.Images | length'

Détails d'une VM

Afficher les informations complètes d'une VM précise.

oapi-cli ReadVms --Filters.VmIds '["VM_ID"]'
# Exemple
oapi-cli ReadVms --Filters.VmIds '["i-935b34c8"]' | jq '.Vms[0]'

VM_ID est l'identifiant de la VM, au format i-935b34c8.

Créer une VM

Lancer une nouvelle machine virtuelle. Trois paramètres décident de la facture et du placement : l'image, le type TINA et la sous-région. Omettre SubregionName laisse Outscale choisir, ce qui pose problème dès qu'un volume doit être attaché ensuite.

oapi-cli CreateVms --ImageId IMAGE_ID --VmType VM_TYPE
# Exemple
oapi-cli CreateVms --ImageId ami-0016b8a0 --VmType tinav6.c2r4p1 --SubregionName eu-west-2a

IMAGE_ID : identifiant de l'image (ami-xxx).
VM_TYPE : type de VM au format TINA (tinav6.c2r4p1).

Créer un volume

Créer un volume de stockage BSU. La sous-région doit être la même que celle de la VM à laquelle vous comptez l'attacher, sinon l'attachement sera refusé et il faudra recréer le volume.

oapi-cli CreateVolume --Size SIZE --SubregionName SUBREGION
# Exemple
oapi-cli CreateVolume --Size 100 --SubregionName eu-west-2a --VolumeType gp2

SIZE : taille du volume en Go.
SUBREGION : sous-région cible (eu-west-2a).

Lister les actions disponibles

Voir l'ensemble des actions OAPI CLI, pour explorer l'API.

oapi-cli --list-calls
# Cibler une famille d'actions
oapi-cli --list-calls | grep Snapshot

Aide sur une action

Voir les paramètres requis et optionnels d'une action.

oapi-cli --help ACTION
# Exemple
oapi-cli --help CreateVms

ACTION est le nom exact de l'action (ReadVms, CreateVms, etc.).

Pièges courants

Ces erreurs sont les plus fréquentes en début de prise en main d'OAPI CLI. Les connaître évite des incidents de production et des heures de diagnostic.

Exécuter sur le mauvais profil

oapi-cli DeleteVms --VmIds[] i-xxx

Symptôme : une VM de production est supprimée à la place d'une VM de dev.

Cause : le profil par défaut pointe vers le compte de production. Vérifiez toujours l'identité avant une commande destructrice.

oapi-cli --profile=dev ReadAccounts --color && \
  oapi-cli --profile=dev DeleteVms --VmIds[] i-xxx

Région non configurée

oapi-cli ReadVms

Symptôme : timeout, ou résultats systématiquement vides.

Cause : aucune région n'est définie dans config.json.

export OSC_REGION=eu-west-2 && oapi-cli ReadVms --color

Clé d'accès de mauvaise longueur

oapi-cli ReadVms

Symptôme : wrong access key or secret key size puis fail to init C sdk, sans le moindre appel réseau.

Cause : oapi-cli contrôle la longueur des clés avant de démarrer. Une clé d'accès tronquée au copier-coller, ou une clé secrète amputée d'un caractère, déclenche ce message. Recopiez les valeurs depuis le Cockpit et vérifiez qu'aucun espace ni retour à la ligne ne s'est glissé dans le JSON.

Credentials dans Git

Le fichier config.json est committé dans le dépôt avec les clés d'accès.

Symptôme : compte Outscale compromis, ressources créées par des bots.

Cause : config.json ajouté au dépôt Git par erreur. Ajoutez-le au .gitignore, révoquez immédiatement les clés exposées et générez-en de nouvelles.

Config au mauvais endroit sur Windows

Le fichier config.json est placé dans ~/.osc/ sur Windows.

Symptôme : Authentication failed malgré des clés valides.

Cause : sur Windows, config.json doit se trouver dans le même répertoire que oapi-cli.exe, pas dans ~/.osc/. Déplacez-le à côté de l'exécutable.

Erreur FUSE sur Linux

./oapi-cli-x86_64.AppImage ReadVms

Symptôme : dlopen(): error loading libfuse.so.2.

Cause : FUSE n'est pas installé sur le système. Installez libfuse2, ou utilisez l'extraction à la volée (plus lente, mais sans dépendance).

./oapi-cli-x86_64.AppImage --appimage-extract-and-run ReadVms --color

Confort au quotidien

Activer la colorisation par défaut

Au lieu de taper --color à chaque fois, créez un alias :

# Bash/Zsh
echo 'alias oapi="oapi-cli --color"' >> ~/.bashrc
source ~/.bashrc

# Utilisation
oapi ReadVms
oapi ReadVolumes

Mode verbose pour debug

Si une commande échoue, activez le mode verbose pour voir les requêtes HTTP :

oapi-cli ReadVms --verbose --color

Vous verrez :

L'URL appelée
Les headers HTTP
Le corps de la requête et de la réponse

Chaîner les commandes avec --set-var

OAPI CLI permet de capturer des valeurs d'une commande pour les réutiliser dans la suivante :

# Créer une VM et capturer son ID
oapi-cli CreateVms --ImageId ami-xxx --VmType tinav6.c2r4p2 \
  --set-var vm_id=Vms.0.VmId \
  CreateTags --ResourceIds[] --var vm_id --Tags.0.Key Name --Tags.0.Value "MaVM"

Cette syntaxe crée une VM, extrait son VmId, et l'utilise immédiatement pour créer un tag.

Aide-mémoire

À garder sous la main : la syntaxe générale, les options, les filtres et les actions de lecture les plus courantes.

Syntaxe et aide

Les quatre lignes qui suivent sont celles à retenir en priorité. Les deux dernières remplacent avantageusement une recherche web : elles décrivent l'API telle que votre binaire la connaît, ce qui évite de découvrir en production qu'un paramètre documenté en ligne n'existe pas encore dans votre version.

Syntaxe	Signification	Exemple
`oapi-cli <Action> [--options]`	Schéma général d'une commande	`oapi-cli ReadVms --color`
`oapi-cli --version`	Vérifier l'installation	`0.15.0`
`oapi-cli --list-calls`	Lister toutes les actions	`ReadVms, CreateVolume...`
`oapi-cli --help ACTION`	Aide sur une action	`oapi-cli --help ReadVms`

Configuration et profils

Ce bloc répond à la question « sur quel compte suis-je en train de travailler ». Gardez en tête la règle de priorité vérifiée plus haut : un profil nommé, par flag ou par OSC_PROFILE, l'emporte sur les variables OSC_ACCESS_KEY et OSC_SECRET_KEY. La dernière ligne du tableau ne donne donc qu'une indication partielle, à recouper avec env | grep OSC_.

Syntaxe	Signification	Exemple
`--profile=NOM`	Sélectionner un profil pour une commande	`oapi-cli --profile=production ReadVms`
`export OSC_PROFILE=NOM`	Définir le profil par défaut pour la session	`export OSC_PROFILE=prod`
`--color`	Coloriser et formater le JSON	`oapi-cli ReadVms --color`
`--verbose`	Mode debug avec requêtes curl	Affiche les headers HTTP
`cat ~/.osc/config.json`	Voir la config (Linux/macOS)	Profils et régions
`cat config.json`	Voir la config (Windows)	Même dossier que l'exécutable
`echo $OSC_PROFILE`	Savoir quel profil est actif	`production`

Filtres

Chaque valeur est un tableau JSON, même quand elle ne contient qu'un élément : oublier les crochets provoque le rejet InvalidParameter code 3003. La dernière ligne rappelle le complément indispensable, jq, pour transformer la réponse en quelque chose de lisible dans un terminal.

Syntaxe	Signification	Exemple
`--Filters.VmStateNames '["running"]'`	Filtrer les VMs par état	`running`, `stopped`, `pending`
`--Filters.VmTypes '["type"]'`	Filtrer par type de VM	`tinav6.c4r8p1`
`--Filters.TagKeys '["KEY"]'`	Filtrer par clé de tag	`Environment`, `Name`
`--Filters.TagValues '["VALUE"]'`	Filtrer par valeur de tag	`production`, `dev`
`--Filters.AccountIds '["123456789012"]'`	Filtrer les images d'un compte	Identifiant numérique, pas un nom
`\| jq '.Vms[].VmId'`	Extraire des champs avec jq	`i-935b34c8`

Actions de lecture

Ces appels sont non destructifs : vous pouvez tous les lancer sans risque pour découvrir un compte inconnu. Attention aux deux premières lignes, qui sont les pièges classiques du débutant : CheckAuthentication ne valide pas des clés d'accès, et ReadRegions répond même avec des clés fausses. Pour prouver que vos identifiants fonctionnent, utilisez ReadAccounts.

Syntaxe	Signification	Exemple
`CheckAuthentication --color`	Vérifier un couple e-mail/mot de passe	Requiert `--Login` et `--Password`
`ReadAccounts --color`	Identifier le compte des clés utilisées	Le vrai test d'authentification
`ReadRegions --color`	Lister les régions	Répond même avec des clés invalides
`ReadVms --color`	Lister les VMs	Toutes vos machines
`ReadVolumes --color`	Lister les volumes	Tous vos disques BSU
`ReadImages --color`	Lister les images	Toutes les OMI disponibles
`ReadSnapshots --color`	Lister les snapshots	Sauvegardes de volumes
`ReadSubnets --color`	Lister les sous-réseaux	Net et Subnets

Composition et chaînage

Ces quatre entrées permettent d'enchaîner plusieurs appels dans une seule invocation, sans passer par un script intermédiaire. Le couple --set-var / --var capture une valeur de la réponse précédente en la désignant par son chemin dans le JSON (Vms.0.VmId = premier élément du tableau Vms, champ VmId).

Syntaxe	Signification	Exemple
`--set-var vm_id=Vms.0.VmId`	Capturer une valeur	Réutilisable dans la commande suivante
`--var vm_id`	Utiliser une variable capturée	ID récupéré précédemment
`--file params.json`	Paramètres depuis un fichier JSON	Config complexe versionnée
`\| jq -r '.Vms[] \| "\(.VmId)\t\(.State)"'`	Sortie en format tabulaire	`i-xxx running`

Pour aller plus loin

EIM, identité et accès : Créer les utilisateurs et les clés d'accès que la CLI consomme, avec le périmètre de droits qui convient.
Réseau, design Net et Subnets : Le plan d'adressage à poser avant de créer la moindre ressource en ligne de commande.
Référence Terraform sur OUTSCALE : Passer des commandes ponctuelles à une infrastructure décrite en code et rejouable.

Annexe : comparaison AWS CLI vs OAPI CLI

Si vous venez d'AWS CLI, voici les équivalences :

AWS CLI	OAPI CLI	Commentaire
`aws --version`	`oapi-cli --version`	Vérifier la version
`aws configure`	Éditer `~/.osc/config.json`	Pas d'assistant interactif
`aws sts get-caller-identity`	`oapi-cli ReadAccounts`	Vérifier l'identité
`aws ec2 describe-instances`	`oapi-cli ReadVms`	Lister les VMs
`aws ec2 describe-volumes`	`oapi-cli ReadVolumes`	Lister les volumes
`aws ec2 describe-regions`	`oapi-cli ReadRegions`	Lister les régions
`aws ec2 describe-images`	`oapi-cli ReadImages`	Lister les images
`aws ec2 run-instances`	`oapi-cli CreateVms`	Créer une VM
`aws ec2 terminate-instances`	`oapi-cli DeleteVms`	Supprimer une VM
`aws --profile prod`	`oapi-cli --profile=prod ...` ou `OSC_PROFILE=prod`	Utiliser un profil
`aws --output json`	`oapi-cli --color`	Formatter le JSON

Différence majeure : AWS CLI utilise aws SERVICE ACTION (ex: aws ec2 describe-instances), tandis qu'OAPI CLI appelle directement l'action (ex: oapi-cli ReadVms).

Annexe : authentification par login/password (avancé)

En plus des clés d'accès, OAPI CLI supporte l'authentification par e-mail et mot de passe. Son périmètre est très restreint et le mécanisme se joue à deux niveaux qu'il ne faut pas confondre.

Premier niveau, la méthode de signature de la requête. Elle se pilote par les options globales --login= et --password=, ou par les variables OSC_LOGIN et OSC_PASSWORD :

export OSC_LOGIN="votre.email@exemple.fr"
export OSC_PASSWORD="VotreMotDePasse"

Second niveau, les paramètres de l'appel lui-même. CheckAuthentication attend Login et Password dans le corps de la requête, et ils ne sont pas déduits des variables d'environnement. Il faut les passer explicitement :

oapi-cli CheckAuthentication --Login votre.email@exemple.fr --Password VotreMotDePasse --color

Signer un appel de ressource avec un couple e-mail/mot de passe est refusé côté serveur :

oapi-cli --login=votre.email@exemple.fr --password=VotreMotDePasse ReadVms

{"Errors":[{"Details":"The authentication using login/password is not allowed for call 'ReadVms'.","Type":"UseOfLoginPasswordNotAllowed","Code":"12006"}]}

Pour lister ou modifier des ressources, il faut une paire clé d'accès / clé secrète. L'option --auth-method=password|accesskey|none permet de forcer explicitement la méthode quand les deux sont présentes dans l'environnement.

Annexe : utiliser un fichier JSON pour les paramètres complexes

Pour les commandes avec beaucoup de paramètres (ex: créer une VM avec réseau personnalisé), utilisez --file :

cat > create-vm.json << 'EOF'
{
  "ImageId": "ami-12345678",
  "VmType": "tinav6.c4r8p2",
  "SubregionName": "eu-west-2a",
  "SecurityGroupIds": ["sg-12345678"],
  "KeypairName": "ma-cle-ssh",
  "BlockDeviceMappings": [
    {
      "DeviceName": "/dev/sda1",
      "Bsu": {
        "VolumeSize": 50,
        "VolumeType": "gp2",
        "DeleteOnVmDeletion": true
      }
    }
  ]
}
EOF

oapi-cli CreateVms --file create-vm.json --color

Cette méthode est indispensable pour les configurations complexes et facilite la réutilisation (versionner le JSON dans Git).