GUIDE

Quickstart — zero to first cascade in ~15 minutes.

What follows works on macOS and Linux. Windows via Docker. If anything in this page doesn't work on your machine, that's a high-signal bug report — the quickstart is the first thing that needs to be right.

Prerequisites

Node 20 or 22 (node --version)
An Anthropic API key or an OpenAI API key. ChatGPT Plus/Pro subscribers can use OAuth instead — no separate API credits.
Optional: a Voyage API key for brand-voice retrieval. Costs <$1/month for solo use. Skip it on the first run and add later.
Optional: npx playwright install chromium — only needed for browser-fallback platforms (Instagram, Reddit, Substack, Rumble, Quora).

1. Install

~/anywhere

# Scaffold a new project $ npx @andersonfda/springy init my-brand
$ cd my-brand
$ npm install

This creates config/brand.yaml, data/, content/, and a starter .env with placeholder keys.

2. Describe your brand

The single most important file. Open config/brand.yaml and fill in, at minimum:

name — who you are.
voice.summary — one paragraph, concrete.
voice.rules — 5-10 short, specific rules ("numbers over adjectives", "show losses alongside wins").
pillars — 2-4 topic pillars you publish about.

Or copy an archetype and edit:

$ cp examples/brands/indie-hacker.yaml config/brand.yaml

Three archetypes ship with springy: indie-hacker.yaml, network-architect.yaml, and saas-founder.yaml. Pick the closest one.

3. Authenticate your LLM

Either:

# Path A — Anthropic API key (paste into .env)
ANTHROPIC_API_KEY=sk-ant-api03-...
# Path B — OpenAI $ npx springy auth openai
   → "Sign in with ChatGPT (Plus/Pro subscription, zero API cost)"
   → "API key (sk-proj-... from platform.openai.com)"
# Then, if you picked OpenAI, add to .env:
SPRINGY_LLM_PROVIDER=openai

4. Preflight

$ npx springy doctor

doctor checks Node version, better-sqlite3 binding, brand.yaml shape, API keys, Playwright, credential age, and queue health. Every failure prints a one-line fix. Pass --live to also hit your LLM provider with a tiny real call (<$0.001) and verify the key actually works.

5. Try offline first

$ npx springy demo

Zero API calls, zero cost. Prints a canned ranked opportunity, the cascade graph, a sample anchor essay, and platform-specific samples. About 60 seconds to read. If this is the moment the tool clicks or doesn't — file feedback.

6. Your first real cascade (dry-run)

$ mkdir -p data/briefings
$ echo "# Anthropic just shipped Opus 5" > data/briefings/test.md
$ npx springy opportunities:rank
$ npx springy cascade --top

Springy picks the top ranked opportunity, generates the anchor essay (critique loop ×3), stops for your approval, fans out to 5-7 platforms in parallel, critiques each, stops again for approval, then writes drafts into content/drafts/<date>-<slug>/. Nothing goes live.

7. Publish

# Wire one platform $ npx springy auth linkedin
# or: bluesky, x, threads, medium, devto, telegram, discord, … # Dry-run: see exactly what would post without posting $ npx springy publish
# Actually post. First --live ever per project asks "type YES". $ npx springy publish --live

8. Automate the loop (optional)

# Installs native scheduler entries (launchd on macOS, # systemd on Linux, Task Scheduler on Windows). $ npx springy cron:install

Three scheduled jobs land: daily cascade at 7:15, hourly queue drain at :05, weekly trace prune on Sunday 3:00. You can preview what would install with cron:dry-run.

When it breaks

Start with:

$ npx springy doctor

If that doesn't surface the answer, open an issue with the bug-report template. Include Node version, OS, the command you ran, the last ~30 lines of output, and doctor output. Security issues go private.