Rabetbase CLI

Prerequisites: Before using any API command, you need to complete authentication and configuration (see below). Mandatory before execution: Before executing any command, you must first read the reference documentation for the corresponding command before invoking it. Naming convention: Uniformly use the

rabetbase <service> <command> [flags]

format. Output format: AI Agent must use

--format json

to get structured output.

Prerequisites

1. Authentication: Complete OAuth login via browser with

   rabetbase auth

2. AppCode: Ensure

   appcode

   (single app) or

   apps

   (multiple apps) is set in

   .rabetbase.json

   , or pass it via

   --appcode <code>

   /

   --app <name>

   (the old name

   .lovrabet.json

   is still readable)
3. Configuration file: Initialize

   .rabetbase.json

   with

   rabetbase project init

   (old name is still compatible for reading)
4. Multi-app scenario: When a project has multiple apps, first configure each app with

   rabetbase app add

   , then switch with

   --app <name>

   or

   rabetbase app use <name>

Agent Quick Execution Sequence

1. Determine requirement type
   • Standard data CRUD → SDK filter/getOne/create/update/delete
   • Simple aggregation → SDK aggregate
   • Complex JOIN / database functions → Custom SQL
   • External system call / cross-table transaction / complex business orchestration → BFF
2. Get metadata first, then write code
   • At least query

     rabetbase dataset detail --code xxx --format json

     first to get table structure
   • For cross-table scenarios, you also need to query the structure of the target table
   • Use

     rabetbase dataset links --format json

     when you need to understand data model relationships
3. SQL workflow strictly in steps
   • Check existing → Confirm fields → Write → Validate(

     sql validate

     ) → Save(

     sql save

     ) → Test(

     sql exec

     )
4. BFF workflow strictly in steps
   • Check existing → Confirm fields → Check public functions → Write → Preview(

     --dry-run

     ) → Save(

     bff save --yes

     )

Agent Prohibited Behaviors

• Don't guess field names — Must get real field names, types, enumeration values from the return value of

  dataset detail

• Don't skip validate — SQL must be validated via

  sql validate

  or

  sql save --dry-run

  before saving
• Don't manually splice API URLs — All operations are done via CLI commands, don't call HTTP interfaces directly
• Don't guess sqlCode / id — Get real identifiers from

  sql list

  or

  bff list

• Don't handle save failures vaguely — Must explicitly inform the user when

  sql save

  /

  bff save

  returns

  blocked

• Don't write SQL without confirming the table structure — Run

  dataset detail

  first, then write SQL
• Don't loop single queries — Use SDK

  filter + $in

  for batch queries, avoid N+1
• Don't use MCP tool names as CLI commands — Use

  rabetbase sql list

  , not

  list_sql_queries

Interface Selection Priority

1. Standard SDK interface (filter/getOne/create, etc.) — Use it if available instead of writing SQL
2. Aggregate interface — For simple grouping and aggregation
3. Custom SQL — For complex JOIN, database functions, cross-table statistics
4. BFF — For external system calls, cross-table transactions, complex business orchestration

SDK Core Rules

Initialization

import { createClient } from "@lovrabet/sdk";
const client = createClient({
  appCode: "your-app-code",
  accessKey: process.env.RABETBASE_ACCESS_KEY,
  models: [{ tableName: "users", datasetCode: "abc123", alias: "users" }],
});

Filter Query (most commonly used)

const result = await client.models.users.filter({
  where: { status: { $eq: "active" } },
  select: ["id", "name"],
  orderBy: [{ createTime: "desc" }],
  currentPage: 1,
  pageSize: 20,
});

select

orderBy

currentPage

pageSize

$eq

$ne

$gte

$lte

$gt

$lt

$in

$contain

$startWith

$endWith

SQL Call

const data = await client.sql.execute<MyRow>({ sqlCode: "xxx", params: { key: "val" } });
if (data.execSuccess && data.execResult) {
  console.log(data.execResult);
}

BFF Call

const result = await client.bff.execute<DashboardData>({
  scriptName: "getUserDashboard",
  params: { userId: "123" },
});

Key Differences between Frontend and BFF

{ execSuccess, execResult }

T[]

getOne(id)

getOne(id)

client.bff.execute({ scriptName, params })

Intent → Command Index

rabetbase dataset list --name "xxx"

--code

rabetbase dataset detail --code xxx

rabetbase dataset operations --code xxx

rabetbase dataset links

rabetbase sql list --name "xxx"

rabetbase sql detail --sqlcode xxx

rabetbase sql validate --file xxx

rabetbase sql save --file xxx

rabetbase sql exec --sqlcode xxx

--params

rabetbase bff list

rabetbase bff detail --id n

rabetbase bff save --file xxx

--yes

rabetbase codegen sdk --code xxx

rabetbase codegen sql --sqlcode xxx

rabetbase app list

rabetbase app use <name>

rabetbase app add <name> --appcode <code>

rabetbase app remove <name>

--app <name>

Command Groups

Mandatory before execution: After locating the command from the table below, be sure to read the reference documentation for the corresponding command first before invoking it.

list

use

add

remove

list

detail

operations

links

list

detail

validate

save

exec

list

detail

save

sdk

sql

Risk Control

read

write

sql save

--dry-run

high-risk-write

bff save

--yes

--yes

sql save

sql validate

riskLevel

.rabetbase.json

RABETBASE_RISK_LEVEL

.lovrabet.json

Output Format

--format json

{ "ok": true, "command": "...", "risk": "read", "data": {...} }

--format pretty

--format table

Common Error Quick Check

auth_required

rabetbase auth

config_missing

rabetbase project init

--appcode

flag_missing

validation_error

api_error

cancelled

--yes

blocked

Conflict Handling

sql save

bff save

blocked: true

• Inform the user to operate manually on the platform
• Write the content to a local draft file (

  .draft.sql

  /

  .draft.js

  )
• Prohibit retrying, prohibit bypassing
• Must explicitly inform the user when saving is not successful, prohibit vague handling

Frontend Page Rules

• The top comment of the page generated by CLI must be retained, use

  @modified

  for additional notes
• Set

  displayName

  for page components
• Must run

  dataset detail

  to confirm fields and relationships before writing pages
• Prohibit emojis, AI-style copy, exclamation marks, fancy colors; copy should be concise and professional
• Use

  @ant-design/icons

  for icons, use AntD token for colors

In-depth Guides

typescript-sdk.md

sql-mybatis.md

frontend-development.md

troubleshooting.md

backend-function.md

data-api-guidelines.md

sql-creation-workflow.md

bff-creation-workflow.md

conflict-detection.md

best-practices.md