Getting Started
This guide walks you through the complete workflow — from a raw idea file to a polished, reviewed, and revised blog post.
Prerequisites
- Node.js >= 18
- A markdown file with your raw ideas (e.g.,
my-idea.md) - (Optional) An API key for an AI provider to generate real content
1. Clone the Repository
git clone https://github.com/mmornati/ai-brief.git
cd ai-brief2. Configure an AI Provider
The pipeline needs an AI to generate content. Set up an OpenAI-compatible provider:
Option A: .env file (recommended)
Copy the example file and fill in your values:
cp .env.example .envEdit .env:
AI_API_KEY=sk-your-api-key-here
AI_BASE_URL=https://api.openai.com/v1
AI_MODEL=gpt-4o-miniThe .env file is automatically loaded when running any CLI command.
Option B: Environment variables
# Required: your API key
export AI_API_KEY=your-api-key-here
# Optional: custom endpoint (default: https://api.openai.com/v1)
# For local models via Ollama: export AI_BASE_URL=http://localhost:11434/v1
export AI_BASE_URL=https://api.openai.com/v1
# Optional: model selection (default: gpt-4o-mini)
export AI_MODEL=gpt-4o-miniSupported providers (pass via --provider):
| Provider | Description |
|---|---|
passthrough | Echoes prompts as output (no AI, for testing) |
openai-compatible | OpenAI API or any compatible endpoint (OpenAI, Ollama, OpenRouter, LocalAI, etc.) |
3. Create an Input File
Create a markdown file with your content idea. This can be as rough as bullet points or free-form notes — the pipeline will validate, research, and structure it:
# My Blog Post Idea
Topic: How AI coding assistants are changing developer workflows
Key points:
- Less boilerplate, more architecture thinking
- Shift from writing code to reviewing code
- New skills developers need to develop
Target audience: Senior developers and tech leads
Tone: Professional but approachable4. Run the Pipeline
# With AI generation:
node src/cli.js run my-idea.md --format blog --provider openai-compatibleThe pipeline executes six steps sequentially (validate → research → structure → write → format → review). Each step calls the AI and prints its thinking to the console.
5. View the Results
After the pipeline completes, two output files are produced:
| File | Contents |
|---|---|
ai-brief-output/blog/my-idea-blog.md | The complete blog post |
ai-brief-output/my-idea-review.md | A separate review report evaluating the final blog post |
The review report is generated by the final pipeline step. It evaluates the blog post critically — checking factual accuracy, clarity, structure, and style. It is saved as a separate file so you can read it independently.
6. Review and Revise
Read the review report to see what improvements were suggested. You have two options for revising the blog post:
Option A: Use the auto-generated review
The review from step 6 already contains expert feedback. You can apply it immediately:
node src/cli.js revise my-idea.md --format blog --provider openai-compatibleThis reads the format step output and the auto-generated review, calls the AI to address every issue, and saves the revised blog post.
Option B: Add your own feedback
You can edit the review file to add your own comments, then run revise with it:
# Edit the review to add your own feedback
# - Keep any issues you agree with
# - Remove issues you disagree with
# - Add your own comments or suggestions
vim ai-brief-output/my-idea-review.md
# Run revise — it will use your edited review
node src/cli.js revise my-idea.md --format blog --provider openai-compatibleOption C: Provide your own feedback file
You can write your own review file from scratch:
# Write your feedback (any markdown format)
cat > my-feedback.md << 'EOF'
# My Feedback
I'd like the introduction to be more concise.
Please add a comparison table in section 3.
EOF
# Run revise with your custom feedback
node src/cli.js revise my-idea.md --format blog --provider openai-compatible --review-file my-feedback.md7. Complete Workflow Summary
1. Write idea.md (raw notes)
2. ai-brief run idea.md --format blog --provider openai-compatible # produces blog + review
3. Read ai-brief-output/idea-review.md # review the feedback
4. (Optional) Edit the review file to add your own comments
5. ai-brief revise idea.md --format blog --provider openai-compatible # incorporate feedback
6. Read ai-brief-output/blog/idea-blog.md # final revised blog post