# The electricblaze CLI: commands, output and what it touches

**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.

> A non-interactive command line tool that puts an Instagram feed component with demo data into a project. Built to be run by coding agents: JSON output, stable exit codes, no prompts.

Canonical: https://electricblaze.com/developer/instagram-feed/cli.html

## At a glance

- **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](https://electricblaze.com/developer/instagram-feed/nextjs.html#widget) 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 electricblaze@0.1.2 add instagram-feed --json` from the project root and read `files` and `next`.

## 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](https://www.npmjs.com/package/electricblaze), MIT license |
| Source | [github.com/ElectricBlaze/electricblaze](https://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](https://github.com/ElectricBlaze/electricblaze/blob/main/SECURITY.md) |

Pin the version in scripts and agent sessions, then verify the signature after an install:

```sh
npx electricblaze@0.1.2 --version
npm install -D electricblaze@0.1.2 && npm audit signatures
```

## Commands

| 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. Read `files`, `notes` and `next`.
- `1`: something is broken, for example an invalid feed file. The failing check carries a `next` command.
- `2`: the command needs something that does not exist yet, or the input was wrong. `next` says what to run instead.

`npx electricblaze connect instagram --json` today (exit 2):

```json
{
  "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):

```json
{
  "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](https://electricblaze.com/developer/instagram-feed/astro.html), [SvelteKit](https://electricblaze.com/developer/instagram-feed/sveltekit.html) and [Nuxt](https://electricblaze.com/developer/instagram-feed/nuxt.html) 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):

```json
{
  "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-feed` installs 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](https://electricblaze.com/developer/instagram-feed/skill.html).

Release notes for every version are on the [changelog](https://electricblaze.com/developer/changelog.html).

## FAQ

### Does the CLI send telemetry?

No. Version 0.1 makes no network calls. The generated loader calls the ElectricBlaze API only when `ELECTRICBLAZE_API_KEY` is set, and that API ships in 0.2.

### Can an agent run it without a human?

Yes. Nothing prompts, every command has `--json`, and exit code 2 always comes with a `next` command. It should still tell the user which files it wrote.

### What happens if I run add twice?

Unchanged files are reported as `unchanged`, edited files as `skipped`. Nothing you changed is overwritten without `--force`.

### Why does add tiktok-feed fail?

Only Instagram exists today. The command exits 2 and lists the available components rather than writing a component that could not work.

### How do I verify the package?

Install a pinned version and run `npm audit signatures`, or open the Provenance section of the version on npmjs.com.

## Related pages

- [Feed schema](https://electricblaze.com/developer/instagram-feed/schema.html)
- [Agent skill](https://electricblaze.com/developer/instagram-feed/skill.html)
- [Changelog](https://electricblaze.com/developer/changelog.html)
- [Next.js](https://electricblaze.com/developer/instagram-feed/nextjs.html)
- [Plain HTML](https://electricblaze.com/developer/instagram-feed/static-site.html)
- [Developers home](https://electricblaze.com/developer/)

---

ElectricBlaze, updated 2026-09-18. Source of this page: https://electricblaze.com/developer/instagram-feed/cli.html