Mawaku CLI ✨

Craft richly lit video-call backdrops from a single prompt. Mawaku (間 ma “space, pause” + 枠 waku “frame”) is a Rust-powered command-line companion that turns location, season, and time-of-day hints into AI-generated interiors.

---

Table of Contents

• Quickstart
• Spotlight Prompts
• Configuration
• Docker Workflow
• Development

---

Quickstart

🧰 Prerequisite: Rust 1.76+ with rustup installed.

1. Install dependencies and view the CLI help

   cd mawaku-rs
   cargo run -p mawaku -- --help

2. Generate a prompt (location is required)

   cargo run -p mawaku -- \
     --location "Lisbon, Portugal" \
     --season spring \
     --time-of-day dusk

3. Export your Gemini API key once

   export GEMINI_API_KEY="your-secret"

   Mawaku reads this variable each time it runs (and warns loudly if it is absent), so you never have to edit the config with raw secrets.

---

Precompiled Linux binaries

Prefer not to install Rust? Every GitHub Release publishes ready-to-run archives built by CI. Pick the archive that matches your host CPU and follow the steps below.

TAG=v0.0.1          # replace with the release you want

x86_64 hosts

ASSET=mawaku-${TAG}-linux-x86_64.tar.gz

ARM64 hosts (e.g., dev container on Apple Silicon)

ASSET=mawaku-${TAG}-linux-arm64.tar.gz

Download, extract, and install

curl -L -o "$ASSET" "https://github.com/Bennoo/mawaku-cli/releases/download/${TAG}/${ASSET}"
mkdir -p ~/.local/bin
tar -xzf "$ASSET" -C ~/.local/bin mawaku
chmod +x ~/.local/bin/mawaku

Move the extracted mawaku binary anywhere on your PATH (for example, /usr/local/bin or ~/.local/bin) to invoke it from any directory.

export PATH="$HOME/.local/bin:$PATH"
mawaku --help

---

Spotlight Prompts

Get inspired by a few curated scenes. Each command runs from the mawaku-rs/ workspace root.

Scene	Command	Mood
Italian Coastal Morning	cargo run -p mawaku -- --location "Italian coastal village" --season summer --time-of-day morning	Sunlit cliffside homes and warm café interiors for breezy AM energy.
Santorini Nightscape	cargo run -p mawaku -- --location "Santorini, Greece" --season summer --time-of-day night	Lantern-lit terraces with caldera views for dramatic twilight calls.
Zermatt Midnight Chalet	cargo run -p mawaku -- --location "Zermatt alpine village, Switzerland" --season winter --time-of-day midnight	Snow-dusted timber chalets with Matterhorn silhouettes and ember glow.
El Nido Monsoon Sunrise	cargo run -p mawaku -- --location "El Nido lagoon, Palawan, Philippines" --season monsoon --time-of-day sunrise	Tropical loft wrapped in sunrise haze and karst cliffs after summer rain.

---

Configuration

Mawaku writes persistent settings to ~/.mawaku/config.toml the first time you run the CLI. Key entries include:

Key / Section	Purpose
prompt	Baseline template the CLI enriches with your inputs.
[gemini_api]	Tracks the environment variable that stores the Gemini API key.
image_output_dir	Directory (inside or outside Docker) for rendered assets.

Gemini credentials

Mawaku never writes the Gemini API key to disk. Instead, [gemini_api] keeps a single entry: api_key_env_var. It defaults to GEMINI_API_KEY, but you can edit the config file to point to any environment variable name you prefer (for example, GEMINI_KEY). Make sure that variable is exported before invoking the CLI.

Image output directory

image_output_dir remains at the root of the file for backward compatibility: older Mawaku releases only understood this top-level key, so keeping it there avoids breaking existing configs while still letting you edit the path manually.

To revert to defaults, delete the file and re-run any Mawaku command; a fresh template is generated automatically.

---

Docker Workflow

Run Mawaku inside an isolated container while keeping prompts, credentials, and images on the host:

1. Build the image

   docker build -f mawaku-rs/Dockerfile -t mawaku-cli mawaku-rs

2. Prime configuration and credentials

   mkdir -p .mawaku-config
   docker run --rm \
     -e GEMINI_API_KEY="YOUR_GEMINI_KEY" \
     -v "$(pwd)/.mawaku-config:/root/.mawaku" \
     mawaku-cli \
     --location "Lisbon, Portugal"

3. Choose an output directory

   mkdir -p outputs
   # Ensure .mawaku-config/config.toml contains:
   # [gemini_api]
   # api_key_env_var = "GEMINI_API_KEY"
   # image_output_dir = "/workspace/outputs"

4. Render a scene

   docker run --rm \
     -v "$(pwd)/.mawaku-config:/root/.mawaku" \
     -v "$(pwd)/outputs:/workspace/outputs" \
     mawaku-cli \
     --location "Hakone, Japan" \
     --season spring \
     --time-of-day dusk

Resulting PNGs appear in ./outputs, while Mawaku keeps credentials under ./.mawaku-config for future runs.

---

Development

Local toolchain

• Install Rust 1.76+ via rustup.
• Use cargo check to iterate quickly and catch type errors early.

Testing

cargo test           # full workspace
cargo test -p mawaku # CLI crate only

Append -- --nocapture to either command to see CLI stdout during tests.

Dev Container

The repo includes .devcontainer/ for a ready-to-code environment:

1. Install Docker and the VS Code Dev Containers extension (or the devcontainer CLI).
2. Reopen the project in the container (Dev Containers: Reopen in Container or devcontainer up --workspace-folder .).
3. The container ships with the Rust toolchain, so you can immediately run cargo check, cargo test, or cargo run without extra setup.
4. Exit the container any time—your project files stay on the host machine.