CLI & terminal companion

lumorig is Lumorig in your terminal. It creates, rebuilds, animates and exports mascots over the API, draws them right in the terminal, and runs a companion that shows what your coding agent is doing. It is built on the TypeScript SDK, so it behaves exactly like the API.

Install and log in#

The package is lumorig; it installs the lumorig binary and the short alias lr (lr create … works everywhere lumorig create … does). Run it with npx, or install it globally so hooks can call lumorig directly. The old mf binary still works but is deprecated; a config saved under ~/.config/mascotforge is picked up until you log in again.

$ npm install -g lumorig
$ lumorig login
Create a key in the studio (Settings → API keys), then paste it here.
API key: lr_sk_…
✔ Logged in. Saved to ~/.config/lumorig/config.json

Config lives at ~/.config/lumorig/config.json (written with mode 600). Set LUMORIG_HOME to use another directory. The environment wins over the file: LUMORIG_API_KEY overrides the saved key and LUMORIG_URL overrides the saved server URL (useful for self-hosting).

Commands#

Flags#

Export file names#

Without -o, lumorig export writes <id>-<animation or format>.<ext> in the current directory, where the extension comes from the file type. Lottie is written as .lottie.json, so lumorig export msc_4hq8z -f lottie -a wave produces msc_4hq8z-wave.lottie.json. Still formats (png, svg, sticker, logo, logo-png) need no animation; animated ones default to wave.

Play in the terminal#

lumorig play renders a mascot as a live pixel grid in your terminal and runs until Ctrl-C (or --seconds). It takes a mascot id (the bundle is fetched with your key) or a local .json file containing either a MascotSpec or a bundle with { spec, clips }, validated before it plays. The animation can be a saved animation name or any preset, fitted on the spot.

$ lumorig play msc_4hq8z celebrate
$ lumorig play ./mascot.spec.json dance --cols 48 --seconds 5

Terminal companion#

lumorig companion runs a mascot in a side terminal on the ai_agent canvas template. It watches a small state file that lumorig state writes, and moves between five states:

Wire it to Claude Code with hooks. lumorig hooks prints the configuration below; lumorig hooks --write merges it into ./.claude/settings.json, keeping your existing hooks and skipping events that already call lumorig state.

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "lumorig state working"
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "lumorig state working"
          }
        ]
      }
    ],
    "Notification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "lumorig state waiting"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "lumorig state done"
          }
        ]
      }
    ]
  }
}

$ lumorig companion msc_4hq8z     # or a local spec.json; remembered for next time
$ lumorig companion               # uses the remembered mascot

Scripting#

Progress goes to stderr and results to stdout, so pipes stay clean. When stderr is not a terminal, progress is printed as plain lines instead of a spinner. Errors exit with status 1 and a one-line message (API validation details are listed under it).

export LUMORIG_API_KEY=lr_sk_…

id=$(lumorig create "a cheerful lighthouse keeper" --style flat --json | jq -r .id)
lumorig animate "$id" celebrate
lumorig export "$id" -f lottie -a celebrate -o public/mascot.lottie.json
lumorig export "$id" -f sticker --size 512 -o public/sticker.png

• Use from AI agents (MCP)lumorig mcp runs the same server over stdio.
• Export formatsWhat each format is good for.