Getting Started

Quickstart

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

Mac app

On an Apple Silicon Mac the desktop app is the quickest start: download the signed DMG, drag ima2 into Applications and open it. See Mac App.

Install and run

Requires Node.js 22 or newer.

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-ai.github.io/ima2-gen/install-mac.sh | bash

Windows (PowerShell)

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

Linux / WSL

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

Each script checks for nvm/fnm/brew/winget, installs Node LTS through the best available method, then installs ima2-gen.

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. Web setup — skip the terminal and pick providers or add API keys in the web UI Settings

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, stop every running ima2 process (ima2 stop) and run the install again.

Develop from source

git clone https://github.com/lidge-ai/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.