Créer un CLI Kitsu portable avec Python et Gazu (2026)

Nous sommes en fin de production, le planning est serré, et vous devez déployer un outil de pipeline essentiel sur une nouvelle machine : quelque chose pour synchroniser les statuts des shots, publier des playblasts ou automatiser un workflow Kitsu. L’outil en lui-même n’est pas compliqué. C’est simplement du Python. Vous l’avez déjà écrit.

Le problème, c’est tout ce qui l’entoure.

La machine sur laquelle vous le déployez n’a pas Python d’installé. Ou alors, elle a une version incorrecte. Le serveur Linux du studio est verrouillé. La machine Windows d’un freelance ne peut pas compiler les dépendances. Quelqu’un demande s’il faut pip, un environnement virtuel ou le SDK Gazu. Et soudain, un « script simple » devient de la documentation, du dépannage… et du temps perdu.

Au lieu de construire des outils de pipeline, vous gérez des environnements.

C’est la partie que personne n’aime : installer Python, figer les versions, traquer les bibliothèques manquantes, et espérer que rien ne casse lors des mises à jour du système. Et lorsque votre outil doit tourner sur les postes des artistes, sur des nœuds de rendu ou sur des serveurs CI, cette fragilité devient un vrai risque pour la production.

Ce que vous voulez réellement est simple : un outil, une commande, qui fonctionne.

Dans cet article, vous allez apprendre à empaqueter vos workflows Kitsu en encapsulant le SDK Python de Kitsu (Gazu) dans une interface en ligne de commande (CLI) et en le compilant en un seul binaire exécutable. Pas d’installations de Python. Pas de gestion des dépendances. Juste un exécutable fiable que vous pouvez déposer sur n’importe quelle machine et utiliser immédiatement.

Pourquoi avez-vous besoin d’une CLI

Les interfaces graphiques sont excellentes pour le travail créatif, mais une fois que vous gérez un pipeline, une interface web peut rapidement devenir un fardeau. Lorsque vous transférez les bonnes tâches Kitsu dans une CLI, vous débloquez une façon de travailler plus rapide, plus scalable et plus propice à l’automatisation.

Vous finissez d’animer cinq shots et vous devez mettre à jour leurs statuts et envoyer des aperçus. Dans un navigateur, cela implique des changements de contexte : Alt-Tab, ouvrir Chrome, naviguer vers Kitsu, entrer dans le projet, trouver l’épisode, cliquer sur le shot, changer le statut, envoyer la vidéo. Puis recommencer pour chaque shot. Avec une CLI, vous restez exactement où vous êtes. Vous tapez kitsu publish --status Review, vous appuyez sur Entrée, et vous passez à autre chose. Vous ne quittez jamais le clavier, vous ne perdez jamais votre focus, et vous n’avez pas à payer le « coût cognitif » des clics dans les menus.

Une CLI vous pousse naturellement à penser en arguments, en listes et en automatisation, et c’est là que ça commence à s’accumuler. Si vous pouvez mettre à jour un shot, vous pouvez en mettre à jour dix ou cent avec exactement la même commande. Vous pouvez boucler sur une séquence, envoyer des noms de shots via un flux, ou piloter l’opération directement depuis un DCC ou une sortie de rendu. Une heure de clics répétitifs dans une interface web devient quelques secondes de travail scripté. Et c’est cohérent, répétable et facile à versionner.

Enfin, tout dans un pipeline ne s’exécute pas sur un poste de travail avec un écran. Parfois, des tâches doivent avoir lieu sur un nœud de ferme de rendu, sur un serveur de build, ou sous forme de processus en arrière-plan qui réagit à des fichiers présents sur le disque. Dans ces environnements, il n’y a ni navigateur, ni utilisateur pour cliquer sur des boutons. Une CLI fonctionne partout où vous avez un shell. Vous pouvez automatiser les publications, les changements de statut, les validations et les opérations de synchronisation, et Kitsu s’intègre plus profondément au pipeline.

1. Concevoir l’interface de la CLI

Avant de toucher à l’API Kitsu, il nous faut l’ossature de notre outil. En Python, il existe plusieurs façons d’analyser les arguments de la ligne de commande, mais pour un outil de pipeline professionnel, je recommande fortement d’utiliser des bibliothèques comme Click ou Typer.

Pour cette démonstration, imaginons un outil appelé kitsu-cli.

Pensez à votre outil comme à un arbre. Le tronc est l’exécutable principal, et les branches sont vos commandes et sous-commandes :

kitsu-cli (root)
└── production (commands related to productions)
    └── list (list all productions)

Voici comment structurer cette logique en Python avec Click. Cette structure est cruciale, car elle rend votre outil extensible. Aujourd’hui, vous gérez des productions ; demain, vous pourriez gérer des assets ou des playlists.

import click
@click.group()
def cli():
"""My Studio Kitsu Tool"""
pass
@cli.group()
def production():
"""Commands for managing productions"""
pass
@production.command()
@click.option('--name', help='Filter by name')
def list(name):
"""List productions"""
click.echo(f"Listing productions: {name}")
if name == 'main':
cli()

À lui seul, cet extrait vous donne un menu d’aide. Si l’utilisateur saisit kit-cli --help, il voit la documentation. C’est de l’empathie développeur : construire des outils qui apprennent à l’utilisateur comment s’en servir.

Pour exécuter la CLI, utilisez simplement la même commande que pour un programme Python classique :

python3 cli.py production list

2. Ajouter des fonctionnalités Gazu

Maintenant que nous avons l’ossature, il nous faut les « muscles ». Kitsu fournit un excellent client Python appelé Gazu.

Si vous n’avez jamais utilisé Gazu auparavant, c’est le pont entre votre script et votre serveur Kitsu.

La première difficulté de tout outil de pipeline, c’est l’authentification. Vous ne voulez pas que vos artistes codent en dur leurs mots de passe dans des scripts. Une CLI robuste vérifie si une session existe déjà. Si ce n’est pas le cas, elle invite l’utilisateur à se connecter une fois et enregistre le token localement. Pour simplifier, nous allons « coder en dur » notre logique d’authentification :

import gazu
gazu.set_host("http://localhost/api")
user = gazu.log_in("admin@example.com", "mysecretpassword")

Une fois authentifié, nous pouvons étoffer la commande list que nous avons écrite plus haut. Pour lister les productions :

@production.command()
@click.option('--name', help='Filter by name')
def list(name):
"""List productions"""
click.echo(f"Listing productions: {name}")

Inutile d’ouvrir un navigateur, d’attendre le chargement de l’application Vue, ni de filtrer la vue. Ce script renvoie des données brutes instantanément.

3. Interface interactive

Les options de commande (comme --name test) sont très bien, mais ce serait bien plus agréable de choisir les productions dans une liste interactive.

Au lieu d’obliger l’utilisateur à taper le nom exact d’une séquence (qu’il risque inévitablement d’orthographier de travers), nous pouvons rendre notre CLI plus intelligente en ajoutant des invites. Si l’utilisateur oublie de fournir un argument, on lui demande simplement.

Une bibliothèque comme questionary est idéale pour cela : elle ajoute des listes de sélection interactives et auto-documentées au terminal.

import questionary
@production.command()
def select():
"""List available productions"""
productions = gazu.project.all_projects()
selected_project = questionary.select(
    "Which project are you working on?", choices=productions
).ask()

click.echo(f"You selected {selected_project}. Loading assets...")

Cette petite amélioration change l’expérience utilisateur : on passe de « outil de hacker effrayant » à « assistant utile ». Elle réduit les taux d’erreur à presque zéro, car l’utilisateur ne peut sélectionner que des options valides récupérées directement depuis Kitsu.

4. Le binaire exécutable unique

Enfin, il nous faut résoudre le problème « Ça ne marche pas sur mon ordinateur portable ». Nous avons un script Python avec des dépendances :gazu, click, questionary, etc.

Pour le lancer sur la machine d’un freelance, il faudrait normalement installer Python, ou créer un environnement virtuel, puis pip install les prérequis. Pour supprimer toutes ces étapes, on peut utiliser PyInstaller.

python3 -m pip install pyinstaller

PyInstaller analyse votre script Python, trouve chaque bibliothèque importée, regroupe aussi l’interpréteur Python lui-même, puis encapsule le tout dans un fichier unique .exe (sur Windows) ou un binaire cible (sur Linux/Mac).

Allez dans le dossier de votre script dans votre terminal et lancez :

python3 -m PyInstaller --onefile --name kitsu-cli cli.py

• --onefile : ce paramètre indique à PyInstaller d’empaqueter tout dans un seul fichier, plutôt que dans un dossier de dépendances « lâches ».
• --name : le nom du fichier binaire final.

Une fois le processus terminé, vérifiez le dossier dist/. Vous y trouverez un fichier nommé kitsu-cli (ou kitsu-cli.exe).

Vous pouvez maintenant prendre ce fichier, le mettre sur une clé USB, l’envoyer par e-mail, ou le déposer sur un lecteur réseau. Un artiste peut le glisser sur son bureau et le lancer tant qu’il a été compilé pour la même architecture système (macOS, Windows, etc.). Il n’a pas besoin que Python soit installé. Il n’a pas besoin d’installer Gazu manuellement. Ça fonctionne juste :

./kitsu-cli production list

Mais ne vous contentez pas de me croire sur parole : testez-le vous-même en clonant notre dépôt Github.

Si vous devez compiler votre CLI pour cibler différents systèmes d’exploitation, vous pouvez utiliser Github Actions.

Exemple de CLI : « Render Fetcher »

Passons à un scénario plus centré pipeline.

Imaginez un workflow où vous gérerez le rendu distribué sur plusieurs machines. Chaque nœud de rendu doit régulièrement récupérer de nouvelles tâches depuis Kitsu : des shots marqués TODO pour le rendu, ainsi que leurs fichiers .blend d’aperçu correspondants. Ces machines sont sans interface (headless), verrouillées et volontairement minimales : pas d’installations Python, pas d’environnements virtuels, pas de gestion compliquée des dépendances.

Ce que vous voulez, c’est un exécutable unique que vous pouvez déposer sur n’importe quel serveur et exécuter comme tâche cron ou service :

./kitsu-cli pull MechaFight /home/user/flamenco/jobs

Le code correspondant ressemblerait à ceci :

import os
import click
import gazu
import questionary
gazu.set_host("http://localhost/api")
user = gazu.log_in("admin@example.com", "mysecretpassword")
@click.group()
def cli():
"""My Studio Kitsu Tool"""
pass
@cli.command()
@click.argument("project_name", required=True)
@click.argument("output_path", required=True)
def pull(project_name, output_path):
click.echo(f"Fetching TODO render tasks for project: {project_name}")
project = gazu.project.get_project_by_name(project_name)

tasks = gazu.task.all_tasks_for_project(project)

rendering = gazu.task.get_task_type_by_name("Rendering")
todo = gazu.task.get_task_status_by_name("todo")

render_tasks = [
    t
    for t in tasks
    if t["task_type_id"] == rendering["id"] and t["task_status_id"] == todo["id"]
]

for task in render_tasks:
    files = gazu.files.get_all_preview_files_for_task(task)
    size = len(files)

    if size > 0:
        latest = files[size - 1]
        if latest["extension"] == "blend":
            target_path = os.path.join(
                output_path, latest["name"] + "." + latest["extension"]
            )
            gazu.files.download_preview_file(latest, target_path)
if name == "main":
cli()

1. Interroger Kitsu - La CLI se connecte à Kitsu (via Gazu) et récupère toutes les tâches de rendu ayant un statut TODO pour un projet donné.
2. Filtrer les tâches - Elle filtre les tâches marquées todo et qui ont un fichier d’aperçu associé (dans ce cas, un fichier .blend).
3. Télécharger les assets - Pour chaque tâche, la CLI télécharge le fichier d’aperçu .blend correspondant vers le chemin de sortie indiqué sur le disque.
4. Rendu - Une fois téléchargés, les fichiers sont prêts pour que Blender les récupère, manuellement ou via un orchestrateur de rendu automatisé comme Flamenco.

Lorsque cette CLI est compilée en un binaire unique, le déploiement devient trivial. Vous pouvez la déposer sur des nœuds de rendu Linux et la lancer depuis cron ou systemd, sans installer Python ni les dépendances. Tous les serveurs récupèrent le travail de la même façon. Les structures de dossiers sont cohérentes. L’état des tâches vient directement de Kitsu. Et votre ferme de rendu reste concentrée sur le rendu.

Encore une fois, jetez-y un œil sur le dépôt Github correspondant.

Conclusion

Créer votre propre CLI Kitsu ne doit pas être compliqué. En encapsulant la bibliothèque Gazu dans une CLI facile à utiliser, puis en la « figeant » avec PyInstaller, vous mettez à l’échelle votre pipeline. Vous supprimez la friction technique liée à la gestion des environnements et vous laissez vos artistes se concentrer sur ce qu’ils font le mieux : créer de belles animations.

En savoir plus sur la combinaison de Kitsu et du scripting Blender en vous abonnant à notre blog !