octl : la CLI OUTSCALE, premiers pas et commandes essentielles

octl pilote vos ressources OUTSCALE depuis le terminal. C'est un binaire statique en Go, publié sous licence BSD-3-Clause et signé avec Sigstore, qui expose l'intégralité de l'API OAPI par des flags typés plutôt que par du JSON à composer à la main. Ce guide vous mène du premier octl --version jusqu'à la création de ressources et l'attente d'un état, sans boucle d'attente maison.

Ce que vous allez apprendre

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

À la fin de ce guide, vous saurez :

• Installer octl en vérifiant sa signature avant de l'exécuter
• Configurer vos identifiants et jongler entre plusieurs profils
• Lister et inspecter vos ressources dans le format qui vous arrange
• Créer une ressource, et attendre qu'elle atteigne un état
• Éviter les erreurs de débutant : mauvaise région, mauvais profil, payload mal formé

octl remplace oapi-cli, qui est archivé

Le dépôt outscale/oapi-cli est archivé depuis juin 2026, et son propre descriptif le déclare déprécié. octl est la CLI qu'OUTSCALE fait vivre aujourd'hui, avec une release en août 2026.

Le changement n'est pas qu'un renommage : la syntaxe des paramètres composés diffère, et une commande oapi-cli recopiée telle quelle échoue. La section « Migrer depuis oapi-cli » en fin de guide donne la correspondance, vérifiée commande par commande.

Votre première session, en trois commandes

Une fois le binaire installé et vos identifiants posés, ces trois commandes disent si tout fonctionne :

octl --version
octl profile current
octl iaas net list

La première confirme la version, la deuxième le profil réellement utilisé, et la troisième prouve que vos identifiants passent et que la région répond. Si les trois passent, vous êtes opérationnel.

Étape 1, installer octl

Le binaire est statique et sans dépendance, ce qui simplifie beaucoup l'installation par rapport à l'ancienne CLI et à ses paquets AppImage.

Linux, vérifié

Téléchargez le binaire, vérifiez sa signature, puis installez-le. L'ordre compte : une somme de contrôle ne prouve rien si vous ne savez pas qui a produit la liste qui la contient.

1. Récupérer le binaire et ses artefacts de signature.

   base=https://github.com/outscale/octl/releases/latest/download
   curl -L -o octl "$base/octl_Linux_x86_64"
   curl -L -O "$base/octl.checksums.txt"

2. Vérifier la signature Sigstore avant de faire confiance au contenu.

   Les binaires de release sont signés via Fulcio pour le certificat, Rekor pour le journal de transparence, et l'identité OIDC de GitHub Actions. La procédure exacte, avec les commandes cosign à jour, est publiée par OUTSCALE dans docs/signature-verification.md.

3. Installer et confirmer.

   chmod +x octl
   sudo mv octl /usr/local/bin/
   octl --version

   La sortie affiche octl version v0.0.31 au moment où ce guide est écrit.

macOS

brew install octl
octl --version

Homebrew vérifie la somme de contrôle que porte la formule, pas la signature. C'est suffisant sur un poste personnel, et c'est la différence avec l'onglet précédent.

Conteneur

Une image outscale/octl est publiée, utile en intégration continue quand vous ne voulez rien installer sur le runner.

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

Mise à jour vérifiée, et comment la couper

octl update télécharge, vérifie la signature, puis remplace le binaire. La vérification n'est pas optionnelle : si elle échoue, la mise à jour est abandonnée avec un message d'erreur. Cela demande le droit d'écriture sur le binaire, donc sudo octl update s'il vit dans /usr/local/bin.

Sur un runner d'intégration continue ou un poste sans accès Internet, l'option globale --no-upgrade empêche la vérification automatique de nouvelle version.

Activer l'autocomplétion

L'autocomplétion couvre les appels d'API, les flags et leurs valeurs, ce qui change beaucoup le confort quand on découvre l'API.

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

# Zsh
octl completion zsh > _octl
sudo mkdir -p /usr/local/share/zsh/site-functions
sudo cp _octl /usr/local/share/zsh/site-functions/

Rechargez ensuite votre shell. La procédure pour fish est dans la documentation d'installation du projet.

Étape 2, se connecter à son compte

octl lit soit des variables d'environnement, soit un fichier de profils, et les variables ont la priorité. Cette précédence est la première source de confusion : un profil marqué par défaut ne sera pas utilisé si les variables correspondantes sont posées.

Variables d'environnement

export OSC_ACCESS_KEY="votre-access-key"
export OSC_SECRET_KEY="votre-secret-key"
export OSC_REGION="eu-west-2"

C'est la forme la plus directe, et celle qui convient à un pipeline où les identifiants viennent d'un gestionnaire de secrets.

Fichier de profils

Le fichier par défaut est ~/.osc/config.json, et son format est un objet dont chaque clé nomme un profil :

{
  "default": {
    "access_key": "MyAccessKey",
    "secret_key": "MySecretKey",
    "region": "eu-west-2"
  },
  "lab": {
    "access_key": "AutreAccessKey",
    "secret_key": "AutreSecretKey",
    "region": "eu-west-2"
  }
}

Le chemin se change avec --config ou OSC_CONFIG_FILE, le profil avec --profile ou OSC_PROFILE. Dès que l'un de ces deux drapeaux est posé, les variables d'environnement ne sont plus consultées.

OUTSCALE n'expose que deux régions en Europe pour ce parcours : eu-west-2 et cloudgouv-eu-west-1. Une région absente de votre configuration est l'erreur la plus fréquente au premier appel.

Gérer plusieurs profils

La sous-commande octl profile évite d'éditer le JSON à la main :

Commande	Ce qu'elle fait
octl profile list	liste les profils du fichier
octl profile add	ajoute un profil
octl profile current	affiche le profil réellement utilisé, drapeaux et variables compris
octl profile use	marque un profil comme celui par défaut
octl profile delete	supprime un profil

Glissez pour voir

octl profile current est la commande à réflexe avant toute opération destructrice : elle répond quel profil s'appliquerait vraiment, en tenant compte de la précédence des variables d'environnement.

Étape 3, lister et inspecter ses ressources

octl offre deux niveaux de commandes, et comprendre leur rapport évite de chercher longtemps.

Les commandes de haut niveau couvrent les gestes courants, avec des flags en minuscules :

octl iaas net list
octl iaas volume list
octl iaas vol ls          # les abréviations fonctionnent

┌──────────────┬──────┬───────────┬──────────────┐
│      ID      │ Name │   State   │   IpRange    │
├──────────────┼──────┼───────────┼──────────────┤
│ vpc-5e6457b0 │      │ available │ 10.60.0.0/16 │
└──────────────┴──────┴───────────┴──────────────┘

La forme générique expose toute l'API, avec les noms d'actions et de paramètres tels que la documentation OUTSCALE les écrit :

octl iaas api ReadNets
octl iaas api CreateNet --IpRange 10.60.0.0/16

Les deux formes sont la même chose, et octl le dit lui-même : une commande de haut niveau affiche l'appel générique qu'elle résout.

Resolving alias to [octl iaas api CreateNet --output yaml --single --IpRange=10.60.0.0/16]

Cette ligne est pédagogiquement précieuse : elle vous apprend le nom exact de l'action et de ses paramètres, ceux que vous retrouverez dans Terraform, dans le SDK et dans la documentation de l'API.

La documentation de l'API est dans la commande

Chaque action porte sa propre aide, avec la description officielle et la liste typée de ses paramètres :

octl iaas api CreateVolume --help

Creates a Block Storage Unit (BSU) volume in a specified Region.
...
Flags:
      --ClientToken string     A unique identifier which enables you to manage the idempotency.
      --DryRun                 If true, checks whether you have the required permissions to perform the action.
      --Iops int               The number of I/O operations per second (IOPS).
      --Size int               The size of the volume, in gibibytes (GiB).
      --SnapshotId string      The ID of the snapshot from which you want to create the volume.
      --SubregionName string   The Subregion in which you want to create the volume.

Le type de chaque paramètre est indiqué, ce qui évite le classique Size passé en chaîne là où l'API attend un entier.

Étape 4, choisir sa sortie

Huit formats sont disponibles via -o : raw, json, yaml, table, csv, none, base64 et text. Les deux qui servent le plus sont table pour lire et json pour scripter.

octl iaas api ReadNets -o csv

ID,Name,State,IpRange
vpc-24db4403,,available,10.81.0.0/16

Un filtre jq est intégré, ce qui évite d'installer et de chaîner un outil externe :

octl iaas api ReadNets --jq '.Nets[].IpRange'
octl iaas api CreateNet --IpRange 10.92.0.0/16 --jq '.Net.NetId'

["10.92.0.0/16"]
["vpc-d16d24b9"]

Le filtre s'applique à la réponse complète

Le jq intégré travaille sur l'enveloppe OAPI, pas sur son contenu déballé. Un CreateNet répond {"Net": {…}}, donc le filtre correct est .Net.NetId et non .NetId. Sans cette précision, le filtre renvoie silencieusement null.

L'option --single déballe les listes à un seul élément en objet, ce que les commandes de haut niveau utilisent déjà pour vous.

À noter, parce que la nuance surprend : la sortie JSON directe arrive déjà déballée. Un CreateNet -o json rend {"NetId": …} au premier niveau, d'où le jq -r '.NetId' des exemples de script, sans le préfixe .Net.

Les colonnes d'un tableau se choisissent, avec un titre et une requête jq par colonne :

octl iaas api ReadNets -o table --columns 'Reseau:.NetId||Plage:.IpRange'

┌──────────────┬──────────────┐
│    Reseau    │    Plage     │
├──────────────┼──────────────┤
│ vpc-253f1e94 │ 10.90.0.0/16 │
│ vpc-69401699 │ 10.91.0.0/16 │
└──────────────┴──────────────┘

Étape 5, filtrer côté serveur

Les filtres OAPI réduisent la réponse avant qu'elle ne parte, ce qui compte sur un compte chargé. Leur syntaxe sous octl est un flag pointé, avec la valeur nue :

octl iaas api ReadVms --Filters.VmStateNames running

["i-97f31cfe"]

La syntaxe de filtre d'oapi-cli échoue ici

C'est le piège numéro un de la migration. Les deux formes que vous trouverez dans d'anciens scripts ne fonctionnent pas :

octl iaas api ReadVms --Filters.VmStateNames '["running"]'   # ❌ parse error
octl iaas api ReadVms --Filters.VmStateNames[] running       # ❌ unknown flag

La première renvoie une erreur d'analyse, la seconde un unknown flag. La forme correcte est la valeur nue, sans crochets ni JSON.

Pour plusieurs valeurs, octl déclare ces filtres comme des listes (strings dans l'aide) et accepte deux écritures, l'une et l'autre vérifiées :

octl iaas api ReadSubregions \
  --Filters.SubregionNames eu-west-2a \
  --Filters.SubregionNames eu-west-2b

octl iaas api ReadSubregions --Filters.SubregionNames eu-west-2a,eu-west-2b

["eu-west-2a", "eu-west-2b"]

Étape 6, créer des ressources et attendre un état

Créer suit la même logique que lire, avec les paramètres de l'action :

net=$(octl iaas api CreateNet --IpRange 10.20.0.0/16 -o json | jq -r '.NetId')
sub=$(octl iaas api CreateSubnet --NetId "$net" --IpRange 10.20.1.0/24 -o json | jq -r '.SubnetId')
octl iaas api CreateVms --ImageId ami-00000001 --VmType tinav6.c1r1p2 --SubnetId "$sub"

Le pipe vers jq -r reste la forme à employer pour capturer un identifiant dans une variable de shell. Le --jq intégré sert à lire et filtrer : même combiné à --single, il rend la valeur entre guillemets JSON, qu'il faudrait déquoter avant usage.

Le format TINA natif tinavW.cXrYpZ est celui que ce parcours emploie partout : tinav6.c1r1p2 décrit une génération 6, un cœur, un gibioctet de mémoire et un profil de performance 2.

Votre type TINA n'apparaît pas dans ReadVmTypes, et c'est normal

Mesuré sur un compte réel le 30 août 2026 : ReadVmTypes retourne 174 types, dont aucun ne commence par tinav. Le catalogue liste les gabarits prédéfinis hérités de la nomenclature AWS (c1.medium, c3.large, m4.xlarge…), pas les types TINA.

La raison est qu'un type TINA se compose à la main : vous écrivez le nombre de cœurs, la mémoire et le profil de performance dont vous avez besoin, et l'API les accepte sans qu'ils figurent dans une liste. La même mesure l'a confirmé : un CreateVms --VmType tinav6.c1r1p2 a bien démarré une machine, alors que ce type est introuvable dans le catalogue.

Chercher son gabarit dans ReadVmTypes est donc une impasse : c'est la documentation du format qu'il faut lire, pas la liste.

Attendre sans écrire de boucle

--waitfor rappelle l'API jusqu'à ce qu'une expression jq soit vraie. C'est la fonctionnalité qui remplace les boucles while maison, et elle n'existait pas dans l'ancienne CLI.

octl iaas api ReadVms --waitfor '.[0].State == "running"' --waitfor-timeout 5m

✅ Condition reached successfully

L'intervalle entre deux essais vaut 5 secondes par défaut, réglable avec --interval, et l'échéance 10 minutes, réglable avec --waitfor-timeout.

Voir la requête avant de l'envoyer

--dry-run affiche le payload que la commande enverrait, sans l'envoyer. C'est l'outil d'apprentissage le plus direct pour comprendre ce que vos flags composent réellement.

octl iaas api CreateVolume --SubregionName eu-west-2a --Size 20 --VolumeType gp2 --dry-run

{
  "Size": 20,
  "SubregionName": "eu-west-2a",
  "VolumeType": "gp2"
}

Ne le confondez pas avec le paramètre --DryRun de l'API, en majuscules, qui envoie bien la requête pour que le service vérifie vos permissions.

Les structures composées passent par --payload

Certaines actions attendent un tableau d'objets, que les flags pointés ne savent pas exprimer. CreateTags en est le cas typique : il prend une liste de ressources et une liste de couples clé-valeur.

octl iaas api CreateTags \
  --payload '{"ResourceIds":["vpc-fbde03ba"],"Tags":[{"Key":"env","Value":"lab"}]}'

[
  {
    "Key": "env",
    "ResourceId": "vpc-fbde03ba",
    "ResourceType": "vpc",
    "Value": "lab"
  }
]

L'option --template accepte le même JSON depuis un fichier, ce qui convient mieux à une charge utile longue ou versionnée dans un dépôt.

Migrer depuis oapi-cli

Le tableau ci-dessous a été vérifié commande par commande contre l'API réelle. Il ne s'agit pas d'un simple renommage : plusieurs formes de l'ancienne CLI échouent sous octl.

Besoin	oapi-cli	octl
Appeler une action	oapi-cli ReadVms	octl iaas api ReadVms
Paramètre simple	--IpRange 10.0.0.0/16	identique, ou --IpRange=10.0.0.0/16
Filtre serveur	--Filters.VmStateNames '["running"]'	--Filters.VmStateNames running
Filtre, autre forme	--Filters.VmStateNames[] running	n'existe plus, même forme que ci-dessus
Filtre à plusieurs valeurs	--Filters.X[] a --Filters.X[] b	flag répété --Filters.X a --Filters.X b, ou --Filters.X a,b
Structure composée	--Tags '[{"Key":…}]'	--payload '{"Tags":[{…}]}'
Booléen d'API	--Overall true, --ShowPrice true	drapeau nu : --Overall, --ShowPrice
Colorisation	--color	n'existe plus, la sortie est colorée nativement
Filtrer la sortie	| jq '.Vms[].VmId'	--jq '.Vms[].VmId', intégré
Attendre un état	boucle while à écrire	--waitfor '<expression jq>'
Profils	OSC_PROFILE	--profile, OSC_PROFILE ou octl profile use
Mise à jour	téléchargement manuel	octl update, signature vérifiée

Glissez pour voir

Le fichier de configuration ne change pas : ~/.osc/config.json garde le même format, vos profils existants fonctionnent tels quels.

Pièges courants

Symptôme	Cause	Solution
bare " in non-quoted-field	Un filtre écrit en JSON, à la manière d'oapi-cli	Passer la valeur nue : --Filters.VmStateNames running
unknown flag: --color	Option de l'ancienne CLI	La supprimer, la sortie est déjà colorée
unknown flag: --Tags.Key	Structure composée exprimée en flags pointés	Utiliser --payload ou --template
Le filtre --jq renvoie null	Le filtre vise le contenu au lieu de l'enveloppe	Viser .Net.NetId, ou ajouter --single
Le mauvais compte répond	Des variables d'environnement masquent le profil	octl profile current avant toute action
Size refusé par l'API	Valeur passée en chaîne là où un entier est attendu	Lire le type dans octl iaas api <Action> --help

Glissez pour voir

À retenir

• octl remplace oapi-cli, archivé et déclaré déprécié par OUTSCALE.
• Le binaire est signé Sigstore, et octl update vérifie avant de remplacer.
• Deux niveaux de commandes : les alias pour aller vite, la forme générique pour toute l'API.
• La documentation de l'API vit dans --help, avec le type de chaque paramètre.
• Les filtres prennent une valeur nue : la syntaxe JSON d'oapi-cli échoue.
• --payload traite les structures composées que les flags pointés ne savent pas exprimer.
• --waitfor remplace les boucles d'attente, et --dry-run montre la requête avant l'envoi.

Pour aller plus loin

• Calcul : instances TINA et sizing : Composer le VmType que vous passerez à CreateVms, et pourquoi il n'est dans aucun catalogue.
• EIM : identité et accès : À qui appartiennent les clés que vous venez de configurer.
• Réseau : design Net + Subnets : Le premier vrai chantier à mener avec cette CLI.

×

📖 Voir la documentation →