Outils CLI OUTSCALE — osc-cli, oapi-cli, aws-cli

OUTSCALE met à disposition trois familles d’outils CLI pour piloter ses ressources en ligne de commande : oapi-cli (le CLI moderne en Rust, recommandé), osc-cli (le CLI historique en Python, en mode maintenance), et aws-cli utilisable sur les API compatibles AWS d’OUTSCALE. Cette page explique comment choisir entre les trois, comment installer chacun, et comment configurer ses identifiants de manière propre.

Ce que vous allez apprendre

Le rôle de chaque CLI et quand l’utiliser.
Installer oapi-cli sur Linux, macOS et Windows.
Configurer ses identifiants AK/SK de manière sécurisée.
Faire vos premiers appels à l’API OAPI depuis la ligne de commande.
Configurer aws-cli pour pointer sur les endpoints OUTSCALE.
Choisir entre les CLI selon le contexte (nouveau projet, migration, scripting).

Prérequis

Un terminal (Bash, Zsh, PowerShell) sur Linux, macOS ou Windows.
Un compte OUTSCALE actif avec une paire de clés AK/SK générée depuis le Cockpit.
Connaître les bases de la ligne de commande Linux/macOS ou PowerShell.

Tableau de comparaison rapide

Critère	`oapi-cli`	`osc-cli`	`aws-cli`
Langage	Rust	Python	Python
Installation	Binaire autonome (Linux, macOS, Windows)	Via PyPI (`pip`)	Via PyPI ou installateur officiel
API supportée	OAPI native (couverture complète)	OAPI native + API compatibles AWS	API compatibles AWS uniquement (FCU, LBU, EIM, OOS)
Statut	Recommandé — actif, fonctionnalités enrichies	Mode maintenance — corrections de bugs uniquement, plus de nouvelles fonctionnalités	Outil tiers AWS, fonctionne par compatibilité
Couverture services	100 % de l’OAPI (FlexibleGpu, VmGroup, OKS, etc.)	Couvre OAPI + API AWS-compatibles	Limité aux 4 services AWS-compatibles (EC2, S3, IAM, ELB)
Autocomplétion shell	Oui (Bash)	Limitée	Oui (Bash, Zsh, PowerShell)
Parsing des erreurs API	Propre, lisible	Stacktrace Python brut	Format AWS standard
Pseudo-variables / chaînage	Oui	Non	Non
Recommandation pour un nouveau projet	Privilégier	À éviter	Si écosystème AWS déjà en place

Choisir le bon CLI

Le choix dépend du contexte du projet et de l’expérience de l’équipe.

Cas 1 — Nouveau projet OUTSCALE

Pour un projet qui démarre sur OUTSCALE, oapi-cli est le choix recommandé. Il est maintenu activement, propose une expérience moderne (autocomplétion, messages d’erreur clairs, pseudo-variables), et couvre l’intégralité de l’OAPI native — y compris les services Outscale-spécifiques (FlexibleGpu, VmGroup, VmTemplate, CarbonFootprint).

Cas 2 — Équipe avec un écosystème AWS existant

Si votre équipe utilise déjà aws-cli au quotidien (scripts, CI/CD, automation), vous pouvez continuer à l’utiliser sur OUTSCALE en pointant les endpoints sur les API compatibles AWS (FCU, LBU, EIM, OOS). Cette approche limite la courbe d’apprentissage initiale, mais ne couvre pas les services Outscale-spécifiques. Pour ces derniers, oapi-cli reste nécessaire en complément.

Cas 3 — Code legacy avec `osc-cli`

Si vous héritez d’un projet existant qui utilise osc-cli, vous pouvez le conserver le temps d’une migration vers oapi-cli. La syntaxe est très proche : dans la majorité des cas, remplacer osc-cli api par oapi-cli en début de commande suffit. Le osc-cli étant en mode maintenance (pas de nouvelles fonctionnalités), planifier la migration évite la dette technique.

Installer `oapi-cli`

oapi-cli est distribué sous forme de binaire autonome, sans dépendance Python ou autre.

L’installation Linux passe par un AppImage ou un téléchargement direct du binaire depuis les releases GitHub officielles.

# Téléchargement de la dernière release (vérifier la version actuelle sur GitHub)
curl -L -o oapi-cli https://github.com/outscale/oapi-cli/releases/latest/download/oapi-cli-linux-x86_64

# Rendre exécutable et déplacer dans le PATH
chmod +x oapi-cli
sudo mv oapi-cli /usr/local/bin/

# Vérifier l'installation
oapi-cli --version

L’installation macOS passe par Homebrew, qui gère automatiquement le téléchargement et les mises à jour.

# Ajouter le tap officiel OUTSCALE si nécessaire
brew tap outscale/tap

# Installer oapi-cli
brew install oapi-cli

# Vérifier l'installation
oapi-cli --version

L’installation Windows passe par le téléchargement de l’archive zip depuis les releases GitHub.

# Télécharger l'archive zip depuis GitHub
# https://github.com/outscale/oapi-cli/releases/latest

# Extraire et déplacer oapi-cli.exe dans un répertoire du PATH
# Par exemple : C:\Tools\oapi-cli\

# Vérifier l'installation depuis PowerShell
oapi-cli --version

Pour activer l’autocomplétion Bash sur Linux ou macOS, sourcer le script de complétion fourni par oapi-cli :

source <(oapi-cli --bash-completion)

À ajouter à votre ~/.bashrc pour persister entre les sessions. La syntaxe exacte selon votre installation est documentée dans le README oapi-cli.

Configurer ses identifiants AK/SK

Avant de pouvoir appeler l’API, il faut fournir vos identifiants. OUTSCALE utilise une paire Access Key (AK) + Secret Key (SK) générée depuis le Cockpit (menu utilisateur > Account Settings > Access Keys).

Trois mécanismes coexistent pour passer les identifiants à oapi-cli :

Variables d’environnement

C’est l’approche la plus simple pour des tests ponctuels.

export OSC_ACCESS_KEY="<votre AK>"
export OSC_SECRET_KEY="<votre SK>"
export OSC_REGION="eu-west-2"

# Premier appel
oapi-cli ReadAccessKeys

Limite : les variables sont visibles dans l’historique shell et dans la liste des processus. À éviter pour un usage en production.

Fichier de configuration `~/.osc/config.json`

Approche recommandée pour un usage régulier. Le fichier de configuration permet de définir plusieurs profils (par exemple un profil par compte OUTSCALE ou par environnement).

{
  "default": {
    "access_key": "<votre AK>",
    "secret_key": "<votre SK>",
    "region": "eu-west-2"
  },
  "secnumcloud": {
    "access_key": "<votre AK SecNumCloud>",
    "secret_key": "<votre SK SecNumCloud>",
    "region": "cloudgouv-eu-west-1"
  }
}

Permissions du fichier : chmod 600 obligatoire pour empêcher la lecture par d’autres utilisateurs.

chmod 600 ~/.osc/config.json

Usage avec un profil spécifique : la sélection se fait via la variable d’environnement OSC_PROFILE.

export OSC_PROFILE=secnumcloud
oapi-cli ReadVms

Gestionnaire de secrets (recommandé en équipe)

Pour un usage en équipe ou en production, stocker les AK/SK dans un gestionnaire de secrets (OpenBao, HashiCorp Vault, AWS Secrets Manager via OUTSCALE) et les récupérer dynamiquement au moment de l’appel. Cette approche évite que les identifiants traînent dans des fichiers locaux ou dans l’historique shell.

# Exemple avec OpenBao (script wrapper)
export OSC_ACCESS_KEY=$(bao kv get -field=ak secret/outscale/dev)
export OSC_SECRET_KEY=$(bao kv get -field=sk secret/outscale/dev)

oapi-cli ReadVms

Premiers appels en ligne de commande

Une fois l’authentification configurée, voici quelques appels typiques pour valider le setup.

Lister les régions disponibles

oapi-cli ReadRegions

La sortie liste les régions accessibles à votre compte. Vérifiez que eu-west-2 ou cloudgouv-eu-west-1 y figure selon votre contexte.

Lister les VMs

oapi-cli ReadVms

Retourne la liste de vos VMs dans la région courante. Si la liste est vide, c’est normal — vous n’avez encore rien créé.

Créer une keypair

oapi-cli CreateKeypair --KeypairName ma-cle-test

La commande retourne la clé privée dans la réponse JSON — à sauvegarder immédiatement, elle n’est affichée qu’une fois.

Filtrer la sortie avec `jq`

oapi-cli retourne du JSON. La combinaison avec jq permet de filtrer ou reformater facilement.

# Lister uniquement les noms et IDs de VMs
oapi-cli ReadVms | jq '.Vms[] | {VmId, State, PublicIp}'

Utiliser `aws-cli` sur OUTSCALE

Si vous préférez aws-cli ou si votre équipe en dépend déjà, vous pouvez l’utiliser directement sur les API compatibles AWS d’OUTSCALE.

Configuration

# Identifiants OUTSCALE (mêmes AK/SK que pour oapi-cli)
export AWS_ACCESS_KEY_ID="<votre AK OUTSCALE>"
export AWS_SECRET_ACCESS_KEY="<votre SK OUTSCALE>"
export AWS_DEFAULT_REGION="eu-west-2"

Appels typiques

# Lister les instances via FCU (compatible EC2)
aws ec2 describe-instances \
  --endpoint-url https://fcu.eu-west-2.outscale.com

# Lister les buckets via OOS (compatible S3)
aws s3 ls \
  --endpoint-url https://oos.eu-west-2.outscale.com

# Créer un user via EIM (compatible IAM)
aws iam create-user \
  --user-name dev-team \
  --endpoint-url https://eim.eu-west-2.outscale.com

Pour un usage régulier, créer un profil dédié OUTSCALE dans ~/.aws/config et un endpoint par défaut par service.

Migrer de `osc-cli` vers `oapi-cli`

Pour une équipe qui hérite d’un code basé sur osc-cli, la migration vers oapi-cli est généralement simple : la grammaire OAPI étant la même, il suffit dans la majorité des cas de remplacer osc-cli api par oapi-cli en début de commande.

# Avant (osc-cli)
osc-cli api ReadVms

# Après (oapi-cli)
oapi-cli ReadVms

Quelques points d’attention :

Les fichiers de configuration : les deux CLI utilisent par défaut ~/.osc/config.json. La syntaxe JSON est compatible — vérifier les chemins exacts dans la doc officielle de chaque outil.
Les messages d’erreur sont plus lisibles avec oapi-cli — utile pour le debugging mais ne change pas la logique d’appel.
Les nouvelles fonctionnalités OAPI sortent uniquement sur oapi-cli. Tout code qui dépend des derniers ajouts doit migrer.

Pour la coexistence temporaire, les deux CLI peuvent être installés en parallèle sans conflit.

Comprendre les erreurs API OUTSCALE

Tous les appels OAPI qui échouent retournent une réponse JSON structurée que les CLI affichent (oapi-cli formate de manière lisible, osc-cli peut afficher une stacktrace Python). Comprendre la structure des erreurs accélère le diagnostic.

Structure d’une erreur OAPI

Chaque erreur retournée par l’OAPI contient trois champs clés :

Champ	Rôle
`Code`	Identifiant numérique unique (par exemple `5023`, `10010`)
`Type`	Catégorie fonctionnelle de l’erreur (par exemple `InvalidResource`, `TooManyResources`)
`Description`	Message détaillé, souvent paramétré avec l’ID concerné (par exemple « The ImageId ‘ami-12345678’ doesn’t exist. »)

Catégories courantes

Type	Quand	Exemple
`AccessDenied`	Identifiants invalides, MFA manquante, API Access Rules non respectées	`Unmatched API access rules` (1, 5, 14)
`InvalidParameter` / `InvalidParameterValue`	Paramètre absent ou avec une valeur non acceptée	`Invalid filter` ou valeur hors plage
`InvalidResource`	Identifiant de ressource inexistant	`The ImageId doesn't exist` (5023, 5033, 5063)
`InvalidState`	Action incompatible avec l’état actuel de la ressource	`VM in invalid state` (6006, 6031)
`MissingParameter`	Paramètre obligatoire absent	Champ requis non fourni
`ResourceConflict`	Conflit avec une autre ressource (doublon, dépendance)	Tentative de suppression d’un Security Group encore référencé
`TooManyResources`	Quota atteint	`Maximum VMs exceeded` (10010, 10022)
`DependencyProblem`	Une autre ressource bloque l’opération	Subnet supprimable seulement si vide
`InternalError`	Erreur côté plateforme	À remonter au support si reproductible

Quelques réflexes de diagnostic

AccessDenied → vérifier les AK/SK (date d’expiration, profil sélectionné), la MFA si l’opération l’exige, et les API Access Rules (filtrage par IP).
InvalidParameter → relire la spec OpenAPI de la méthode pour le format exact (souvent un format de date, un préfixe d’ID, ou un type incorrect).
InvalidResource → vérifier d’abord la région courante (l’ID peut exister dans une autre région) puis le compte.
TooManyResources → consulter My Data > My Quotas dans Cockpit, prévoir une demande d’augmentation au support OUTSCALE.

La référence officielle

La liste exhaustive des codes, types et messages d’erreur est documentée dans la référence des erreurs API OUTSCALE. À garder dans les favoris pour les sessions de debug intensives.

À retenir

oapi-cli (Rust, autonome) est le CLI recommandé pour OUTSCALE — actif, complet, expérience moderne.
osc-cli (Python) est en mode maintenance : conserver le temps d’une migration, ne plus l’utiliser pour de nouveaux développements.
aws-cli fonctionne sur les 4 API compatibles AWS d’OUTSCALE (FCU, LBU, EIM, OOS) en pointant les endpoints — utile si l’équipe a déjà une expertise AWS.
Identifiants AK/SK : variables d’environnement pour les tests, fichier de config (chmod 600) pour l’usage régulier, gestionnaire de secrets pour la production en équipe.
Premier appel de validation : oapi-cli ReadRegions (ou aws ec2 describe-regions --endpoint-url …) pour confirmer que l’authentification fonctionne.
Ne jamais commiter une AK/SK : gitleaks en pre-commit hook, rotation régulière des clés.
Les erreurs API retournent un triplet Code / Type / Description — la liste exhaustive est dans la référence officielle des erreurs.

Prochaines étapes

Découverte du Cockpit OUTSCALE L'interface web complémentaire de la CLI pour le diagnostic visuel.

La CLI oapi (guide complet) Le détail de oapi-cli, syntaxe, options, exemples avancés.

TINA OS et la compatibilité API AWS Pourquoi aws-cli fonctionne sur OUTSCALE.

L'extension OSC Viewer pour Visual Studio Code Compléter la CLI par une exploration visuelle dans l'éditeur.