LunariaJS CLI Commands Detailed - Master init, build, and preview

In the previous two articles, we introduced LunariaJS’s core concepts and configuration methods. Today, let’s dive into LunariaJS’s command line tool (CLI), mastering the usage and best practices of every command.

💡 Official Documentation: LunariaJS Documentation - CLI

CLI Overview

LunariaJS provides a powerful command line tool that allows you to:

Initialize projects: Quickly create configuration files
Build dashboards: Generate localization status visualization pages
Preview dashboards: Start a local server to view results

Running Methods

There are three ways to run LunariaJS CLI:

# Method 1: Using npx (recommended, no installation required)
npx lunaria [command]

# Method 2: Using npm scripts (recommended)
npm run lunaria:[command]

# Method 3: Direct execution (requires global or project installation)
lunaria [command]

Global Options

All commands support the following global options:

Option	Short	Description
`--help`	`-h`	Display help information
`--version`	`-v`	Display version number
`--config <path>`	`-c`	Specify configuration file path

Viewing Help

# View main command help
npx lunaria --help

# View subcommand help
npx lunaria init --help
npx lunaria build --help
npx lunaria preview --help

lunaria init - Initialize Project

The lunaria init command is used to quickly create LunariaJS configuration files.

Basic Usage

npx lunaria init

After running, the CLI will interactively ask for configuration information:

? What is the source language of your project? (en)
? What languages do you want to support? (comma-separated, e.g., zh-cn, ja, ko)
? Where are your source files located? (e.g., docs/{slug}.md)
? Where should localized files be stored? (e.g., i18n/{lang}/{slug}.md)
? Where should the dashboard be generated? (lunaria-dashboard)

Command Parameters

Parameter	Description	Default
`--config <path>`	Specify output configuration file path	`lunaria.config.json`
`--typescript`	Generate TypeScript configuration file	`false`
`--yes` / `-y`	Skip interaction, use defaults	`false`
`--force` / `-f`	Force overwrite existing configuration file	`false`

Interactive Initialization Process

Let’s look at a complete interactive initialization example:

$ npx lunaria init

🌙 LunariaJS - Localization Dashboard Generator

? What is the source language of your project? en
? What languages do you want to support? zh-cn, ja, ko
? Where are your source content files? src/content/docs/{slug}.md
? Where are your localized content files? src/i18n/{lang}/docs/{slug}.md
? Where should the dashboard be output? public/lunaria
? Dashboard title My Docs Localization Status

✨ Created lunaria.config.json

Next steps:
1. Review and adjust lunaria.config.json
2. Run `npx lunaria build` to generate your dashboard
3. Run `npx lunaria preview` to preview locally

Generate TypeScript Configuration

If you prefer TypeScript configuration files:

npx lunaria init --typescript

This generates lunaria.config.ts:

// lunaria.config.ts
import { defineConfig } from '@lunariajs/core';

export default defineConfig({
  sourceLanguage: 'en',
  languages: ['en', 'zh-cn', 'ja', 'ko'],
  files: [
    {
      sourcePath: 'src/content/docs/{slug}.md',
      localizationPath: 'src/i18n/{lang}/docs/{slug}.md',
    },
  ],
  dashboard: {
    outputDir: 'public/lunaria',
    title: 'My Docs Localization Status',
  },
});

Quick Initialization (Skip Interaction)

Use the --yes option to quickly create default configuration:

npx lunaria init --yes

This creates a configuration file with all default values:

{
  "sourceLanguage": "en",
  "languages": ["en"],
  "files": [
    {
      "sourcePath": "docs/{slug}.md",
      "localizationPath": "i18n/{lang}/{slug}.md"
    }
  ],
  "dashboard": {
    "outputDir": "lunaria-dashboard"
  }
}

Specify Configuration File Path

npx lunaria init --config ./config/lunaria.json

Best Practices

Interactive for first use: Let the CLI guide you through configuration
Use TypeScript for subsequent use: Get better type support and IDE hints
Version control: Commit configuration files to Git repository

lunaria build - Build Dashboard

The lunaria build command is LunariaJS’s core command, used to generate the localization dashboard.

Basic Usage

npx lunaria build

Command Parameters

Parameter	Description	Default
`--config <path>`	Specify configuration file path	`lunaria.config.json`
`--output <dir>`	Specify output directory (overrides config)	`dashboard.outputDir` from config
`--silent`	Silent mode, no log output	`false`
`--verbose`	Verbose output mode	`false`

Build Process Details

When you run lunaria build, LunariaJS executes the following steps:

1. Load Configuration File

📄 Loading configuration from lunaria.config.json...

2. Scan Source Files

🔍 Scanning source files in src/content/docs/...
   Found 42 source files

3. Analyze Translation Status

📊 Analyzing translation status...
   - en (source): 42 files
   - zh-cn: 38 done, 3 outdated, 1 missing
   - ja: 30 done, 8 outdated, 4 missing
   - ko: 25 done, 10 outdated, 7 missing

4. Generate Dashboard

🎨 Generating dashboard...
   - Creating HTML pages
   - Generating CSS styles
   - Building JavaScript bundle

5. Output Results

✅ Dashboard generated successfully!
   Output: public/lunaria/
   Files: 15 files, 128KB total

Verbose Output Mode

Use --verbose to see more build details:

npx lunaria build --verbose

Output example:

📄 Loading configuration from lunaria.config.json

🔍 Scanning files...
   Pattern: src/content/docs/{slug}.md
   Files found:
   - src/content/docs/index.md
   - src/content/docs/getting-started.md
   - src/content/docs/configuration.md
   ...

📊 Analyzing translation status...

   File: index.md
   - en: source (modified: 2026-02-28)
   - zh-cn: done (modified: 2026-02-27)
   - ja: outdated (modified: 2026-02-20, source newer)
   - ko: missing

   File: getting-started.md
   - en: source (modified: 2026-02-28)
   - zh-cn: done (modified: 2026-02-28)
   - ja: done (modified: 2026-02-25)
   - ko: outdated (modified: 2026-02-15, source newer)
   ...

🎨 Generating dashboard...
   - Writing index.html
   - Writing styles.css
   - Writing script.js
   - Writing data/status.json

✅ Build completed in 1.2s
   Output: public/lunaria/

Silent Mode

In CI/CD environments, you can use silent mode:

npx lunaria build --silent

Custom Output Directory

Temporarily override the output directory from configuration:

npx lunaria build --output ./dist/i18n-dashboard

Integration with package.json

// package.json
{
  "scripts": {
    "build": "astro build && lunaria build",
    "lunaria:build": "lunaria build",
    "lunaria:build:verbose": "lunaria build --verbose"
  }
}

Build Artifacts

lunaria build generates the following files in the output directory:

lunaria-dashboard/
├── index.html          # Main page
├── assets/
│   ├── index.css       # Stylesheet
│   └── index.js        # JavaScript logic
├── data/
│   └── status.json     # Translation status data
└── favicon.ico         # Site favicon

Common Build Errors

Error 1: Configuration file not found

Error: Configuration file not found at lunaria.config.json

Solution:

# First run init to create configuration
npx lunaria init
# Or specify configuration file path
npx lunaria build --config ./config/lunaria.json

Error 2: Source directory does not exist

Error: Source directory "docs" does not exist

Solution: Check if files.sourcePath configuration is correct.

lunaria preview - Preview Dashboard

The lunaria preview command is used to start a local server to preview the generated dashboard.

Basic Usage

npx lunaria preview

Command Parameters

Parameter	Description	Default
`--config <path>`	Specify configuration file path	`lunaria.config.json`
`--port <number>`	Specify server port	`3000`
`--open`	Automatically open browser	`false`
`--host`	Listen on all network interfaces	`false`

Start Preview Server

$ npx lunaria preview

🌙 LunariaJS Preview Server

Local:   http://localhost:3000
Network: http://192.168.1.100:3000

Press Ctrl+C to stop

Specify Port

npx lunaria preview --port 8080

Automatically Open Browser

npx lunaria preview --open

Allow External Access

In team environments, allow colleagues to access via LAN:

npx lunaria preview --host

Preview Notes

Build first: The preview command doesn’t automatically run build, make sure to run lunaria build first
No hot reload: Currently doesn’t support hot reload, need to rebuild after configuration changes
Port conflicts: If default port is occupied, use --port to specify a different port

Command Combination Usage Scenarios

Development Environment Workflow

# 1. Initialize configuration (first time)
npx lunaria init

# 2. Build dashboard
npx lunaria build

# 3. Preview results
npx lunaria preview --open

Integration with Astro Starlight

// package.json
{
  "scripts": {
    "dev": "astro dev",
    "build": "astro build && lunaria build",
    "preview": "astro preview",
    "lunaria:preview": "lunaria preview --port 3001"
  }
}

CI/CD Pipeline

# .github/workflows/i18n-check.yml
name: i18n Status Check

on: [pull_request]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - run: npm ci

      - name: Build Lunaria Dashboard
        run: npm run lunaria:build -- --silent

      - name: Upload Dashboard
        uses: actions/upload-artifact@v4
        with:
          name: lunaria-dashboard
          path: lunaria-dashboard/

Local Debugging Scenario

# Verbose output mode helps debugging
npx lunaria build --verbose

# If build has issues, check configuration
npx lunaria init --force  # Regenerate configuration

# Build again
npx lunaria build --verbose

CLI Advanced Tips

1. Using Environment Variables

# Set Node.js environment variable
NODE_ENV=production npx lunaria build

# Custom environment variable
LUNARIA_OUTPUT=./dist/dashboard npx lunaria build

Using in configuration file:

// lunaria.config.ts
export default defineConfig({
  dashboard: {
    outputDir: process.env.LUNARIA_OUTPUT || 'lunaria-dashboard',
  },
});

2. Combining Multiple Commands

# Complete initialization and build in one command
npx lunaria init --yes && npx lunaria build

# Or use npm scripts
npm run lunaria:init && npm run lunaria:build

3. Debugging Configuration Issues

# Check if configuration file is valid
npx lunaria build --verbose 2>&1 | head -20

4. Version Check

# View current version
npx lunaria --version

# Check for new versions
npm outdated @lunariajs/core

CLI Troubleshooting

Q1: Command not found

Problem: lunaria: command not found

Solution:

# Use npx
npx lunaria [command]

# Or install globally
npm install -g @lunariajs/core

Q2: Permission denied

Problem: EACCES: permission denied

Solution:

# Check directory permissions
ls -la .

# Or use sudo (not recommended)
sudo npx lunaria build

Q3: Out of memory

Problem: JavaScript heap out of memory

Solution:

# Increase Node.js memory limit
NODE_OPTIONS="--max-old-space-size=4096" npx lunaria build

Q4: Slow build

Problem: Long build times for large projects

Solution:

# Check file count
npx lunaria build --verbose | grep "Files found"

# Optimize configuration, exclude unnecessary files

Summary

This article covered LunariaJS CLI’s three core commands in detail:

Command	Function	Common Parameters
`lunaria init`	Initialize configuration file	`--typescript`, `--yes`, `--force`
`lunaria build`	Build localization dashboard	`--output`, `--silent`, `--verbose`
`lunaria preview`	Preview dashboard locally	`--port`, `--open`, `--host`

Key Points:

Use npx lunaria init to get started quickly
lunaria build is the core command, generates visualization dashboard
lunaria preview is convenient for local debugging and preview
Integrate CLI commands into package.json scripts

Next Steps

In the next article, we’ll dive into LunariaJS localization dashboard usage, including:

Dashboard interface details
Translation status interpretation
File status tracking
Filtering and search functionality
Dashboard customization

Stay tuned!

💡 Recommended Reading:

LunariaJS Documentation

LunariaJS CLI Reference

LunariaJS Chinese Documentation

LunariaJS Japanese Documentation

LunariaJS Korean Documentation