shipart

your README deserves better than a blank top.

generate README hero images for open source projects using AI. one command, six built-in themes, three dynamic theme modes powered by nano banana 2 (gemini-3.1-flash-image-preview).

$ shipart .

shipart → /home/user/myproject
  name:        myproject
  description: a fast CLI for developers
  category:    CLI tool
  tech:        Node.js, TypeScript, CLI
  theme:       terminal-dark

  generating with gemini-3.1-flash-image-preview... (attempt 1/3)
  saved → /home/user/myproject/banner.png (1.1 MB)

done. 1 banner(s) generated.
  → /home/user/myproject/banner.png

---

api key

get a free key at aistudio.google.com/apikey, then:

export GOOGLE_AI_KEY=your_key_here

shipart also checks GEMINI_API_KEY, ~/.openclaw/workspace/.credentials/google_ai_key, and ~/.config/shipart/key.

---

install

npm install -g @safetnsr/shipart

or run without installing:

npx @safetnsr/shipart .

---

usage

shipart .                                          # generate for current directory
shipart ./myproject                                # specify directory
shipart . --theme bold                             # choose built-in theme
shipart . --output ./docs/hero.png                 # custom output path
shipart . --variations 3                           # generate 3 alternatives
shipart . --model gemini-2.5-flash                 # use a different google model
shipart . --patch-readme                           # also update README.md
shipart . --dry-run                                # preview the prompt
shipart --list-themes                              # show all built-in themes

---

themes

six built-in themes:

terminal-dark — pure black bg, white monospace text, terminal aesthetic

minimal — white bg, clean typography, lots of negative space

bold — high-contrast, large typography, vibrant background

gradient — dark gradient bg (deep blue → purple), modern SaaS look

retro — pixel art / 8-bit aesthetic, bright colors on dark

paper — off-white, subtle texture, editorial/blog feel

---

dynamic themes

the killer feature: generate themes from real sources.

--theme-from-url

screenshots the URL, extracts dominant colors, uses it as your theme:

shipart . --theme-from-url https://linear.app

requires playwright: npm install playwright && npx playwright install chromium

--theme-from-css

parses CSS custom properties from your stylesheet:

shipart . --theme-from-css ./src/globals.css

works with any CSS file containing --primary, --background, --accent, etc. also detects tailwind config.

--theme-prompt

describe your aesthetic in plain text:

shipart . --theme-prompt "dark purple glassmorphism, blurred edges, neon accent"

---

smart project reading

shipart reads your project automatically:

• package.json — name, description, keywords, main dependencies
• pyproject.toml / Cargo.toml / go.mod — fallback for python, rust, go projects
• README.md — first H1, first paragraph, code block languages

---

options

flag	description	default
--theme <name>	built-in theme	terminal-dark
--theme-from-url <url>	extract theme from website	—
--theme-from-css <file>	extract theme from CSS	—
--theme-prompt <text>	custom theme description	—
--model <id>	google AI model to use	gemini-3.1-flash-image-preview
--variations <n>	number of images (1-3)	1
--output <path>	output file path	./banner.png
--patch-readme	prepend banner to README.md	false
--dry-run	print prompt, don't generate	false
--list-themes	show available themes	—

---

mit license