Outils CLI OUTSCALE : octl, osc-cli, aws-cli

OUTSCALE met à disposition trois familles d'outils CLI pour piloter ses ressources en ligne de commande : octl (le CLI actuel, écrit en Go), osc-cli (le CLI historique en Python, en mode maintenance), et aws-cli utilisable sur les API compatibles AWS d'OUTSCALE. Une quatrième, oapi-cli, est archivée depuis juin 2026 et ne doit plus servir à démarrer un projet. Cette page explique comment choisir, comment installer chacun, et comment configurer ses identifiants proprement.

Ce que vous allez apprendre

Le rôle de chaque CLI et quand l'utiliser.
Installer octl sur Linux, macOS et dans un conteneur.
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

Les deux lignes décisives sont Statut et API supportée. Elles suffisent à trancher dans la plupart des cas : octl est le seul développé activement tout en couvrant la totalité de l'OAPI native, tandis qu'aws-cli reste cantonné aux services compatibles AWS. Le reste du tableau départage les situations où ce premier critère ne suffit pas, par exemple une équipe déjà outillée autour d'AWS.

Critère	`octl`	`oapi-cli`	`osc-cli`	`aws-cli`
Langage	Go	Rust	Python	Python
Installation	Binaire statique, Homebrew, conteneur	AppImage	Via PyPI (`pip`)	Via PyPI ou installateur officiel
API supportée	OAPI native, OOS, support préliminaire OKS	OAPI native	OAPI native + API compatibles AWS	API compatibles AWS uniquement
Statut	Recommandé : actif, v0.0.31 en août 2026	Archivé en juin 2026, déclaré déprécié	Mode maintenance : correctifs seulement	Outil tiers AWS, fonctionne par compatibilité
Signature des binaires	Sigstore, vérifiée par `octl update`	Aucune publiée	Chaîne PyPI	Chaîne AWS
Autocomplétion shell	Bash, Zsh, fish	Bash	Limitée	Bash, Zsh, PowerShell
Filtrage de sortie	`--jq` intégré, formats table, csv, yaml, json	Pipe vers `jq`	Pipe vers `jq`	`--query` (JMESPath)
Attente d'un état	`--waitfor` sur expression `jq`	Boucle à écrire	Boucle à écrire	`wait` sur commandes prédéfinies
Recommandation pour un nouveau projet	Privilégier	À éviter, archivé	À é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, octl est le choix recommandé. Il est maintenu activement, ses binaires sont signés avec Sigstore, et il couvre l'intégralité de l'OAPI native, y compris les services propres à OUTSCALE comme FlexibleGpu ou l'empreinte carbone. Son confort quotidien pèse aussi : --jq intégré, --waitfor pour attendre un état sans écrire de boucle, et la documentation de chaque action dans --help. Le guide dédié La CLI octl le prend en main pas à pas.

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 propres à OUTSCALE. Pour ces derniers, octl reste nécessaire en complément.

Cas 3, Code legacy avec `osc-cli` ou `oapi-cli`

Si vous héritez d'un projet qui utilise osc-cli ou oapi-cli, vous pouvez le conserver le temps d'une migration vers octl. Les deux anciens outils sont dans une impasse : osc-cli est en mode maintenance, et oapi-cli est archivé, donc ne recevra plus ni correctif ni nouvelle opération d'API. La migration n'est pas qu'un renommage : la syntaxe des filtres et des structures composées diffère, et la correspondance vérifiée figure dans le guide octl.

Installer `octl`

octl est un binaire statique en Go, sans dépendance à installer : ni runtime Python, ni AppImage, ni FUSE.

curl -L -o octl https://github.com/outscale/octl/releases/latest/download/octl_Linux_x86_64
chmod +x octl
sudo mv octl /usr/local/bin/
octl --version

Les binaires de release sont signés avec Sigstore. Sur un poste sensible ou un runner partagé, vérifiez la signature avant d'exécuter le binaire : la procédure est publiée dans docs/signature-verification.md.

brew install octl
octl --version

Homebrew contrôle la somme de contrôle portée par la formule, pas la signature Sigstore. C'est suffisant sur un poste personnel.

Une image outscale/octl est publiée, pratique en intégration continue quand rien ne doit être installé sur le runner.

docker run --rm -e OSC_ACCESS_KEY -e OSC_SECRET_KEY -e OSC_REGION \
  outscale/octl iaas net list

octl update télécharge, vérifie la signature, puis remplace le binaire. Si la vérification échoue, la mise à jour est abandonnée. Prévoyez sudo si le binaire vit dans /usr/local/bin, et l'option globale --no-upgrade sur un runner qui ne doit contacter personne.

L'autocomplétion couvre les appels d'API, les flags et leurs valeurs :

octl completion bash > octl-completion.bash
sudo cp octl-completion.bash /etc/bash_completion.d/

Les formes zsh et fish sont dans la documentation d'installation.

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 à octl :

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
octl iaas api 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
octl iaas api 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)

octl iaas api 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

octl iaas api 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

octl iaas api 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

octl iaas api 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`

octl embarque un filtre jq, ce qui évite d'installer et de chaîner un outil externe. Le filtre s'applique à l'enveloppe complète de la réponse : sur un ReadVms, la liste vit sous la clé Vms.

# Lister uniquement les noms et IDs de VMs
octl iaas api 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

aws-cli réutilise exactement les mêmes AK/SK que octl : aucune clé supplémentaire à générer. Le point à noter est le nom des variables, qui suit la convention AWS (AWS_ACCESS_KEY_ID) et non la convention Outscale (OSC_ACCESS_KEY). La région, elle, reste une région Outscale valide comme eu-west-2 ou cloudgouv-eu-west-1.

# Identifiants OUTSCALE (mêmes AK/SK que pour octl)
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 vers `octl`

Deux points de départ mènent à octl, et ils ne coûtent pas le même effort.

Depuis osc-cli, la grammaire OAPI étant la même, il suffit de remplacer le préfixe de commande :

osc-cli api ReadVms          # avant
octl iaas api ReadVms        # après

Depuis oapi-cli, le changement de préfixe ne suffit pas. Quatre formes de l'ancienne CLI échouent telles quelles, et une commande recopiée sans adaptation rend une erreur plutôt qu'un résultat :

Ce que faisait `oapi-cli`	Sous `octl`
`--Filters.VmStateNames '["running"]'`	`--Filters.VmStateNames running`
`--Filters.VmStateNames[] running`	même forme que ci-dessus
`--Tags '[{"Key":…}]'`	`--payload '{"Tags":[{…}]}'`
`--color`	n'existe plus, la sortie est colorée nativement

Le guide octl détaille la correspondance complète, vérifiée commande par commande.

Trois points d'attention communs aux deux migrations :

Le fichier de configuration ne change pas : ~/.osc/config.json garde le même format, vos profils existants fonctionnent tels quels.
Les nouvelles opérations de l'API n'arrivent plus que dans octl : oapi-cli étant archivé et osc-cli en maintenance, tout code qui dépend d'un ajout récent doit migrer.
La coexistence temporaire est possible : les trois CLI s'installent en parallèle sans conflit, ce qui permet de migrer script par script.

Comprendre les erreurs API OUTSCALE

Tous les appels OAPI qui échouent retournent une réponse JSON structurée que les CLI affichent (octl la formate lisiblement, 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

Le champ Type est le premier à lire, car il oriente directement vers la correction. Un type en AccessDenied ou InvalidParameter pointe vers votre appel (identifiants, format), alors qu'un TooManyResources ou un InternalError renvoie vers la plateforme (quota atteint, incident côté Outscale). Cette distinction évite de chercher un bug dans son script quand le problème est un simple quota.

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

À chaque type d'erreur correspond une première vérification qui résout la majorité des cas. Le point le plus contre-intuitif concerne InvalidResource : avant de conclure qu'une ressource n'existe pas, vérifiez la région courante, car un ID valide dans eu-west-2 sera introuvable si votre profil pointe sur cloudgouv-eu-west-1.

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

octl (Go, binaire statique signé Sigstore) est le CLI recommandé pour OUTSCALE : actif, complet, avec --jq et --waitfor intégrés.
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 : octl iaas api 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.

Pour aller plus loin

EIM, identité et accès : Les clés AK/SK configurées ici prennent leur sens une fois rattachées à des utilisateurs, des groupes et des policies.
Référence Terraform sur OUTSCALE : Le passage de l'appel CLI ponctuel à une infrastructure décrite en code et rejouable.
OSC Viewer pour Visual Studio Code : L'exploration visuelle des ressources dans l'éditeur, en complément des commandes vues ici.

Ressources externes

Comparaison entre OSC CLI et oapi-cli, Documentation OUTSCALE
Installer et configurer oapi-cli
Installer et configurer OSC CLI
octl, GitHub
oapi-cli, GitHub : dépôt archivé, conservé pour référence historique
osc-cli, GitHub
Configurer aws-cli pour OUTSCALE
Référence des erreurs API OUTSCALE, codes, types, messages