Command Reference

This section lists all commands supported by lovrabet, with detailed usage instructions and examples for each.

Windows Users Note: For the best experience, it's recommended to execute all commands in Git Bash. Basic functionality works in CMD/PowerShell, but it hasn't been thoroughly tested.

Basic Commands

`lovrabet --help` - View Help

This command is especially useful when you forget how to use a specific command:

# View all available commands
lovrabet --help

# View help for a specific command
lovrabet create --help
lovrabet api --help

Authentication

`lovrabet auth` - Login Authentication

This is the command you must execute when using the CLI for the first time.

lovrabet auth

Execution Steps:

Run the command and press Enter
CLI will start a local secure server
Automatically open browser and redirect to login page
Complete login in the browser
After successful login, return to terminal and press q to exit

Login Information Storage: ~/.lovrabet/cookie

Project Management

`lovrabet create` - Create Project

Used to create a new Lovrabet project.

# Interactive creation, CLI will ask for project name and other configurations
lovrabet create

# Directly specify project name
lovrabet create my-awesome-project

What Happens During Creation?

✅ Create project directory and basic file structure
✅ Copy initial code from template
✅ Automatically install npm dependencies
✅ Configure Prettier code formatting
✅ Create .lovrabetrc project configuration file

Tip: If you're unsure about the project name, just run lovrabet create and the CLI will guide you through the configuration step by step.

`lovrabet add page` - Add Page

Quickly add a new page to the project.

lovrabet add page

Interactive Configuration:

Select Page Template:
- blank - Blank page, suitable for starting from scratch
- hello-world - Page with example content, suitable for learning and reference
Enter Route Path:
- Single-level route: about, contact
- Multi-level route: user/profile, admin/settings, shop/product/detail

Generated File Location:

Path about → src/pages/about/
Path user/profile → src/pages/user/profile/

Path Naming Rules:

Length: 1-100 characters
Cannot start or end with /
Cannot contain consecutive //
Each path segment can only contain: letters, numbers, -, _

Development

`lovrabet start` - Start Development Server

Run in the project root directory to start the local development server.

lovrabet start

What Happens?

Starts Vite development server (usually http://localhost:5173)
Supports Hot Module Replacement (HMR)
Automatically opens browser
SDK Version Check v1.2.0+: Automatically detects @lovrabet/sdk version in the project, shows upgrade prompt when below 1.2.0

How It Works: This command actually runs vite, but the CLI automatically handles paths and environment variables.

SDK Version Compatibility (v1.2.0+)

CLI v1.2.0+ checks SDK version at startup. If @lovrabet/sdk < 1.2.0 is detected, a yellow warning will be displayed prompting an upgrade to ensure you can use the latest features like model aliases.

`lovrabet build` - Build Production Code

Package your project into production-ready code.

lovrabet build

Output:

Generates optimized static files in the dist/ directory
JavaScript and CSS files are compressed and minified
Images and other resources are optimized

When to Use: When you need to deploy to production or test the production environment locally.

`lovrabet preview` - Preview Build Results

Preview the packaged project locally.

# Simple preview
lovrabet preview

# Live build and preview
lovrabet preview --watch

Use Cases:

Simple Preview: Preview results after build completion
Live Preview: Automatically rebuild and update preview after code changes

Difference: preview shows production environment results, start shows development environment results.

Configuration Management

`lovrabet init` - Initialize Configuration File v1.1.12+

Quickly initialize Lovrabet configuration files for existing projects.

# Interactive initialization
lovrabet init

# Directly specify appcode
lovrabet init --appcode my-app-code

Use Cases:

Use this when you have an existing frontend project and want to add Lovrabet support. No need to recreate the project, just initialize the configuration.

What Happens?

Creates .lovrabetrc configuration file in project root
Configuration includes application code (appcode)
Automatically inherits global configuration (if any)
Records creation time and CLI version information

Interactive Input:

If you don't specify the --appcode parameter, CLI will guide you:

Supports real-time format validation (only letters, numbers, -, and _ allowed)
Immediate prompts on input errors
Automatically detects and prevents overwriting existing configuration files

Available Parameters:

Parameter	Description	Example	Required
`--appcode`	Application code	`--appcode my-app`	No (interactive input if not specified)

Example:

# Add Lovrabet support to existing React project
cd existing-react-project
lovrabet init --appcode my-app
lovrabet api pull
lovrabet start

Notes:

⚠️ If .lovrabetrc file already exists in the current directory, the command will fail with a prompt
✅ Can be executed from any subdirectory of the project, configuration file will be created in project root

`lovrabet config` - Project Configuration Management

Manage project-level and global-level configuration.

# Set configuration item
lovrabet config set <key> <value>

# View specific configuration item
lovrabet config get <key>

# View all configuration items
lovrabet config list

Common Configuration Items:

Key	Description	Example
`app`	Application code, used for API generation	`my-app-code`
`apiUrl`	API base URL	`https://api.example.com`

Configuration Hierarchy:

Executed inside project: Configuration saved to .lovrabetrc file in project root
Executed outside project: Configuration saved to ~/.lovrabetrc in user home directory
Priority: CLI parameters > Project config > Global config > Default values

Example:

# Set application code
lovrabet config set app my-project

# View application code
lovrabet config get app

# View all configurations
lovrabet config list

`lovrabet menu sync` - Sync Menu v1.1.15+

Intelligently sync local pages with Lovrabet platform menus.

# Execute in project directory
lovrabet menu sync

What Happens?

Automatically scans all pages in local src/pages directory
Retrieves existing menu list from Lovrabet platform
Displays comparison results in table format in terminal
Guides you to configure JS and CSS CDN links for missing menus
Batch creates all missing menus

Comparison Table Example:

  Path            Local    Lovrabet Platform
  home            ✓        ✓
  user/profile    ✓        ✗
  shop/products   ✓        ✗

✓ Green: Exists
✗ Red: Does not exist (needs creation)

Use Cases:

# Scenario 1: Sync after developing new pages
lovrabet add page
lovrabet menu sync

# Scenario 2: Batch create menus for multiple pages
lovrabet menu sync

# Scenario 3: Periodically check local and platform consistency
lovrabet menu sync

Prerequisites:

Logged in (lovrabet auth)
Application code configured (lovrabet config set app <code>) or use --appcode parameter
Page files exist in src/pages directory

Detailed Tutorial

For complete usage guide and best practices, see Menu Sync Documentation

API Integration

`lovrabet api pull` - Generate API Code

Automatically pull API definitions from backend and generate frontend calling code.

# Use app code from project configuration
lovrabet api pull

# Specify app code (v1.1.7+)
lovrabet api pull --appcode my-app-code

# Specify output directory (v1.1.7+)
lovrabet api pull --output ./lib/api

# Combine parameters
lovrabet api pull --appcode my-app-code --output ./lib/api

Version Note

Starting from v1.1.7:

Positional parameters are no longer supported (e.g., lovrabet api pull my-app-code)
Use --appcode parameter to specify application code
New --output parameter to customize output directory

v1.2.0 Configuration Format Upgrade

Starting from v1.2.0, generated configuration uses array format with datasetCode as the core identifier:

// api.ts generated by v1.2.0+
export const LOVRABET_MODELS_CONFIG = {
  appCode: 'my-app',
  models: [
    {
      datasetCode: '8d2dcbae08b54bdd84c00be558ed48df',
      tableName: 'users',
      alias: 'users',      // Optional: Model alias (syntactic sugar)
      name: 'User Management',    // Optional: UI display name
    },
  ],
} as const;

Access Methods:

Standard method (recommended): client.models.dataset_8d2dcbae08b54bdd84c00be558ed48df.filter() - Globally unique, AI-friendly
Alias method (syntactic sugar): client.models.users.filter() - Human-readable, functionally identical

Available Parameters:

Parameter	Description	Example	Version
`--appcode`	Specify application code	`--appcode my-app`	v1.1.7+
`--output`	Specify output directory	`--output ./lib/api`	v1.1.7+

Execution Steps:

CLI asks what name you want for the API file (default api)
Pulls API configuration and data structure from backend
Generates TypeScript type definitions and client code
Automatically formats code

Generated Files:

src/api/<name>.ts - API interface definitions and data types
src/api/client.ts - Pre-configured client instance

Prerequisites:

Logged in (lovrabet auth)
Application code configured (lovrabet config set app <code>) or use --appcode parameter

`lovrabet api doc` - Generate API Documentation v1.1.10+

Automatically generate API usage documentation (Markdown format) for team reference and sharing.

# Generate documentation for all datasets
lovrabet api doc

# Generate documentation for specific datasets only (v1.1.12+)
lovrabet api doc --datasetcode dataset_abc123

# Generate documentation for multiple datasets (v1.1.12+)
lovrabet api doc --datasetcode ds_001,ds_002,ds_003

# Specify output directory
lovrabet api doc --output ./api-docs

# Combine parameters
lovrabet api doc --appcode my-app --datasetcode ds_001 --output ./docs

What Gets Generated?

Each dataset generates an independent Markdown file (default in ./docs directory), containing:

📚 Dataset basic information and field definitions
📊 API endpoint descriptions (query, create, update, delete)
💡 Complete request and response examples
🔧 Usage notes and limitations

Available Parameters:

Parameter	Description	Example	Version
`--appcode`	Specify application code	`--appcode my-app`	v1.1.10+
`--output`	Specify output directory	`--output ./api-docs`	v1.1.10+
`--datasetcode`	Specify dataset codes (comma-separated for multiple)	`--datasetcode ds_001,ds_002`	v1.1.12+
`--env`	Specify environment (optional)	`--env <env>`	v1.1.10+

Smart Validation v1.1.12+:

When using --datasetcode parameter:

✅ Automatically checks if specified dataset codes exist
⚠️ Displays warnings for non-existent dataset codes
📊 Shows matched dataset count statistics

Use Cases:

# Scenario 1: Team collaboration - Generate docs and commit to Git
lovrabet api doc
git add docs/
git commit -m "docs: Update API documentation"

# Scenario 2: Selective generation - Only update specific dataset docs
lovrabet api doc --datasetcode users,orders

# Scenario 3: Multi-app management - Generate separate docs for different apps
lovrabet api doc --appcode user-app --output ./docs/user-api
lovrabet api doc --appcode admin-app --output ./docs/admin-api

Prerequisites:

Logged in (lovrabet auth)
Application code configured (lovrabet config set app <code>) or use --appcode parameter

Utility Commands

`lovrabet logs` - Log Management

View and manage CLI operation logs.

# View logs
lovrabet logs

# Clear logs
lovrabet logs --clear

Log Contents:

Executed commands and parameters
Command execution time and duration
Error messages and stack traces
CLI version and environment information

Log File Location: .lovrabet.log in project root (JSONL format)

When to View Logs: When command execution fails or you encounter issues, logs can help you identify the problem.

Common Command Combinations

Here are some commonly used command combinations for different scenarios:

First Time Using CLI (Create New Project)

lovrabet auth                    # Login
lovrabet create my-project       # Create project
cd my-project                    # Enter project
lovrabet config set app my-app   # Configure application
lovrabet api pull               # Generate API
lovrabet start                  # Start development

Add Lovrabet Support to Existing Project v1.1.12+

lovrabet auth                         # Login (if not already logged in)
cd existing-project                   # Enter existing project
lovrabet init --appcode my-app        # Initialize configuration
lovrabet api pull                     # Generate API code
lovrabet api doc                      # Generate API documentation
lovrabet menu sync                    # Sync menus to platform (v1.1.15+)
lovrabet start                        # Start development

Daily Development Workflow

lovrabet start                  # Start development server
lovrabet add page               # Add new page
lovrabet menu sync              # Sync menus to platform (v1.1.15+)
lovrabet api pull               # Update API
lovrabet build                  # Build for testing
lovrabet preview                # Preview results

API Documentation Update Workflow v1.1.10+

lovrabet api doc                      # Generate all documentation
# or
lovrabet api doc --datasetcode ds_001 # Only update specific dataset docs
git add docs/
git commit -m "docs: Update API documentation"

Troubleshooting

lovrabet logs                   # View logs
lovrabet config list            # Check configuration
lovrabet --help                 # View help

Frequently Asked Questions

Q1: What's the difference between `lovrabet init` and `lovrabet create`?

These are two commands for completely different use cases:

lovrabet create - Create New Project

Use Case: Start a new Lovrabet project from scratch

lovrabet create my-new-project
cd my-new-project

What it does:

✅ Creates new project directory
✅ Generates complete project structure (src, public, config files, etc.)
✅ Copies all initial code from template
✅ Automatically installs dependencies (npm install)
✅ Creates .lovrabetrc configuration file
✅ Configures Prettier and other tools

lovrabet init - Add Configuration to Existing Project v1.1.12+

Use Case: You already have a frontend project and want to add Lovrabet support

cd existing-react-project
lovrabet init --appcode my-app

What it does:

✅ Only creates .lovrabetrc configuration file
❌ Does not create project directory
❌ Does not generate project structure
❌ Does not install dependencies

Comparison Table:

Feature	`create`	`init`
When to use	Starting new project	Existing project wants Lovrabet integration
Creates project directory	✅ Yes	❌ No
Generates project structure	✅ Yes	❌ No
Installs dependencies	✅ Yes	❌ No
Creates config file	✅ Yes	✅ Yes
Use case	Starting from scratch	Existing React/Vue projects

Practical Examples:

# Scenario 1: Starting new project - Use create
lovrabet create my-shop-project
cd my-shop-project
lovrabet start

# Scenario 2: Existing project - Use init
cd my-existing-react-app
lovrabet init --appcode shop-app
lovrabet api pull
lovrabet start

Symptoms: When running lovrabet api pull or other commands requiring login, you get "Login authentication failed" or 401 error.

Solution:

# 1. Logout (optional)
lovrabet logout

# 2. Re-login
lovrabet auth

# 3. Re-execute the previously failed command
lovrabet api pull

How to Check Login Status:

There's currently no direct command to check login status, but you can try running a command that requires login (like lovrabet api pull). If it prompts you to login, the status has expired.

Login Validity Period:

Login status is managed by the backend and typically lasts for a long time. If you haven't used the CLI for an extended period, you may need to re-login.

Q3: What's the difference between `lovrabet api pull` and `lovrabet api doc`?

Both commands are related to APIs, but serve completely different purposes:

lovrabet api pull - Generate API Calling Code

lovrabet api pull --appcode my-app

Purpose:

Generates frontend API calling code files (TypeScript)
Output location: src/api/
Usage: Import and use directly in your project code

Output example:

// src/api/api.ts
import { lovrabetClient } from '@/api/client';
const users = await lovrabetClient.getUsers();

lovrabet api doc - Generate API Documentation v1.1.10+

lovrabet api doc

Purpose:

Generates API usage documentation (Markdown format)
Output location: docs/
Usage: For team members to read, understand APIs, or commit to Git repository

Output example:

# User Dataset API Documentation

## Data Fields
| Field Name | Type | Description |
|------------|------|-------------|
| id | number | User ID |
| name | string | Username |
...

When to Use:

api pull: During development, when you need to call APIs
api doc: When writing documentation, or when team needs to understand API details

Q4: Why is the generated API filename not what I want?

Reason: CLI asks during generation what name you want to use, default is api.

Solution:

Customize name during generation:

lovrabet api pull
# CLI will ask: Enter API file name (default: api)
# You can enter: myapi
# Final output: src/api/myapi.ts

Manually rename after generation:

# Rename file directly after generation
mv src/api/api.ts src/api/myapi.ts
# And update import paths in your code

Use --output to customize directory:

lovrabet api pull --output ./src/services
# This will generate API files in src/services/ directory

Q5: How do I update generated API code?

When backend APIs change, you need to regenerate the API code.

Steps:

# 1. Backup existing files (optional, recommended to commit to Git first)
git add .
git commit -m "backup: Backup before API code update"

# 2. Re-pull API
lovrabet api pull

# 3. CLI will ask if you want to overwrite, select Yes

# 4. Check changes
git diff src/api/

# 5. If there are issues, you can revert
git checkout src/api/

Notes:

⚠️ Regenerating will overwrite existing files, so backup or commit to Git first
✅ Recommended to use Git for code management, makes it easy to compare changes
📝 After API changes, related calling code may also need modifications

Q6: I only want to generate documentation for some datasets, how do I do that?

Use the --datasetcode parameter to specify datasets for documentation generation v1.1.12+:

# Generate documentation for users dataset only
lovrabet api doc --datasetcode users

# Generate documentation for multiple datasets (comma-separated)
lovrabet api doc --datasetcode users,orders,products

How to Get Dataset Codes:

Run lovrabet api pull, CLI will display all datasets
Or check lovrabet.config.js configuration file
Or first run lovrabet api doc to generate all documentation, dataset codes are visible from filenames

Smart Validation:

If the dataset code you specify doesn't exist, CLI will display a warning:

! The following dataset codes do not exist: invalid_dataset
* Filtered 2 matching datasets from 50 total datasets

Q7: What should Windows users do if commands fail?

Recommended Solution: Use Git Bash to execute all CLI commands

Why:

CLI has been thoroughly tested in Git Bash
CMD/PowerShell may have compatibility issues
Git Bash provides better terminal experience

How to Install Git Bash:

Download and install Git for Windows
Select to include Git Bash during installation
After installation, right-click any folder → "Git Bash Here"
Execute CLI commands in Git Bash

Common Issues:

If you encounter issues in CMD:

# Issue: Command not recognized or path error
# Solution: Switch to Git Bash

# Issue: npm install fails
# Solution: Check Node.js version >= 20
node --version

Q8: How do I check CLI version and updates?

Check Current Version:

lovrabet --version
# or
npm list -g @lovrabet/cli

Update to Latest Version:

# Using npm
npm update -g @lovrabet/cli

# Using bun (recommended)
bun update -g @lovrabet/cli

# Force reinstall
npm install -g @lovrabet/cli --force

View Update Log:

Check Changelog to learn about latest version features
Or visit npm page to view version history

Basic Commands​

lovrabet --help - View Help​

Authentication​

lovrabet auth - Login Authentication​

Project Management​

lovrabet create - Create Project​

lovrabet add page - Add Page​

Development​

lovrabet start - Start Development Server​

lovrabet build - Build Production Code​

lovrabet preview - Preview Build Results​

Configuration Management​

lovrabet init - Initialize Configuration File v1.1.12+​

lovrabet config - Project Configuration Management​

Menu Management​

lovrabet menu sync - Sync Menu v1.1.15+​

API Integration​

lovrabet api pull - Generate API Code​

lovrabet api doc - Generate API Documentation v1.1.10+​

Utility Commands​

lovrabet logs - Log Management​

Common Command Combinations​

First Time Using CLI (Create New Project)​

Add Lovrabet Support to Existing Project v1.1.12+​

Daily Development Workflow​

API Documentation Update Workflow v1.1.10+​

Troubleshooting​

Frequently Asked Questions​

Q1: What's the difference between lovrabet init and lovrabet create?​

Q2: What if my login status has expired?​

Q3: What's the difference between lovrabet api pull and lovrabet api doc?​

Q4: Why is the generated API filename not what I want?​

Q5: How do I update generated API code?​

Q6: I only want to generate documentation for some datasets, how do I do that?​

Q7: What should Windows users do if commands fail?​

Q8: How do I check CLI version and updates?​

Basic Commands

`lovrabet --help` - View Help

Authentication

`lovrabet auth` - Login Authentication

Project Management

`lovrabet create` - Create Project

`lovrabet add page` - Add Page

Development

`lovrabet start` - Start Development Server

`lovrabet build` - Build Production Code

`lovrabet preview` - Preview Build Results

Configuration Management

`lovrabet init` - Initialize Configuration File v1.1.12+

`lovrabet config` - Project Configuration Management

Menu Management

`lovrabet menu sync` - Sync Menu v1.1.15+

API Integration

`lovrabet api pull` - Generate API Code

`lovrabet api doc` - Generate API Documentation v1.1.10+

Utility Commands

`lovrabet logs` - Log Management

Common Command Combinations

First Time Using CLI (Create New Project)

Add Lovrabet Support to Existing Project v1.1.12+

Daily Development Workflow

API Documentation Update Workflow v1.1.10+

Troubleshooting

Frequently Asked Questions

Q1: What's the difference between `lovrabet init` and `lovrabet create`?

Q2: What if my login status has expired?

Q3: What's the difference between `lovrabet api pull` and `lovrabet api doc`?

Q4: Why is the generated API filename not what I want?

Q5: How do I update generated API code?

Q6: I only want to generate documentation for some datasets, how do I do that?

Q7: What should Windows users do if commands fail?

Q8: How do I check CLI version and updates?