> ## Documentation Index > Fetch the complete documentation index at: https://docs.swarms.world/llms.txt > Use this file to discover all available pages before exploring further. # CLI Quickstart Tutorial > A hands-on walkthrough — build a real multi-agent research-and-writing workflow using only the Swarms CLI # CLI Quickstart Tutorial This tutorial builds a working multi-agent workflow from scratch using only the CLI — no Python required until the final optional step. By the end you'll have a reusable agent library, a YAML pipeline, and a one-command way to run it. **You'll build:** a research → write → review pipeline that takes a topic and produces a polished briefing. **Time:** 15–20 minutes. **Prerequisites:** Python 3.10+, one provider API key (OpenAI or Anthropic). *** ## Step 1 — Install and Initialize ```bash theme={null} pip install -U swarms swarms init ``` The wizard prompts for a project directory, a workspace path, and your API keys. When it finishes, you'll have: ``` my-swarm/ ├── .env # your API keys └── workspace/ # where agents read and write files ``` Verify the install: ```bash theme={null} swarms setup-check ``` If every check passes, the CLI will print a "next step" tip suggesting a real first command. Follow it — or stay with this tutorial. *** ## Step 2 — Pick a Model Before configuring agents, decide which model you'll use. Browse the catalog: ```bash theme={null} swarms models --provider anthropic ``` Pick one that fits your budget. Inspect details: ```bash theme={null} swarms models --info claude-opus-4-7 ``` You'll see context window, supported features, and per-million-token pricing. For this tutorial we'll use: * `claude-opus-4-7` for the writer (quality matters most) * `gpt-4o` for the researcher (good cost/quality tradeoff) * `gpt-4o` for the reviewer If you only have one provider key, use that provider's strongest model for all three. The pipeline still works. *** ## Step 3 — Define the Agent Library (Markdown) The most ergonomic way to define a reusable agent is a markdown file with YAML frontmatter. Create three files inside an `agents/` folder: **`agents/researcher.md`** ```markdown theme={null} --- name: Researcher description: Researches a topic thoroughly with citations model_name: gpt-4o temperature: 0.2 --- You are a senior research analyst. Given a topic, produce a detailed research summary with these sections: 1. **Context** — Why this topic matters right now (1 paragraph) 2. **Key facts** — 5–7 bullet points with concrete numbers, dates, and named sources 3. **Open questions** — What remains uncertain or contested 4. **Citations** — Inline source attributions for every factual claim Be specific. Prefer numbers over adjectives. ``` **`agents/writer.md`** ```markdown theme={null} --- name: Writer description: Turns research into a concise polished briefing model_name: claude-opus-4-7 temperature: 0.5 --- You are a writer for an executive briefing newsletter. Given research notes, produce a 400-word briefing with this structure: - **Lede** — One sentence that captures the entire story - **Body** — Three short paragraphs covering context, evidence, and stakes - **Takeaway** — One actionable sentence for a decision-maker Use plain language. Cut every word that doesn't earn its place. ``` **`agents/reviewer.md`** ```markdown theme={null} --- name: Reviewer description: Critiques the writing for accuracy, clarity, and concision model_name: gpt-4o temperature: 0.1 --- You are a senior editor. Given a draft briefing and the source research, produce a critique with: 1. **Accuracy issues** — Claims the draft makes that aren't supported by the research 2. **Clarity issues** — Sentences a busy executive would skip 3. **Specific rewrites** — Suggested replacement language for the weakest two paragraphs 4. **Verdict** — "Ship", "Revise", or "Restart" ``` Confirm they load: ```bash theme={null} swarms load-markdown --markdown-path ./agents/ ``` You should see a table listing all three agents with their models and descriptions. *** ## Step 4 — Run a Single Agent Before chaining, sanity-check one agent in isolation: ```bash theme={null} swarms agent \ --name "Researcher" \ --description "Researches a topic thoroughly" \ --system-prompt "You are a senior research analyst. Produce a detailed summary with citations." \ --task "What's the current state of mRNA vaccine development for cancer?" \ --model-name "gpt-4o" \ --streaming-on ``` `--streaming-on` shows tokens arriving in real time so you can tell whether the agent is on track without waiting for the full response. *** ## Step 5 — Chain Them: YAML Pipeline Create `pipeline.yaml`: ```yaml theme={null} agents: - name: Researcher model_name: gpt-4o temperature: 0.2 system_prompt: | You are a senior research analyst. Given a topic, produce a detailed research summary with context, key facts (with citations), and open questions. - name: Writer model_name: claude-opus-4-7 temperature: 0.5 system_prompt: | You are a writer for an executive briefing newsletter. Turn the research notes into a 400-word briefing with a lede, three-paragraph body, and one-sentence takeaway. - name: Reviewer model_name: gpt-4o temperature: 0.1 system_prompt: | You are a senior editor. Given a draft briefing and the source research, return: accuracy issues, clarity issues, specific rewrites for the weakest paragraphs, and a verdict of Ship/Revise/Restart. swarm: type: SequentialWorkflow task: | Topic: How are large language models being used in drug discovery in 2026? ``` Run it: ```bash theme={null} swarms run-agents --yaml-file pipeline.yaml ``` Each agent receives the previous one's output as context. The Researcher's notes flow into the Writer's brief, which flows into the Reviewer's critique. Total cost on `gpt-4o` + `claude-opus-4-7` will be a few cents. *** ## Step 6 — Try a Different Architecture The same agents can run as a Concurrent Workflow (all three see the same task in parallel) or as a Mixture of Agents (workers + aggregator). Try Concurrent for a different angle: ```yaml theme={null} # pipeline-concurrent.yaml agents: - name: Optimist model_name: gpt-4o system_prompt: Argue the strongest case for the topic - name: Pessimist model_name: claude-opus-4-7 system_prompt: Argue the strongest case against the topic - name: Realist model_name: gpt-4o system_prompt: Provide a balanced analysis of the topic swarm: type: ConcurrentWorkflow task: | Should our R&D team adopt LLMs as a daily tool for protein design? ``` Run: ```bash theme={null} swarms run-agents --yaml-file pipeline-concurrent.yaml ``` You get three independent perspectives in parallel rather than a chained refinement. *** ## Step 7 — Auto-Generate a Swarm When you don't know which architecture fits, let the CLI design one: ```bash theme={null} swarms autoswarm \ --task "Produce a competitive analysis of CRISPR-based cancer therapies in 2026" \ --model "gpt-4o" \ --no-run \ -o ./generated_swarm.py ``` `--no-run` writes the generated Python file without executing it, so you can inspect it first. Open `generated_swarm.py` — it's plain `swarms` Python code you can edit, version-control, or rerun manually. To run it immediately, drop `--no-run`: ```bash theme={null} swarms autoswarm \ --task "Produce a competitive analysis of CRISPR-based cancer therapies in 2026" \ --model "gpt-4o" ``` *** ## Step 8 — Deep Analysis with Heavy Swarm For research-grade depth, `heavy-swarm` decomposes the task into specialist questions and runs each through a worker for multiple loops: ```bash theme={null} swarms heavy-swarm \ --task "What are the second-order economic effects of AI coding assistants on the software labor market over the next five years?" \ --loops-per-agent 3 \ --worker-model-name "claude-opus-4-7" \ --question-agent-model-name "gpt-4o" \ --verbose ``` This costs more (3 loops × N workers × 1 question-generator) but produces noticeably deeper output than a single LLM call. Use sparingly. *** ## Step 9 — Council Debate When the task has multiple valid answers and you want disagreement surfaced: ```bash theme={null} swarms llm-council \ --task "Should we rewrite our Python data pipeline in Rust?" \ --verbose ``` Each council member responds independently; the chairman synthesizes, highlighting agreements and conflicts. *** ## Step 10 — Save and Resume an Agent For long-running tasks (autonomous research, ongoing chat with memory), persist state to disk: ```bash theme={null} swarms agent \ --name "ProjectAssistant" \ --description "Remembers context across days" \ --system-prompt "You are a project assistant. Remember every fact I tell you." \ --task "My project is called Helios. The team has 4 engineers." \ --autosave \ --saved-state-path ./helios.json ``` The next time you run the same command pointing at `./helios.json`, the agent picks up exactly where it left off — including everything you told it. *** ## Step 11 — Use a Tip on Every Run Run `swarms tips` whenever you want a quick reminder of a flag you might have forgotten: ```bash theme={null} swarms tips --count 3 ``` Or print every CLI power-user trick: ```bash theme={null} swarms tips --category pro --all ``` *** ## Step 12 — When Things Break If a command errors out, the CLI classifies the failure and prints targeted hints. Try these intentionally to see the error system at work: ```bash theme={null} swarms agent --name X --description Y --system-prompt Z --task "hi" --model-name "gpt-99" ``` You'll see a "Could not load info" message with the closest model name suggestions. ```bash theme={null} swarms agnt # typo ``` You'll see `Did you mean swarms agent?`. *** ## What You Built You now have: * A reusable agent library in `agents/*.md` * A repeatable sequential pipeline in `pipeline.yaml` * A concurrent variant in `pipeline-concurrent.yaml` * A fluency with the four most useful swarm-level commands (`run-agents`, `autoswarm`, `heavy-swarm`, `llm-council`) * A way to persist and resume long-running agents Commit `agents/` and `pipeline.yaml` to git — they're plain text. Anyone who clones your repo can run your workflow with the same one-liner. ## Next Steps The long-form CLI tour, including power-user tricks Every command, every flag, with examples YAML and markdown configuration formats in depth Learn the architectures behind each swarm command