METAPHORE

Turn any technical concept into a clear human story.

METAPHORE transforms dense technical concepts, architectures, incidents, and AI outputs into structured, memorable narratives — without distorting the truth.

You bring your own LLM key. METAPHORE handles the cognitive translation.

Quick Start

npm install -g metaphore-cli
metaphore --key mkey_your_key_here
metaphore "what is a reverse proxy?"

Get your mkey at console.metaphore.app. That's it — three commands, you're done.

What You Get

Give METAPHORE any technical input. Get back:

1. Core technical truth — what is really happening
2. Why it's hard to understand — the confusion point
3. Short analogy — one sentence
4. Story — 3-act narrative (setup, confrontation, resolution)
5. Mapping table — story element → real technical element
6. Limits of the analogy — honest about where it breaks
7. Operational summary — what to remember, what to do next
8. Moral — one memorable sentence

Every story maps back to reality through an explicit mapping table. Simplify without distorting — that's the rule.

Who It's For

• Builders using AI who need to understand what the AI actually did
• Founders and operators managing technical work they didn't write
• Teams that repeatedly explain complex systems to non-technical stakeholders
• Anyone who has read a technically correct explanation and still felt lost

Usage

metaphore "your input" [options]

Options

| Flag | Values | Description | |------|--------|-------------| | --audience | CEO, junior-dev, 12-year-old, founder, operator, salesperson | Who the explanation is for | | --style | building, restaurant, postal, hospital, workshop, theater | Analogy domain | | --depth | short, full (default) | One paragraph vs. full 3-act story | | --objective | understand, decide, debug, explain-to-someone, learn | What the reader needs to do next | | --lang | Any language code | Override output language (auto-detected from input by default) | | --provider | anthropic, openai, gemini | Which LLM to use (default: your console setting) | | --model | Model name | Override default model |

Examples

# Basic — explain a concept
metaphore "what is nginx?"

# For a CEO, in French
metaphore "explain our microservices architecture" --audience CEO --lang fr

# Quick debug summary
metaphore "why does my webhook fail with 200 but no event processed" --objective debug --depth short

# For a junior dev, using a building analogy
metaphore "auth vs authorization" --audience 12-year-old --style building

# Using OpenAI instead of Anthropic
metaphore "explain OAuth" --provider openai

# Using Gemini
metaphore "what is TLS" --provider gemini

See EXAMPLES.md for full before-and-after output demonstrations.

Setup

Your mkey connects the CLI to your METAPHORE account. Get it at console.metaphore.app.

metaphore --key mkey_your_key_here

This saves your key to ~/.metaphore. You only need to do this once.

Advanced: direct API keys

Power users can also use raw LLM API keys without an mkey. Add them to ~/.metaphore or set them as environment variables:

ANTHROPIC_API_KEY=sk-ant-...    # for --provider anthropic
OPENAI_API_KEY=sk-...           # for --provider openai
GEMINI_API_KEY=AI...            # for --provider gemini

Default models per provider:

• Anthropic: claude-sonnet-4-5
• OpenAI: gpt-4o
• Gemini: gemini-2.5-pro

Override with --model:

metaphore "explain CORS" --provider openai --model gpt-4-turbo

Pricing

METAPHORE is free to start. You bring your own LLM key — no markup.

| Tier | Transforms | Price | |------|------------|-------| | Trial | First 3 | Free (no key needed) | | Free (BYOK) | 4–25 | $0 — you pay your LLM provider directly | | Pro | Unlimited | $4.99/month or $29.99/year |

Free tier transforms (25 total) are a one-time allowance, not monthly.

Upgrade at metaphore.app.

Channels

| Channel | Status | |---------|--------| | CLI | Live — npm install -g metaphore-cli | | Web | Live — metaphore.app | | Claude Code (MCP) | Live — npx metaphore-mcp (setup) | | Telegram | Live — @MetaphoreBot | | API | Live — POST https://api.metaphore.app/transform |

Requirements

• Node.js 18+ (uses ES modules and top-level await)
• An API key from at least one supported provider

License

The METAPHORE methodology is released under CC BY-NC-SA 4.0.

You may share and adapt for non-commercial purposes with attribution and under the same license. Commercial use requires separate permission.

Author

Created by Philippe Nerette.

Understanding should not be the bottleneck.