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.

Filing feedback? Read the Tester Guide first — same flow as below, with explicit safety checklists, dry-run-before-live gates, and bug-report instructions tuned for technical alpha testers. Cross-references: platform support · known limitations.

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 (offers an opt-in 6-question brand wizard) $ npx @andersonfda/springy init my-brand
$ cd my-brand

This creates config/brand.yaml, config/platforms.yaml, .env, a starter briefing at data/briefings/_sample.md (so step 6 produces a real draft on a fresh install), and a .gitignore that excludes secrets, tokens, and runtime DB. init also offers to npm install the scoped package locally so npx springy … resolves correctly — pass --no-install to skip and run it yourself.

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)

# init seeded data/briefings/_sample.md so this works on a fresh install. # Drop your own topic alongside it (or replace it) any time: $ echo "# Anthropic just shipped Opus 5" > data/briefings/today.md
$ npx springy opportunities:rank
$ npx springy cascade --top --dry-run

Springy picks the top ranked opportunity, generates the anchor essay (critique loop ×3), stops for your approval, fans out to the 4 default text platforms (LinkedIn, X-thread, Threads, Bluesky) in parallel, critiques each, stops again for approval, then writes drafts into content/drafts/<date>-<slug>/. --dry-run means no provider calls and no writes to cascade_steps; drop the flag once you trust the output. Add --seo to also fan out to Medium + Dev.to.

If a cascade fails partway, the error prints a trace id and a resume command — npx springy cascade --resume <traceId> replays cached steps and re-runs only what didn't complete.

7. Publish

# Wire one platform (LinkedIn or Bluesky are the easiest first picks) $ npx springy setup linkedin
$ npx springy auth linkedin
# Dry-run: see exactly what would post, with no network call $ npx springy publish
# One-platform live publish for the FIRST time. The first --live # ever per project asks "type YES". --platform filters the drainer # to one platform's queued rows so you can validate without # publishing everything queued. $ npx springy publish --live --platform linkedin

8. Automate the loop (optional)

# Installs native scheduler entries (launchd on macOS, # systemd on Linux, cron on POSIX, Task Scheduler on Windows). $ npx springy cron:dry-run # preview the four jobs first $ npx springy cron:install

Four scheduled jobs land — all in dry-run mode by default so day-1 doesn't surprise you:

Daily cascade at 07:15 local — overridable with SPRINGY_DAILY_HOUR / SPRINGY_DAILY_MIN.
Hourly queue drain at :05 — dry-run until you re-run with cron:install --live.
Daily voice refresh at 01:00 local (off-hours, after morning posts have accumulated metrics).
Weekly trace prune on Sunday 03:00 — deletes JSONL traces older than 90 days.

Add --seo to bake Medium + Dev.to into the daily command, or set SPRINGY_CRON_SEO=1. Pause everything later with cron:remove.

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.