@creative-int/kumori

Kumori CLI

AI-powered image transformation from your terminal.

Distribution posture

The scoped @creative-int/kumori package is intentionally public on npm. The CLI uses the shared creative-int command chassis and Oclif manifest lifecycle, while the installed executable remains the short kumori command.

Install

npm install --global @creative-int/kumori
kumori --help

From this repository:

pnpm install
pnpm -C apps/cli build
node apps/cli/bin/run.js --help

Commands

kumori image.jpg --filter anime
kumori generate image.png --filter holo --sticker
kumori generate
kumori filters
kumori tui
kumori auth
kumori whoami
kumori logout

Running kumori <input> remains the short form for kumori generate <input>. Running kumori with no arguments opens an interactive local image picker and then the live Convex filter catalog. kumori filters reads the same live catalog, with a short local cache for transient network failures.

kumori tui launches the sibling Rust terminal studio. From a source checkout, run pnpm tui:build first if the binary has not been built.

Shell and machine contract

• Human output uses the shared chrome, scene, and footer slots from @creative-int/cli-kit/shell.
• --json and --format json return the canonical cli-core { data, meta } success envelope.
• --ndjson emits one canonical envelope per command result.
• Typed failures emit { error, meta } without interactive prompt output.
• auth and logout stay intentionally interactive because they open a browser or delete the local token.

Exit codes are stable across text and machine output:

Code	Meaning	Next action
0	Success or intentional cancellation	None
1	Generation/backend failure	Retry; use --json for the typed error
64	Invalid command usage	Check kumori <command> --help
66	Missing or invalid input file	Fix the input path or image
78	Authentication, network, or service configuration unavailable	Run kumori auth for auth failures, or check connectivity and retry

Authentication and environment

kumori auth starts a device authorization, opens Kumori's own /cli/authorize page, and stores the revocable operator grant in ~/.kumori/auth.json. The CLI never opens an auth-vendor consent page or a localhost callback. Each command exchanges the stored grant for a short-lived Convex session.

Non-interactive generation can provide a short-lived Convex JWT through KUMORI_AUTH_TOKEN or a revocable operator grant through KUMORI_OPERATOR_TOKEN. KUMORI_AUTH_API_URL overrides the production Convex HTTP endpoint for local testing. CONVEX_URL overrides the development deployment; --prod selects Kumori's production deployment.

Verification

pnpm verify
pnpm prepack
pnpm postpack

verify runs package lint, typecheck, build, command tests, and help smoke. prepack generates oclif.manifest.json; postpack removes it after package proof.