Makaron Character Library CLI

A portable, zero-dependency CLI and Agent Skill for creating distinct character identities and generating consistent images or videos through Makaron.

Install for an AI agent

npx makaron-character-library-cli setup

This performs the same two-stage installation pattern as makaron-cli setup:

1. installs the CLI globally;
2. copies the bundled makaron-character-library Skill into the selected Agent environment.

Target a specific supported Agent when needed:

npx makaron-character-library-cli setup --agent codex
npx makaron-character-library-cli setup --agent claude-code

The CLI can also run without global installation:

npx -y makaron-character-library-cli --help

Requires Node.js 18 or newer. Image/video rendering also requires makaron-cli authentication through MAKARON_API_KEY or ~/.makaron/auth.json. Never place the API key in a command, character record, repository, or log.

Quick start

export CHARLIB_LIBRARY="$HOME/.charlib"

charlib doctor --live --json
charlib init --name "My Characters" --json
charlib create \
  --name "Lin Xia" \
  --seed 1042 \
  --gender woman \
  --age-band young-adult \
  --culture-region east-asia \
  --personality gentle,curious \
  --role protagonist \
  --json

Generate the canonical face first. Later views automatically reuse approved face and full-body references:

charlib render --character lin-xia --view face-closeup --download --json
charlib render --character lin-xia --view full-body --download --json
charlib render --character lin-xia --view turnaround --download --json
charlib render --character lin-xia --view expression-grid --download --json
charlib render --character lin-xia --view presentation-board --download --json
charlib render --character lin-xia --view video-anchor --video-model seedance --download --json

For long jobs, submit asynchronously and resume by run ID:

charlib render --character lin-xia --view video-anchor --no-wait --json
charlib wait --run-id RUN_ID --character lin-xia --view video-anchor --download --json

Every operational command emits JSON. Errors use { "ok": false, "error": ... } and a non-zero exit code.

Data portability

No user-specific source path is embedded in the package. Each agent chooses its own library location with --library or CHARLIB_LIBRARY; the default is ~/.charlib on that machine.

Development

npm test
npm pack --dry-run
node bin/charlib.mjs setup --dry-run

The former Python implementation remains in src/character_library as a compatibility reference. The public npm package ships only the Node CLI, the single-file Agent Skill, plugin manifests, README, and license.