From 70982797c7d0b4a28bb10e48c6e1130db331bd95 Mon Sep 17 00:00:00 2001 From: ViditOstwal Date: Sun, 9 Aug 2026 13:08:47 +0530 Subject: [PATCH] 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. --- docs/edge/ar/concepts/cli.mdx | 16 ++++++-- docs/edge/ar/concepts/testing.mdx | 7 +++- docs/edge/en/concepts/cli.mdx | 16 ++++++-- docs/edge/en/concepts/testing.mdx | 7 +++- docs/edge/ko/concepts/cli.mdx | 16 ++++++-- docs/edge/ko/concepts/testing.mdx | 7 +++- docs/edge/pt-BR/concepts/cli.mdx | 16 ++++++-- docs/edge/pt-BR/concepts/testing.mdx | 7 +++- lib/cli/src/crewai_cli/cli.py | 44 ++++++++++++++++++++-- lib/cli/src/crewai_cli/templates/AGENTS.md | 12 +++++- lib/cli/tests/test_cli.py | 26 +++++++++++-- 11 files changed, 148 insertions(+), 26 deletions(-) diff --git a/docs/edge/ar/concepts/cli.mdx b/docs/edge/ar/concepts/cli.mdx index e89829eb9..e20c7232d 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 061dc7fb3..fabec804d 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 ``` + + العلم القديم `--n_iterations` لا يزال يعمل، لكنه مهمل ومخفي من `--help`. + استخدم `--n-iterations` (أو `-n`) بدلاً من ذلك. + + عند تشغيل أمر `crewai test`، سيتم تنفيذ الطاقم للعدد المحدد من التكرارات، وستُعرض مقاييس الأداء في نهاية التشغيل. سيظهر جدول الدرجات في النهاية لعرض أداء الطاقم من حيث المقاييس التالية: diff --git a/docs/edge/en/concepts/cli.mdx b/docs/edge/en/concepts/cli.mdx index a6825c6ba..aa02e4a6b 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 dbac110b4..3f44509d6 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 ``` + + The older `--n_iterations` flag still works but is deprecated and hidden from + `--help`. Use `--n-iterations` (or `-n`) instead. + + 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 9a10eb147..7a681937f 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 671143d9a..b86bf411f 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 ``` + + 이전 `--n_iterations` 플래그는 여전히 동작하지만 사용 중단되었으며 `--help`에는 + 표시되지 않습니다. 대신 `--n-iterations`(또는 `-n`)를 사용하세요. + + `crewai test` 명령어를 실행하면 crew가 지정한 횟수만큼 실행되고, 수행이 끝나면 성능 지표가 표시됩니다. 실행 마지막에 표시되는 점수 표는 다음과 같은 지표로 crew의 성능을 보여줍니다: diff --git a/docs/edge/pt-BR/concepts/cli.mdx b/docs/edge/pt-BR/concepts/cli.mdx index 1d8140648..7577e3408 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 8277757e0..838ff5b58 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 ``` + + A flag antiga `--n_iterations` ainda funciona, mas está obsoleta e oculta no + `--help`. Use `--n-iterations` (ou `-n`) em vez disso. + + 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 b08e5ac24..dd95b7338 100644 --- a/lib/cli/src/crewai_cli/cli.py +++ b/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", diff --git a/lib/cli/src/crewai_cli/templates/AGENTS.md b/lib/cli/src/crewai_cli/templates/AGENTS.md index f79784896..2abd189cb 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 ` → ✅ `crewai create skill ` - ⚠️ `crewai template add ` → ✅ `crewai create template ` +### 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 --skip_provider # New crew project +crewai create crew --skip-provider # New crew project crewai create flow # New flow project crewai create tool # Custom tool repository crewai create skill # 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/tests/test_cli.py b/lib/cli/tests/test_cli.py index 438196ebb..9f55e28dc 100644 --- a/lib/cli/tests/test_cli.py +++ b/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 )