Makaron Persona + Look CLI

makaron-persona-look-cli keeps stable character identity (Persona) separate from styling (Look). It provides owner-local administration plus a Worker-backed library that an Agent can search, and uses Makaron as the default render engine for one customer-ready three-view turnaround image.

What an Agent gets

find is the no-generation delivery route: --kind persona returns matched Persona library images, and --kind look returns matched Look library images. --count N (default 1) returns exactly N different references or BLOCKED; --exclude ID[,ID...] omits prior internal selections, including records that share their source image. It does not expose IDs or selection metadata to the end user. preview downloads the selected Persona source/approved auxiliary views and the Look source, plus a safe selection.json render brief. It is intentionally a source-reference pack, not a synthesized image. render is the combined Persona + Look delivery route: it creates a locked selection for each requested result, sends those private inputs to the caller's authenticated Makaron CLI, and writes one full-body front/right-side/back turnaround sheet per selection. The Persona is the only identity reference; the Look image's face is excluded.

The raw private-library/ is ignored by Git and is never included in the npm package. D1 holds catalog metadata, private R2 holds approved source bytes, and a Worker issues an individual credential to each enrolling Agent. The individual credential is stored only in the Agent's local mode-600 config file and is never printed by the CLI.

One-command Agent setup

After the Worker has been deployed, the reviewed library has been synced, and the released package contains that HTTPS Worker URL in personlib.default_api_url, any Agent can run:

npx -y makaron-persona-look-cli setup

That command installs the CLI and the makaron-persona-look Skill globally, creates a per-Agent Worker credential through open self-registration, and saves it locally. No registration token needs to be handed to the Agent.

For a pre-release or a Worker URL that is not yet embedded in the package, use the same command with an explicit endpoint:

npx -y makaron-persona-look-cli setup --api-url https://your-worker.example
personlib remote doctor --json
personlib remote preview --brief '为一个20秒 K-pop 女团舞台视频找冷感、银黑未来街头造型人物参考图' --output-dir ./personlib-selection --json

The Worker is deployed at https://personlib-agent.bzz0309.workers.dev and its HTTPS URL is embedded in the package. prepublishOnly blocks a future npm release if that endpoint is removed.

Owner deployment

See the Worker deployment guide. The owner must first create the private R2 bucket and D1 database, deploy the Worker with OPEN_ENROLLMENT="true", supply a private OWNER_SYNC_TOKEN, and synchronize the reviewed library:

personlib remote sync --library ./private-library --dry-run --json
personlib remote sync --library ./private-library --json

remote sync remains owner-only. It uploads private asset bytes in controlled batches after its manifest write, so a partial network failure can be safely rerun without exposing sources. Open enrollment authorizes Agents to receive their own credentials, but does not expose an anonymous catalog or direct R2 object URLs.

Agent natural-language route

Once setup and remote doctor succeed, use the route that matches the request:

# Persona-only: return matching library image(s); no Makaron request.
personlib remote find --kind persona --brief '3个长相高冷的亚洲女生' --count 3 --output-dir ./personlib-personas --json

# Follow-up internal search: exclude the previous records without exposing their IDs to an end user.
personlib remote find --kind persona --brief '长相高冷的亚洲女生' --count 2 --exclude P-001,P-002 --output-dir ./personlib-personas-next --json

# Look-only: return matching library image(s); no Makaron request.
personlib remote find --kind look --brief '3套 Y2K 的妆造' --count 3 --output-dir ./personlib-looks --json

# Persona + Look: create locked selections internally, then render each exact selection.
personlib remote render --brief '3个都市风格的亚洲女生' --count 3 --output-dir ./personlib-turnarounds --dry-run --json
personlib remote render --brief '3个都市风格的亚洲女生' --count 3 --output-dir ./personlib-turnarounds --json

The third route is a paid external generation action. render --brief first creates Agent-bound, 24-hour selection tokens containing the exact Persona plus catalog Look or a complete temporary Look specification, then resolves those exact tokens; it never reranks or silently swaps a result after selection. A pre-confirmed single selection can also be rendered with --selection. In the owner-approved direct-delivery mode, an Agent keeps tokens internal and makes exactly one Makaron submission per selection without a second user confirmation. A batch writes turnaround-01/, turnaround-02/, and so on; each directory contains one turnaround image (or a pending run ID with --no-wait), turnaround-plan.json, prompt_used.md, and qc_report.md. If a find request has fewer than --count distinct eligible records after exclusions, it returns BLOCKED, insufficient_matches: true, and the available count without downloading partial or duplicate images. The CLI removes only brand identifiers: visible logos, wordmarks, brand names, protected monograms, recognizable trademark symbols, and brand/team crests. Ordinary stripes, numbers, abstract graphics, and shoe construction remain part of the Look. The CLI never automatically retries a paid job. Use --dry-run to inspect every locked request and complete prompt without downloading inputs or submitting anything, or --no-wait to keep returned Makaron run IDs for later retrieval.

亚洲女生 is a hard retrieval and render condition, not a visual guess. The Worker requires both an owner-reviewed east_asian appearance tag and the Persona metadata presentation: "feminine adult"; no matching record returns BLOCKED before Makaron is called. 韩国女生 additionally requires korean_style_compatible. Appearance tags are never inferred by the running model. The current library needs owner review before any existing Persona is made eligible for these requests.

都市, urban, city, city chic, and downtown all retrieve the urban/commute/editorial Look family; users do not need to rewrite 都市风格 as 都市通勤.

性感, sexy, sensual, 夜生活, 夜店, nightlife, and 约会夜 retrieve owner-reviewed adult evening Looks only; they never use a Look source face as the rendered identity.

For an explicit free Persona + Look source-reference pack, retain preview:

personlib remote preview --brief '20 秒嘻哈说唱女 rapper 舞台视频，红黑街头风、宽松工装、强节奏' --output-dir ./personlib-selection --json

Local owner-admin commands

node bin/personlib.mjs list --library ./private-library --json
node bin/personlib.mjs show --persona P-001 --library ./private-library --json
node bin/personlib.mjs review-persona --persona P-001 --appearance-tags east_asian,korean_style_compatible --reviewed-by owner-name --owner-confirmed --library ./private-library --json
node bin/personlib.mjs show --look L-001 --library ./private-library --json
node bin/personlib.mjs review-look --look L-001 --family 'adult hip-hop streetwear' --silhouette 'relaxed low-rise layered proportion' --garments 'unbranded color-block jacket, cropped top, baggy denim and retro sneakers' --palette 'red, blue, ivory and indigo' --materials 'nylon, cotton jersey and washed denim' --accessories 'minimal metal chain' --scene 'neutral adult music-fashion studio' --reviewed-by owner-name --owner-confirmed --library ./private-library --json
node bin/personlib.mjs recommend --brief '请使用人物资产库，为一个 15 秒高端美妆广告找一位 25 岁左右、东亚、干净冷感的女性人物。' --library ./private-library --json
node bin/personlib.mjs fetch --brief '请为一个 15 秒成年女性地铁皮夹克通勤广告找一套都市造型。' --output-dir ./selection --library ./private-library --json
node bin/personlib.mjs compose --persona P-003 --look L-011 --library ./private-library --json
node bin/personlib.mjs validate --library ./private-library --json

To intake a new owner-authorized reference:

node bin/personlib.mjs intake \
  --image /absolute/path/to/reference.png \
  --reference /absolute/path/to/second-face-view.png \
  --reference /absolute/path/to/third-face-view.png \
  --into persona \
  --rights authorized \
  --library ./private-library --json

intake records neither facial nor styling assertions automatically. A human/vision-review step adds Persona or Look fields. A Look always carries a source-face exclusion and brand-sanitization rule.

review-persona is an owner-only manual-audit command. It writes the reviewed tags plus reviewer/time provenance; do not run it from an image model, an automatic classifier, or an Agent guess. review-look is the equivalent owner-only gate for a new Look: all seven structured styling fields, source-face exclusion, source-brand replacement, and reviewer/time provenance are required before it can become private-staged. Follow either review with owner remote sync so the Worker receives only approved metadata and private source bytes.

Test

npm test
npm run test:remote
npm pack --dry-run --json