Skip to main content

Installation and Login

This page is mainly for integration engineers, skill maintainers, and delivery engineers. Business users usually do not need to perform these steps themselves.

The content here is aligned with lovrabet-runtime-cli v2.1.x and @lovrabet/cli-framework v1.0.3. The latest version already bundles jq, so in most cases you do not need to install jq separately.

When this page matters​

Read this page if:

  • you are setting up lovrabet on a machine for the first time
  • you are preparing a runtime environment for an Agent client
  • you need to install or update Lovrabet skills
  • you need to log in with an AccessKey and confirm which apps are visible to the current account

If you are already using AI coding tools such as Claude Code, Codex, Cursor, Trae, or Windsurf, you can simply copy the prompt below into your AI assistant. It will install the CLI, install the Skill, and handle AccessKey login — you only need to paste your AccessKey when prompted.

Prompt (copy and paste into your AI assistant):

Please install Lovrabet CLI: https://www.lovrabet.com/agent-install-guides/lovrabet-cli.md

Supported AI Agent tools: Claude Code, Codex, Cursor, Trae, Windsurf, GitHub Copilot

💡 If you prefer to control each step yourself, or do not use an AI Agent tool, continue with the manual installation below.

Manual Install: 1. Install the CLI​

Prerequisite

Node.js >= 20

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

2. Install skills​

Use the built-in CLI command to install or update the Lovrabet Skill:

lovrabet skill install

It invokes the official skills tool globally. You can also run the equivalent command directly:

npx skills add lovrabet/lovrabet-cli -g -y

Skills help the Agent understand:

  • which workflow should be used for which business request
  • which SQL or BFF is allowed in that workflow
  • which actions must stay read-only and which ones may write

3. Log in with an AccessKey​

Lovrabet Runtime CLI now uses AccessKey as its main auth path.

lovrabet auth login
lovrabet auth login --access-key ak_xxxxxxxxxxxxxxxx

Then verify:

lovrabet auth status
lovrabet auth info --format compress

Where to get the AccessKey:

Workbench → Avatar → AccessKey Management

AccessKeys do not expire automatically

If you suspect a leak, rotate the key in the platform.

4. Confirm apps and the default candidate​

After login, the next step is usually to confirm which apps are visible to the current account. Lovrabet Runtime CLI does not require creating a “project” or initializing a local workspace first; most commands can target an app directly with --app or --appcode.

lovrabet app list
lovrabet app list --local
lovrabet app list --no-cache
lovrabet app use crm

The key point is:

  • app list and app pull maintain the local cache
  • .lovrabet.json is only an optional local user-intent config, such as defaultApp, appcode, env, and accessKey

The current version no longer stores the full remote app directory inside .lovrabet.json.

5. App selection priority​

At runtime, app selection typically follows this order:

  1. explicit --appcode
  2. explicit --app
  3. confirmed current app context
  4. configured defaultApp candidate
  5. top-level compatibility field appcode

defaultApp is only a default candidate, not strong context. If the request clearly points to a business domain such as orders, products, inventory, or CRM and no app was specified, first validate the default candidate by searching datasets with the request keywords. If that does not match, expand the search to the app list.

Common examples:

lovrabet data filter --appcode app-xxxxxxxx --code <datasetCode> --params '{"pageSize":10}'
lovrabet dataset list --app crm --name 客户
lovrabet app use crm
lovrabet dataset list --name 客户

After installation and login, it is a good idea to run:

lovrabet auth status
lovrabet auth info --format compress
lovrabet doctor
lovrabet app list

If you already know a dataset keyword, you can also try:

lovrabet dataset list --name 客户

This is not about teaching business users to run commands.
It is about confirming that the Agent will have a stable environment to call.

7. Common global flags​

FlagMeaning
--appcodeUse a specific appcode directly
--appSelect an app by name for this command
--envproduction / development / daily
--formatjson / pretty / compress, default compress
--jqFilter JSON output with jq
--dry-runPreview the action without executing
--yesSkip confirmation for high-risk actions
--non-interactiveForce CI / non-interactive mode
--globalUse or write global config

8. What the config file looks like now​

Typical shapes are very simple:

Direct appcode mode​

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

Default app mode​

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

The current design keeps local config focused on user intent, while the app directory itself comes from the remote platform plus local cache. A defaultApp means “try this candidate first when there is no stronger app signal,” not “force every request into this app.”

9. One practical note for business-facing setups​

If you are enabling this for business teams, the two most useful things to teach are:

  • how to describe the business problem clearly
  • how to say “read-only” or “preview first” when writes are involved

The CLI details should stay mostly behind the Agent.