Getting Started

Quickstart

Install globally, choose your auth method, and start generating images and videos. No API key required for the default OAuth paths.

Install and run

npm install -g ima2-gen
ima2 setup
ima2 serve

Then open http://localhost:3333.

One-Click Install (no npm required)

Don't have Node.js or npm? Use the platform install script — it detects your environment, installs Node LTS if needed, then installs ima2-gen.

macOS

curl -fsSL https://lidge-jun.github.io/ima2-gen/install-mac.sh | bash

Windows (PowerShell)

irm https://lidge-jun.github.io/ima2-gen/install-windows.ps1 | iex

Linux / WSL

curl -fsSL https://lidge-jun.github.io/ima2-gen/install-linux.sh | bash

Each script checks for nvm/fnm/brew/winget, installs Node LTS through the best available method, and handles stale process cleanup automatically.

Port discovery. If 3333 is busy, ima2-gen binds the next free port and writes the real URL to ~/.ima2/server.json. Use ima2 open or the URL printed in the terminal instead of assuming the port.

Setup (choose auth)

ima2 setup offers four authentication methods:

  1. GPT OAuth — sign in with ChatGPT (free, images only)
  2. Grok OAuth — sign in with xAI/Grok (images + video)
  3. Both — GPT + Grok (full feature access)
  4. API Key — paste your OpenAI API key (paid)

Video generation requires Grok OAuth (option 2 or 3). Add it later with ima2 grok login, which defaults to the manual-paste flow.

If your GPT OAuth token expires, re-run ima2 setup (option 1) to refresh it.

Updating. Stop the server with Ctrl+C — ima2-gen performs a clean shutdown (closes DB, sockets, and child processes). Then run npm install -g ima2-gen@latest. If you see EBUSY on Windows, use the install script which handles stale process cleanup automatically.

Develop from source

git clone https://github.com/lidge-jun/ima2-gen.git
cd ima2-gen
npm install
npm run dev          # build the UI, run the TS server with --watch + diagnostics
npm run typecheck
npm test
npm run build

npm run dev builds the UI and starts the TypeScript server entry with --watch. Treat the .ts files as the source of truth; the paired .js artifacts are produced by the build, never edited by hand.