At a glance
Status, checked 2026-09-18: version 0.1.2, released 2026-09-18. add, preview, doctor and skill work with demo data. login, connect and list need the JSON API and exit 2 until 0.2.
- Use it when
- you want a feed component, types and realistic demo data in a project in one step, and you need output a script or an agent can parse.
- Do not use it when
- you need real posts from the CLI today: that is 0.2. Use the widget embed for real posts now.
- What the human does
- nothing for the demo. The CLI has no account, no login and no telemetry in 0.1.
- Next step
- run
npx [email protected] add instagram-feed --jsonfrom the project root and readfilesandnext.
Before you run it
An agent should tell the user what it is about to run. These facts are what the user needs to say yes:
| Question | Answer |
|---|---|
| Package | electricblaze on npm, MIT license |
| Source | github.com/ElectricBlaze/electricblaze |
| Runtime | Node.js 18 or newer, no dependencies; no install scripts |
| Publishing | Only from GitHub Actions with npm provenance; no npm token exists outside the workflow |
| Writes | Only inside the project directory or --dir; every file is listed in the output |
| Overwrites | Never a file you edited, unless you pass --force; line endings do not count as an edit |
| Network | None in 0.1. The generated loader calls the ElectricBlaze API only when ELECTRICBLAZE_API_KEY is set (0.2) |
| Security contact | SECURITY.md |
Pin the version in scripts and agent sessions, then verify the signature after an install:
npx [email protected] --version
npm install -D [email protected] && npm audit signaturesCommands
| Command | Does | Works today |
|---|---|---|
add instagram-feed | Writes the component, loader, types and demo feed for the detected framework | Yes |
preview [instagram] | Prints the feed as JSON; --formats=reel --limit=6 filter it | Yes, demo data |
doctor | Checks Node, framework, installed kit, feed validity and account state | Yes |
skill | Installs the agent skill into .claude/skills/ and .agents/skills/ | Yes |
login | Device-flow sign in, like gh auth login | No, exits 2 until 0.2 |
connect instagram | Prints a URL for the account owner and waits for the connection | No, exits 2 until 0.2 |
list | Lists connected accounts | No, exits 2 until 0.2 |
Flags: --json, --yes, --help, --version, --force, --dir=<path>, --framework=next|html|data, --agent=claude,codex, --limit=<n>, --formats=reel,post. A flag the command does not accept is an error, not a silent no-op.
Exit codes and JSON output
Every command accepts --json and never prompts. Three exit codes cover every outcome:
0: done. Readfiles,notesandnext.1: something is broken, for example an invalid feed file. The failing check carries anextcommand.2: the command needs something that does not exist yet, or the input was wrong.nextsays what to run instead.
npx electricblaze connect instagram --json today (exit 2)
{
"ok": false,
"command": "connect",
"status": "not_available_yet",
"message": "\"connect\" needs the ElectricBlaze API and ships in 0.2. Everything else works in demo mode today.",
"next": "Keep the demo feed for now; read https://electricblaze.com for the API status."
}npx electricblaze add tiktok-feed --json (exit 2)
{
"ok": false,
"error": "unknown component \"tiktok-feed\"",
"available": ["instagram-feed"],
"next": "Run: npx electricblaze add instagram-feed"
}What add writes, per framework
The framework is detected from package.json. --framework=next|html|data overrides it.
| Detected | Kit | Files |
|---|---|---|
next | next | components/eb/InstagramFeed.tsx, InstagramFeed.module.css, lib/eb/instagram.ts, lib/eb/feed.d.ts, lib/eb/demo/instagram.json, .env.example (under src/ with src/app). With only a pages/ directory the output notes that the component needs the App Router; the loader works in getStaticProps |
astro, @sveltejs/kit, nuxt, @remix-run/react, react-router, gatsby, vite | data | lib/eb/feed.d.ts, lib/eb/demo/instagram.json (under src/ when it exists) |
No package.json, or anything else | html | electricblaze/instagram-feed.js, .css, instagram.json, instagram.demo.js, feed.d.ts |
The data kit is deliberate. Those frameworks would not serve a script dropped into the project root, and each has its own way to load JSON. See Astro, SvelteKit and Nuxt for the component to write.
When the project has AGENTS.md or CLAUDE.md, add appends a block between <!-- electricblaze:start --> and <!-- electricblaze:end -->. It tells the next coding agent where the feed lives and where real posts come from. Running add again updates the block in place.
doctor, the next-step machine
doctor finds whichever kit is installed, even one that does not match the framework, validates the feed file against the schema and reports the account state.
npx electricblaze doctor --json in a Next.js project after add (trimmed)
{
"ok": true,
"framework": "next",
"kit": "next",
"checks": [
{ "name": "node", "status": "ok", "detail": "Node 24.13.0" },
{ "name": "framework", "status": "ok", "detail": "Next.js (app router)" },
{ "name": "component", "status": "ok", "detail": "instagram-feed (next)" },
{ "name": "feed", "status": "ok", "detail": "12 posts, schema v1, demo data" },
{ "name": "account", "status": "warn", "detail": "not connected: demo feed",
"next": "Real posts today: connect the account in the ElectricBlaze widget and paste its snippet (https://electricblaze.com). JSON by API key: npx electricblaze connect instagram, ships in 0.2." }
]
}Other ways to install the same component
- shadcn:
npx shadcn@latest add ElectricBlaze/electricblaze/instagram-feedinstalls the Next.js files through the shadcn registry in the repository. - Claude Code plugin:
/plugin marketplace add ElectricBlaze/electricblaze, then/plugin install electricblaze@electricblaze. - Agent skill only:
npx electricblaze skill. See the skill page.
Release notes for every version are on the changelog.