Common Workflows

This page does not try to cover every command. It focuses on the workflows most commonly reused in practice, both by direct terminal users and by agents that need a stable execution path.

Workflow 1: Read context before doing anything else

Before any write, read the current instance, app, and dataset context.

hbi auth status --output json
hbi app list --area personal-area --root --output json
hbi dataset list --app retail-ops --output json

The goal is to confirm:

• The current identity is authenticated
• The target instance is reachable
• The target app really exists
• The current identity can already see the datasets needed later

Workflow 2: Query the data model or validate an expression

When the task is still at the “can this dataset answer the question?” stage, use data-model query for a lightweight validation.

hbi data-model query --app <app-id> --dataset <dataset-id> "SUM({amount})"

Typical use cases:

• Validate a metric definition first
• Let the agent confirm the data model before building charts
• Turn HQL / HE fragments into inputs for later dashboard work

Workflow 3: Create a dashboard or report

One of the most common delivery actions is creating a dashboard or report from an app.

# Create an analytic / page dashboard
hbi dashboard create --app <app-id> "Regional Sales Cockpit"

# Create a report (requires explicit data bindings)
hbi dashboard create --app <report-app-id> "Sales Report" \
  --dashboard-type report \
  --data-app <data-app-id> \
  --dataset <dataset-id>

Note

--data-app and --dataset are only used with --dashboard-type report. Regular analytic/page dashboards usually bind data later during chart/filter configuration or a dashboard plan apply step.

Workflow 4: Continue building charts and other elements

After the dashboard exists, continue with charts, containers, filters, buttons, iframes, and other elements.

hbi element chart create \
  --dashboard <dashboard-id> \
  --app <app-id> \
  --dataset <dataset-id> \
  line

hbi element container create \
  --dashboard <dashboard-id> \
  --app <app-id> \
  --file container.yaml

hbi element filter update \
  <filter-uid> \
  --dashboard <dashboard-id> \
  --app <app-id> \
  --file filter.yaml

These commands are especially agent-friendly because:

• Their input boundaries are explicit
• They work well with YAML spec files
• Their results can feed directly into later steps

Workflow 5: Confirm dashboard / report results in the browser

After you create or update a dashboard / report through CLI, it is worth returning to the corresponding page and confirming the result there.

Recommended order:

1. Open the target dashboard or report page
2. Confirm that this is the exact page affected by the change
3. Check whether Autopilot is connected
4. Decide whether this change is expected to repaint the current page directly

If your real question is “did the out-of-browser change make it back into the current page?”, this step is often more valuable than issuing more commands immediately. See Realtime Sync & Autopilot for the feedback model.

Workflow 6: Preview permission changes

Permission changes are one of the clearest cases where --dry-run should come first.

# Inspect current permissions
hbi authorize get app <id>

# Preview a grant
hbi authorize grant app <id> --user 123:editor --dry-run

# Execute the real grant
hbi authorize grant app <id> --user 123:editor

# Revoke access
hbi authorize revoke app <id> --user 123

Recommended pattern:

1. Let the agent return the --dry-run result
2. Execute the real grant only after a human confirms

Workflow 7: Inspect or preview system configuration

CLI is not only for business objects. It can also read system configuration and preview updates.

hbi preferences get --output json
hbi preferences everest --output json
hbi preferences smtp --output json

hbi preferences everest update --file everest.yaml --dry-run
hbi preferences smtp verify --file smtp.yaml --dry-run

This is useful for:

• Environment checks
• Configuration reviews
• Previewing changes before apply
• Having an agent explain the impact of configuration differences

Recommended output formats

For direct human use, table is convenient. For agents, scripts, and CI, prefer:

--output json
--output yaml

Why:

• Stable structure
• Easier downstream parsing
• Better for passing intermediate results to later steps or other systems

Workflow rules for agents

To make agent execution more reliable, use these defaults:

1. Read context before writing
2. Preview risky actions with --dry-run
3. Prefer structured output
4. Return the key commands, key outputs, and any unresolved blockers together

If your real goal is to let an agent finish a BI task end to end, what matters most is not any isolated command but the sequence between these workflows.