Frame Your Profile

A free and open-source API to frame your GitHub avatar using creative themes. Perfect for README files, portfolios, or social media.

🌐 Live API: https://github-avatar-frame-api.onrender.com

🧪 Live Examples by Theme

💻 CLI Usage

The GitHub Avatar Frame API comes with a command-line interface (CLI) for easy avatar generation directly from your terminal. Perfect for developers who prefer working in code editors and terminals.

🚀 Installation

Option 1: Install globally from npm

npm install -g github-avatar-frame-cli

Option 2: Use locally (from project root)

# Build the CLI
npm run build:cli

Use the CLI

npm run cli -- <command>

📖 Usage

Generate an avatar:

github-avatar-frame generate <username> [options]

Examples:

# Basic usage
github-avatar-frame generate octocat

# With custom theme and size
github-avatar-frame generate octocat --theme flamingo --size 512

# With text overlay
github-avatar-frame generate octocat --text "GitHub User" --text-color "#ff0000"

# With emojis
github-avatar-frame generate octocat --emojis "🚀,💻,🔥" --emoji-position corners

# Save to custom file
github-avatar-frame generate octocat --output my-avatar.png

# Use local API server
github-avatar-frame generate octocat --url http://localhost:3000

⚙️ CLI Options

Option	Default	Description
--theme, -t	base	Frame theme (base, classic, darkmode, eternity, flamingo, gitblaze, macros, minimal, neon, ocean, starry)
--size, -s	256	Avatar size in pixels (64-1024)
--canvas, -c	light	Background color (light, dark)
--shape, -sh	circle	Avatar shape (circle, rounded)
--radius, -r	25	Corner radius for rounded shape
--text, -tx	none	Custom text to display
--text-color, -tc	#ffffff	Text color in HEX format
--text-size, -ts	20	Text size in pixels (8-100)
--text-position, -tp	bottom	Text position (top, bottom, center)
--emojis, -e	none	Comma-separated list of emojis
--emoji-size, -es	40	Emoji size in pixels (16-120)
--emoji-position, -ep	top	Emoji position (top, bottom, corners)
--output, -o	avatar.png	Output file path
--url, -u	https://github-avatar-frame-api.onrender.com	API base URL

📋 Other Commands

# List available themes
github-avatar-frame themes

# Show API information
github-avatar-frame info

# Show help
github-avatar-frame --help

🤖 AI-Powered Frame Suggestions

The CLI also supports AI-powered frame suggestions that analyze your GitHub profile and recommend the perfect theme:

# Get AI-powered frame suggestion
github-avatar-frame suggest <username>

# Example
github-avatar-frame suggest octocat

https://github-avatar-frame-api.onrender.com/api/framed-avatar/{username}?theme={theme}&size={size}&canvas={canvas}&shape={shape}&radius={radius}

🧮 Query Parameters:

Parameter	Type	Default	Description	Example
username	string	required	GitHub username	octocat
theme	string	base	Frame theme (eternity, base, flamingo)	flamingo
size	integer	256	Avatar size in px (64–1024)	300
canvas	string	light	Background color of avatar canvas: light / dark	dark
shape	string	circle	Avatar shape: circle or rounded	rounded
radius	integer	25	Corner radius for rounded shape in px	50
text	string	optional	Custom text to display on avatar	Hello World
textColor	string	#ffffff	Color of text in HEX format	#ff0000
textSize	integer	20	Size of text in pixels (8-100)	24
textPosition	string	bottom	Position of text: top / bottom / center	top
emojis	string	optional	Comma-separated list of emojis	🚀,💻,🔥
emojiSize	integer	40	Size of emojis in pixels (16-120)	30
emojiPosition	string	top	Position of emojis: top / bottom / corners	corners

📌 Example with text and emojis:

https://github-avatar-frame-api.onrender.com/api/framed-avatar/octocat?theme=base&text=GitHub%20User&textColor=%23ffffff&textSize=20&textPosition=bottom&emojis=%F0%9F%9A%80%2C%F0%9F%92%BB%2C%F0%9F%94%A5&emojiSize=30&emojiPosition=top

Canvas	Shape	Radius	Example URL	Preview
light	circle	-	URL
dark	circle	-	URL
light	rounded	20	URL
dark	rounded	50	URL

📥 Embed in README

![My Avatar](https://github-avatar-frame-api.onrender.com/api/framed-avatar/your-username?theme=flamingo&size=256&canvas=dark&shape=rounded&radius=20)

🔧 Development Issues: 🧰 Installation problems

npm cache clean --force rm -rf node_modules package-lock.json npm install

🔌 Port conflicts 🔎 Check if port 3000 is in use netstat -ano | findstr :3000 Kill process or change port in server config