diff --git a/docs/edge/ar/concepts/cli.mdx b/docs/edge/ar/concepts/cli.mdx
index e89829eb9d..e20c7232d8 100644
--- a/docs/edge/ar/concepts/cli.mdx
+++ b/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. التشغيل
diff --git a/docs/edge/ar/concepts/testing.mdx b/docs/edge/ar/concepts/testing.mdx
index 061dc7fb37..fabec804d3 100644
--- a/docs/edge/ar/concepts/testing.mdx
+++ b/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`، سيتم تنفيذ الطاقم للعدد المحدد من التكرارات، وستُعرض مقاييس الأداء في نهاية التشغيل.
 
 سيظهر جدول الدرجات في النهاية لعرض أداء الطاقم من حيث المقاييس التالية:
diff --git a/docs/edge/en/concepts/cli.mdx b/docs/edge/en/concepts/cli.mdx
index a6825c6baa..aa02e4a6b9 100644
--- a/docs/edge/en/concepts/cli.mdx
+++ b/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:
diff --git a/docs/edge/en/concepts/testing.mdx b/docs/edge/en/concepts/testing.mdx
index dbac110b43..3f44509d64 100644
--- a/docs/edge/en/concepts/testing.mdx
+++ b/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:
diff --git a/docs/edge/ko/concepts/cli.mdx b/docs/edge/ko/concepts/cli.mdx
index 9a10eb147c..7a681937f7 100644
--- a/docs/edge/ko/concepts/cli.mdx
+++ b/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")
 
 예시:
diff --git a/docs/edge/ko/concepts/testing.mdx b/docs/edge/ko/concepts/testing.mdx
index 671143d9a0..b86bf411f2 100644
--- a/docs/edge/ko/concepts/testing.mdx
+++ b/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의 성능을 보여줍니다:
diff --git a/docs/edge/pt-BR/concepts/cli.mdx b/docs/edge/pt-BR/concepts/cli.mdx
index 1d81406484..7577e34081 100644
--- a/docs/edge/pt-BR/concepts/cli.mdx
+++ b/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:
diff --git a/docs/edge/pt-BR/concepts/testing.mdx b/docs/edge/pt-BR/concepts/testing.mdx
index 8277757e06..838ff5b588 100644
--- a/docs/edge/pt-BR/concepts/testing.mdx
+++ b/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:
diff --git a/lib/cli/src/crewai_cli/cli.py b/lib/cli/src/crewai_cli/cli.py
index b08e5ac24e..11a9844bd2 100644
--- a/lib/cli/src/crewai_cli/cli.py
+++ b/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)
 
diff --git a/lib/cli/src/crewai_cli/templates/AGENTS.md b/lib/cli/src/crewai_cli/templates/AGENTS.md
index f797848965..2abd189cb5 100644
--- a/lib/cli/src/crewai_cli/templates/AGENTS.md
+++ b/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
diff --git a/lib/cli/src/crewai_cli/utils.py b/lib/cli/src/crewai_cli/utils.py
index e7517eb686..df77341df6 100644
--- a/lib/cli/src/crewai_cli/utils.py
+++ b/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",
     )
 
diff --git a/lib/cli/tests/test_cli.py b/lib/cli/tests/test_cli.py
index 438196ebb8..6c71e0d08a 100644
--- a/lib/cli/tests/test_cli.py
+++ b/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)