Skip to content

Commands

commands

Typer command implementations for the Mirumoji CLI

Each CLI command uses Typer and Rich to expose the shared core's functionality in a user-friendly way

build(transcribe=None, version=None)

Builds the Mirumoji images locally from source

Clones/Updates the managed mirumoji repo checkout at the resolved version's release tag and builds the frontend + backend images locally for the chosen backend

Backend Resolution

The backend value is resolved in the following order

  • Value Passed To --transcribe, If Present

  • Value Stored in Config, If Present

  • Default Value (MODAL)

Version Resolution Order

The release tag whose source is built is resolved in the following order

  • Value Passed To --image-version, If Present

  • MIRUMOJI_IMAGE_VERSION Stored In Config, If Present

  • Shell's MIRUMOJI_IMAGE_VERSION Environment Variable, If Present

  • Default Value (The Installed Package Version)

The locally built images always carry the local build tags, so the version only selects which release's source (its v<version> git tag) is built

config_clear()

Removes All Keys from The Launcher's Managed Configuration

config_delete(key)

Removes A Single Key From The Launcher's Managed Configuration

config_import(path)

Imports A Custom .env File Into The Launcher's Managed Configuration

Merges the file's variables into the managed config, overriding existing values and keeping any the file omits

config_path()

Prints The Path To The Launcher's Managed Configuration File

config_set(key, value)

Sets (Upserts) A Single Key In The Launcher's Managed Configuration

Rejects unknown keys, and validates the value for the deployment keys (MIRUMOJI_TRANSCRIBE_BACKEND / MIRUMOJI_IMAGE_SOURCE)

config_show(raw=False, output_json=False)

Shows The Launcher's Managed Configuration, Masking Secret Values

Pass --raw to reveal the secret values in full, for copying a generated password or auditing a key

dev_server(host='0.0.0.0', port=8000, reload=False)

Runs the Mirumoji server with uvicorn

Launches the FastAPI server directly with uvicorn (no Docker), using the app factory. Intended for local development and Python-only iteration

dev_up(transcribe=None, path=None, detach=True)

Launches the Mirumoji Docker Compose Application For Development

Builds the Mirumoji images locally from a mirumoji repo clone at an arbitrary path without updating it

Intended for development only. Accepts a path to a mirumoji repo checkout and builds the frontend + backend images locally for the chosen backend

Backend Resolution

The backend value is resolved in the following order

  • Value Passed To --transcribe, If Present

  • Value Stored in Config, If Present

  • Default Value (MODAL)

Steps

  • Resolves the backend according to the order of precedence listed above

  • Validates that every required variable is configured (the managed config file is never altered in a run)

  • Acquires the host's LAN IPv4 to build the frontend's self-signed certificate

  • Builds the correct compose file based on the backend choice

  • Builds images locally

  • Runs Docker Compose Up using the managed config as the --env-file

doctor()

Reports the status of every external dependency

Runs every environment check and renders a report informing which pre-requisites are present and which are missing

down(volumes=False, yes=False)

Stops the Mirumoji Docker Compose Application

gui()

Launches the Mirumoji desktop GUI

Launches the Flet desktop GUI. Requires the gui extra (Flet). The shipped standalone executables are built separately

logs(service=None, follow=False, tail=None)

Streams logs from the Mirumoji Docker Compose application

Streams Docker Container logs for the whole compose application or a single service

modal_deploy(gen_password=False, force=False, version=None, host_on_gpu=None, nonpreemptible=None)

Deploys A Fully Functional Mirumoji App To Your Modal Account

Deploys a Modal web function running a FastAPI app serving both the modal transcribe backend and the built frontend

The app is accessible at the printed URL and gated by HTTP Basic Auth with mirumoji as the username and the MIRUMOJI_WEB_PASSWORD managed config variable as the password

--generate-password (-gp)

  • When this flag is passed, a unique password is generated and stored in the managed config under MIRUMOJI_WEB_PASSWORD

  • When this flag is passed and MIRUMOJI_WEB_PASSWORD already exists as a variable in the managed config (mirumoji config show), or as an environment variable in the current shell, the already-existent value is used and no new password is created

  • When this flag is not passed and the MIRUMOJI_WEB_PASSWORD variable doesn't exist in either the managed config or the current shell, this command displays an error message

  • The MIRUMOJI_WEB_PASSWORD set in the managed config has preference over the one set in the current shell and is the one that will be used when both are set

Idempotent Deployment

  • Re-running this command rolls the app forward only on version bumps without ever creating duplicates

  • Pass --force (-f) to always redeploy the app

Version Resolution Order

The version value is resolved in the following order

  • Value Passed To --image-version, If Present

  • MIRUMOJI_IMAGE_VERSION Stored In Config, If Present

  • Shell's MIRUMOJI_IMAGE_VERSION Environment Variable, If Present

  • Default Value (The Installed Package Version)

Distinction From The Mirumoji modal-offload App

  • When running mirumoji locally with the modal transcribe backend set up, the server automatically creates and manages a different Modal app called mirumoji-offload

  • mirumoji-offload is configured using your mirumoji-managed configuration variables (MIRUMOJI_MODAL_SCALEDOWN_WINDOW, MIRUMOJI_MODAL_GPU, MODAL_FORCE_BUILD, MODAL_TOKEN_ID, MODAL_TOKEN_SECRET, MIRUMOJI_MODAL_IMAGE), is always GPU-enabled, and always scales down to 0 when there's no GPU-task running

  • The Modal app that this command deploys (mirumoji-host) runs the server with the modal transcribe backend and serves the frontend in a single Modal CPU-Only container that only scales down when the app is stopped (mirumoji modal down)

  • The server running in the mirumoji-host app will automatically create a mirumoji-offload app (or use an already live one) with your mirumoji-managed configuration whenever you request a task that needs a GPU, which means that both apps will exist simultaneously

  • This separation exists because letting a GPU-enabled container sit idly can incur expensive idle-GPU charges. Separating the cheap CPU-only operations (running in mirumoji-host) from the expensive operations that require a GPU (mirumoji-offload) avoids these extra unnecessary charges because mirumoji-offload always scales to 0 (meaning it is never running unless an active GPU task needs it), while mirumoji-host keeps running at all times to make the app accessible (for watching videos, Japanese-tokenization, dictionary-lookups, etc...)

App Configuration

All of your mirumoji-managed configuration (mirumoji config), such as LLM keys and modal-offload configuration (scaledown window, which GPU is used), is passed to the container running mirumoji-host as a Modal Secret, so this is like running the local modal transcribe backend, with the only difference being that everything (including what would normally run locally) will be running in Modal

App Data
  • Unlike the local mirumoji up, which keeps your data as local Docker volumes, the data you upload or generate while using the hosted app (your media files and the mirumoji database) is kept inside an automatically created, or reused, Modal volume
- You can download this data at any time with `mirumoji modal
  download-data`

- You can also delete the entire volume at any time with
  `mirumoji modal down -v`

modal_down(volume=False, yes=False)

Stops the Modal-Hosted App And Optionally Deletes Its Data Volume

Offload Worker

The GPU-offload worker is owned by the server and stopped by it during shutdown

Volume Deletion

  • The data volume is only deleted when --volume is passed. Modal refuses to delete a volume mounted on a running app, so the app is stopped first

  • When --volume is passed, a failed stop (the app is already stopped or was never deployed) is only a warning, so the volume can still be deleted

  • Deleting it permanently erases the hosted profiles, media, and database

modal_download_data(destination=Path('mirumoji-data'))

Downloads The Modal-Hosted App's Data Volume To A Local Directory

Downloads everything in the mirumoji-data volume (the media you uploaded and the mirumoji database) so it can be backed up or inspected locally. Re-downloading into the same directory overwrites the existing copies

modal_logs(tail=100, follow=False)

Shows The Modal-Hosted App's Logs

Fetches the most recent host log entries, or live-streams them with --follow. Useful for diagnosing a deploy or a failing job on the host

A followed stream starts from the newest entries, so --tail only applies to a one-shot fetch

modal_status()

Shows The Status Of The Modal-Hosted App + Its Data Volume

mirumoji-offload

The GPU-offload worker Modal app is owned by the server (deployed on the first GPU call and torn down in its lifespan), so it is not shown or managed here

pull(transcribe=None, version=None)

Pulls the Mirumoji images from Docker Hub

Pulls the pre-built Mirumoji Docker Images from Docker Hub for the chosen backend

Backend Resolution

The backend value is resolved in the following order

  • Value Passed To --transcribe, If Present

  • Value Stored in Config, If Present

  • Default Value (MODAL)

Version Resolution Order

The version value is resolved in the following order

  • Value Passed To --image-version, If Present

  • MIRUMOJI_IMAGE_VERSION Stored In Config, If Present

  • Shell's MIRUMOJI_IMAGE_VERSION Environment Variable, If Present

  • Default Value (The Installed Package Version)

render(transcribe=Backend.MODAL, build=False, version=None, output=Path('docker-compose.yaml'))

Renders a resolved docker compose file from the packaged template

Writes a resolved compose file from the packaged template for a chosen backend + image source. Used to produce the static files referenced by the manual-install documentation

Version Resolution Order

The version value is resolved in the following order

  • Value Passed To --image-version, If Present

  • MIRUMOJI_IMAGE_VERSION Stored In Config, If Present

  • Shell's MIRUMOJI_IMAGE_VERSION Environment Variable, If Present

  • Default Value (The Installed Package Version)

reset(keep_config=False, keep_logs=False, yes=False)

Deletes Mirumoji's Local Data Folder From This Machine

Removes media, the database, cached builds, and (unless kept) the config and logs. Docker data volumes are not touched, use down --volumes for those

status()

Displays the status of the Mirumoji Docker Compose application's services

Shows the running compose application's services and their health as a table

up(transcribe=None, build=None, detach=True, version=None)

Launches the Mirumoji Docker Compose Application

Backend Resolution

The backend value is resolved in the following order

  • Value Passed To --transcribe, If Present

  • Value Stored in Config, If Present

  • Default Value (MODAL)

Image Source Resolution

The image source value is resolved in the following order

  • --pull / --build flags, If Present

  • Value Stored in Config, If Present

  • Default Value (PULL)

Version Resolution Order

The version value is resolved in the following order

  • Value Passed To --image-version, If Present

  • MIRUMOJI_IMAGE_VERSION Stored In Config, If Present

  • Shell's MIRUMOJI_IMAGE_VERSION Environment Variable, If Present

  • Default Value (The Installed Package Version)

Steps

  • Resolves the backend / image source according to the order of precedence listed above

  • Validates that every required variable is configured (the managed config file is never altered in a run)

  • Acquires the host's LAN IPv4 to build the frontend's self-signed certificate

  • Builds the correct compose file based on the backend / image source choice

  • Builds images locally for a build source. For a pull source it does not pull explicitly, letting docker compose up fetch only the missing images (use mirumoji pull to refresh on demand)

  • Runs Docker Compose Up using the managed config as the --env-file