CLI — L.U.N.A. Docs

Usage

Install the CLI globally on macOS, Windows, or Linux:

terminal

npm i -g luna-workspace

Shortest first run without a permanent install:

terminal

npx luna-workspace setup

If the npm package is not published yet, install directly from GitHub:

terminal

npm i -g github:Sehastrajit/Luna

Run the CLI from the repository root:

terminal

npm run luna -- <command>

The double dash (--) is required by npm to pass arguments to the script. Everything after it is forwarded to cli/luna.mjs.

After running npm link (see Global install), you can drop the npm run luna -- prefix and just use luna:

terminal

luna setup      # first-time wizard
luna dev        # start desktop stack
luna docker     # start via Docker (auto-detects mode)
luna help       # list all commands

Commands

Command	Description
`help`	Print command list and usage.
`install:command`	Print the one-line global CLI installer.
`setup`	Interactive first-time wizard — selects variant, installs dependencies, creates `.env`, and pulls Ollama models.
`doctor`	Verify Node.js, npm, Python, Ollama, and Docker are installed and at the right versions.
`health`	Hit the running backend's `/api/system/health` endpoint and display the JSON response.
`chat`	Start an interactive terminal chat session with a running Luna backend. Pass a message as an argument for a one-shot query.
`dev`	Start Vite and Electron together (full desktop stack). Personal variant.
`dev:lan`	Start with Vite bound to `0.0.0.0` for LAN access from other devices.
`web`	Start the FastAPI backend and Vite dev server without Electron (browser UI only).
`web:lan`	Same as `web` but binds to `0.0.0.0` for LAN access.
`backend`	Start only the FastAPI backend on port 8899.
`frontend`	Start only the Vite dev server on port 5173.
`electron`	Start only the Electron shell (backend must already be running).
`tunnel`	Start an ngrok tunnel to the backend port. Useful for registering Telegram / Discord / Slack webhooks during development.
`build`	Build the frontend for production (`frontend/dist/`).
`dist`	Build the frontend and package the Windows NSIS installer.
`check`	Run lightweight Python syntax checks on critical backend files.
`processes`	Print all registered backend background processes as JSON.
`clean`	Remove local runtime and build artefacts that are gitignored.

setup

terminal

luna setup

The interactive wizard on first run:

output

  Choose your variant

  1. Personal
     Voice, vision, desktop automation, Spotify, maps.
     Casual AI companion. Single user. No auth required.

  2. Business
     Professional team assistant. Multi-user JWT auth.
     Rate limiting, Slack/Telegram/Discord channels.

  Enter 1 or 2 (default: 1): _

After variant selection, the wizard prompts for your LLM provider, installs all dependencies, and pulls Ollama models if needed. Takes about 2 minutes on a fast connection.

doctor

terminal

luna doctor

output

  ✓ Node.js 20.x
  ✓ npm 10.x
  ✓ Python 3.11
  ✓ Ollama running
  ✓ Docker available

health

terminal

luna health

Requires the backend to be running. Returns the live system status from/api/system/health including LLM provider and active features.

chat

terminal

# Interactive session
luna chat

# One-shot query
luna chat "what time is it?"

# Auto-approve or auto-deny confirmation prompts
luna chat --yes "create the requested workspace file"
luna chat --no "try this but deny risky actions"

Inside the interactive session, use /new to start a fresh conversation and/help for terminal commands. Use /exit to quit.

The terminal uses the same chat stream as web and Electron. It handles tool confirmations, plans, plan progress, proactive messages, command events, web research, workspace file tools, installed skills, agent tasks, and Google/Microsoft workspace tool calls.

tunnel

terminal

luna tunnel

Starts ngrok pointing at the backend port. Requires ngrok to be installed and onPATH. Use the printed HTTPS URL as your webhook base when registering Telegram, Discord, or Slack integrations during development.

check

terminal

luna check

Runs python -m py_compile on the critical backend entry points — a fast sanity check that catches import errors and syntax mistakes before opening a PR.

clean

terminal

luna clean

Deletes frontend/dist/, electron/dist/, and any other gitignored build artefacts. Does not touch data/ — your memory and runtime data are preserved.

⚠️

clean does not delete data/

If you want to fully reset Luna's memory, personality, and conversation history, manually delete data/luna.db and data/chroma/.

Docker commands

The Docker commands wrap scripts/docker.mjs and auto-detect the right compose file based on luna_variant and llm_provider in your.env.

Command	Description
`docker`	Auto-detect mode from `.env` and start the appropriate compose stack. Business variant → `compose.business.yml`, cloud LLM → `compose.cloud.yml`, GPU detected → GPU overlay, otherwise CPU.
`docker:business`	Force Business variant compose file regardless of `.env`.
`docker:gpu`	Force GPU compose overlay (`compose.yml + compose.gpu.yml`).
`docker:cloud`	Force cloud compose file — no Ollama container started.
`docker:down`	Stop and remove all Luna containers across all compose files.
`docker:logs`	Tail the Luna container logs in real time.
`docker:pull`	Re-pull Ollama models into a running container (after changing `ollama_model` in `.env`).

Auto-detection logic

detection order

1. --business flag → compose.business.yml
2. luna_variant=business in .env → compose.business.yml
3. --cloud flag → compose.cloud.yml
4. llm_provider is a cloud provider → compose.cloud.yml
   (anthropic, google, groq, cohere, mistral, openai-compatible, nvidia-nim)
5. --gpu flag → compose.yml + compose.gpu.yml
6. NVIDIA GPU detected on host → GPU overlay
7. fallback → compose.yml (CPU)

Starting the Business variant

terminal

cp .env.business.example .env
# Edit .env — set jwt_secret, business_name, llm_provider
luna docker:business

# → http://localhost:8899
# → Admin API: http://localhost:8899/api/admin/

Upgrading

terminal

git pull
luna docker      # rebuilds containers with new image

ℹ️

luna docker vs docker compose

luna docker does preflight checks, builds containers, pulls Ollama models, and waits for the health endpoint before printing the success banner. Use raw docker compose commands when you want finer control.

Global install

Link the CLI globally so you can run luna from anywhere instead ofnpm run luna --:

terminal

# From the repo root
npm link

# Now run from anywhere
luna setup
luna dev
luna doctor
luna docker

To unlink later:

terminal

npm unlink

ℹ️

Windows PATH

On Windows, npm's global bin directory must be on your PATH. If luna isn't found after linking, run npm config get prefix and add that path's \bin subdirectory to your environment variables.

Developer workflow

Typical flow for a feature PR:

terminal

# 1. First time — run setup wizard
luna setup

# 2. Verify dependencies any time
luna doctor

# 3. Start full stack for development
luna dev

# 4. Make your changes in frontend/ or backend/

# 5. Check backend syntax hasn't broken
luna check

# 6. Build frontend to catch TypeScript errors
cd frontend && npm run build && cd ..

# 7. Quick smoke test
luna health

# 8. Open PR

If you only need the backend running (e.g. testing API changes with curl):

terminal

luna backend
# In another terminal:
curl http://localhost:8899/api/system/health

Testing channel integrations locally:

terminal

luna backend
luna tunnel
# → https://abc123.ngrok-free.app
# Paste that URL into Telegram BotFather / Discord App / Slack App settings