Phottly CLI

AI photoshoots from your terminal — or from any coding agent. One face photo in, a stream of phone-camera-realistic 9:16 photos out, with the same person in every shot.

Install · Commands · MCP / agents · Recipes · phottly.com

---

_{Same person, three scenes. Nothing here was photographed — one reference face, three generations.}

Install

npm install -g phottly
phottly login          # opens the browser, OAuth 2.1 + PKCE, token stored in ~/.phottly

Node 18.17+. Zero dependencies — the whole client is one file, bin/phottly.js, and you can read all of it in a couple of minutes.

Quickstart

phottly avatars                                    # list your reference faces
phottly generate --mode ultrareal_selfies \
                 --avatar <asset-id> \
                 --frames 4 --lighting bright --wait

--wait polls until the shoot finishes and prints one URL per frame. Without it you get a generation id and poll yourself:

phottly status <generation-id> --wait
phottly save <generation-id> --title "Spring set"   # keep it in your gallery

Commands

Command	What it does
phottly login	Browser OAuth. Credentials land in ~/.phottly/credentials.json, mode 0600.
phottly logout	Clears them.
phottly credits	Balance and plan, as JSON.
phottly avatars	Your reference avatars — the id is what --avatar wants.
phottly generate	Starts a shoot. See flags below.
phottly status <id>	Progress, frame URLs, or the failure reason. Add --wait to block.
phottly save <id>	Persists the frames to your gallery.

Generate flags

Flag	Values	Notes
--mode	posts, selfies, ultrareal_selfies, ultrareal_fits, custom	Required in practice; defaults to custom.
--avatar	asset id	Required. From phottly avatars.
--frames	integer	Default 2. Each frame costs credits.
--lighting	dark, mix, bright	ultrareal_* modes only.
--resolution	1K, 2K, 4K	Default 1K.
--prompt	free text	Scene description for custom, or an override elsewhere.
--preset	preset name	posts mode.
--model	render model	Advanced; leave unset unless you know which one you want.
--wait	—	Poll to completion instead of returning immediately.

Modes

Mode	Output
ultrareal_selfies	Phone-camera selfies — the realism-first mode. Grain, imperfect framing, real skin.
ultrareal_fits	Outfit / mirror-shot sets from the same face.
posts	Feed-style photos built from a curated scene preset.
selfies	Selfies with on-image text, for hook-style posts.
custom	Your own scene, via --prompt.

Use it from an agent

The same account works over MCP, so Claude Code, Claude Desktop, Cursor or anything else that speaks MCP can run shoots directly:

https://phottly.com/mcp

Setup per client, plus the tools it exposes (modes, preset categories, credit quotes, async start/status): docs/mcp.md.

Recipes

Batch a week of content, build a UGC ad set, keep one identity across a whole campaign, wire generation into CI — docs/recipes.md.

# a week of feed posts, one per scene, all the same person
for scene in "morning coffee, kitchen window" "walking the dog, autumn park" "gym mirror, evening"; do
  phottly generate --mode custom --avatar "$AVATAR" --prompt "$scene" --frames 2 --wait
done

What people build with it

People show up looking for slightly different things — an AI selfie generator, AI photos of yourself, a general AI image generator, AI influencer content — and end up running one of these:

You want	Run
AI selfies of yourself that don't look plastic — realistic AI selfies from one photo, same face every time	--mode ultrareal_selfies
AI dating profile photos — a set for Tinder, Hinge or Bumble that looks like a life, not a six-photo headshot drop	--mode ultrareal_selfies --frames 6
An AI Instagram feed — post on Instagram without taking photos, keep a faceless Instagram page filled	--mode posts in a loop, one scene per day
AI influencer content — run a virtual influencer that posts daily without prompting	fixed --avatar, varied --prompt
Faceless TikTok / Reels / Shorts — 9:16 vertical stills and hooks without filming	--mode selfies for on-image hook text
UGC-style ad creative — the same presenter across a whole ad set	one avatar, one prompt per angle

All output is 9:16 vertical, sized for TikTok, Instagram Reels and YouTube Shorts.

FAQ

Is this an AI selfie generator or an AI photo editor?

A generator. You give it one reference face and it makes new photos of that person in new scenes. It is not a general AI photo editor — if you want to edit photos you already have (retouch, enhance, upscale, filter an existing shot), this is the wrong tool. AI image editing and AI photo generation are two different jobs and one tool rarely does both well.

How is it different from Lensa, Remini, EPIK or Aragon?

Those are mostly one-and-done: you buy a batch of avatars or headshots, or you enhance a photo you already took, and that's the transaction. Phottly is built for an ongoing stream — the same identity, new scenes, indefinitely, plus video. If you need 40 LinkedIn-style headshots once, a headshot tool is cheaper. If you need to keep posting, that's the gap this fills.

How does it keep the same face across generations?

Identity comes from the avatar (your uploaded reference), not from the prompt. Pass the same --avatar id and the person stays the same across every scene, lighting and outfit. That's the whole reason the CLI exposes avatars as first-class ids.

Why do most AI generated images look fake, and these less so?

Because most tools optimise for pretty: even skin, perfect symmetry, studio light, shallow depth of field. Real phone photos have grain, uneven light, slightly wrong framing and visible skin texture. The ultrareal_* modes optimise for the phone-camera look rather than the render look — which is also why --lighting dark reads as more believable than bright even though it's noisier.

Is there a free AI photo generator tier?

No free trial. Generation costs credits, on a plan or as one-time credit packs — phottly.com/pricing. The CLI itself is free and MIT-licensed; it's the generation that costs money, because GPUs do.

Can it do video?

The product does — short 9:16 clips and hooks alongside stills. This CLI covers the photo modes; video runs in the web studio and the iOS app for now.

Can an AI agent drive it?

Yes — that's what MCP is for. Claude Code, Claude Desktop, Cursor or anything speaking MCP can list modes, quote credits, start a shoot and poll it.

How it works

1. Upload one clear face photo on phottly.com or in the iOS app — that becomes an avatar.
2. Pick a mode (or a preset scene). No prompt engineering required; custom is there when you want it.
3. Generate. Every frame keeps the same identity, in 9:16, at phone-camera realism rather than glossy-render realism.
4. Save or download. Frame URLs are printed by status; save files them in your gallery.

Generation costs credits — plans and credit packs are on phottly.com/pricing.

Notes

• Auth is OAuth 2.1 with PKCE and dynamic client registration against phottly.com. No API key to paste, nothing secret in this repo.
• PHOTTLY_BASE_URL overrides the host, for self-hosted or staging deployments.
• Generations are async. A 4-frame shoot takes a while; --wait polls every 10s.
• Be a person about likeness. Generate faces you have the right to use — yours, a consenting model's, or a synthetic one. The examples above are synthetic.

License

MIT. The CLI is a thin client over the public Phottly API; the service itself is not open source.

phottly.com · npm · built by @n1-ghosty