Suivez ces étapes dans l'ordre pour mettre à niveau de CLI 2.x vers V3.
Démarrez une session V3 dans l'espace de travail que vous voulez migrer. Dans Kiro CLI 3.0.0 ou une version ultérieure, kiro-cli sans indicateur de harnais démarre aussi V3 sur une machine capable de l'exécuter et pose d'abord la question aux utilisateurs V2 existants; kiro-cli --v3 nomme le harnais et saute cette invite. Consultez Choisir un harnais d'agent pour savoir quel harnais chaque lancement démarre.
kiro-cli --v3
V3 utilise un magasin de sessions différent de celui de V2. Démarrer V3 ne modifie ni ne supprime vos sessions V2 existantes.
- Pour continuer une session V2 dans V3, utilisez
/sessions,--resumeou--resume-id. Kiro crée une copie V3, conserve la session V2 originale et ne reporte pas les approbations d'outils enregistrées de la session V2. Dans Kiro CLI 3.0.0 ou une version ultérieure,--resume-idavec un ID de session V2 reste sur V2, sauf si vous transmettez aussi--v3. - Pour continuer une session V2 sur le harnais V2, exécutez
kiro-cli chat --v2 --resume-picker.
V2 ne peut pas ouvrir une session V3.
Si vous avez besoin d'une copie externe d'une conversation importante, ouvrez-la avec le harnais qui l'a créée et exécutez /chat save <path>. Traitez le fichier exporté comme une archive, à moins d'avoir vérifié que le harnais cible peut le charger.
À partir de la session V3, exécutez la conversion et examinez ses diagnostics avant de modifier des fichiers manuellement :
> /upgrade-agent > /upgrade-agent diagnostics
La commande sauvegarde les profils sélectionnés, convertit les champs de permissions et de Hooks compatibles, et signale tout ce qui nécessite une attention manuelle. Effectuez ces étapes manuelles à partir du rapport. Exécutez /upgrade-agent de nouveau après avoir modifié les paramètres de confiance V2 pour que les règles V3 générées restent à jour. Si le menu de sélection affiche un agent désynchronisé, consultez Mise à niveau des configurations d'agent avant de le reconstruire, car cette action écrase les modifications V3 manuelles.
/upgrade-agent convertit une carte hooks sous forme d'objet en un tableau plat de documents de Hooks. Il conserve les anciennes chaînes de déclencheurs en camelCase comme alias de compatibilité acceptés. Utilisez le PascalCase lorsque vous rédigez ou révisez manuellement les définitions migrées. Déplacez les Hooks qui doivent s'exécuter indépendamment d'un profil dans des fichiers autonomes .kiro/hooks/*.json, et mettez à jour les cinq déclencheurs de cycle de vie de la CLI :
| CLI 2.x | CLI V3 |
|---|---|
agentSpawn | SessionStart |
userPromptSubmit | UserPromptSubmit |
preToolUse | PreToolUse |
postToolUse | PostToolUse |
stop | Stop |
CLI V3 prend aussi en charge PostFileCreate, PostFileSave et PostFileDelete pour les modifications de fichiers effectuées par l'agent, ainsi que PreTaskExec et PostTaskExec autour de l'exécution des tâches de spec. Les Hooks manuels sont une ancienne fonctionnalité de l'IDE 0.x. Consultez Migration des Hooks pour le schéma actuel de la CLI, le comportement des critères de correspondance, l'emplacement global des Hooks et un exemple complet avant et après.
Examinez les règles permissions créées par /upgrade-agent, puis appliquez les changements restants ci-dessous. Résolvez chaque avertissement avant d'utiliser le profil migré dans la CI.
Pour les pipelines CI, --trust-all-tools accorde une approbation à l'échelle de la session. Pour une approbation sans interface plus étroite, --trust-tools accepte des ID d'outils V3 exacts. Vous pouvez aussi créer ~/.kiro/settings/permissions.yaml avec des règles allow propres à chaque capacité dans votre environnement CI.
Remplacements au niveau de la session conservés dans V3 :
kiro-cli chat --v3 --no-interactive --trust-all-tools "Run the CI task" kiro-cli chat --v3 --no-interactive --trust-tools=read_file,grep_search "Review this repository" /tools trust-all
Dans V3, --trust-tools n'est pris en compte qu'avec --no-interactive; l'interface utilisateur interactive du terminal l'ignore. CLI 2.x accepte ses propres noms d'outils. Gardez --v3 ou --v2 dans vos scripts : une exécution sans interface qui ne nomme aucun harnais suit les valeurs par défaut indiquées sous Scripts et CI, qui dépendent des autres indicateurs que vous transmettez.
Nouvelle approche (~/.kiro/settings/permissions.yaml pour la portée utilisateur) :
rules: - capability: shell match: ["git *", "npm *", "npx *"] effect: allow - capability: fs_write match: ["src/**", "tests/**"] effect: allow - capability: fs_read effect: allow - capability: mcp match: ["my-server/*"] effect: allow
Pour la référence complète — changements de comportement, définitions de portée et tableau de conversion des motifs — consultez Migration des permissions →.
Sous-agents : dans CLI 2.x, les outils approuvés au préalable d'un sous-agent s'exécutaient sans invite, même si le parent ne les autorisait pas. Dans CLI V3, l'appel d'outil d'un sous-agent s'exécute sans invite seulement lorsque la politique de la session parente l'autorise aussi, et les exécutions sans interface refusent l'appel. Si un agent parent dépendait de ce comportement, copiez les règles allow du sous-agent dans les permissions.rules de l'agent parent, ou dans votre permissions.yaml d'utilisateur ou d'espace de travail. Consultez Autorisations des sous-agents.
/upgrade-agent conserve les champs de profil pris en charge et convertit les entrées tools et toolsSettings connues. Examinez sa sortie et ses diagnostics avant d'utiliser le profil :
- Le champ
toolsutilise maintenant des balises de catégorie ou des sélecteurs directs. L'étape 6 associe les noms courants de CLI 2.x selon leur destination. toolsSettingsetallowedToolsdeviennent despermissions.rulesfondées sur les capacités.- Les profils peuvent rester en JSON ou utiliser Markdown avec un frontmatter YAML et une requête système dans le corps.
- Les champs comme
excludedTools,includeMcpJson,includePowers,resources,permissionsetwelcomeMessagesont facultatifs.
Migration de toolsSettings vers permissions :
toolsSettings V2 | Règle permissions V3 |
|---|---|
execute_bash.allowedCommands: ["^git status$"] | { "capability": "shell", "match": ["git status"], "effect": "allow" } |
execute_bash.deniedCommands: ["^rm -rf"] | { "capability": "shell", "match": ["rm -rf*"], "effect": "deny" } |
execute_bash.denyByDefault: true | { "capability": "shell", "exclude": ["git *", "npm *"], "effect": "deny" } |
fs_read.allowedPaths: ["src/**"] | { "capability": "fs_read", "match": ["src/**"], "effect": "allow" } |
fs_read.deniedPaths: [".env"] | { "capability": "fs_read", "match": [".env"], "effect": "deny" } |
fs_write.allowedPaths: ["src/**"] | { "capability": "fs_write", "match": ["src/**"], "effect": "allow" } |
Remarque : les
allowedCommandsetdeniedCommandsde V2 utilisaient des motifs regex. Les permissions V3 utilisent des globs : retirez les ancres comme^et$, remplacez.*par*, et réécrivez les regex complexes sous forme de plusieurs règles.
Consultez la référence de configuration d'agent pour les champs actuels et les serveurs MCP intégrés, et sa section Format Markdown pour un exemple Markdown complet. Si le profil contient des Hooks, examinez leur tableau converti ou déplacez l'automatisation indépendante du profil dans un fichier autonome, comme décrit dans Migration des Hooks.
L'outil AWS structuré de CLI 2.x (use_aws, alias privilégié aws) n'est pas intégré à V3. Configurez plutôt un serveur MCP AWS. L'entrée AWS MCP distante gérée du répertoire de serveurs MCP utilise cette configuration :
.kiro/settings/mcp.json :
{ "mcpServers": { "aws-mcp": { "url": "https://aws-mcp.us-east-1.api.aws/mcp", "disabled": false } } }
Examinez l'accès IAM du serveur avant de l'utiliser, et consultez le registre pour connaître les options de configuration actuelles.
V3 utilise des identifiants différents pour la sélection dans le profil d'agent, la politique de permissions et la correspondance à l'exécution. Ne substituez pas un espace de noms à un autre.
Le champ tools accepte des balises de catégorie et certains ID d'outils directs :
| Noms CLI 2.x acceptés | Sélecteur V3 | Type de sélecteur |
|---|---|---|
fs_read, fsRead, read, grep, glob, code, introspect | read | Balise de catégorie |
fs_write, fsWrite, write | write | Balise de catégorie |
execute_bash, execute_cmd, executeCmd, shell | shell | Balise de catégorie |
web_fetch, web_search | web | Balise de catégorie |
agent_crew, use_subagent, subagent | subagent | Balise de catégorie |
knowledge | knowledge | ID d'outil direct |
/upgrade-agent réécrit les noms de liste de tâches de CLI 2.x (task, todo, todo_list) en todo_list, mais CLI V3 n'a pas d'outil de liste de tâches; cette entrée ne sélectionne donc rien. Retirez-la du profil converti.
Le champ capability utilise des classes d'opérations, et non des balises de profil ou des ID d'outils :
| Famille d'outils CLI 2.x | Capacité de permission V3 |
|---|---|
fs_read, fsRead, read, grep, glob, code, introspect | fs_read |
fs_write, fsWrite, write | fs_write |
execute_bash, execute_cmd, executeCmd, shell | shell |
web_fetch | web_fetch |
web_search | web_search |
agent_crew, use_subagent, subagent | subagent |
knowledge n'a aucune correspondance de capacité par outil générée. Définissez des règles pour les opérations que le workflow effectue réellement au lieu d'inventer un nom de capacité.
Les critères de correspondance PreToolUse et PostToolUse de V3 acceptent un sélecteur d'outil (un ID d'outil V3, une balise de catégorie, @builtin, @mcp, @<server>, @<server>/<tool> ou un caractère générique */?) ou une expression régulière. Un critère de correspondance qui contient des métacaractères regex est évalué uniquement comme une regex non ancrée par rapport à l'ID d'outil interne. /upgrade-agent réécrit les noms CLI 2.x connus vers la balise correspondante; utilisez ce tableau lorsque vous rédigez un critère de correspondance manuellement :
| Critère de correspondance CLI 2.x | Critère de correspondance de Hook V3 |
|---|---|
fs_read, fsRead, read | read (balise; couvre aussi grep_search, file_search, code, introspect) ou ^(read_file|list_directory)$ |
grep | grep_search |
glob | file_search |
fs_write, fsWrite, write | write (balise) ou ^(fs_write|fs_append|str_replace|delete_file)$ |
execute_bash, execute_cmd, executeCmd, shell | shell (balise) ou execute_bash (correspond aussi à execute_pwsh) |
web_fetch | web_fetch |
web_search | remote_web_search |
code | code |
introspect | introspect |
use_aws, aws | Aucun outil intégré V3; faites correspondre l'outil MCP configuré avec @<server>/<tool> ou son ID interne mcp_<server>_<tool> |
L'indicateur sans interface --trust-tools accepte une liste d'ID d'outils V3 séparés par des virgules — par exemple, --trust-tools=read_file,grep_search — et, dans Kiro CLI 3.3.0 ou version ultérieure, aussi des noms d'outils V2, des références @server et des motifs */?, mais jamais des regex (consultez le mode sans interface). Consultez le catalogue d'outils pour les balises de profil et les ID intégrés, Permissions pour les capacités et Types de Hooks pour le comportement des critères de correspondance.
-
À partir de votre shell, validez chaque configuration d'agent migrée :
bashkiro-cli agent validate --path .kiro/agents/my-agent.json -
Démarrez ou revenez à une session V3 dans l'espace de travail migré. Exécutez
/configet/hookspour confirmer que Kiro a chargé les agents, les permissions et les Hooks attendus. -
Exécutez des commandes représentatives pour vérifier le comportement d'approbation que vous visiez.
Résolvez chaque avertissement de conversion ou erreur de validation avant d'utiliser la configuration dans la CI.
- Migration des permissions — conseils détaillés sur la migration des indicateurs de confiance vers
permissions.yaml - Migration des Hooks — correspondance complète des déclencheurs et référence du nouveau format
Guide de migration