---
title: "Référence CLI de Kodama : kodactl et kodama"
description: "Référence de kodactl, le client en ligne de commande de Kodama, et du binaire kodama : installation, configuration, commandes, formats et codes de sortie."
canonical_url: https://optimi.com/fr/docs/kodama/cli
md_url: https://optimi.com/fr/docs/kodama/cli.md
language: fr
alternates:
  - lang: en
    url: https://optimi.com/en/docs/kodama/cli
    md_url: https://optimi.com/en/docs/kodama/cli.md
last_updated: 2026-11-14
---

# Référence CLI

Kodama fournit deux binaires :

| Binaire | Rôle |
| --- | --- |
| `kodactl` | Le client en ligne de commande. Il appelle l’API REST et fonctionne donc depuis un ordinateur portable, depuis la CI et depuis l’intérieur d’un conteneur de pipeline |
| `kodama` | Le binaire serveur. Sur un poste de travail, vous utilisez `kodama up`, `kodama down` et `kodama status` ; les autres commandes exécutent les services d’une installation |

Les deux proviennent de la même version, et
`curl -fsSL https://raw.githubusercontent.com/optimiware/kodama/master/install.sh | sh`
installe les deux. `kodactl version` et `kodama version` affichent la version et
la révision des sources.

## Configurer kodactl

Après `kodama up`, une ligne suffit :

```sh
source ~/.kodama/instances/default/env.sh
```

Pour une autre installation, définissez vous-même les mêmes valeurs. Chaque
option globale a une variable d’environnement :

| Option | Variable | Signification |
| --- | --- | --- |
| `--url` (aussi `--server`, `--server-url`) | `KODAMA_URL`, `KODAMA_SERVER` | L’URL du serveur Kodama |
| `--ca-file` | `KODAMA_CA_FILE` | Lot de certificats d’AC au format PEM, pour une installation avec une AC privée |
| `--project` | `KODAMA_PROJECT` | Le projet par défaut |
| `--output` | `KODAMA_OUTPUT` | `table` (par défaut) ou `json` |
| `--credential-file` | `KODAMA_CREDENTIAL_FILE` | Un fichier qui contient un jeton : un jeton d’administrateur ou de service, ou le jeton d’exécution monté |
| `--session` (aussi `--session-file`) | `KODAMA_SESSION` | Le fichier qui conserve la session de `kodactl login` |
| `--config` | `KODAMA_CONFIG` | Un fichier de configuration |

Deux façons de s’authentifier :

- **Une personne** lance `kodactl login`. La session est enregistrée et
  renouvelée pour les commandes suivantes.
- **Une automatisation** fait pointer `KODAMA_CREDENTIAL_FILE` vers un fichier
  de jeton. Dans un conteneur de pipeline, `kodactl` lit par défaut
  l’identifiant d’exécution monté.

`env.sh` définit `KODAMA_CREDENTIAL_FILE` sur un jeton d’administrateur.
Supprimez cette variable pour utiliser votre propre session.

## Se connecter

| Commande | Effet |
| --- | --- |
| `kodactl login` | Se connecter avec le navigateur (OIDC avec PKCE). `--device` ou `--no-browser` utilise le flux par appareil, pour une machine sans navigateur |
| `kodactl logout` | Révoquer le jeton de rafraîchissement et supprimer la session locale |
| `kodactl refresh` | Renouveler la session enregistrée avant son expiration |
| `kodactl status` | Afficher l’émetteur, l’URL du serveur et l’expiration de la session |
| `kodactl whoami` | Afficher votre principal, son type, son périmètre et ses rôles. `--offline` le déduit de la session enregistrée sans appeler le serveur |

## Exécuter et observer

| Commande | Effet |
| --- | --- |
| `kodactl run <file> [--input k=v]` | Démarrer un fichier de pipeline local en le transmettant directement, et le suivre jusqu’à sa fin. Rien n’est enregistré |
| `kodactl inspect <execution-id>` | Afficher une exécution et ses actions |
| `kodactl watch <execution-id>` | Interroger le serveur à intervalles réguliers jusqu’à la fin de l’exécution |
| `kodactl logs <execution-id> [--action <name>] [--stream stdout\|stderr] [-f]` | Lire le journal conservé d’une action ; `-f` le suit jusqu’à la fin de l’action |
| `kodactl pipeline apply <directory\|file>` | Enregistrer tous les fichiers `.yaml` et `.yml` d’un répertoire, ou un seul fichier, et afficher l’ID de chaque pipeline |

`run` affiche la sortie standard de chaque action conteneur, dans l’ordre des
actions, à la fin de l’exécution ; l’ID de l’exécution et le résultat vont sur
la sortie d’erreur standard. Sans `--action`, `logs` sélectionne l’action en
cours, ou la dernière qui a démarré.

## Traiter la boîte de réception

| Commande | Effet |
| --- | --- |
| `kodactl inbox` | Lister les approbations en attente, les tâches en attente et les tâches en échec pour vos rôles |
| `kodactl approve <execution-id> [--comment <text>] [--output k=v]` | Répondre à la demande en attente par `pass` |
| `kodactl reject <execution-id> --reason <text> [--output k=v]` | Y répondre par `fail` ; le motif est obligatoire |

`approve` et `reject` trouvent eux-mêmes la demande en attente de l’exécution.
Utilisez `--action <id>` pour la désigner. `--output` renseigne un champ de
réponse que la demande a déclaré, et peut être répété.

## Tâches

| Commande | Effet |
| --- | --- |
| `kodactl task create --title <t> [--description <d>] [--pipeline <id>] [--input k=v]` | Créer une tâche ouverte ; rien ne démarre |
| `kodactl task run --title <t> --pipeline <id> [--description <d>] [--input k=v]` | Créer une tâche et la démarrer aussitôt |
| `kodactl task list` | Lister les tâches du projet |
| `kodactl task show <task-id>` | Afficher l’état, les versions et la question en suspens ; `--output json` ajoute les messages |
| `kodactl task start <task-id>` | Démarrer une nouvelle exécution d’une tâche existante |
| `kodactl task reply <task-id> --answer <text>` | Répondre à la question en suspens d’une tâche en attente ; une nouvelle exécution est mise en file d’attente |
| `kodactl task cancel <task-id>` | Annuler une tâche et son exécution en cours |

`start` et `cancel` lisent eux-mêmes la version courante de la tâche ; passez
`--expected-version <v>` pour fixer la version que vous avez consultée.

## Membres

| Commande | Effet |
| --- | --- |
| `kodactl member list` | Lister les appartenances du projet et leurs versions |
| `kodactl member grant <principal-or-subject> --role <role>[,<role>…]` | Définir l’ensemble complet des rôles d’un principal : `admin`, `engineer`, `reviewer`, `operator`, `viewer` |
| `kodactl member revoke <principal-or-subject>` | Supprimer une appartenance |

Une cible qui commence par `oidc-` est utilisée telle quelle. Sinon, passez un
sujet OIDC, ou `--github <login>`, et `kodactl` déduit l’ID du principal à
partir de l’émetteur. Sur l’installation locale, ces commandes nécessitent le
jeton d’administrateur à l’échelle du tenant :

```sh
kodactl --credential-file "$KODAMA_TENANT_ADMIN_CREDENTIAL_FILE" member list
```

## MCP

| Commande | Effet |
| --- | --- |
| `kodactl mcp install [claude\|cursor\|codex]` | Écrire l’entrée Kodama dans la configuration MCP du client |
| `kodactl mcp stdio` | Relier le JSON-RPC de l’entrée et de la sortie standard au point d’accès `/mcp` du serveur, avec votre identifiant |

`mcp install` accepte `--print` pour afficher l’extrait sans écrire de fichier,
`--name` pour renommer le serveur (par défaut `kodama`), `--config-file` pour
un chemin explicite, et `--local` pour écrire `.mcp.json` dans le répertoire
courant (Claude uniquement). Les fichiers par défaut sont `~/.claude.json`,
`~/.cursor/mcp.json` et `~/.codex/config.toml`.

## Appeler n’importe quelle opération

`kodactl call` invoque n’importe quelle opération publique par son nom, avec
une entrée JSON :

```sh
kodactl call execution.list --input='{"project_id":"project-local"}'
KODAMA_OUTPUT=json kodactl call task.read --input='{"task_id":"<task-id>"}'
kodactl call task.cancel --input='{"task_id":"<task-id>"}' \
  --expected-version=3 --idempotency-key=cancel-task-1
```

Les trois options s’écrivent `--flag=value`. L’entrée porte les identifiants
que la route REST a dans son chemin, comme `project_id` ou `task_id`.
`--expected-version` et `--idempotency-key` correspondent aux champs de
l’enveloppe de requête décrite dans **[API et MCP](/fr/docs/kodama/api)**, qui
liste aussi les opérations.

## Assistant d’identification Git

`kodactl helper <get|store|erase>` est un assistant d’identification Git. Il
fournit votre jeton d’accès courant, ou le jeton d’exécution monté dans un
conteneur, comme mot de passe de l’utilisateur `kodama`, et uniquement aux
origines Git que l’installation enregistre comme étant de confiance.

## Sortie et codes de sortie

Les tableaux sont le format par défaut. `--output json`, ou
`KODAMA_OUTPUT=json`, affiche du JSON pour les scripts.

| Code | Signification |
| --- | --- |
| 0 | Succès. Pour `run` et `watch` : l’exécution a réussi |
| 1 | Échec. Pour `run` et `watch` : l’exécution a échoué ou a été annulée. `run` se termine aussi avec le code 1 quand l’exécution s’arrête sur une demande qui attend une personne |
| 2 | Erreur d’utilisation |

`kodactl help <command>` affiche l’usage d’une commande.

## Le binaire kodama

**Sur un poste de travail**

| Commande | Effet |
| --- | --- |
| `kodama up` | Démarrer un Kodama local sur Podman, ou renouveler ses identifiants s’il est déjà en cours d’exécution |
| `kodama status` | Inspecter le Kodama local ; `--json` affiche le rapport en JSON |
| `kodama down` | L’arrêter et conserver l’état ; `--purge` supprime les volumes et le répertoire d’état |

| Option de `kodama up` | Variable | Valeur par défaut |
| --- | --- | --- |
| `--name` | `KODAMA_INSTANCE` | `default` |
| `--state-dir` | `KODAMA_UP_STATE_DIR` | `~/.kodama/instances/<name>` |
| `--listen` | `KODAMA_UP_LISTEN` | Port 8443 |
| `--tenant` | `KODAMA_UP_TENANT` | `tenant-local` |
| `--project` | `KODAMA_UP_PROJECT` | `project-local` |
| `--image` | `KODAMA_UP_IMAGE` | L’image publiée de la version du binaire |
| `--socket` | `KODAMA_UP_SOCKET` | Le socket Podman de l’utilisateur |

**Dans une installation**

| Commande | Effet |
| --- | --- |
| `kodama server` | Exécuter le plan de contrôle (`--profile development`, `test` ou `production`) |
| `kodama migrate` | Appliquer les migrations de la base de données et définir les mots de passe des rôles |
| `kodama bootstrap-admin` | Créer le premier tenant et le premier administrateur à partir d’un jeton OIDC |
| `kodama git serve` | Exécuter le service Git smart-HTTP |
| `kodama git provision-tenant` | Créer le dépôt `admin` du tenant |
| `kodama git provision-repository` | Initialiser un dépôt et y enregistrer par un commit ses règles d’accès par défaut |
| `kodama auth serve` | Exécuter le fournisseur OIDC intégré et le courtier de connexion sociale |
| `kodama auth principal-id` | Déduire l’ID de principal d’un émetteur et d’un sujet OIDC |
| `kodama services` | Exécuter un adaptateur de service |
| `kodama agent` | Lancer une seule exécution bornée de l’agent natif |

`kodama <command> --help` affiche les options d’une commande.
**[Exploitation](/fr/docs/kodama/exploitation)** indique où chacune est utilisée.