# 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 22.20.0 or later
- A Lovrabet account with access to the target runtime app
- A User Access Key for authenticated commands

## Install

```bash
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:

```bash
lovrabet cli-skill install
lovrabet doctor
```

You can also run a specific version with npm tooling:

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

## Quick Start

Authenticate first:

```bash
lovrabet auth login
lovrabet auth info --format compress
```

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

```bash
lovrabet auth login --access-key <ACCESS_KEY>
```

List available runtime apps:

```bash
lovrabet app list
```

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

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

Discover a dataset and inspect its contract before querying records:

```bash
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:

```bash
lovrabet config init --region cn
lovrabet config init --region id
```

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

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

```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 uses `runtimeDomain`, while search uses the optional `kbServiceDomain`. 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:

```bash
lovrabet cli-skill install
```

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

```bash
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 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:

```bash
lovrabet <service> --help
lovrabet <service> <command> --help
```

## Output and Automation

Global options are available across commands:

```bash
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.

## 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 KB Service V2 directly. Official Mainland China and Indonesia connections resolve the endpoint automatically:

```bash
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 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 KB management remains unchanged. Results retain `schemaVersion: 2` and the runtime profile.