ideare

Put your brand into your project: the tab icon, the share card, the app icons, the colors and the fonts. One command, then the files stay in step with your brand like a lockfile.

npx ideare init acme-bakery

That finds your framework (Next.js with app/ or pages/, Vite, or a plain index.html), prints the brand's name and domain, lists every file it will add or replace, and asks once. It backs up any file of yours it replaces, in .ideare/backup/. Pulling an approved brand needs no account.

Where the files go

| | Next.js app/ | Next.js pages/ | Vite | Plain HTML | |---|---|---|---|---| | Icons | app/favicon.ico, icon.svg, apple-icon.png | public/ | public/ | next to index.html | | Share card | app/opengraph-image.png, twitter-image.png | public/og.png | public/og.png | og.png | | Manifest | app/manifest.webmanifest | public/site.webmanifest | public/site.webmanifest | site.webmanifest | | Colors and fonts | app/ideare/, imported once from globals.css | beside the CSS _app imports | src/ideare/, imported from src/index.css | ideare/, linked in the head | | Head tags | Next.js writes them | in pages/_document's <Head>, between markers | between <!-- ideare:head --> markers | the same |

brand/ holds the masters: brand.json, the three mark drawings, art/style.txt and brand.md. ideare.json says which brand and version you want and where files go; edit its paths to move them. ideare.lock.json holds the version and every file's sha256. Commit all of it.

A Vite app served from a folder (base: "/docs/" in vite.config) gets a manifest that links its pictures from that folder. ideare reads base without running the config. When code sets it, ideare says so: add "base": "/docs/" to ideare.json.

A card for each page

List pages in ideare.json to give them their own share card:

"pages": [
  { "path": "/about", "title": "About us" },
  { "path": "/pt", "locale": "pt-BR" }
]

A page with a title (and an optional subtitle) gets a card with that title, made on your computer. A page with only a locale gets the brand's card in that language. In Next.js's app/, the card goes in the page's own folder, as opengraph-image.png. In Vite and plain HTML, it goes in og/ of the public folder, and its tags go in the page's own HTML file (about.html or about/index.html). A page with no HTML file of its own, or a page in pages/, gets the file and a note with the tag to add.

Commands

npx ideare pull               # get the version ideare.json asks for ("latest" by default)
npx ideare pull --version 3   # get v3
npx ideare pull --frozen      # exactly what ideare.lock.json says, or fail
npx ideare status             # your version against ideare's, and files changed by hand
npx ideare check              # fail when a brand file differs from the lock (for CI)
npx ideare check --strict     # also fail on brand notes, like hard-to-read colors
npx ideare login              # sign in from the browser
npx ideare logout             # forget the key on this computer
npx ideare push               # send brand/ back
npx ideare open               # the brand's public page

push refuses when the brand changed in ideare since your last pull. From an owner or admin it publishes a new version and pulls it; from anyone else it waits for the owner to approve.

Every command takes --yes (answer yes) and --json (one JSON object on stdout, messages on stderr), for scripts and agents. In CI, set IDEARE_API_KEY instead of running login.

Send the files as a GitHub PR

npx ideare pull --pr

This gets the same approved version as pull. It lists the files, branch and GitHub repository, then asks before it writes or sends anything. Add --yes to go ahead without the question. With --json and no --yes, the confirmation error includes the plan, and nothing is written.

Use a git checkout at the latest commit of origin's default branch. Install GitHub CLI and run gh auth login first. origin must point to that GitHub repository. ideare uses your existing git and GitHub login. No GitHub App or new token is needed.

ideare creates a separate worktree under ~/.cache/ideare/pr-delivery/. It uses the usual file writer, backups and lockfile there, commits only the files it wrote or removed, pushes the new branch and opens a draft PR into the default branch. It never merges. Your current branch, files and staged changes stay untouched. With no file changes, there is no commit or PR.

Commit any edits to the brand files, ideare.json, the lockfile, head tags or CSS imports first. If Vite sets the site's base, commit its config and build script too. Clear assume-unchanged and skip-worktree on these files if set: those git flags hide local edits. Unrelated edits can stay. Local drafts (init --local or init --from-code) cannot be sent with --pr: approve the brand in ideare, then link the approved brand with init <brand> first. --version and --frozen still choose the version as they do with a normal pull.

If a push or PR request fails, ideare keeps the branch and worktree and prints a read-only command to check what happened. Run that command first: the push or PR may already exist. Do not run pull --pr again to recover the saved branch. After merging or closing the PR, remove its saved worktree with git worktree remove <printed-path> when you no longer need it.

With no account

npx ideare init --local --from brand.json

This makes every file on this computer from a brand.json (such as the one "Download my kit" gives you), with nothing native to install. pull makes them again from brand/brand.json.

To start from the project you already have:

npx ideare init --from-code

This reads your CSS variables (--primary, --background and the like, light and dark), your Tailwind theme, a logo file in public/ or src/assets/ (logo.svg, brand.svg, icon.svg), and the name, language and description in your page's head or package.json. It prints what it found and what it made up, then writes brand/brand.json and the files. No account, and no AI. A PNG logo stays out: ideare turns pictures into drawings in the studio. To put the brand in ideare, run npx ideare login, then npx ideare push.

Node 20.3 or later. MIT.