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.

lib/cli/src/crewai_cli/cli.py

@@ -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",
+    "skip_provider",
+    is_flag=True,
+    hidden=True,
+    help="[Deprecated: use --skip-provider] Skip provider validation",
+)
 @click.option(
     "--classic",
     is_flag=True,
@@ -288,11 +300,19 @@ 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",
+    "n_iterations",
+    type=int,
+    hidden=True,
+    help="[Deprecated: use --n-iterations]",
+)
 @click.option(
     "-f",
     "--filename",
@@ -309,10 +329,18 @@ 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",
+    "task_id",
+    type=str,
+    hidden=True,
+    help="[Deprecated: use --task-id]",
+)
 @click.option(
     "-f",
     "--filename",
@@ -504,11 +532,19 @@ 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",
+    "n_iterations",
+    type=int,
+    hidden=True,
+    help="[Deprecated: use --n-iterations]",
+)
 @click.option(
     "-m",
     "--model",

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/tests/test_cli.py

@@ -38,6 +38,15 @@ def test_train_default_iterations(train_crew, runner):
 
 @mock.patch("crewai_cli.cli.train_crew")
 def test_train_custom_iterations(train_crew, runner):
+    result = runner.invoke(train, ["--n-iterations", "10"])
+
+    train_crew.assert_called_once_with(10, "trained_agents_data.pkl")
+    assert result.exit_code == 0
+    assert "Training the Crew for 10 iterations" in result.output
+
+
+@mock.patch("crewai_cli.cli.train_crew")
+def test_train_custom_iterations_snake_case_alias(train_crew, runner):
     result = runner.invoke(train, ["--n_iterations", "10"])
 
     train_crew.assert_called_once_with(10, "trained_agents_data.pkl")
@@ -47,12 +56,12 @@ def test_train_custom_iterations(train_crew, runner):
 
 @mock.patch("crewai_cli.cli.train_crew")
 def test_train_invalid_string_iterations(train_crew, runner):
-    result = runner.invoke(train, ["--n_iterations", "invalid"])
+    result = runner.invoke(train, ["--n-iterations", "invalid"])
 
     train_crew.assert_not_called()
     assert result.exit_code == 2
     assert (
-        "Usage: train [OPTIONS]\nTry 'train --help' for help.\n\nError: Invalid value for '-n' / '--n_iterations': 'invalid' is not a valid integer.\n"
+        "Usage: train [OPTIONS]\nTry 'train --help' for help.\n\nError: Invalid value for '-n' / '--n-iterations': 'invalid' is not a valid integer.\n"
         in result.output
     )
 
@@ -103,6 +112,15 @@ def test_test_default_iterations(evaluate_crew, runner):
 
 @mock.patch("crewai_cli.cli.evaluate_crew")
 def test_test_custom_iterations(evaluate_crew, runner):
+    result = runner.invoke(test, ["--n-iterations", "5", "--model", "gpt-4o"])
+
+    evaluate_crew.assert_called_once_with(5, "gpt-4o", trained_agents_file=None)
+    assert result.exit_code == 0
+    assert "Testing the crew for 5 iterations with model gpt-4o" in result.output
+
+
+@mock.patch("crewai_cli.cli.evaluate_crew")
+def test_test_custom_iterations_snake_case_alias(evaluate_crew, runner):
     result = runner.invoke(test, ["--n_iterations", "5", "--model", "gpt-4o"])
 
     evaluate_crew.assert_called_once_with(5, "gpt-4o", trained_agents_file=None)
@@ -112,12 +130,12 @@ def test_test_custom_iterations(evaluate_crew, runner):
 
 @mock.patch("crewai_cli.cli.evaluate_crew")
 def test_test_invalid_string_iterations(evaluate_crew, runner):
-    result = runner.invoke(test, ["--n_iterations", "invalid"])
+    result = runner.invoke(test, ["--n-iterations", "invalid"])
 
     evaluate_crew.assert_not_called()
     assert result.exit_code == 2
     assert (
-        "Usage: test [OPTIONS]\nTry 'test --help' for help.\n\nError: Invalid value for '-n' / '--n_iterations': 'invalid' is not a valid integer.\n"
+        "Usage: test [OPTIONS]\nTry 'test --help' for help.\n\nError: Invalid value for '-n' / '--n-iterations': 'invalid' is not a valid integer.\n"
         in result.output
     )