Passer au contenu principal
Afficher en Markdown

Mode sans interface

Le mode sans interface vous permet d'exécuter Kiro CLI dans le cadre de votre pipeline CI/CD pour automatiser les revues de code, générer des tests ou diagnostiquer les échecs de compilation — aucun terminal interactif requis. Authentifiez-vous avec une clé API, transmettez une requête, et Kiro l'exécute de bout en bout.

Authentification

Le mode sans interface nécessite une clé API définie comme variable d'environnement KIRO_API_KEY. Si vous n'en avez pas encore créé une, suivez les étapes dans Générer une clé API.

Pour plus de détails sur la préséance de l'authentification et la vérification de vos identifiants actifs, consultez Authentification.

Exécuter des commandes sans interface

Transmettez --no-interactive avec votre instruction initiale. L'instruction peut être fournie comme argument positionnel ou via l'entrée standard (stdin). Lorsque l'entrée standard est redirigée et qu'aucun argument positionnel n'est fourni, Kiro lit l'intégralité du flux comme instruction. Une exécution locale sans interface qui ne nomme aucun harnais exécute V2, avec les exceptions énumérées sous Scripts et CI; ajoutez --v3 ou --v2 afin que l'exécution ne dépende pas de la valeur par défaut.

bash
# Positional argument kiro-cli chat --no-interactive "your prompt here" # Stdin only: pipe the entire instruction printf '%s\n' "your prompt here" | kiro-cli chat --no-interactive

Puisqu'il n'y a aucun utilisateur pour approuver les appels d'outils, les sessions V3 locales peuvent utiliser --trust-all-tools pour une approbation à l'échelle de la session ou --trust-tools avec une liste d'ID d'outils séparés par des virgules. Utilisez des règles permissions.yaml délimitées pour des politiques de capacités réutilisables. CLI 2.x utilise ses propres noms d'outils avec --trust-tools.

Dans Kiro CLI 3.3.0 ou version ultérieure, une entrée --trust-tools dans une exécution V3 --no-interactive peut aussi être un nom d'outil V2, @server ou @server/tool pour les outils d'un serveur MCP, @builtin ou un motif */?. Un nom V2 approuve chaque outil V3 de sa capacité de permission, de sorte que --trust-tools=write approuve aussi delete_file et str_replace; read n'approuve jamais l'outil code, et grep, glob, code et introspect n'approuvent que leurs propres outils. Un outil approuvé s'exécute sur tout chemin pour lequel il demanderait une approbation, y compris à l'extérieur de l'espace de travail. Une exécution V2 --no-interactive accepte les ID shell V3 run_command et execute_pwsh, ainsi que les motifs qui les nomment, comme son outil shell.

bash
# V3: trust all tools for this session kiro-cli chat --v3 --no-interactive --trust-all-tools "Write tests for the auth module and run them" # V3: trust only the exact tools needed kiro-cli chat --v3 --no-interactive --trust-tools=read_file,grep_search "Find all TODO comments in src/"

En V3, l'appel d'outil d'un sous-agent s'exécute sans approbation seulement lorsque la politique de la session parente l'autorise aussi. Sinon, l'appel nécessite une approbation, et une exécution sans interface le refuse avec cette erreur :

[denied] tool permission approval is not supported in non-interactive mode. Use --trust-all-tools to auto-approve.

Ajouter le sous-agent à trustedAgents ne change rien à cela. Ajoutez les règles allow du sous-agent aux permissions.rules de l'agent parent ou à permissions.yaml, ou utilisez --trust-all-tools. Consultez Autorisations des sous-agents.

Exécuter une requête ou un SOP comme premier message

Dans Kiro CLI 2.33 ou une version ultérieure, un premier message qui commence par @<prompt-name> exécute cette requête au lieu d'envoyer le texte tel que saisi, tant dans une session interactive qu'avec --no-interactive. Le nom correspond à une requête d'espace de travail, globale ou MCP, sans égard à la casse; @agent-sop:<name> exécute le SOP nommé. Le texte qui suit le nom devient les arguments de la requête. Avant 2.33, un premier message qui nommait une requête d'un serveur MCP encore en cours de démarrage était envoyé tel que saisi.

bash
kiro-cli chat --agent <agent> --no-interactive "@agent-sop:<name> Payments eu-west-1"

Kiro attend que les serveurs MCP qui fournissent des requêtes aient fini de démarrer, jusqu'à 30 secondes par défaut, avant de décider. Un nom auquel aucune requête ne correspond une fois que tous les serveurs ont démarré est envoyé tel que saisi. Une mention de type chemin comme @src/main.rs reste une référence de fichier. Pour confirmer que le SOP est accessible à l'agent, lancez une session interactive avec le même --agent et exécutez /prompts list; le SOP apparaît sous son nom agent-sop:.

Hooks V3 et outils intégrés

À partir de Kiro CLI 2.27.1, les exécutions non interactives V3 chargent les Hooks de l'agent sélectionné et de l'espace de travail. Les Hooks PreToolUse s'exécutent avant un appel d'outil et peuvent le refuser. Consultez Hooks pour les déclencheurs et les actions pris en charge.

--trust-all-tools approuve automatiquement les demandes de confirmation des Hooks. --trust-tools ne le peut pas, car une demande de Hook n'est pas liée à un ID d'outil. Sans --trust-all-tools, Kiro la refuse. Un Hook qui bloque est définitif, quel que soit l'indicateur utilisé. Pour l'automatisation, rédigez des Hooks qui renvoient une décision finale d'autorisation ou de refus.

Les exécutions non interactives V3 activent par défaut la base de connaissances et l'intelligence du code. Définissez chat.enableKnowledge ou chat.enableCodeIntelligence à false pour désactiver l'un ou l'autre de ces outils. Consultez Outils intégrés et la référence des paramètres.

Paramètres V3 enregistrés

Kiro CLI 2.31.1 et les versions ultérieures appliquent les paramètres enregistrés de compaction et de Tool Search aux exécutions non interactives V3.

ObjectifParamètres
Compaction automatiquechat.disableAutoCompaction, compaction.excludeMessages, compaction.excludeContextWindowPercent
Tool SearchtoolSearch.enabled, toolSearch.minPct, toolSearch.minTokens

Pour appliquer les seuils de Tool Search enregistrés, enregistrez aussi toolSearch.enabled true.

Enregistrez les valeurs avec kiro-cli settings, comme vous le faites pour les sessions interactives :

bash
kiro-cli settings compaction.excludeMessages 4 kiro-cli settings toolSearch.enabled true

Si une exécution sans interface se comporte différemment après une mise à niveau, exécutez kiro-cli settings list pour trouver les valeurs compaction.* ou toolSearch.* enregistrées. Supprimez une valeur globale indésirable avec kiro-cli settings --delete <name>. Pour une valeur marquée (workspace), ajoutez --workspace après settings. La suppression d'une valeur touche aussi les sessions interactives.

Consultez Compaction, Tool Search et la référence des paramètres pour chaque paramètre.

Bac à sable local des commandes

Les exécutions sans interface V3 de Kiro CLI 2.31 et des versions ultérieures lisent les paramètres sandbox.json globaux et de projet. Lorsque les paramètres résolus ont enabled: true, Kiro demande la mise en bac à sable sans indicateur supplémentaire. Si Kiro ne peut pas activer le bac à sable, l'exécution émet un avertissement et se poursuit sans mise en bac à sable. Si l'encapsulation MCP demandée échoue, les commandes en bac à sable restent protégées, mais pas les serveurs MCP touchés.

Ajoutez --sandbox lorsque votre script doit s'arrêter au lieu de se poursuivre sans toute la protection demandée :

bash
kiro-cli chat --v3 --sandbox --no-interactive "Run the test suite"

L'exécution se termine avant le début de la tâche lorsque le bac à sable ne peut pas s'activer. Elle se termine également lorsque mcpSandboxing est activé, mais que les serveurs MCP locaux ne peuvent pas être encapsulés. Consultez Bac à sable local des commandes pour la configuration de la plateforme, les paramètres et la récupération.

Exemples CI/CD

GitHub Actions

yaml
name: Kiro Code Review on: [pull_request] jobs: review: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Install Kiro CLI run: curl -fsSL https://cli.kiro.dev/install | bash - name: Review PR changes env: KIRO_API_KEY: ${{ secrets.KIRO_API_KEY }} run: kiro-cli chat --v3 --no-interactive --trust-tools=read_file,grep_search "Review the changes in this PR for security issues"

Autres scénarios

bash
# Generate and run tests kiro-cli chat --v3 --no-interactive --trust-all-tools "Write tests for the auth module and run them" # Troubleshoot a failing build with the full instruction on stdin { printf '%s\n\n' "Explain this build failure and suggest a fix:" cat build-error.log } | kiro-cli chat --v3 --no-interactive --trust-tools=read_file

Utilisez --require-mcp-startup lorsqu'une exécution non interactive dépend des outils MCP. V2 et V3 attendent les serveurs MCP configurés avant de soumettre l'instruction. En V3, Kiro se termine avec le code 3 si un serveur échoue, si son état de démarrage ne peut pas être déterminé ou s'il ne signale aucun état dans les 30 secondes. Sans cet indicateur, Kiro consigne les problèmes de démarrage MCP et poursuit l'exécution. Consultez les codes de sortie pour gérer les échecs dans les scripts.

Sélection de l'agent

Transmettez --agent <name> pour exécuter une commande non interactive avec un agent précis. Sans --agent, une nouvelle exécution V3 utilise chat.defaultAgent lorsqu'il est configuré. Si aucun agent par défaut n'est configuré, elle utilise l'agent intégré par défaut. Sans modèle explicite, une nouvelle exécution V3 applique chat.defaultModel lorsqu'il est configuré; un agent sélectionné qui spécifie un modèle peut le remplacer. V2 détermine son agent et son modèle par défaut à l'interne.

bash
kiro-cli settings chat.defaultAgent my-project-agent kiro-cli chat --v3 --no-interactive "Write tests for the auth module" # runs on my-project-agent

Transmettez --model <id> pour fixer le modèle d'une exécution. Sur V2 et V3, une valeur explicite remplace le modèle configuré de l'agent sélectionné; sur V3, elle remplace également chat.defaultModel, et sur V2, elle remplace le modèle enregistré d'une session reprise. V2 supprime les espaces en début et en fin avant de transmettre au système dorsal un ID non vide qui ne figure pas dans la liste; une valeur vide ne transmet aucun remplacement et laisse la sélection de modèle actuelle inchangée. Sans --model, une session reprise conserve son agent et son modèle d'origine.

Transmettez --effort <level> pour définir l'effort de raisonnement d'une exécution non interactive. Les niveaux pris en charge dépendent du modèle sélectionné. En V3, l'indicateur s'applique uniquement à la session démarrée par Kiro et ne modifie pas la valeur par défaut enregistrée pour chaque modèle.

Sortie structurée

Transmettez --output-format stream-json pour recevoir les événements d'exécution sous forme de JSON Lines sur la sortie standard. Chaque ligne est un objet JSON autonome, ce qui facilite son traitement dans les scripts, les pipelines de journalisation et les tâches CI par rapport au texte mis en forme.

bash
kiro-cli chat --v3 --no-interactive --trust-all-tools --output-format stream-json "Summarize open TODOs in src/"

--output-format stream-json nécessite V2 ou V3 (--agent-engine v2 ou --agent-engine v3).

Gérer les exécutions interrompues

En V3, une exécution non interactive interrompue écrit un enregistrement d'interruption final dans stream-json. Traitez cet enregistrement final comme la fin de l'exécution interrompue plutôt que d'attendre un autre enregistrement de fin d'exécution.

Attendre les workflows en cours

Si votre instruction démarre un workflow et que le tour se termine avant qu'il ne se stabilise, une exécution non interactive V3 l'attend avant de se terminer. Le délai d'attente par défaut est de six heures.

Remplacez le délai d'attente avec la variable d'environnement KIRO_HEADLESS_WORKFLOW_TIMEOUT_SECS, en secondes :

bash
# Wait up to 10 minutes for workflows to settle KIRO_HEADLESS_WORKFLOW_TIMEOUT_SECS=600 kiro-cli chat --v3 --no-interactive "Run the release-check workflow"

La valeur doit être un nombre entier positif de secondes ne dépassant pas la valeur par défaut de six heures. Une valeur invalide, nulle ou supérieure au plafond revient silencieusement à la valeur par défaut de six heures plutôt que de produire une erreur.

La progression de chaque workflow est écrite dans la sortie de l'exécution au fur et à mesure. Lorsqu'un workflow se termine, il signale l'un des résultats suivants :

RésultatSignification
completedLe workflow s'est terminé avec succès.
failedLe workflow s'est terminé dans un état d'échec.
abortedLe workflow a été arrêté avant d'être terminé.
pausedLe workflow attend à un point de pause.
(état inconnu)Kiro n'a pas pu déterminer l'état final du workflow.

Si un workflow ne se termine pas dans le délai d'attente, l'exécution signale workflow run incomplete (<outcomes>) avec une indication de récupération. Elle ne signale pas un simple succès.

Sessions cloud en V3

Kiro CLI V3 peut démarrer une session cloud de façon interactive ou non interactive. Ajoutez --cloud pour exécuter la tâche dans un bac à sable cloud géré, et --repo pour démarrer avec un ou plusieurs dépôts.

bash
kiro-cli --cloud --repo owner/repository kiro-cli chat --v3 --no-interactive --cloud --repo owner/repository "Review the open pull request"

Dans Kiro CLI 3.4.0 ou une version ultérieure, --cloud --resume reprend votre session cloud la plus récente dans une exécution --no-interactive. Kiro choisit la session cloud la plus récente de l'ensemble de votre compte, et non par répertoire. Lorsque vous n'avez aucune session cloud, l'exécution s'arrête avec le code de sortie 1 et affiche no cloud session to --resume; start one with --cloud. Avant la version 3.4.0, une exécution sans interface refusait --cloud avec --resume. --repo ne peut toujours pas être combiné avec --resume.

bash
kiro-cli chat --v3 --no-interactive --cloud --resume "Continue the task"

Pour confirmer que l'exécution a repris la session, lisez la sortie d'erreur standard (stderr) : une exécution reprise affiche [cloud] session <id> avec l'ID de la session existante, et l'état de sortie est 0.

Pour tous les indicateurs de session cloud, le flux de démarrage, la configuration des dépôts, la sortie, le comportement de reprise et de suppression, ainsi que ce qui diffère des sessions locales, consultez Sessions cloud.

Échecs en texte brut et état de sortie

Les exécutions en texte brut expliquent quand un tour a été annulé ou refusé. Elles affichent aussi pourquoi une session n'a pas pu être créée ou reprise. Un appel d'outil échoué inclut son message d'erreur lorsqu'il en existe un. Si la sortie standard se ferme avant la fin, Kiro se termine avec un état non nul au lieu de terminer le tour.

Dans Kiro CLI 3.4.0 ou une version ultérieure, une nouvelle session sans interface V2 ou V3 dont la requête ne tient pas dans la fenêtre de contexte du modèle, avec la requête système de l'agent, ses fichiers de contexte et ses définitions d'outils, s'arrête avec le code de sortie 1 et une erreur sur la sortie d'erreur standard (stderr). Avant la version 3.4.0, l'exécution répondait à partir d'une copie résumée ou tronquée de la requête. Une session reprise n'est pas touchée. Raccourcissez l'entrée, répartissez-la sur plusieurs exécutions, ou allégez les fichiers de contexte et les outils de l'agent, puis relancez l'exécution. Avec --output-format stream-json, l'exécution se termine par un enregistrement d'erreur au lieu d'un enregistrement de fin; traitez-le comme la fin de l'exécution. Pour confirmer la cause, vérifiez l'état de sortie après l'exécution : il est 1, et la sortie d'erreur standard indique que la requête ne tient pas dans la fenêtre de contexte du modèle.

Référence des indicateurs

IndicateurDescription
--no-interactiveExécuter sans session interactive. Nécessite une instruction non vide, fournie comme argument positionnel ou via l'entrée standard (stdin)
--cloudExécuter la tâche V3 dans une session cloud
--repo <owner/repository>Ajouter un ou plusieurs dépôts séparés par des virgules à une session cloud V3
--resume-id <ID>Reprendre une session locale ou cloud par ID
--resumeReprendre la session correspondante la plus récente; consultez gestion des sessions. Dans Kiro CLI 3.4.0 ou une version ultérieure, avec --cloud, reprendre votre session cloud la plus récente, ou se terminer avec le code 1 lorsqu'il n'y en a aucune
--agent <name>Exécuter avec un agent précis. Lorsque l'indicateur est omis, une nouvelle exécution V3 utilise chat.defaultAgent lorsqu'il est configuré, sinon l'agent intégré par défaut
--model <id>Fixer le modèle de l'exécution. Prend la priorité sur un modèle indiqué dans la configuration de l'agent et, sur V3, sur chat.defaultModel
--effort <level>Définir l'effort de raisonnement de l'exécution lorsque le modèle sélectionné le prend en charge
--agent-engine <v1|v2|v3>Sélectionner la version du harnais d'agent. Les indicateurs raccourcis --v2 et --v3 sont également acceptés. Dans Kiro CLI 3.0.0 ou une version ultérieure, une exécution sans interface qui ne nomme aucun harnais utilise V2, avec les exceptions indiquées sous Scripts et CI
--output-format stream-jsonÉmettre les événements d'exécution sous forme de JSON Lines sur la sortie standard pour un usage programmatique (V2/V3 uniquement)
--trust-all-toolsApprouver automatiquement tous les appels d'outils sans demander confirmation
--trust-tools=<tool-ids>V3 non interactif : approuver automatiquement les ID d'outils listés; dans Kiro CLI 3.3.0 ou version ultérieure, aussi les noms d'outils V2, les références @server, @builtin et les motifs */?. CLI 2.x accepte ses propres noms d'outils. Ignoré par V3 interactif
--sandboxExiger le bac à sable local des commandes et se terminer si la protection ne peut pas démarrer
--require-mcp-startupAttendre les serveurs MCP requis et se terminer avec le code 3 si le démarrage échoue

Variables d'environnement

VariableDescription
KIRO_API_KEYClé API utilisée pour l'authentification sans interface
KIRO_HEADLESS_WORKFLOW_TIMEOUT_SECSNombre de secondes pendant lesquelles une exécution non interactive V3 attend que les workflows en cours se stabilisent avant de se terminer. Valeur par défaut : 21600 (six heures). Les valeurs invalides, nulles ou supérieures au plafond reviennent à la valeur par défaut

Bonnes pratiques

  • Stockez KIRO_API_KEY comme secret dans votre plateforme CI/CD — ne l'inscrivez jamais en dur dans les configurations de pipeline et ne l'ajoutez jamais à un système de gestion de versions.
  • Nommez le harnais avec --v2 ou --v3 dans chaque commande sans interface, afin que l'exécution ne change pas de harnais lorsque vous ajoutez ou retirez --trust-all-tools.
  • Dans les sessions V3 locales sans interface, privilégiez --trust-tools avec les ID d'outils dont vous avez besoin plutôt que --trust-all-tools. Utilisez des règles d'autorisation à portée limitée dans permissions.yaml lorsque la politique doit être réutilisable.
  • Ajoutez --require-mcp-startup lorsque votre pipeline dépend de serveurs MCP, afin que la tâche s'arrête avant de commencer plutôt que de s'exécuter sans les outils attendus.
  • Avec V2 ou V3, fournissez votre instruction comme argument positionnel ou transmettez-la via l'entrée standard (stdin), mais pas les deux. V2 et V3 ne lisent l'entrée standard que lorsqu'aucun argument positionnel n'est présent.
  • Vérifiez les codes de sortie dans votre pipeline pour gérer les échecs de façon appropriée.
  • Renouvelez régulièrement vos clés API et révoquez celles qui ne sont plus utilisées depuis le portail Kiro.

Limitations

  • Vous devez fournir une instruction initiale non vide, soit comme argument positionnel, soit via l'entrée standard (stdin).
  • Aucune saisie utilisateur en cours de session n'est possible.
  • Les commandes à barre oblique interactives (sélecteur /model, sélecteur /agent) ne sont pas disponibles.
  • Les fonctionnalités de l'interface utilisateur du terminal sont désactivées.

Connexes

Page mise à jour : 17 novembre 2026