lovrabet-runtime-cli — Lovrabet Runtime CLI

A runtime CLI for business personnel and integration developers, providing capabilities for dataset queries, data CRUD, SQL execution, and BFF invocations.

Structured Output & jq: Use --format compress
(single-line envelope) first when machine-readable JSON is needed; use --format json
for indentation. Both can be combined with the global --jq '<expr>'
to narrow down output; the semantics are consistent with
rabetbase
, see Output Format & --jq for details.

Usage Sequence

Check guides first, then references.

Flow / Decision:
- App Resolution
- Dataset & Data Workflow
- SQL & BFF Workflow
- Troubleshooting
Command Details / Parameter References:
- ```
references/*.md
```

Installation

bash

npm install -g @lovrabet/lovrabet-cli

Authentication

The current primary method is User Access Key (client-ak). Priority: CLI flags > Environment Variables > Configuration File.

User AK: Configure accessKey
in
```
.lovrabet.json
```
or
```
LOVRABET_ACCESS_KEY
```
(suitable for CI); when
```
accessKey
```
exists, use client-ak
Cookie: Read for historical compatibility, no longer the recommended primary method; new documents and Agent guidance default to the AK process

See Authentication Reference for details.

Authentication Command Selection

Only want to update AK while retaining existing configuration: Use
```
lovrabet auth login
```
Want to rebuild the authentication configuration for the current scope from scratch: Use
```
lovrabet auth init
```
Do NOT treat
```
auth init
```
as a regular login command; it will clear existing configurations under the current scope and then only write back the new authentication result
```
auth login --env
```
exists only as a compatibility layer for implementation; do not promote it by default in guidance; prefer
```
auth init --env ...
```
when you need to "clear and rebuild + write to env"

Configuration Scope Principle (

--global

)

Write operations default to the current project (such as
```
app init
```
,
```
app import
```
,
```
config set
```
,
```
config delete
```
), unless the user explicitly passes
```
--global
```
.
Do NOT add
```
--global
```
to commands without user request — the default behavior is already "project-first"; only use
```
--global
```
when the user clearly wants to modify global configurations or is not in a project and intends to write to the global scope.
config set
/
config delete
: When there is no project configuration file (no
```
.lovrabet.json
```
resolved in the current directory) and
```
--global
```
is not passed, the CLI refuses to execute and prompts to use
```
--global
```
or run
```
lovrabet app init
```
first; it will not silently write to the global scope.
app list
: Defaults to remote-first + local cache;
```
--local
```
reads only the cache;
```
--no-cache
```
forces fetching from the online source and refreshes the cache.
app pull
: Only refreshes the local app cache, does not write the remote application list to
```
.lovrabet.json
```
; it is a manual refresh command, use
```
app list
```
preferentially in daily use
app use
/
app import
: Only operate on local user intent configurations (
```
defaultApp
```
/ top-level
```
appcode
```
), see Application Management for details.

Prohibited Behaviors for Agents

Do NOT add
--global
without permission — see the "Configuration Scope Principle" above; default to writing to the project and reading merged configurations; only use
```
--global
```
in scenarios explicitly requested by the user or specified in documents.
Prohibit modifying configuration files to elevate permissions — Do not modify
```
.lovrabet.json
```
, environment variables, or cache content to increase
```
riskLevel
```
, switch to an
```
accessKey
```
not explicitly authorized by the user, forge
```
defaultApp
```
/
```
appcode
```
/
```
env
```
, or break current permission boundaries to complete tasks. When permissions are insufficient, clearly explain the restrictions and request the user to provide legitimate target applications, credentials, or confirm the scope.

Agent Decision: When to Fetch Application Information

Do not always run

app list

before executing

dataset

data

sql

bff

. First determine whether the current requirement truly requires "app resolution".

Scenarios Where the Current Application Can Be Used Directly

Use the current application directly first without running

app list

first if any of the following conditions are met:

The user has explicitly provided
```
--appcode
```
The user has explicitly provided
```
--app <name>
```
There is a clear
```
defaultApp
```
in the current configuration
The issue is clearly a continuation of operations in the "current project / current default application" context

In such cases, proceed directly to:

```
dataset list --name ...
```
```
dataset detail --code ...
```
```
data filter/getOne/create/update/delete
```

Do not run an extra application discovery command to generate noise.

Scenarios Where Application Information Must Be Fetched First

Perform app resolution first, and run

lovrabet app list

if necessary, when:

The user only provides business requirements without any app clues
For example: "Help me query the order dataset" "Check the customer table in CRM"
There is no
```
defaultApp
```
and no explicit
```
--appcode
```
There are multiple candidate apps in the current configuration, and the requirement description is not sufficient to directly lock one
The user explicitly says "First see which applications I have" or "Which application should this requirement be in"

Usage of

app list

Default:
```
lovrabet app list
```
- Remote-first, automatically refreshes cache when necessary
Only want to reuse local cache:
```
lovrabet app list --local
```
Clearly need to force a refresh:
```
lovrabet app list --no-cache
```

How to Determine Which Application to Use Based on Requirements

Follow the priority below, do not skip steps arbitrarily:

Explicit specification first
- Directly use the app name, appcode, or current project context provided by the user
Local default first
- Use the default application first if there is a
```
defaultApp
```
  and the requirement does not show conflicts
Requirement keyword mapping
- When business domain keywords appear in the requirement, perform semantic matching first using the
```
name
```
  from the
```
app list
```
  output
- Examples:
```
CRM
```
  ,
```
Order
```
  ,
```
E-commerce
```
  ,
```
License
```
  ,
```
Requirements Management
```
Verification-based convergence
- Execute
```
dataset list --app <name> --name <keyword>
```
  for candidate applications
- Converge to the app whose returned datasets match better

Recommended Decision Flow

When the user says "Help me query some business data", the recommended flow is:

First determine whether there is a clear app context currently
If not, run
```
lovrabet app list
```
Select 1-2 candidate apps based on business keywords

Execute

dataset list --app <name> --name <keyword>

for candidate apps

Proceed with
```
dataset detail
```
or
```
data filter
```
after hitting a match

Do NOT Do the Following

Do not run
```
app list
```
every time
Do not make arbitrary decisions based only on app names without verifying via
```
dataset list
```
Do not write the platform application directory back to
```
.lovrabet.json
```
Do not judge that an app does not exist just because it is not in the local configuration; check the cache/remote directory first

Service	Command	Description	Risk Level	Requires Cookie
auth	`login`	Save accessKey	—	—
auth	`init`	Clear current scope configuration and rebuild authentication	write	—
auth	`logout`	Clear local accessKey	—	—
app	`init`	Create `.lovrabet.json` configuration	write	—
app	`list`	List applications visible to the current AK (remote-first, with cache)	read	—
app	`pull`	Refresh local app cache	write	—
app	`use`	Switch default application	write	—
app	`import`	Import top-level configuration from upgraded .rabetbase.json	write	—
config	`list`	View complete configuration	read	—
config	`get`	Read configuration item	read	—
config	`set`	Write configuration item	write	—
config	`delete`	Delete configuration item	write	—
skill	`install`	Globally install official runtime Skill	write	—
dataset	`list`	List datasets (including field lists)	read	Yes
dataset	`detail`	View dataset structure	read	Yes
data	`filter`	Query data records by condition	read	—
data	`getOne`	Get a single record by ID	read	—
data	`aggregate`	Aggregation statistics	read	—
data	`create`	Create new record	write	—
data	`update`	Update record	write	—
data	`delete`	Delete record (requires `--yes` )	high-risk-write	—
sql	`detail`	View SQL query details	read	Yes
sql	`exec`	Execute SQL query	read	—
bff	`detail`	View BFF script details	read	Yes
bff	`exec`	Execute BFF function	read	—
logs	`show`	View command execution history	read	—
logs	`clear`	Clear command history	read	—

Intent → Command Index

Initialization & Configuration

Intent	Command
Install / Refresh Skill	`lovrabet skill install`
Initialize configuration	`lovrabet app init --appcode <code> [--env daily] [--global]`
Import from upgraded rb configuration	`lovrabet app import --file /path/to/.rabetbase.json`
Login	`lovrabet auth login`
Reset and rebuild authentication configuration	`lovrabet auth init --access-key ak_xxx [--env daily]`
Logout	`lovrabet auth logout`
View configuration	`lovrabet config list`
Read configuration item	`lovrabet config get <key>`
Set configuration item	`lovrabet config set <key> <value> [--global]`
Delete configuration item	`lovrabet config delete <key> [--global]`
View application list	`lovrabet app list`
View only locally cached application list	`lovrabet app list --local`
Force refresh online application list	`lovrabet app list --no-cache`
Manually refresh app cache	`lovrabet app pull`
Switch default application	`lovrabet app use <name>`

Dataset & Data Operations

Intent	Command
Find dataset	`lovrabet dataset list [--name keyword] [--code exact-code]`
View dataset fields	`lovrabet dataset detail --code <code> [--verbose]`
Query data	`lovrabet data filter --code <code> --params '{"where":{"status":{"$eq":"active"}},"currentPage":1,"pageSize":20}'`
Get single record	`lovrabet data getOne --code <code> --params '{"id":123}'`
Create new record	`lovrabet data create --code <code> --params '{"name":"test","amount":100}'`
Update record	`lovrabet data update --code <code> --params '{"id":123,"status":"done"}'`
Delete record	`lovrabet data delete --code <code> --params '{"id":123}' --yes`
Aggregation statistics	`lovrabet data aggregate --code <code> --params '{"aggregate":[{"field":"amount","type":"SUM","alias":"total"}],"groupBy":["status"]}'`

SQL & BFF

Intent	Command
View SQL	`lovrabet sql detail --sqlcode <code>`
Execute SQL	`lovrabet sql exec --sqlcode <code> --params '{"key":"value"}'`
View BFF	`lovrabet bff detail --id <id>`
Execute BFF	`lovrabet bff exec --name <functionName> --params '{"key":"value"}'`

Logs

Intent	Command
View logs	`lovrabet logs`
Clear logs	`lovrabet logs clear`

Unified --params Design

data

sql exec

, and

bff exec

all pass JSON request bodies via

--params

, which are directly forwarded to the runtime API:

bash

lovrabet <service> <command> --code <code> --params '<json>'

Data CRUD Workflow

bash

# 1. Locate the target dataset
lovrabet dataset list --name "Order"

# 2. View field structure (confirm dataset code + field names)
lovrabet dataset detail --code <datasetCode>

# 3. Query data
lovrabet data filter --code <datasetCode> --params '{"where":{"status":{"$eq":"active"}},"currentPage":1,"pageSize":20}'

# Go to page 2
lovrabet data filter --code <datasetCode> --params '{"where":{"status":{"$eq":"active"}},"currentPage":2,"pageSize":20}'

# 4. Get single record
lovrabet data getOne --code <datasetDataset> --params '{"id":123}'

# 5. Create record (preview with dry-run first)
lovrabet data create --code <datasetCode> --params '{"name":"test","amount":100}' --dry-run
lovrabet data create --code <datasetCode> --params '{"name":"test","amount":100}'

# 6. Update record
lovrabet data update --code <datasetCode> --params '{"id":123,"status":"completed"}'

# 7. Delete record (high risk, requires confirmation)
lovrabet data delete --code <datasetCode> --params '{"id":123}' --dry-run
lovrabet data delete --code <datasetCode> --params '{"id":123}' --yes

--params Structure for filter

The

--params

JSON is directly forwarded as the

filter

request body:

json

{
  "where": { "status": { "$eq": "active" } },
  "select": ["id", "name", "status"],
  "orderBy": [{ "id": "desc" }],
  "currentPage": 1,
  "pageSize": 20
}

where Query Syntax

Operator	Meaning	Example
`$eq`	Equal to	`{"status":{"$eq":"active"}}`
`$ne`	Not equal to	`{"status":{"$ne":"deleted"}}`
`$gte/$gteq/$lte/$lteq`	Comparison	`{"amount":{"$gte":100}}`
`$contain`	Contains match	`{"name":{"$contain":"test"}}`
`$startWith`	Prefix match	`{"name":{"$startWith":"pre"}}`
`$endWith`	Suffix match	`{"name":{"$endWith":"suf"}}`
`$notNull`	Non-null check	`{"app_code":{"$notNull":true}}`
`$in`	In	`{"status":{"$in":["active","pending"]}}`
`$and/$or`	Combined conditions	`{"$and":[...]}`

--params Structure for aggregate

The

--params

JSON is directly forwarded as the

aggregate

request body, with fields aligned with the SDK

AggregateParams

json

{
  "select": ["category_id"],
  "aggregate": [
    { "type": "SUM", "field": "amount", "alias": "total_amount", "round": true, "precision": 2 }
  ],
  "where": { "status": { "$eq": "active" } },
  "groupBy": ["category_id"],
  "having": [
    { "columnName": "total_amount", "condition": { "$gte": 1000 } }
  ],
  "join": [
    { "type": "LEFT", "table": "users", "condition": { "user_id": "id" } }
  ],
  "orderBy": [{ "total_amount": "desc" }],
  "currentPage": 1,
  "pageSize": 20
}

Global Options

Option	Description
`--appcode <code>`	Override appcode
`--env <env>`	Environment: production / development / daily
`--format <fmt>`	Output: json / pretty / compress (default preference see configuration & `--help` )
`--jq '<expr>'`	Perform jq filtering on the final printed JSON for json / compress; behavior is consistent with `rabetbase` , see lovrabet-output-format-jq.md for details
`--app <name>`	Specify application in multi-app mode
`--dry-run`	Preview without execution (write commands)
`--yes`	Skip confirmation (high-risk-write)
`--non-interactive`	Non-interactive mode (CI)

Configuration File

.lovrabet.json

in the project root directory (see Configuration Reference for complete fields, priority, and environment variables):

json

{
  "appcode": "app-xxxxxxxx",
  "env": "daily",
  "accessKey": "ak_xxx"
}

The configuration file only saves user intent configurations, not the platform application directory. The remote application list cache is located at:

text

~/.lovrabet/cache/<env>/<ak-fingerprint>/my-apps.json

Example of multi-app intent configuration:

json

{
  "accessKey": "ak_xxx",
  "env": "daily",
  "defaultApp": "crm"
}

Risk Control

Level	Command	Protection
read	dataset list/detail, data filter/getOne/aggregate, sql detail/exec, bff detail/exec, app list, config list/get, logs	None
write	data create, data update, app use, config set/delete, app import	dry-run preview
high-risk-write	data delete	Requires `--yes` or interactive confirmation

Detailed References

Topic	File
Output Format & `--jq`	lovrabet-output-format-jq.md
Authentication	lovrabet-auth.md
Initialization	lovrabet-init.md
Application Management	lovrabet-app.md
Configuration Management	lovrabet-config-commands.md
Configuration File Reference	lovrabet-config.md
Dataset Discovery	dataset-discovery-workflow.md
Data CRUD	data-crud-workflow.md
SQL Workflow	lovrabet-sql-workflow.md
BFF Workflow	lovrabet-bff-workflow.md
Logs	lovrabet-logs.md

lovrabet

NPX Install

Tags

SKILL.md Content (Chinese)

lovrabet-runtime-cli — Lovrabet Runtime CLI

Usage Sequence

Installation

Authentication

Authentication Command Selection

Configuration Scope Principle (
`--global`
)

Prohibited Behaviors for Agents

Agent Decision: When to Fetch Application Information

Scenarios Where the Current Application Can Be Used Directly

Scenarios Where Application Information Must Be Fetched First

Usage of
`app list`

How to Determine Which Application to Use Based on Requirements

Recommended Decision Flow

Do NOT Do the Following

Intent → Command Index

Initialization & Configuration

Dataset & Data Operations

SQL & BFF

Logs

Unified --params Design

Data CRUD Workflow

--params Structure for filter

where Query Syntax

--params Structure for aggregate

Global Options

Configuration File

Risk Control

Detailed References

lovrabet

NPX Install

Tags

SKILL.md Content (Chinese)

lovrabet-runtime-cli — Lovrabet Runtime CLI

Usage Sequence

Installation

Authentication

Authentication Command Selection

Configuration Scope Principle (--global)

Prohibited Behaviors for Agents

Agent Decision: When to Fetch Application Information

Scenarios Where the Current Application Can Be Used Directly

Scenarios Where Application Information Must Be Fetched First

Usage of app list

How to Determine Which Application to Use Based on Requirements

Recommended Decision Flow

Do NOT Do the Following

Intent → Command Index

Initialization & Configuration

Dataset & Data Operations

SQL & BFF

Logs

Unified --params Design

Data CRUD Workflow

--params Structure for filter

where Query Syntax

--params Structure for aggregate

Global Options

Configuration File

Risk Control

Detailed References

Configuration Scope Principle (
`--global`
)

Usage of
`app list`