Advanced: Configuration, Cache, and Integration Troubleshooting

This page is for enterprise IT, delivery and implementation teams, developers extending the platform, and Skill maintainers. Business users rarely need to understand .lovrabet.json, the app cache, AccessKey scopes, or integration details.

The short version

The Lovrabet CLI is an AI operations suite built for business scenarios. For business users, the main path is to state a business goal and let the Agent call the CLI to query, verify, execute, and collaborate. Configuration, cache, and app resolution belong to the technical maintenance layer — you only deal with them during onboarding, custom development, troubleshooting, or enterprise-wide deployment.

The current configuration model boils down to one sentence:

Local config only stores "how I prefer to use the CLI"; the remote plus the cache store "which apps actually exist in the system". defaultApp is the first candidate to validate against, not a forced context.

When to read this page

Scenario	What you need
Enterprise IT deploying the Agent for business teams	Standardize the CLI, Skills, AccessKeys, and the default candidate app
Delivery teams debugging issues on site	Check whether the AK, environment, app cache, and dataset permissions are healthy
Customizing or self-hosting the Lovrabet stack	Know which names, package names, domains, and Skill sources are configurable
Skill maintainers encoding business workflows	Understand the priority order of defaultApp, --app, and --appcode
CI / automation integration	Control behavior such as --format compress, --jq, --dry-run, and --yes

What local config stores

.lovrabet.json stores only user-intent settings, for example:

• accessKey
• env
• format
• riskLevel
• defaultApp
• The legacy top-level appcode for single-app compatibility

It does not store the full platform app catalog, and it does not represent a "project" on the Lovrabet platform.

A typical config looks like:

{
  "accessKey": "ak_xxx",
  "env": "production",
  "format": "compress",
  "defaultApp": "crm"
}

The two config layers

| Scope | File path | Purpose | |-|-| | Local config | ./.lovrabet.json | Optional user-intent settings for the current directory | | Global config | ~/.lovrabet.json | Machine-wide defaults |

When reading, local config overrides global config. "Local" here refers only to the file scope — it is not a platform project concept.

When writing config, keep in mind:

• Prefer explicit --app / --appcode for day-to-day business commands
• Don't modify .lovrabet.json just to run a one-off query
• config set / config delete are advanced maintenance commands
• If there is no local config and --global is not passed, the CLI refuses to run — this prevents silently polluting the global config

App catalog and cache

The app catalog visible to the current AK is maintained by two commands:

lovrabet app list
lovrabet app pull

The catalog is cached locally, for example:

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

Responsibilities at a glance:

• .lovrabet.json stores "how I prefer to use the CLI"
• The cache stores "which apps this account can actually see"
• The remote platform is the source of truth for the app catalog

Common troubleshooting commands:

lovrabet app list
lovrabet app list --local
lovrabet app list --no-cache
lovrabet app pull --env daily

App resolution rules

When running dataset / data / sql / bff, the app source priority is roughly:

1. Explicit --appcode
2. Explicit --app
3. The confirmed current app context
4. The defaultApp default candidate
5. The legacy top-level appcode field

defaultApp is only a weak candidate. When the user's request touches a new business domain — orders, products, inventory, CRM, tickets — first validate datasets by keyword under the default candidate; only broaden the search to the full app list if that fails. Never assume defaultApp is correct just because it exists in the config.

Recommended troubleshooting flow:

lovrabet app list
lovrabet dataset list --app <appName> --name <业务关键词>
lovrabet dataset detail --code <datasetCode>
lovrabet data filter --code <datasetCode> --params '{"currentPage":1,"pageSize":5}'

Auth and permission checks

The current Lovrabet Runtime CLI uses AccessKey as its primary auth path.

lovrabet auth login
lovrabet auth status
lovrabet auth info --format compress

Recommended check order:

1. Confirm auth info returns the user for the current AK
2. Confirm app list shows the target app
3. Verify the business object exists with dataset list --name <keyword>
4. Inspect fields and permission boundaries with dataset detail
5. Add --dry-run before any write command

Integration and custom development

To point the CLI at a self-hosted backend or custom service domains (the runtime domain carries the main traffic for dataset / sql / bff), see Custom service domains and self-hosted backends.

If your enterprise deploys the Lovrabet stack independently — or you want to rename the Lovrabet CLI, swap the npm package, or change the Skill source — start with the product constants in the runtime CLI project.

The relevant config lives in:

src/constant/product.ts
src/constant/distribution.ts

Commonly changed items:

Config type	Examples
CLI display and command name	lovrabet / Lovrabet CLI
npm package name	@lovrabet/lovrabet-cli
Skill install source	lovrabet/lovrabet-cli
Domains and console links	Website, docs, user center, AccessKey management
Local config filename	.lovrabet.json
cache / log naming	Cache directory, runtime log files

When customizing, change the constants first — don't scatter string replacements across command implementations.

CI and Agent automation tips

For automation scenarios:

• Use environment variables or explicit flags instead of implicit local config
• Default to --format compress output
• Add --jq when you need specific fields
• Run --dry-run first for regular writes
• Require an explicit --yes for high-risk writes

Examples:

LOVRABET_ACCESS_KEY=ak_xxx \
lovrabet dataset list --app crm --name 客户 --format compress

lovrabet data update \
  --app crm \
  --code <datasetCode> \
  --params '{"id":123,"status":"processing"}' \
  --dry-run

Common misconceptions

Misconception	Correct understanding
The app list lives in .lovrabet.json	The app catalog comes from the remote and the cache
app use writes the full app details	app use writes only defaultApp
If defaultApp exists, it must be used	defaultApp is a default candidate that still needs validation against business semantics
Business users need to understand these details	Config details are mainly for IT, delivery, custom development, and Skill maintainers
Agents can freely guess apps / fields	Validate first against real app list, dataset list, and dataset detail output

One-sentence summary

Business users never need to read this page — they just state business goals. Technical readers use it to turn the Lovrabet CLI into a stable, debuggable, customizable runtime entry point that Agents can call safely.