MODULE 2.1

⌨️ Command line in practice

The web interface brought you here, but the terminal is where the tool becomes a productivity machine. In this module, you’ll master the command run and all its flags — from --context a --skip-research — to automate, scale, and save money.

Topics

Minutes

⚡

Practical

⌨️

Terminal

Illustrative diagram — the flags adjust the central command, which launches the complete pipeline.

Detailed content

🧩 Why use the CLI

The web interface is user-friendly and perfect for your first analysis. But the moment you want to run ten companies in a row, schedule an analysis overnight, or repeat exactly the same operation, the terminal (CLI) is clearly the better choice. It’s the same engine—just without the browser middleman.

✓ The CLI shines when

✓You run several companies in sequence (batch)
✓Anyone who wants to automate with a script or scheduler
✓Uses a remote server, with no graphical interface
✓You need to repeat the same analysis precisely

🖥️ The web is still great for

•Your first analysis, without memorizing anything
•Track progress visually
•Download the files with one click
•Anyone who prefers to point and click

💡 Tip — it’s not “or,” it’s “and”

You can use both: the web to explore and the CLI for production. Both read and write to the same folder output/, so work done in one appears in the other.

▶️ The run command

There’s one command that does everything, from start to finish. Memorize this one: it launches all 3 phases and delivers the complete package in a new folder.

⌨️ The central command

# Ative o ambiente primeiro
source venv/bin/activate        # Mac/Linux
# .\venv\Scripts\activate       # Windows

# O comando que faz tudo
python -m strategy_factory.main run "Stripe"

# Resultado: uma pasta nova com o pacote completo
output/stripe/
├── markdown/        (15 documentos)
├── presentations/   (2 apresentações .pptx)
├── documents/       (2 relatórios .docx)
└── mermaid_images/  (5 diagramas .png)

The name in quotes becomes the folder "slug" — "Stripe" → output/stripe.

🔑 Command anatomy

python -m — runs a Python module
strategy_factory.main — the tool’s main program
run — the subcommand that runs the pipeline
"Stripe" — the argument: the company name

💬 The --context flag

The name alone sometimes isn’t enough — think of companies with common names or that aren’t well known. The flag --context guides the research and greatly improves the quality of the documents.

⌨️ With and without context

# Sem contexto — a IA adivinha sozinha
python -m strategy_factory.main run "Acme"

# Com contexto — a pesquisa fica muito mais precisa
python -m strategy_factory.main run "Acme" \
  --context "B2B payments, fintech, 200 funcionários"

✓ Good context includes

✓Sector / industry (fintech, healthcare, retail)
✓Business model (B2B, B2C, SaaS)
✓Approximate size (employees, revenue)
✓Region, if relevant

✗ Avoid

✗Keep it vague for little-known companies
✗Forgetting the quotation marks around the text
✗Trust only the name when it’s ambiguous
✗Writing a huge paragraph — keep it concise

💡 Tip — context is your steering wheel

For well-known names (Stripe, Nubank), context is optional. For everyone else, it’s what keeps the AI from researching the wrong company — a short text that guides the entire analysis.

⚙️ The --mode flag

The flag --mode determines the research depth — and with it, the cost and time. There are two values: quick (default) and comprehensive.

⌨️ The two modes

# Quick é o padrão — não precisa nem da flag
python -m strategy_factory.main run "Stripe"
python -m strategy_factory.main run "Stripe" --mode quick

# Comprehensive — pesquisa mais profunda (e mais cara)
python -m strategy_factory.main run "Stripe" --mode comprehensive

🐇 quick (default)

•~9 research searches
•2-3 minutes · ~US$ 0,05
•Great for triage and a first pass

🐢 comprehensive

•~18 research searches
•5–10 minutes · ~US$ 0.50
•For the company you’re going to present to

💡 Tip — Module 2.2 goes deeper

Here, you only need to know that the flag exists and what each value does. The next module compares the two modes in detail, with costs and a decision tree.

🧪 The --dry-run flag

Before spending a cent, simulate it. The flag --dry-run shows what would be generated, but doesn't make any AI calls. It’s your safety net.

⌨️ Free simulation

# Simula tudo, sem gastar nada
python -m strategy_factory.main run "Stripe" --dry-run

# Saída esperada (exemplo):
# [DRY RUN] Pesquisa: 9 buscas planejadas (Perplexity)
# [DRY RUN] Síntese: 15 documentos planejados (Gemini)
# [DRY RUN] Geração: 2 PPTX + 2 DOCX + 5 PNG
# [DRY RUN] Custo estimado: ~US$ 0,05 · Nenhuma chamada feita.

🎯 Use dry-run to

Test the installation right after setup, without spending
Check the keys — if you get a key error here, the .env is wrong
View the plan of execution before actually running it

💡 Tip — the first command, every time

Just installed it? Run a --dry-run before anything else. It's the cheapest (free) way to check that everything is in place.

📋 status & list

After running a few analyses, you'll want to inspect what's already there. Two read commands—that don't use API credits — take care of that.

⌨️ Inspect analyses

# Detalhe de uma empresa: progresso, fase, custo
python -m strategy_factory.main status "Stripe" --detailed

# Todas as empresas já analisadas
python -m strategy_factory.main list

📊

status "Company" --detailed

Shows what stage the analysis is at, which deliverables are ready, and how much has been spent so far. Without --detailed, it shows a short summary.

📚

list

Lists all the companies that already have a folder in output/ — your complete analysis history at a glance.

💡 Tip — reading is free

Both status how much list only read local files. Use them as much as you like: they never consume API credits.

🔁 resume, reset & skip

The last commands are for recovery and savings: resume where you left off, start over from scratch, and reuse saved results without paying again.

⌨️ Resume, clear, and skip phases

# Retoma de onde parou (após queda ou Ctrl+C)
python -m strategy_factory.main resume "Stripe"

# Limpa tudo e recomeça do zero (--yes pula a confirmação)
python -m strategy_factory.main reset "Stripe" --yes

# Reaproveita resultados em cache, pulando fases:
python -m strategy_factory.main run "Stripe" --skip-research    # reusa a pesquisa
python -m strategy_factory.main run "Stripe" --skip-synthesis   # reusa os documentos
python -m strategy_factory.main run "Stripe" --skip-generation  # reusa os arquivos

⏱️ Timeline of a recovery

The research ends

Phase 1 records the research_cache.json. This money has already been spent.

The synthesis fails midway

The internet goes down or you hit the limit (429 error). The state.json records where it left off.

resume continues for free

O resume reuses the cached research and only reruns the missing synthesis. You don’t pay for Phase 1 again.

💡 Tip — only adjusting the documents? Skip the research

If you only want to regenerate the documents (because you edited a prompt, for example), use --skip-research. The research, which is the expensive part, comes from the cache — and the cost drops sharply.

⌨️ Module Summary

✓

Why the CLI — batches, automation, server, and precision; the web is still great for getting started.

✓

run "Company" — the central command that runs all 3 phases and creates output/slug.

✓

--context — clues (industry, model, size) that greatly improve the research.

✓

--mode — quick (default, inexpensive) or comprehensive (in-depth, more expensive).

✓

--dry-run — simulates without spending; ideal for testing the installation and keys.

✓

status, list, resume, reset, --skip-* — inspect, resume, clear, and reuse the cache.

Next Module:

2.2 — Quick vs. Comprehensive modes — choose between quick and in-depth modes with a clear understanding of cost, models, and time.

← Back to Track Next Module →