CLI¶
개념¶
CrewAI는 파이썬 라이브러리로 쓰는 게 보통이지만, 프로젝트를 만들고 훈련시키고 실행하고 관리하는 일을 명령줄에서 처리하고 싶을 때가 있어요. 그런 작업을 전담하는 게 CrewAI CLI죠. CLI는 crew와 flow를 생성(create), 훈련(train), 실행(run), 관리(manage)하는 명령어 묶음을 제공합니다.
설치¶
CLI를 쓰려면 우선 CrewAI가 설치되어 있어야 해요.
기본 사용법¶
CrewAI CLI 명령어의 기본 구조는 다음과 같습니다.
제공되는 명령어¶
1. Create — 프로젝트 생성¶
새 crew나 flow를 만듭니다.
TYPE:"crew"또는"flow"중 선택NAME: crew나 flow의 이름
예시:
기본적으로 crewai create crew는 JSON 우선 프로젝트를 만들며, crew.jsonc와 agents/*.jsonc를 생성합니다. 좀 더 오래된 Python/YAML 스캐폴드(crew.py, config/agents.yaml, config/tasks.yaml)가 필요하다면 crewai create crew my_new_crew --classic처럼 --classic을 붙이면 돼요.
2. Version — 버전 확인¶
설치된 CrewAI의 버전을 보여줍니다.
--tools: (선택) CrewAI tools의 설치 버전도 보여줌
예시:
3. Train — 훈련¶
크루를 지정한 반복 횟수만큼 훈련시킵니다.
-n, --n_iterations INTEGER: 훈련 반복 횟수 (기본값: 5)-f, --filename TEXT: 훈련에 쓸 커스텀 파일 경로 (기본값:"trained_agents_data.pkl")
예시:
4. Replay — 특정 태스크부터 재실행¶
특정 태스크부터 크루 실행을 다시 재생합니다.
-t, --task_id TEXT: 이 task ID부터, 이후의 모든 태스크를 포함해 재생
예시:
5. Log-tasks-outputs — 태스크 출력 조회¶
가장 최근 crew.kickoff()의 태스크 출력을 가져옵니다.
6. Reset-memories — 메모리 초기화¶
크루의 메모리(long, short, entity, latest_crew_kickoff_outputs)를 초기화합니다.
-l, --long: LONG TERM 메모리 초기화-s, --short: SHORT TERM 메모리 초기화-e, --entities: ENTITIES 메모리 초기화-k, --kickoff-outputs: LATEST KICKOFF TASK OUTPUTS 초기화-kn, --knowledge: KNOWLEDGE 저장소 초기화-akn, --agent-knowledge: AGENT KNOWLEDGE 저장소 초기화-a, --all: 모든 메모리 초기화
예시:
7. Test — 테스트¶
크루를 테스트하고 결과를 평가합니다.
-n, --n_iterations INTEGER: 테스트 반복 횟수 (기본값: 3)-m, --model TEXT: 크루 테스트에 쓸 LLM 모델 (기본값:"gpt-4o-mini")
예시:
8. Run — 실행¶
크루나 flow를 실행합니다.
9. Chat — 대화형 세션¶
버전 0.98.0부터, crewai chat 명령어를 실행하면 크루와 인터랙티브한 세션이 시작됩니다. AI 어시스턴트가 크루를 실행하는 데 필요한 입력을 요청하며 안내하고, 입력이 모두 준비되면 크루가 태스크를 실행해요. 결과를 받은 뒤에도 어시스턴트와 계속 대화하며 추가 지시나 질문을 이어갈 수 있습니다.
10. Deploy — 배포¶
크루나 flow를 CrewAI AMP에 배포합니다.
- 인증: CrewAI AMP에 배포하려면 인증이 필요해요. 다음으로 로그인하거나 계정을 만들 수 있습니다.
- 배포 생성: 인증이 끝나면 로컬 프로젝트 루트에서 crew나 flow의 배포를 생성할 수 있어요.
- 로컬 프로젝트 구성을 읽습니다.
- 로컬에서 발견한 환경 변수(예:
OPENAI_API_KEY,SERPER_API_KEY)를 확인하라고 안내합니다. 이 키는 Enterprise 플랫폼의 배포와 함께 안전하게 저장되므로, 실행 전에 민감한 키가 로컬에(예:.env파일) 올바르게 설정되어 있는지 확인하세요. - 배포를 해당 원격 GitHub 리포지토리와 연결합니다(보통 자동으로 감지돼요).
- 배포 실행: 인증이 끝나면 crew나 flow를 CrewAI AMP에 배포할 수 있어요.
- CrewAI AMP 플랫폼에서 배포 프로세스를 시작합니다.
- 성공적으로 시작되면
Deployment created successfully!메시지와 함께 Deployment Name과 고유한 Deployment ID(UUID)가 출력됩니다. - 배포 상태: 최근 배포 시도의 현재 상태를 확인할 수 있어요.
가장 최근 배포 시도의 상태(예:
Building Images for Crew,Deploy Enqueued,Online)를 가져옵니다. - 배포 로그: 배포 로그를 확인할 수 있어요. 배포 로그를 터미널로 스트리밍합니다.
- 배포 목록: 모든 배포를 나열합니다.
- 배포 삭제: CrewAI AMP 플랫폼에서 해당 배포를 삭제합니다.
- 도움말: CrewAI Deploy CLI의 도움말 메시지를 보여줍니다.
11. Login — 로그인¶
이메일 입력 없이 보안 디바이스 코드 흐름을 통해 CrewAI AMP에 인증합니다.
동작 흐름:
- 터미널에 인증 URL과 짧은 코드가 표시됩니다.
- 브라우저가 해당 인증 URL로 열립니다.
- 코드를 입력/확인하면 인증이 완료됩니다.
참고:
- OAuth2 프로바이더와 도메인은
crewai config로 설정합니다(기본값은login.crewai.com). - 로그인 성공 후 CLI는 Tool Repository에도 자동으로 인증을 시도합니다.
- 구성을 리셋한 경우
crewai login을 다시 실행해 재인증하세요.
12. API Keys — API 키 설정¶
crewai create crew 명령어를 실행하면 CLI가 사용 가능한 LLM 프로바이더 목록을 보여주고, 선택한 프로바이더에 맞는 모델을 고르도록 안내합니다. 선택한 모델은 생성된 .env 파일에 저장되고, 생성된 각 agent JSONC 파일에서 자체 llm을 설정할 수 있어요. LLM 프로바이더와 모델을 선택하면 API 키 입력을 요청합니다.
사용 가능한 LLM 프로바이더¶
CLI가 추천하는 가장 인기 있는 LLM 프로바이더 목록이에요:
- OpenAI
- Groq
- Anthropic
- Google Gemini
- SambaNova
프로바이더를 선택하면 해당 프로바이더의 사용 가능한 모델을 보여주고 API 키 입력을 요청합니다.
기타 옵션¶
"other"를 선택하면 LiteLLM이 지원하는 프로바이더 목록에서 선택할 수 있어요. 프로바이더를 선택하면 CLI가 Key 이름과 API 키를 입력하도록 안내합니다. 각 프로바이더의 키 이름은 다음 링크에서 확인하세요:
13. Config — 설정 관리¶
CrewAI의 CLI 설정을 관리합니다.
명령어:¶
list: 모든 CLI 설정 파라미터 표시set: CLI 설정 파라미터 설정reset: 모든 CLI 설정 파라미터를 기본값으로 초기화
사용 가능한 설정 파라미터¶
enterprise_base_url: CrewAI AMP 인스턴스의 Base URLoauth2_provider: 인증에 쓰는 OAuth2 프로바이더 (예: workos, okta, auth0)oauth2_audience: 대상 API/리소스를 식별하는 데 쓰는 OAuth2 audience 값oauth2_client_id: 인증 요청 중 사용되는 OAuth2 클라이언트 IDoauth2_domain: 토큰 발급에 쓰는 OAuth2 프로바이더 도메인 (예: your-org.auth0.com)
예시¶
현재 설정 표시:
예시 출력:
| Setting | Value | Description |
|---|---|---|
| enterprise_base_url | https://app.crewai.com | Base URL of the CrewAI AMP instance |
| org_name | Not set | Name of the currently active organization |
| org_uuid | Not set | UUID of the currently active organization |
| oauth2_provider | workos | OAuth2 provider (e.g., workos, okta, auth0) |
| oauth2_audience | client_01YYY | Audience identifying the target API/resource |
| oauth2_client_id | client_01XXX | OAuth2 client ID issued by the provider |
| oauth2_domain | login.crewai.com | Provider domain (e.g., your-org.auth0.com) |
enterprise base URL 설정:
OAuth2 프로바이더 설정:
OAuth2 도메인 설정:
모든 설정을 기본값으로 초기화:
14. Traces — 트레이스 관리¶
Crew와 Flow 실행의 트레이스 수집 설정을 관리합니다.
명령어:¶
enable: crew/flow 실행의 트레이스 수집 활성화disable: crew/flow 실행의 트레이스 수집 비활성화status: 현재 트레이스 수집 상태 표시
트레이싱 동작 방식¶
트레이스 수집은 우선순위 순서로 세 가지 설정을 확인해 제어됩니다.
- 코드의 명시적 플래그 (최우선 — 활성화와 비활성화 모두 가능):
tracing=True는 항상 활성화합니다(그 외 모든 것을 덮어씀).tracing=False는 항상 비활성화합니다(그 외 모든 것을 덮어씀).tracing=None또는 생략하면 낮은 우선순위 설정을 확인합니다.- 환경 변수 (두 번째 우선순위):
- 코드에서
tracing이True나False로 명시되지 않았을 때만 확인합니다. - 트레이스를 활성화하려면
true나1로 설정합니다. - 사용자 선호 (최저 우선순위):
- 코드에
tracing이 설정되지 않고CREWAI_TRACING_ENABLED가true로 설정되지 않았을 때만 확인합니다. crewai traces enable를 실행하는 것만으로 트레이스가 활성화됩니다.
실무 관점¶
- 프로젝트를 새로 시작한다면 기본 JSON 우선 스캐폴드(
crew.jsonc+agents/*.jsonc)를 쓰는 게 최신 권장 방식이에요. 예전 Python/YAML 스캐폴드가 꼭 필요할 때만--classic을 쓰는 게 좋습니다. - 훈련 반복 횟수와 테스트 반복 횟수는 서로 다르게 기본값이 잡혀 있어요. 훈련은 기본 5회, 테스트는 기본 3회, 테스트 모델 기본값은
gpt-4o-mini. 명령어마다 기본값이 다르니 헷갈리지 않게 확인하는 게 좋습니다. - 배포 전에 민감한 키부터 챙기세요.
crewai deploy create는 로컬에서 발견한 환경 변수(예:OPENAI_API_KEY)를 확인하며 안내하고, 이를 배포와 함께 안전하게 저장합니다. 실행 전에.env등에 키가 올바르게 설정되어 있는지 확인해야 해요. - 트레이스는 우선순위가 명확해요. 코드의
tracing플래그 →CREWAI_TRACING_ENABLED환경 변수 →crewai traces enable사용자 설정 순으로 확인됩니다. 코드에서 명시적으로tracing=True를 주면 그보다 낮은 설정은 모두 무시되죠. 어디서 켜졌는지 헷갈릴 때는crewai traces status로 현재 상태를 확인하면 됩니다.
더 알아보기¶
- CrewAI AMP — 배포 플랫폼
- LiteLLM Providers — 기타 LLM 프로바이더의 키 이름 확인