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".

docs/edge/ar/concepts/cli.mdx

@@ -54,6 +54,16 @@ crewai create flow my_new_flow
 
 افتراضيًا، ينشئ `crewai create crew` مشروعًا JSON-first يحتوي على `crew.jsonc` و `agents/*.jsonc`. استخدم `crewai create crew my_new_crew --classic` فقط إذا أردت البنية القديمة Python/YAML مع `crew.py` و `config/agents.yaml` و `config/tasks.yaml`.
 
+#### أسماء مستعار قديمة للأعلام (مهملة)
+
+لا تزال أعلام snake_case القديمة تعمل، لكنها مخفية من `--help`. يُفضّل استخدام صيغ kebab-case الموثّقة في أقسام الأوامر أدناه.
+
+| مهمل | استخدم بدلاً منه |
+| :--- | :--- |
+| `--skip_provider` (في `crewai create crew`) | `--skip-provider` |
+| `--n_iterations` (في `crewai train`، `crewai test`) | `--n-iterations` |
+| `--task_id` (في `crewai replay`) | `--task-id` |
+
 ### 2. الإصدار
 
 عرض الإصدار المثبت من CrewAI.
@@ -72,7 +82,7 @@ crewai version [OPTIONS]
 crewai train [OPTIONS]
 ```
 
-- `-n, --n_iterations INTEGER`: عدد تكرارات التدريب (افتراضي: 5)
+- `-n, --n-iterations INTEGER`: عدد تكرارات التدريب (افتراضي: 5)
 - `-f, --filename TEXT`: مسار ملف مخصص للتدريب (افتراضي: "trained_agents_data.pkl")
 
 ### 4. الإعادة
@@ -83,7 +93,7 @@ crewai train [OPTIONS]
 crewai replay [OPTIONS]
 ```
 
-- `-t, --task_id TEXT`: إعادة تنفيذ الطاقم من معرّف المهمة هذا، بما في ذلك جميع المهام اللاحقة
+- `-t, --task-id TEXT`: إعادة تنفيذ الطاقم من معرّف المهمة هذا، بما في ذلك جميع المهام اللاحقة
 
 ### 5. سجل مخرجات المهام
 
@@ -117,7 +127,7 @@ crewai reset-memories [OPTIONS]
 crewai test [OPTIONS]
 ```
 
-- `-n, --n_iterations INTEGER`: عدد تكرارات الاختبار (افتراضي: 3)
+- `-n, --n-iterations INTEGER`: عدد تكرارات الاختبار (افتراضي: 3)
 - `-m, --model TEXT`: نموذج LLM لتشغيل الاختبارات (افتراضي: "gpt-4o-mini")
 
 ### 8. التشغيل

docs/edge/ar/concepts/testing.mdx

@@ -20,7 +20,7 @@ crewai test
 إذا أردت تشغيل المزيد من التكرارات أو استخدام نموذج مختلف، يمكنك تحديد المعاملات هكذا:
 
 ```bash
-crewai test --n_iterations 5 --model gpt-4o
+crewai test --n-iterations 5 --model gpt-4o
 ```
 
 أو باستخدام الصيغة المختصرة:
@@ -29,6 +29,11 @@ crewai test --n_iterations 5 --model gpt-4o
 crewai test -n 5 -m gpt-4o
 ```
 
+<Note>
+  العلم القديم `--n_iterations` لا يزال يعمل، لكنه مهمل ومخفي من `--help`.
+  استخدم `--n-iterations` (أو `-n`) بدلاً من ذلك.
+</Note>
+
 عند تشغيل أمر `crewai test`، سيتم تنفيذ الطاقم للعدد المحدد من التكرارات، وستُعرض مقاييس الأداء في نهاية التشغيل.
 
 سيظهر جدول الدرجات في النهاية لعرض أداء الطاقم من حيث المقاييس التالية:

docs/edge/en/concepts/cli.mdx

@@ -103,6 +103,16 @@ These older commands still work but print a yellow deprecation warning. Prefer t
 
 Lifecycle commands are unchanged — for example `crewai tool install`, `crewai skill publish`, and `crewai template list` stay under their resource groups.
 
+#### Deprecated flag aliases
+
+These older snake_case flags still work but are hidden from `--help`. Prefer the kebab-case forms documented in each command section below.
+
+| Deprecated | Use instead |
+| :--- | :--- |
+| `--skip_provider` (on `crewai create crew`) | `--skip-provider` |
+| `--n_iterations` (on `crewai train`, `crewai test`) | `--n-iterations` |
+| `--task_id` (on `crewai replay`) | `--task-id` |
+
 ### 2. Version
 
 Show the installed version of CrewAI.
@@ -128,7 +138,7 @@ Train the crew for a specified number of iterations.
 crewai train [OPTIONS]
 ```
 
-- `-n, --n_iterations INTEGER`: Number of iterations to train the crew (default: 5)
+- `-n, --n-iterations INTEGER`: Number of iterations to train the crew (default: 5)
 - `-f, --filename TEXT`: Path to a custom file for training (default: "trained_agents_data.pkl")
 
 Example:
@@ -145,7 +155,7 @@ Replay the crew execution from a specific task.
 crewai replay [OPTIONS]
 ```
 
-- `-t, --task_id TEXT`: Replay the crew from this task ID, including all subsequent tasks
+- `-t, --task-id TEXT`: Replay the crew from this task ID, including all subsequent tasks
 
 Example:
 
@@ -192,7 +202,7 @@ Test the crew and evaluate the results.
 crewai test [OPTIONS]
 ```
 
-- `-n, --n_iterations INTEGER`: Number of iterations to test the crew (default: 3)
+- `-n, --n-iterations INTEGER`: Number of iterations to test the crew (default: 3)
 - `-m, --model TEXT`: LLM Model to run the tests on the Crew (default: "gpt-4o-mini")
 
 Example:

docs/edge/en/concepts/testing.mdx

@@ -20,7 +20,7 @@ crewai test
 If you want to run more iterations or use a different model, you can specify the parameters like this:
 
 ```bash
-crewai test --n_iterations 5 --model gpt-4o
+crewai test --n-iterations 5 --model gpt-4o
 ```
 
 or using the short forms:
@@ -29,6 +29,11 @@ or using the short forms:
 crewai test -n 5 -m gpt-4o
 ```
 
+<Note>
+  The older `--n_iterations` flag still works but is deprecated and hidden from
+  `--help`. Use `--n-iterations` (or `-n`) instead.
+</Note>
+
 When you run the `crewai test` command, the crew will be executed for the specified number of iterations, and the performance metrics will be displayed at the end of the run.
 
 A table of scores at the end will show the performance of the crew in terms of the following metrics:

docs/edge/ko/concepts/cli.mdx

@@ -54,6 +54,16 @@ crewai create flow my_new_flow
 
 기본적으로 `crewai create crew`는 `crew.jsonc`와 `agents/*.jsonc`가 있는 JSON-first 프로젝트를 만듭니다. `crew.py`, `config/agents.yaml`, `config/tasks.yaml`을 사용하는 기존 Python/YAML 스캐폴드가 필요할 때만 `crewai create crew my_new_crew --classic`을 사용하세요.
 
+#### 사용 중단된 플래그 별칭
+
+이전 snake_case 플래그는 여전히 동작하지만 `--help`에는 표시되지 않습니다. 아래 각 명령 섹션에 문서화된 kebab-case 형식을 사용하세요.
+
+| 사용 중단 | 대신 사용 |
+| :--- | :--- |
+| `--skip_provider` (`crewai create crew`) | `--skip-provider` |
+| `--n_iterations` (`crewai train`, `crewai test`) | `--n-iterations` |
+| `--task_id` (`crewai replay`) | `--task-id` |
+
 ### 2. 버전
 
 설치된 CrewAI의 버전을 표시합니다.
@@ -79,7 +89,7 @@ crewai version --tools
 crewai train [OPTIONS]
 ```
 
-- `-n, --n_iterations INTEGER`: crew를 훈련할 반복 횟수 (기본값: 5)
+- `-n, --n-iterations INTEGER`: crew를 훈련할 반복 횟수 (기본값: 5)
 - `-f, --filename TEXT`: 훈련에 사용할 커스텀 파일의 경로 (기본값: "trained_agents_data.pkl")
 
 예시:
@@ -96,7 +106,7 @@ crewai train -n 10 -f my_training_data.pkl
 crewai replay [OPTIONS]
 ```
 
-- `-t, --task_id TEXT`: 이 task ID에서부터 crew를 다시 재생하며, 이후의 모든 task를 포함합니다.
+- `-t, --task-id TEXT`: 이 task ID에서부터 crew를 다시 재생하며, 이후의 모든 task를 포함합니다.
 
 예시:
 
@@ -143,7 +153,7 @@ crew를 테스트하고 결과를 평가합니다.
 crewai test [OPTIONS]
 ```
 
-- `-n, --n_iterations INTEGER`: crew를 테스트할 반복 횟수 (기본값: 3)
+- `-n, --n-iterations INTEGER`: crew를 테스트할 반복 횟수 (기본값: 3)
 - `-m, --model TEXT`: Crew에서 테스트를 실행할 LLM 모델 (기본값: "gpt-4o-mini")
 
 예시:

docs/edge/ko/concepts/testing.mdx

@@ -20,7 +20,7 @@ crewai test
 더 많은 반복 횟수로 실행하거나 다른 모델을 사용하려면 다음과 같이 매개변수를 지정할 수 있습니다:
 
 ```bash
-crewai test --n_iterations 5 --model gpt-4o
+crewai test --n-iterations 5 --model gpt-4o
 ```
 
 또는 축약형을 사용할 수 있습니다:
@@ -29,6 +29,11 @@ crewai test --n_iterations 5 --model gpt-4o
 crewai test -n 5 -m gpt-4o
 ```
 
+<Note>
+  이전 `--n_iterations` 플래그는 여전히 동작하지만 사용 중단되었으며 `--help`에는
+  표시되지 않습니다. 대신 `--n-iterations`(또는 `-n`)를 사용하세요.
+</Note>
+
 `crewai test` 명령어를 실행하면 crew가 지정한 횟수만큼 실행되고, 수행이 끝나면 성능 지표가 표시됩니다.
 
 실행 마지막에 표시되는 점수 표는 다음과 같은 지표로 crew의 성능을 보여줍니다:

docs/edge/pt-BR/concepts/cli.mdx

@@ -55,6 +55,16 @@ crewai create flow my_new_flow
 
 Por padrão, `crewai create crew` cria um projeto JSON-first com `crew.jsonc` e `agents/*.jsonc`. Use `crewai create crew my_new_crew --classic` somente quando quiser o scaffold antigo em Python/YAML com `crew.py`, `config/agents.yaml` e `config/tasks.yaml`.
 
+#### Aliases de flags obsoletas
+
+As flags antigas em snake_case ainda funcionam, mas ficam ocultas no `--help`. Prefira as formas em kebab-case documentadas em cada seção de comando abaixo.
+
+| Obsoleto | Use em vez disso |
+| :--- | :--- |
+| `--skip_provider` (em `crewai create crew`) | `--skip-provider` |
+| `--n_iterations` (em `crewai train`, `crewai test`) | `--n-iterations` |
+| `--task_id` (em `crewai replay`) | `--task-id` |
+
 ### 2. Version
 
 Mostre a versão instalada do CrewAI.
@@ -80,7 +90,7 @@ Treine o crew por um número específico de iterações.
 crewai train [OPTIONS]
 ```
 
-- `-n, --n_iterations INTEGER`: Número de iterações para treinar o crew (padrão: 5)
+- `-n, --n-iterations INTEGER`: Número de iterações para treinar o crew (padrão: 5)
 - `-f, --filename TEXT`: Caminho para um arquivo customizado para treinamento (padrão: "trained_agents_data.pkl")
 
 Exemplo:
@@ -113,7 +123,7 @@ Reexecute a execução do crew a partir de uma tarefa específica.
 crewai replay [OPTIONS]
 ```
 
-- `-t, --task_id TEXT`: Reexecuta o crew a partir deste task ID, incluindo todas as tarefas subsequentes
+- `-t, --task-id TEXT`: Reexecuta o crew a partir deste task ID, incluindo todas as tarefas subsequentes
 
 Exemplo:
 
@@ -160,7 +170,7 @@ Teste o crew e avalie os resultados.
 crewai test [OPTIONS]
 ```
 
-- `-n, --n_iterations INTEGER`: Número de iterações para testar o crew (padrão: 3)
+- `-n, --n-iterations INTEGER`: Número de iterações para testar o crew (padrão: 3)
 - `-m, --model TEXT`: Modelo LLM para executar os testes no Crew (padrão: "gpt-4o-mini")
 
 Exemplo:

docs/edge/pt-BR/concepts/testing.mdx

@@ -20,7 +20,7 @@ crewai test
 Se quiser rodar mais iterações ou utilizar um modelo diferente, você pode especificar os parâmetros assim:
 
 ```bash
-crewai test --n_iterations 5 --model gpt-4o
+crewai test --n-iterations 5 --model gpt-4o
 ```
 
 ou usando as formas abreviadas:
@@ -29,6 +29,11 @@ ou usando as formas abreviadas:
 crewai test -n 5 -m gpt-4o
 ```
 
+<Note>
+  A flag antiga `--n_iterations` ainda funciona, mas está obsoleta e oculta no
+  `--help`. Use `--n-iterations` (ou `-n`) em vez disso.
+</Note>
+
 Ao executar o comando `crewai test`, a crew será executada pelo número especificado de iterações, e as métricas de desempenho serão exibidas ao final da execução.
 
 Uma tabela de pontuações ao final mostrará o desempenho da crew em relação às seguintes métricas:

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",
     )
 

lib/cli/tests/test_cli.py

@@ -14,6 +14,7 @@ from crewai_cli.cli import (
     flow_add_crew,
     flow_run,
     login,
+    replay,
     reset_memories,
     run,
     test,
@@ -38,21 +39,34 @@ 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"])
+    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")
+    assert result.exit_code == 0
+    assert "Training the Crew for 10 iterations" in result.output
+    assert (
+        "Warning: The flag '--n_iterations' is deprecated. Use '--n-iterations' instead."
+        in result.output
+    )
+
+
 @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,25 +117,121 @@ 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"])
+    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)
+    assert result.exit_code == 0
+    assert "Testing the crew for 5 iterations with model gpt-4o" in result.output
+    assert (
+        "Warning: The flag '--n_iterations' is deprecated. Use '--n-iterations' instead."
+        in result.output
+    )
+
+
 @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
     )
 
 
+def test_train_help_hides_legacy_flag_aliases(runner):
+    result = runner.invoke(train, ["--help"])
+
+    assert result.exit_code == 0
+    assert "--n-iterations" in result.output
+    assert "--n_iterations" not in result.output
+
+
+def test_test_help_hides_legacy_flag_aliases(runner):
+    result = runner.invoke(test, ["--help"])
+
+    assert result.exit_code == 0
+    assert "--n-iterations" in result.output
+    assert "--n_iterations" not in result.output
+
+
+def test_create_help_hides_legacy_flag_aliases(runner):
+    result = runner.invoke(create, ["--help"])
+
+    assert result.exit_code == 0
+    assert "--skip-provider" in result.output
+    assert "--skip_provider" not in result.output
+
+
+def test_replay_help_hides_legacy_flag_aliases(runner):
+    result = runner.invoke(replay, ["--help"])
+
+    assert result.exit_code == 0
+    assert "--task-id" in result.output
+    assert "--task_id" not in result.output
+
+
+@mock.patch("crewai_cli.create_json_crew.create_json_crew")
+def test_create_skip_provider_flag(create_json_crew, runner):
+    result = runner.invoke(create, ["crew", "my-crew", "--skip-provider"])
+
+    assert result.exit_code == 0, result.output
+    create_json_crew.assert_called_once_with("my-crew", None, True)
+    assert "deprecated" not in result.output.lower()
+
+
+@mock.patch("crewai_cli.create_json_crew.create_json_crew")
+def test_create_skip_provider_snake_case_alias_warns(create_json_crew, runner):
+    result = runner.invoke(create, ["crew", "my-crew", "--skip_provider"])
+
+    assert result.exit_code == 0, result.output
+    create_json_crew.assert_called_once_with("my-crew", None, True)
+    assert (
+        "Warning: The flag '--skip_provider' is deprecated. Use '--skip-provider' instead."
+        in result.output
+    )
+
+
+@mock.patch("crewai_cli.cli.replay_task_command")
+def test_replay_task_id_flag(replay_task_command, runner):
+    result = runner.invoke(replay, ["--task-id", "task_123"])
+
+    assert result.exit_code == 0, result.output
+    replay_task_command.assert_called_once_with("task_123", trained_agents_file=None)
+    assert "Replaying the crew from task task_123" in result.output
+
+
+@mock.patch("crewai_cli.cli.replay_task_command")
+def test_replay_task_id_snake_case_alias_warns(replay_task_command, runner):
+    result = runner.invoke(replay, ["--task_id", "task_123"])
+
+    assert result.exit_code == 0, result.output
+    replay_task_command.assert_called_once_with("task_123", trained_agents_file=None)
+    assert (
+        "Warning: The flag '--task_id' is deprecated. Use '--task-id' instead."
+        in result.output
+    )
+
+
+@mock.patch("crewai_cli.cli.replay_task_command")
+def test_replay_without_task_id(replay_task_command, runner):
+    result = runner.invoke(replay)
+
+    assert result.exit_code == 0, result.output
+    replay_task_command.assert_called_once_with(None, trained_agents_file=None)
+    assert "Replaying the crew from task None" in result.output
+
+
 @mock.patch("crewai_cli.cli.run_crew")
 def test_run_uses_project_runner_by_default(run_crew, runner):
     result = runner.invoke(run)