Pourquoi les utilitaires en ligne de commande ont besoin de leur propre alternative à OpenAPI et comment fonctionne le projet Usage

Chaque fois que j'écris un petit utilitaire en ligne de commande, la même histoire se répète. D'abord vous esquissez des arguments et des options dans le code. Ensuite vous décidez d'ajouter l'autocomplétion pour bash et zsh, vous plongez dans la mémorisation de la syntaxe des scripts shell ou la recherche de générateurs. Ensuite vous devez mettre en forme la documentation en Markdown, mettre à jour les pages man, et penser à supporter les variables d'environnement. Si le projet est réécrit dans un autre langage ou gagne des wrappers Python ou Bash, vous devez dupliquer manuellement toute la structure des arguments.

Le développeur jdx, connu pour le gestionnaire de versions populaire mise, a abordé cette routine de manière systématique et a créé le projet Usage.

Un contrat plutôt que des solutions dispersées

L'idée centrale derrière Usage est simple : les logiciels en ligne de commande ont besoin de leur propre alternative à OpenAPI ou Swagger. Au lieu de lier les descriptions d'arguments à une bibliothèque spécifique dans un langage spécifique, Usage propose une spécification portable unique au format KDL.

KDL n'a pas été choisi au hasard. Ce langage de document est plus propre et plus lisible que JSON ou YAML, ce qui le rend pratique pour décrire des commandes imbriquées, des options, des alias courts et des types de données.

Décrire l'interface de votre utilitaire dans ce format une seule fois résout plusieurs problèmes à la fois :

• Générer des scripts d'autocomplétion pour tous les shells de commande populaires.
• Assemblage automatique de la documentation en Markdown et en pages man.
• Analyse des arguments depuis des scripts dans d'autres langages.
• Génération de squelette de code pour différentes bibliothèques CLI.

À quoi cela ressemble en Rust

Si vous écrivez en Rust, vous n'avez pas du tout besoin d'écrire le manifeste KDL à la main. Le projet inclut une crate usage-rs qui génère la spécification directement depuis votre structure de données en utilisant des macros derive.

Voici un exemple basique :

[dependencies]
usage = { package = "usage-rs", version = "6" }

use usage::Cli;

#[derive(Cli)]
#[usage(bin = "example", version)]
struct App {
    /// Print more detail.
    #[usage(short = 'v', long, count)]
    verbose: u8,

    /// Files to process.
    files: Vec<String>,
}

fn main() {
    let app = App::parse();
    // app.verbose и app.files готовы к работе
}

L'analyseur runtime n'entraîne pas de dépendances lourdes. En même temps, vous pouvez exporter une spécification KDL prête à l'emploi depuis la même structure et l'utiliser dans une infrastructure de build externe ou des pipelines CI/CD.

Différences par rapport à clap, le familier

La plupart des développeurs Rust sont habitués à utiliser clap. L'auteur de Usage reconnaît ouvertement l'influence de cette bibliothèque et a conservé un format de sortie similaire pour les messages d'aide et les rapports d'erreurs afin de rendre la transition aussi painless que possible.

La différence réside dans la philosophie. clap est strictement orienté vers l'écosystème Rust. usage déplace le schéma d'interface à un niveau supérieur, le transformant en un contrat universel. Vous pouvez prendre la spécification et analyser les arguments dans un script Bash via l'utilitaire CLI usage sans réécrire votre logique de validation des options.

Des entreprises comme 37signals font déjà partie des sponsors du projet. Cela démontre l'intérêt de l'industrie pour la standardisation des interfaces de terminal.

À qui le projet est utile maintenant

Usage ne sera probablement pas nécessaire pour un script occasionnel de vingt lignes. Cependant, l'outil s'intègre parfaitement au développement d'utilitaires internes complexes, de clients CLI d'API et d'outils de plateforme utilisés par différentes équipes.

Si vous êtes fatigué de synchroniser manuellement la documentation avec les options et d'écrire des scripts d'autocomplétion pour chaque shell, le projet mérite définitivement un coup d'œil. La documentation et les guides de migration sont disponibles sur le site officiel usage.jdx.dev.