Advanced: Tips and Troubleshooting

This page is for whoever integrates, maintains, or debugs the CLI. If you only use it through an Agent, you generally don't need to read it end to end.

---

Available output formats

The runtime CLI supports three output formats:

Format	Best for
compress	Agents, scripts, CI — the default
json	Debugging, saving the raw structure
pretty	Human reading in a terminal

Common usage:

lovrabet app list --format json
lovrabet data filter --code <datasetCode> --format pretty
lovrabet schema --format compress

To keep filtering fields from structured output, add --jq:

lovrabet app list --format compress --jq '.data.items[] | {name, appcode}'

---

How --jq works now

The current version ships a built-in jq sidecar. Resolution order:

1. JQ_PATH
2. The jq bundled with the CLI
3. jq on the system PATH

In most cases you no longer need to install jq separately.

---

What the logs tell you

The CLI records command history:

lovrabet logs show
lovrabet logs clear

When troubleshooting, the logs are a good place to check:

• Which commands actually ran
• Whether they succeeded or failed
• Roughly how long they took

---

Importing from a rabetbase config

If you already have a .rabetbase.json, the recommended approach is:

lovrabet app import --file .rabetbase.json

If the old file still uses the legacy structure, run this first:

rabetbase project upgrade

Then import.

---

The most common errors

Error	Common cause	First step
Authentication required	No usable AccessKey	Run lovrabet auth login first
Set accessKey in .lovrabet.json or pass LOVRABET_ACCESS_KEY.	No AK in the config	Check auth status or the environment variable
Set appcode via --appcode or in .lovrabet.json.	No app resolved in the current context	Check app use, --appcode, defaultApp
App "<name>" not found	The chosen app isn't visible to the current account	Run lovrabet app list first
Flag --code validation failed	Malformed dataset code	Copy it again from the dataset list output
Invalid JSON for --params	Broken JSON	Format the JSON separately, then pass it in
risk "write" but riskLevel is "read"	Blocked by the permission guardrail	Manually adjust riskLevel in the config file
High-risk operation requires --yes	Data deletion in non-interactive mode	Add --yes explicitly

---

The most effective troubleshooting order

Work through these in order:

1. lovrabet auth status
2. lovrabet doctor
3. lovrabet app list
4. lovrabet logs show
5. Add --format json if needed
6. Add --dry-run for write-related issues

This sequence beats diving straight into the source code.

---

What the current config file should look like

The core config of the runtime CLI is now a top-level user-intent file — not the old local multi-app profile model.

A typical shape:

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

If you see a lot of legacy apps blocks, the file may still load — but that's no longer the recommended layout.

---

When to suspect Skills rather than the CLI

If the command itself runs fine but the Agent returns wrong results, the problem isn't necessarily the CLI. It could be that:

• The skill misinterprets a business object
• The skill hard-codes outdated SQL / BFF names
• The skill's default app or business flow is stale

Work backwards and check:

• Is the business prompt clear?
• Is the flow bound in the skill still valid?
• Should this run dataset discovery first, instead of jumping straight to SQL / BFF?