Lovrabet CLI

Lovrabet CLI is the runtime command-line interface for Lovrabet applications. It helps developers, delivery teams, operators, and AI agents work with published apps, datasets, records, SQL queries, Backend Function scripts, files, OCR, knowledge bases, artifacts, and runtime Skills from a stable terminal surface.

The CLI is designed for runtime operations: discover the right app, inspect data contracts, query real records, execute approved runtime capabilities, and turn repeatable workflows into agent-ready Skills.

Requirements

• Node.js 24.0.0 or later
• A Lovrabet account with access to the target runtime app
• A User Access Key for authenticated commands

Install

npm install -g @lovrabet/lovrabet-cli@latest
lovrabet --version
lovrabet --help

The npm package automatically installs the same-version Built-in Skill. If the postinstall warning reports an external Skills CLI, network, or permission problem, repair it after resolving the cause:

lovrabet cli-skill install
lovrabet doctor

You can also run a specific version with npm tooling:

npx @lovrabet/lovrabet-cli@latest --help

Quick Start

Authenticate first:

lovrabet auth login
lovrabet auth info --format compress

For non-interactive environments, pass an Access Key explicitly:

lovrabet auth login --access-key <ACCESS_KEY>

List available runtime apps:

lovrabet app list

Bind the current workspace to an app, or pass --app / --appcode on each command:

lovrabet workspace init --app <app-name>
lovrabet workspace init --appcode <app-code>

Discover a dataset and inspect its contract before querying records:

lovrabet dataset list --name customer
lovrabet dataset detail --code <dataset-code>
lovrabet data filter --code <dataset-code> --params '{"currentPage":1,"pageSize":20}'

Use --format pretty for human-readable output and --format json or --format compress for scripts and agents.

Country/Region and Independent Deployment Routing

Configure an official node by country/region:

lovrabet config init --region cn
lovrabet config init --region id

For an independent deployment, both Lovrabet CLIs can import the same versioned routing manifest:

lovrabet config init --domain-config ./lovrabet-domains.json

{
  "protocol": "lovrabet-routing/v1",
  "kind": "enterprise",
  "cdn": {
    "libraries": "https://cdnjs.cloudflare.com/ajax/libs",
    "lovrabet": "https://g.lovrabet.com"
  },
  "domains": {
    "userDomain": "https://user.customer.example.com",
    "apiDomain": "https://api.customer.example.com",
    "runtimeDomain": "https://runtime.customer.example.com",
    "skillDomain": "https://skills.customer.example.com",
    "kbServiceDomain": "https://kb.customer.example.com",
    "kbDomain": {
      "rabetbase-cli": "https://kb-admin.customer.example.com"
    },
    "appDomain": "https://app.customer.example.com"
  }
}

A Domain can be a shared HTTPS origin string or a consumer-specific object. For every Domain it consumes, Lovrabet CLI resolves lovrabet-cli first and then default; if neither exists, the import fails instead of using another consumer's Domain. It preserves but does not consume the shared manifest's kbDomain; Personal KB management and search use kbServiceDomain; other runtime operations continue to use runtimeDomain. Official region mode and explicit independent-deployment Domains are mutually exclusive.

The same file may also contain CDN settings, database metadata, or Domains for other consumers. Lovrabet CLI ignores and does not persist fields it does not use; it validates userDomain, apiDomain, runtimeDomain, skillDomain, and optional kbServiceDomain.

Official routing is compiled into this package from the independent lovrabet-routing repository. The CLI does not download that catalog at runtime. Generated files under src/generated/ are read-only snapshots with a consumer projection digest and must be updated through the routing repository's generator.

AI Agent Skill

The Lovrabet CLI Built-in Skill ships inside the npm package and is installed with the CLI. Use the repair command when lovrabet doctor reports it missing or inconsistent:

lovrabet cli-skill install

After selecting an app, install app-specific business Skills when available:

lovrabet skill install
lovrabet skill install --scope personal
lovrabet skill install --scope company

Business Skills continue to install into user-level Agent Skill directories by default, with app-prefixed link names such as <appCode>--<skillCode>. Use lovrabet skill install --project to link them into the current project's .agents/skills/<skillCode> directory. Project and user-level installations can coexist; an explicit project installation does not remove existing user-level links or the cache they still reference.

Common Commands

| Area | Commands | | --- | --- | | Authentication | lovrabet auth login, lovrabet auth info, lovrabet auth logout | | User accounts | lovrabet user-account bind | | App and workspace | lovrabet app list, lovrabet workspace init, lovrabet workspace use | | Dataset discovery | lovrabet dataset list, lovrabet dataset detail, lovrabet dataset sdk-doc | | Data operations | lovrabet data filter, lovrabet data getOne, lovrabet data create, lovrabet data batchCreate, lovrabet data import-excel, lovrabet data update, lovrabet data delete, lovrabet data aggregate | | SQL and Backend Function | lovrabet sql detail, lovrabet sql exec, lovrabet bff detail, lovrabet bff exec | | Personal assets | lovrabet personal-bff list, lovrabet artifact list, lovrabet kb list | | Runtime files and OCR | lovrabet file upload, lovrabet file query-url, lovrabet ocr recognize | | Skills | lovrabet cli-skill install, lovrabet skill install, lovrabet skill create, lovrabet skill validate, lovrabet skill push --diagram-file, lovrabet skill diagram-show | | Diagnostics | lovrabet doctor, lovrabet schema, lovrabet logs show, lovrabet update |

Run command-level help for flags and prerequisites:

lovrabet <service> --help
lovrabet <service> <command> --help

Output and Automation

Global options are available across commands:

lovrabet dataset list --format json
lovrabet data filter --code <dataset-code> --params '{"currentPage":1,"pageSize":10}' --jq '.data'
lovrabet data update --code <dataset-code> --params '{"id":1,"status":"done"}' --dry-run

Important options:

• --app <name>: select an app profile by name
• --appcode <code>: override the target app code
• --format json|pretty|compress: choose output format
• --jq <expr>: filter JSON output
• --dry-run: preview supported write operations
• --yes: skip confirmation for high-risk writes
• --non-interactive: force CI-friendly behavior

Safety Notes

• Inspect dataset contracts with dataset detail before writing records.
• Prefer read commands before write commands when diagnosing data issues.
• Use --dry-run where supported before create, update, delete, artifact, Personal Backend Function, or Skill operations.
• Use --yes only when the target app, dataset, parameters, and impact are already verified.
• Before binding a DingTalk account, use auth info and --dry-run to verify the current AccessKey identity and target user ID.
• Do not commit Access Keys, generated credentials, or local user config files.

Recoverable Excel Import

Inspect the target dataset with lovrabet dataset detail --code <dataset-code>. For METADATA, import one XLSX worksheet using a local JSON mapping from Excel headers to field codes, for example {"Name":"name","Amount":"amount"}:

lovrabet data import-excel --appcode <app-code> --code <dataset-code> --file ./records.xlsx --mapping ./mapping.json --dry-run
lovrabet data import-excel --appcode <app-code> --code <dataset-code> --file ./records.xlsx --mapping ./mapping.json
lovrabet data import-excel --appcode <app-code> --code <dataset-code> --file ./records.xlsx --mapping ./mapping.json --resume

The command uses the current User AK and an accessible published app. It checks metadata, field values and the server import contract before writing. Dry-run reports valid/invalid rows, empty rows, errors and warnings without writing records or a checkpoint. Successful writes are verified field by field through readback. Keep the original file, mapping, identity, target and checkpoint when resuming an uncertain result; do not delete the checkpoint or start a new import.

Use --sheet for a worksheet name or 1-based index, --header-row for the header row, and --batch-size (1–500, default 500). Requests also respect the server's byte limit. --checkpoint and --report select private output files; defaults are the XLSX path plus .import-checkpoint.json and .import-report.json. The source, mapping and output files must be different. XLSX files are limited to 20 MB, expanded content to 100 MB, rows to 100,000 and columns to 256. Formula cells require cached results; unsupported, generated or reserved fields cannot be mapped as business inputs.

For DB_TABLE, follow the Excel-to-JSON batch workflow. Validate the full file against the actual writable fields, value types and business keys; check existing records, then prepare fixed JSON batches within the target API's row/byte limits and local argument-size limits. lovrabet data batchCreate --appcode <app-code> --code <dataset-code> --params '<JSON array>' submits one batch. It does not parse XLSX or split batches; --dry-run only previews the request and does not validate server constraints or write permissions. Record each batch's intent/result and read back its IDs or confirmed unique business keys before advancing. Unknown outcomes require reconciliation, not a whole-batch resend; do not assume atomic rollback or automatic upsert. There is no import checkpoint or --resume for this route. Missing source, permission or import contract errors stop the import without switching APIs. Non-Excel batchCreate remains available for both METADATA and DB_TABLE.

Documentation

• Website: https://www.lovrabet.com
• Developer documentation: https://open.lovrabet.com/
• CLI help: lovrabet --help

License

Licensed under Apache-2.0. See LICENSE and NOTICE for details.

Knowledge search

lovrabet kb search calls POST /api/knowledge-base/search with explicit public, company, and personal scopes. Official Mainland China and Indonesia connections resolve the endpoint automatically:

lovrabet kb search --appcode <appCode> --query "approval rules" --topk 5 --format json
lovrabet kb search --kb-service-url https://kb.override.example --appcode <appCode> --query "approval rules" --format json

For independent deployments, configure kbServiceDomain in the connection settings. Only --kb-service-url overrides a single search request without saving it; that override must come from the user or deployment administrator. Origins cannot include credentials, a path, query, or fragment. Global has no registered KB endpoint and does not borrow another region's address. Search uses the current user AK, rejects redirects, and does not switch endpoints on failure. Personal management uses the configured kbServiceDomain; the search-only URL override does not change management requests. Results retain schemaVersion: 2 and the runtime profile.

Personal knowledge management

kb list, kb detail, kb create, and kb update use the configured KB Service HTTPS origin and the current User AK. Requests omit cookies, reject redirects, and support cancellation with a 60-second timeout per request. Writes are never retried automatically. Each command pins one origin across reads and writes. After a timeout, connection failure, HTTP 5xx, or an unverifiable write response, the entry may already have been saved: reconcile through read-only kb detail or kb list before writing again. Create uses POST /api/knowledge-base/personal/create; update uses POST /api/knowledge-base/personal/update, always as JSON. All knowledge calls, including reads, use POST with appCode in the JSON body and no protocol header. Detail uses POST /api/knowledge-base/personal/get-one; detail and update send the string ID in JSON body.id. The personal scope comes from the path; body.scope is omitted. Update reads the current version and sends expectedVersion even when a new title is provided. HTTP 409 is a conflict; preserve the input and read again before deciding on another update. Successful saved VOs are verified by detail readback. IDs remain strings throughout flags and output, including IDs beyond JavaScript's safe integer range. Dry-run shows the actual method, path and JSON; update dry-run only reads the current version.

kb list aggregates all personal pages, including collections over 300 entries, and keeps data.total/items; --verbose includes complete content. The default page size is 50. POST personal/page sends appCode/currentPage/pageSize/view=summary in the JSON body. Each summary is followed by a detail read on the same configured service, verifying ID, app, scope, owner and version. A failed or changed readback fails the entire list; partial content is never presented as a complete record. No content is truncated. Invalid records, inconsistent page totals, duplicate IDs, or missing records fail the command. Pagination is not a snapshot: concurrent replacement without a changed total or duplicate ID may not be detected; avoid editing the collection while listing it.

kb detail retains the full stored body. An empty UTF-8 file intentionally clears the body on update. A missing response body field is a protocol error. After writing, read the entry back and check retrieval separately; saved content does not by itself prove that indexing or search is ready.

Responses retain the Result envelope and existing userId/ragStatus/ragErrorMessage fields. JSON long IDs are parsed from their original numeric tokens into strings without rounding.

Report a problem

lovrabet issue report --title "Query failed" --description-file ./issue.md --dry-run
lovrabet issue report --title "Query failed" --description-file ./issue.md

Uses your current identity; an application is optional. Preview the redacted content before submitting. On success, the command displays Issue log submitted. Include reproduction steps and error evidence explicitly; conversation and command history are not collected automatically.