CLI

The Luna CLI wraps every developer and operations script into a single consistent interface. Set up, run, build, check, and debug the full stack from one command.

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-S/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 interfaces/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

CommandDescription
helpPrint command list and usage.
install:commandPrint the one-line global CLI installer.
setupInteractive first-time wizard — selects variant, installs dependencies, creates .env, and pulls Ollama models.
doctorVerify Node.js, npm, Python, Ollama, and Docker are installed and at the right versions.
healthHit the running backend's /api/system/health endpoint and display the JSON response.
chatStart an interactive terminal chat session with a running Luna backend. Pass a message as an argument for a one-shot query.
webStart the server and open Luna in your browser at http://localhost:8899.
web:lanSame as web, reachable from phones and tablets on your network.
dev / dev:lanAliases for web / web:lan.
serveStart the server. --tailscale also shares it with your tailnet over HTTPS port 8899; --tailscale --off stops sharing. See Remote access.
backendStart only the FastAPI server on port 8899.
frontendStart only the Vite dev server for the mobile React UI.
tunnelExpose the Vite dev server through a Cloudflare tunnel.
buildBuild the React frontend.
checkRun lightweight Python syntax checks on critical backend files.
processesPrint all registered backend background processes as JSON.
cleanRemove build artifacts and runtime data.

npm scripts

From a clone, these npm scripts wrap the CLI and the build steps. In PowerShell, prefer them over npm run luna -- …, because PowerShell drops the --.

ScriptDoes
npm run setupFirst-time setup wizard.
npm run webServer + browser UI at http://localhost:8899.
npm run serve:tailscaleStart the server and share it over Tailscale.
npm run serve:tailscale:offStop sharing over Tailscale.
npm run build:desktopWindows installer in dist/desktop/.
npm run build:mobileSync the web build into interfaces/mobile for Android Studio / Xcode.
npm run docsThis docs site at http://localhost:3000.

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 interfaces/web/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.

CommandDescription
dockerAuto-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:businessForce Business variant compose file regardless of .env.
docker:gpuForce GPU compose overlay (compose.yml + compose.gpu.yml).
docker:cloudForce cloud compose file — no Ollama container started.
docker:downStop and remove all Luna containers across all compose files.
docker:logsTail the Luna container logs in real time.
docker:pullRe-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 deploy/.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 interfaces/web/ or server/

# 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