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.