Standardize CLI flags to kebab-case (#6880)

* Standardize CLI flags to kebab-case with deprecated snake_case aliases.

Unify active long-option naming across create, train, test, and replay while keeping hidden backward-compatible aliases and documenting the migration in edge docs and AGENTS.md.

* Emit deprecation warnings when snake_case CLI flag aliases are used.

Route hidden legacy flags through separate internal params so warnings fire only when the alias is supplied, and extend CLI tests for create, replay, and --help coverage.

* Merge CLI deprecation warn helpers into warn_deprecated(kind=...).

Replace warn_deprecated_command and warn_deprecated_flag with one helper that accepts kind="command" or kind="flag".

lib/cli/src/crewai_cli/cli.py

@@ -19,7 +19,7 @@ from crewai_cli.utils import (
     enable_prompt_line_editing,
     is_dmn_mode_enabled,
     read_toml,
-    warn_deprecated_command,
+    warn_deprecated,
 )
 
 
@@ -145,7 +145,19 @@ def uv(uv_args: tuple[str, ...]) -> None:
 )
 @click.argument("name", required=False, default=None)
 @click.option("--provider", type=str, help="The provider to use for the crew")
-@click.option("--skip_provider", is_flag=True, help="Skip provider validation")
+@click.option(
+    "--skip-provider",
+    "skip_provider",
+    is_flag=True,
+    help="Skip provider validation",
+)
+@click.option(
+    "--skip_provider",
+    "deprecated_skip_provider",
+    is_flag=True,
+    hidden=True,
+    help="[Deprecated: use --skip-provider] Skip provider validation",
+)
 @click.option(
     "--classic",
     is_flag=True,
@@ -176,12 +188,16 @@ def create(
     name: str | None,
     provider: str | None,
     skip_provider: bool = False,
+    deprecated_skip_provider: bool = False,
     classic: bool = False,
     declarative: bool = False,
     in_project: bool = True,
     output_dir: str | None = None,
 ) -> None:
     """Create a new crew, flow, tool, skill, or template."""
+    if deprecated_skip_provider:
+        warn_deprecated(kind="flag", old="--skip_provider", new="--skip-provider")
+        skip_provider = True
     dmn_mode = is_dmn_mode_enabled()
     if not type:
         if dmn_mode:
@@ -288,11 +304,20 @@ def version(tools: bool) -> None:
 @crewai.command()
 @click.option(
     "-n",
-    "--n_iterations",
+    "--n-iterations",
+    "n_iterations",
     type=int,
     default=5,
     help="Number of iterations to train the crew",
 )
+@click.option(
+    "--n_iterations",
+    "deprecated_n_iterations",
+    type=int,
+    default=None,
+    hidden=True,
+    help="[Deprecated: use --n-iterations]",
+)
 @click.option(
     "-f",
     "--filename",
@@ -300,8 +325,15 @@ def version(tools: bool) -> None:
     default="trained_agents_data.pkl",
     help="Path to a custom file for training",
 )
-def train(n_iterations: int, filename: str) -> None:
+def train(
+    n_iterations: int,
+    deprecated_n_iterations: int | None,
+    filename: str,
+) -> None:
     """Train the crew."""
+    if deprecated_n_iterations is not None:
+        warn_deprecated(kind="flag", old="--n_iterations", new="--n-iterations")
+        n_iterations = deprecated_n_iterations
     click.echo(f"Training the Crew for {n_iterations} iterations")
     train_crew(n_iterations, filename)
 
@@ -309,10 +341,19 @@ def train(n_iterations: int, filename: str) -> None:
 @crewai.command()
 @click.option(
     "-t",
-    "--task_id",
+    "--task-id",
+    "task_id",
     type=str,
     help="Replay the crew from this task ID, including all subsequent tasks.",
 )
+@click.option(
+    "--task_id",
+    "deprecated_task_id",
+    type=str,
+    default=None,
+    hidden=True,
+    help="[Deprecated: use --task-id]",
+)
 @click.option(
     "-f",
     "--filename",
@@ -326,13 +367,20 @@ def train(n_iterations: int, filename: str) -> None:
         "CREWAI_TRAINED_AGENTS_FILE."
     ),
 )
-def replay(task_id: str, trained_agents_file: str | None) -> None:
+def replay(
+    task_id: str | None,
+    deprecated_task_id: str | None,
+    trained_agents_file: str | None,
+) -> None:
     """Replay the crew execution from a specific task.
 
     Args:
         task_id: The ID of the task to replay from.
         trained_agents_file: Optional trained-agents pickle path.
     """
+    if deprecated_task_id is not None:
+        warn_deprecated(kind="flag", old="--task_id", new="--task-id")
+        task_id = deprecated_task_id
     try:
         click.echo(f"Replaying the crew from task {task_id}")
         replay_task_command(task_id, trained_agents_file=trained_agents_file)
@@ -504,11 +552,20 @@ def memory(
 @crewai.command()
 @click.option(
     "-n",
-    "--n_iterations",
+    "--n-iterations",
+    "n_iterations",
     type=int,
     default=3,
     help="Number of iterations to Test the crew",
 )
+@click.option(
+    "--n_iterations",
+    "deprecated_n_iterations",
+    type=int,
+    default=None,
+    hidden=True,
+    help="[Deprecated: use --n-iterations]",
+)
 @click.option(
     "-m",
     "--model",
@@ -529,8 +586,16 @@ def memory(
         "CREWAI_TRAINED_AGENTS_FILE."
     ),
 )
-def test(n_iterations: int, model: str, trained_agents_file: str | None) -> None:
+def test(
+    n_iterations: int,
+    deprecated_n_iterations: int | None,
+    model: str,
+    trained_agents_file: str | None,
+) -> None:
     """Test the crew and evaluate the results."""
+    if deprecated_n_iterations is not None:
+        warn_deprecated(kind="flag", old="--n_iterations", new="--n-iterations")
+        n_iterations = deprecated_n_iterations
     click.echo(f"Testing the crew for {n_iterations} iterations with model {model}")
     evaluate_crew(n_iterations, model, trained_agents_file=trained_agents_file)
 
@@ -708,7 +773,7 @@ def tool() -> None:
 @click.argument("handle")
 def tool_create(handle: str) -> None:
     """[Deprecated: use `crewai create tool`] Create a custom tool project."""
-    warn_deprecated_command(old="crewai tool create", new="crewai create tool")
+    warn_deprecated(kind="command", old="crewai tool create", new="crewai create tool")
     from crewai_cli.tools.main import ToolCommand
 
     tool_cmd = ToolCommand()
@@ -760,7 +825,9 @@ def skill() -> None:
 )
 def skill_create(name: str, in_project: bool) -> None:
     """[Deprecated: use `crewai create skill`] Create a new agent skill."""
-    warn_deprecated_command(old="crewai skill create", new="crewai create skill")
+    warn_deprecated(
+        kind="command", old="crewai skill create", new="crewai create skill"
+    )
     from crewai_cli.skills.main import SkillCommand
 
     skill_cmd = SkillCommand()
@@ -825,7 +892,9 @@ def template_list() -> None:
 )
 def template_add(name: str, output_dir: str | None) -> None:
     """[Deprecated: use `crewai create template`] Add a template to the current directory."""
-    warn_deprecated_command(old="crewai template add", new="crewai create template")
+    warn_deprecated(
+        kind="command", old="crewai template add", new="crewai create template"
+    )
     template_cmd = TemplateCommand()
     template_cmd.add_template(name, output_dir)
 

lib/cli/src/crewai_cli/templates/AGENTS.md

@@ -48,6 +48,14 @@ These commands remain supported but print a yellow deprecation warning. Prefer t
 - ⚠️ `crewai skill create <name>` → ✅ `crewai create skill <name>`
 - ⚠️ `crewai template add <name>` → ✅ `crewai create template <name>`
 
+### Deprecated CLI flag aliases (still supported)
+
+These snake_case flags still work but are hidden from `--help`. Prefer kebab-case:
+
+- ⚠️ `--skip_provider` → ✅ `--skip-provider` (on `crewai create crew`)
+- ⚠️ `--n_iterations` → ✅ `--n-iterations` (on `crewai train`, `crewai test`)
+- ⚠️ `--task_id` → ✅ `--task-id` (on `crewai replay`)
+
 ### How to verify you're using current patterns:
 1. You ran the version check and docs lookup steps above before writing code
 2. All LLM references use `crewai.LLM` or string shorthand (`"openai/gpt-4o"`)
@@ -145,7 +153,7 @@ uv sync                   # Sync dependencies
 uv lock                   # Lock dependencies
 
 # Project scaffolding
-crewai create crew <name> --skip_provider       # New crew project
+crewai create crew <name> --skip-provider       # New crew project
 crewai create flow <name>                       # New flow project
 crewai create tool <handle>                     # Custom tool repository
 crewai create skill <name>                      # Agent skill (./skills/ in crew projects)
@@ -1159,7 +1167,7 @@ Python >=3.10, <3.14
 ```bash
 uv tool install crewai        # Install CrewAI CLI
 uv tool list                  # Verify installation
-crewai create crew my_crew --skip_provider   # Scaffold a crew project
+crewai create crew my_crew --skip-provider   # Scaffold a crew project
 crewai create tool my_tool                   # Scaffold a tool repository
 crewai create skill my_skill                 # Scaffold an agent skill
 crewai install                # Install project dependencies

lib/cli/src/crewai_cli/utils.py

@@ -5,7 +5,7 @@ import os
 from pathlib import Path
 import re
 import shutil
-from typing import Any
+from typing import Any, Literal
 
 import click
 from crewai_core.project import (
@@ -44,15 +44,21 @@ __all__ = [
     "render_template",
     "tree_copy",
     "tree_find_and_replace",
-    "warn_deprecated_command",
+    "warn_deprecated",
     "write_env_file",
 ]
 
 
-def warn_deprecated_command(*, old: str, new: str) -> None:
-    """Print a yellow deprecation warning for a legacy CLI command path."""
+def warn_deprecated(
+    *,
+    kind: Literal["command", "flag"],
+    old: str,
+    new: str,
+) -> None:
+    """Print a yellow deprecation warning for a legacy CLI command or flag."""
+    label = "command" if kind == "command" else "flag"
     click.secho(
-        f"Warning: The command '{old}' is deprecated. Use '{new}' instead.",
+        f"Warning: The {label} '{old}' is deprecated. Use '{new}' instead.",
         fg="yellow",
     )