CLI and project layout
Every crewai CLI command verified against source — create, run, train, test, replay, eval, checkpoint, flow, tool, template, skill, memory TUI, deploy, and traces.
Verified against
crewai1.15.41 (source:crewai_cli/cli.py,crewai_cli/create_json_crew.py,crewai_cli/templates/crew/*; checked 2026-11-19). Since the 1.15 line the CLI lives in its owncrewai-clidistribution, installed automatically withcrewai;crewai.clistill imports but emits aDeprecationWarningpointing atcrewai_cli.
The crewai CLI is a Click group. This page is a command-by-command tour grounded in the installed cli.py, so every flag matches reality — not a blog post about an older release.
Minimal runnable example
Section titled “Minimal runnable example”crewai create crew my_research_crew --classic # Python/YAML layout used throughout this guidecd my_research_crewuv sync # or: pip install -e .crewai runcreate scaffolds a project; run invokes the run_crew entry point wired up in pyproject.toml.
JSON-first is now the default. Without
--classic,crewai create crewstarts an interactive wizard (agents, tasks, provider, platform tools) and writes a JSON-first project:crew.jsonc, oneagents/<name>.jsoncper agent, plustools/,skills/andknowledge/.crewai runruns either layout. The Python/YAML@CrewBaselayout below is what you get with--classic, and it is what the rest of this guide’s examples assume.
Installing the CLI
Section titled “Installing the CLI”pip install "crewai[tools]"# oruv tool install crewaicrewai --version or crewai version prints the version (add --tools for crewai-tools).
Command cheat sheet
Section titled “Command cheat sheet”| Command | What it does |
|---|---|
crewai create crew <name> | Scaffold a crew project (interactive JSON wizard; --classic for Python/YAML). |
crewai create flow <name> | Scaffold a flow project (--declarative for a definition-file flow). |
crewai create tool/skill/template <name> | Scaffold a tool, an agent skill, or install a template (-o <dir>). |
crewai run [--inputs JSON] | Run the project — crew or flow, whichever pyproject.toml declares. --inputs '{"topic": "AI"}' passes a JSON object to a flow or a JSON crew; --definition and -f as below. |
crewai install | Sync dependencies (wraps uv). |
crewai update | Convert a Poetry project to uv: rewrites pyproject.toml and keeps the original as pyproject-old.toml. It does not upgrade CrewAI (see Gotchas). |
crewai train -n 5 -f trained.pkl | Kick off main:train: run the crew with human feedback on every task, then distil the feedback (see Training mode). |
crewai test -n 3 -m gpt-6-luna | Kick off main:test (eval; OpenAI models only). |
crewai eval [--no-open] | Grade the last traced run through CrewAI AMP, running the crew first if there is none or the project changed since; --models a,b compares models on a deployment. --no-open prints the report link instead of opening a browser (SSH, CI). crewai eval export ID downloads an evaluation’s full data into ./crewai-eval-ID/. |
crewai replay -t <task_id> | Re-run starting from a specific task. |
crewai log-tasks-outputs | List logged task outputs. |
crewai reset-memories -m -kn -a | Reset memory / knowledge / kickoff outputs. |
crewai memory | Interactive Memory TUI. |
crewai chat | Chat with the crew (uses Crew.chat_llm; see Gotchas). |
crewai checkpoint | TUI browser for saved checkpoints. |
crewai checkpoint list/info/resume/diff/prune | Scripted checkpoint ops. |
crewai flow kickoff | Run the flow (equivalent to crewai run in a flow project). |
crewai flow plot | Render the flow graph to an HTML file and open it in the browser. |
crewai flow add-crew <name> | Embed a crew in the flow. |
crewai triggers list/run <app>/<trigger> | Platform triggers. |
crewai tool install/publish <handle> | Tool Repository (platform). tool create is deprecated in favour of crewai create tool. |
crewai skill list/search/install/publish | Agent skills. list shows local skills; search [QUERY] lists your organisation’s skills on AMP. skill create is deprecated in favour of crewai create skill. |
crewai template list | Browse project templates (template add is deprecated in favour of crewai create template). |
crewai deploy create/list/push/status/logs/remove | CrewAI AMP deployments. |
crewai login / logout | Auth against CrewAI AMP. |
crewai org list/switch/current | Organization context. |
crewai enterprise configure <url> | AMP OAuth2 setup. |
crewai config list/set/reset | Local CLI settings. |
crewai env view | Show tracing env vars. |
crewai traces enable/disable/status | Tracing opt-in. |
crewai uv <args> | Wrapper over uv that injects tool credentials. |
Project layout — crewai create crew --classic
Section titled “Project layout — crewai create crew --classic”my_crew/├── pyproject.toml├── README.md├── AGENTS.md # also CLAUDE.md / CURSOR.md / GEMINI.md for coding assistants├── knowledge/ # file sources given as strings are read from here (starts with user_preference.txt)└── src/my_crew/ ├── __init__.py ├── main.py # entry points: run / train / replay / test ├── crew.py # @CrewBase with @agent / @task / @crew decorators ├── tools/ # custom_tool.py: a BaseTool example └── config/ ├── agents.yaml # agent roles, goals, backstories └── tasks.yaml # task descriptions, expected outputsagents.yaml
Section titled “agents.yaml”researcher: role: > {topic} Senior Data Researcher goal: > Uncover cutting-edge developments in {topic} backstory: > You're a seasoned researcher with a knack for finding relevant sources.Each top-level key is a name referenced from crew.py (self.agents_config["researcher"]). The scaffold also defines a second agent, reporting_analyst, in the same file. The role, goal and backstory text may contain {topic}-style placeholders filled from kickoff(inputs=...).
tasks.yaml
Section titled “tasks.yaml”research_task: description: > Conduct thorough research about {topic} (current year: {current_year}). expected_output: > Ten bullet points of the most relevant findings. agent: researchercrew.py
Section titled “crew.py”from crewai import Agent, Crew, Process, Taskfrom crewai.project import CrewBase, agent, crew, task
@CrewBaseclass MyCrew: """Research + reporting crew."""
@agent def researcher(self) -> Agent: return Agent(config=self.agents_config["researcher"], verbose=True)
@agent def reporting_analyst(self) -> Agent: return Agent(config=self.agents_config["reporting_analyst"], verbose=True)
@task def research_task(self) -> Task: return Task(config=self.tasks_config["research_task"])
@task def reporting_task(self) -> Task: return Task(config=self.tasks_config["reporting_task"], output_file="report.md")
@crew def crew(self) -> Crew: return Crew(agents=self.agents, tasks=self.tasks, process=Process.sequential, verbose=True)@CrewBase loads config/agents.yaml and config/tasks.yaml into self.agents_config and self.tasks_config, collects the @agent and @task methods into self.agents and self.tasks in definition order, and @crew returns the Crew. We ran the scaffold from crewai create crew --classic against a scripted model: both tasks ran in order, the second saw the first’s output as context, and report.md was written by the output_file on reporting_task. The agents in the scaffold set no llm, so they use the default model unless you add llm= or set MODEL.
main.py
Section titled “main.py”import sys
from my_crew.crew import MyCrew
INPUTS = {"topic": "AI agents"}
def run(): MyCrew().crew().kickoff(inputs=INPUTS)
def train(): MyCrew().crew().train(n_iterations=int(sys.argv[1]), filename=sys.argv[2], inputs=INPUTS)
def replay(): MyCrew().crew().replay(task_id=sys.argv[1])
def test(): MyCrew().crew().test(n_iterations=int(sys.argv[1]), eval_llm=sys.argv[2], inputs=INPUTS)The generated main.py also has a run_with_trigger() function. pyproject.toml wires these to console scripts (run_crew, train, replay, test, run_with_trigger, plus one named after the project), so crewai run, crewai train, etc. work out of the box.
Training mode
Section titled “Training mode”crewai train -n 5 -f trained_agents_data.pklTraining is human-in-the-loop, not an automatic scorer. Crew.train(n_iterations, filename, inputs) (the second argument is required; the scaffolded train() reads -n and -f from the command line):
- Copies the crew and turns on
human_input=Truefor every task andallow_delegation=Falsefor every agent. - Runs the copy
ntimes with yourinputs. After each task the console asks you for feedback on the output. The agent revises its answer, and the initial output, your feedback and the improved output are stored per agent in an intermediatetraining_data.pkl. - When the iterations finish, an LLM evaluator (
TaskEvaluator.evaluate_training_data) condenses each agent’s feedback into a list of suggestions, a 0 to 10 quality score and a summary, and saves them under the agent’srolein the file you named. - If anything fails, both pickle files are cleared.
To use the result, point the crew at the file. At run time each agent appends You MUST follow these instructions: and its suggestions to its task prompt. The file is chosen in this order: Crew(trained_agents_file="path.pkl"), the CREWAI_TRAINED_AGENTS_FILE environment variable, then trained_agents_data.pkl in the working directory. crewai run -f path.pkl, crewai test -f and crewai replay -f set the environment variable for you. Suggestions are keyed by agent role, so renaming a role orphans its training data.
Testing mode
Section titled “Testing mode”crewai test -n 3 -m gpt-6-lunaCalls Crew.test(n_iterations=3, eval_llm=...) with the model you pass — runs the crew n times, scores every task with the eval LLM, and prints a consolidated table. Good for regression runs in CI.
Replay
Section titled “Replay”crewai log-tasks-outputs # list the task ids from the last kickoffcrewai replay -t <task_id>replay re-runs the crew starting from the named task and reuses the stored outputs of earlier tasks as context. The outputs come from the latest kickoff, saved by every Crew.kickoff() in latest_kickoff_task_outputs.db inside CrewAI’s per-user data directory ($CREWAI_STORAGE_DIR if set). We replayed a two-task crew from its second task: one model call, with the first task’s stored output in the prompt. The id is looked up in the stored outputs, so a freshly built crew with the same tasks can replay an id printed by an earlier process. Only the most recent kickoff is kept. crewai reset-memories -k clears it.
Reset memories
Section titled “Reset memories”crewai reset-memories -m # unified Memorycrewai reset-memories -kn # crew knowledgecrewai reset-memories -akn # agent-level knowledgecrewai reset-memories -k # cached kickoff outputscrewai reset-memories -a # all of the aboveThe legacy --long, --short, --entities flags are accepted (they do not appear in --help) and print a deprecation warning that says “all memory is now unified.” Each flag resets only what the crew in the current project has configured: -m on a crew without memory enabled fails with “Memory memory system is not initialized”.
Checkpoints
Section titled “Checkpoints”crewai checkpoint # interactive TUIcrewai checkpoint list ./.checkpoints # non-interactive listcrewai checkpoint info ./.checkpoints # show latest (or pass a file)crewai checkpoint resume [checkpoint_id] # resume runcrewai checkpoint diff id1 id2 # side-by-side comparecrewai checkpoint prune --keep 20 --older-than 30d --dry-run--location on the group sets the default directory (./.checkpoints); SQLite files are auto-detected by .db extension.
crewai create flow my_flowcrewai run # run the flow (`crewai flow kickoff` still works)crewai flow plot # builds the HTML graph and opens it in your browsercrewai flow add-crew research # embed a crew scaffold inside the flow projectDeployments — CrewAI AMP
Section titled “Deployments — CrewAI AMP”crewai logincrewai deploy create # first-time (--zip uploads a ZIP even if there is a git origin)crewai deploy push # redeploycrewai deploy listcrewai deploy status -u <uuid>crewai deploy logs -u <uuid>crewai deploy remove -u <uuid>crewai deploy validate runs the same pre-flight checks as create/push without contacting the platform — handy in CI. In 1.15.41 it looks for src/<package>/main.py with a Flow subclass in flow projects, so a declarative flow project (crewai create flow --declarative, which has flow.yaml and no main.py) fails with missing_flow_main and no_flow_subclass. crewai run works for those projects; validation and deploy checks do not accept them yet.
Tool Repository
Section titled “Tool Repository”crewai create tool my_toolcrewai tool install acme/my_toolcrewai tool publish --publicRequires crewai login. Tools are Python packages auto-wrapped as BaseTools.
Tracing
Section titled “Tracing”crewai traces enablecrewai traces statuscrewai env view # view CREWAI_TRACING_ENABLED, etc.Set CREWAI_TRACING_ENABLED=true in .env for an always-on setup.
Patterns
Section titled “Patterns”1. Scripted CI check
Section titled “1. Scripted CI check”- run: pip install "crewai[tools]"- run: crewai deploy validate- run: crewai test -n 2 -m gpt-6-lunadeploy validate exits non-zero on blocking issues. crewai test calls the real model (it needs the API key as a CI secret and costs tokens) and prints a score table. It does not fail the job on a low score, and in 1.15.41 it also exits 0 when the run itself errors (the CLI catches the error and prints it), so keep offline unit tests with a stub LLM as the gate (see Production).
2. Scheduled resume from checkpoint
Section titled “2. Scheduled resume from checkpoint”# cron: every hour, pick up the most recent interrupted runcrewai checkpoint resumeresume without an ID defaults to the most recent checkpoint.
3. Dry-run prune
Section titled “3. Dry-run prune”crewai checkpoint prune --keep 50 --older-than 14d --dry-runShows what would be removed; drop --dry-run to commit.
4. Provision + run a template
Section titled “4. Provision + run a template”crewai template listcrewai create template marketing-campaign -o mkt-campaigncd mkt-campaign && uv sync && crewai run5. Ad-hoc chat against a deployed crew
Section titled “5. Ad-hoc chat against a deployed crew”crewai chatSet Crew(chat_llm=LLM(...)) for a predictable model; the CLI opens a REPL that routes inputs through the crew on demand.
Gotchas
Section titled “Gotchas”crewai runrelies on[project.scripts]. If you rename entry points inpyproject.toml, the CLI still expects therun_crewscript. Edit both sides together.- Scaffolds pin
crewai[tools]>=<installed version>,<2.0.0. Projects created by an older CLI keep their older floor; bump it when you upgrade so the project and the CLI agree. reset-memorieswithout flags prints a help line and exits. You must pick at least one type.replay -tneeds logged outputs.log-tasks-outputsconfirms what’s available.- Legacy
--long/--short/--entitiesare shims. They all map to--memorynow; don’t rely on the distinction. crewai chatmodel resolution. It usesCrew.chat_llm; if that is unset it falls back to theMODELenvironment variable, then CrewAI’s default model (gpt-6-luna), not to the agents’ own LLMs. If the model cannot be created it prints “Unable to find a Chat LLM” and exits.crewai updatedoes not upgrade CrewAI. To upgrade the CLI useuv tool upgrade crewai; inside a project usecrewai install --upgrade-package crewai --upgrade-package crewai-tools.crewai uvexpects apyproject.toml. Outside a crew project it errors out with a clear message.