Article body
Full article
Summary: HENGSHI CLI is exposed through the hbi command. It makes a subset of HENGSHI SENSE data, modeling, dashboard, permission, and operations actions discoverable as commands for human terminals, automation scripts, and Agents with tool-calling capabilities. The web interface and APIs continue to serve their respective use cases. By organizing BI operations into commands, parameters, and structured results, the CLI helps teams inspect plans before execution and verify state afterward.
Start with command discovery and invocation boundaries
Web interfaces, APIs, and command lines solve different problems. Agents with browser tools can operate pages, and business users need interfaces to review charts, layouts, and interactions. APIs remain appropriate for direct integration with existing services. The CLI provides a stable entry point for terminals and tool calls: discover resource domains and parameters through help, then pass structured output to scripts, Agents, or people for further judgment.
The current hbi top-level help lists command domains including app, dataset, data-model, metric, measure, dashboard, permission, authorize, pipeline, and scheduler. This is a broad BI engineering surface. The target instance’s version, enabled capabilities, and the current identity’s permissions jointly determine whether a command is available and what it can see or change.
| Interface | Appropriate uses | What an Agent must establish first | Common control points |
|---|---|---|---|
| Web UI | Visual exploration, chart and interaction acceptance, and human collaboration | Page state, login status, target environment, and visible resources | Page permissions, human review, and browser sessions |
| API | Service-to-service integration and fixed contracts in existing systems | API version, request model, authentication, and error handling | Caller credentials, rate limits, and service logs |
| HENGSHI CLI | Terminal execution, scripted workflows, and Agent tool calls | Command help, SENSE host, resource IDs, current identity, and authorization | Structured output, preflight previews, and state checks after execution |
Separate platform, semantic model, and executor responsibilities
HENGSHI SENSE owns platform resources; the CLI makes explicit calls
hbi targets a particular HENGSHI SENSE instance through HBI_HOST or —api-url. SENSE hosts platform resources such as applications, datasets, data models, dashboards, organizations, and permissions. The CLI sends read or operation requests for these resource domains to the specified instance and returns table, JSON, or YAML output. The target instance determines resource ownership, identity validation, and permission decisions.
Data models, atomic metrics, business metrics, and subject areas have corresponding command domains. Before generating HQL, creating charts, or adjusting a model, an Agent should read existing datasets, model relationships, metric definitions, and permission boundaries. A semantic model provides defined business objects and calculation rules. The Agent must still check the task’s time window, filters, and target assets; the CLI cannot decide whether the business question has been understood correctly.
The Agent chooses the process, skills constrain the sequence, and the CLI executes
Official documentation distinguishes human requirement and risk confirmation, Agent task decomposition, skills-based domain workflows, and the CLI’s actual reads and writes. The Agent decides whether to inspect data or assets first. Skills identify resource domains, help discovery, and checkpoints. The CLI takes explicit parameters and returns results. People confirm write targets, authorization scope, and delivery outcomes.
Access boundaries should be part of the workflow. hbi marks permission as read-only permission querying, while authorize provides get, grant, and revoke. Local help shows that grant targets can include app, folder, api-set, connection, and kanban. Querying before making changes helps distinguish permission to act from the permissions being granted. Using —as-user also requires the current OAuth client to have sudo scope; it is not merely a display option.
Verify results through state before and after execution
For write commands that support previews, —dry-run can inspect targets and parameters; the current command’s help defines its exact behavior. A preview does not replace state verification after actual execution, nor prove that permissions, dependencies, and target state will still satisfy requirements when the action runs. Teams should retain preview results, necessary approvals, and execution receipts in the change record.
JSON, YAML, and table output allow subsequent steps to consume the same result. —write-output can also write results to local files. Output may contain resource metadata or query results, so local directory permissions, pipeline logs, temporary-file retention, and manually exported copies all fall within data governance. Describing the CLI as a channel does not imply that arbitrary execution environments retain no business data.
Several credential paths are supported. Official documentation lists device login, client credentials, temporary overrides through HBI_TOKEN or —token, and interactive login that writes to the CLI’s local credential store. The system Keyring is one supported protection method. Automation should receive credentials through controlled secret injection and accounts with minimal permissions. Avoid placing secrets in command-line arguments, script bodies, or logs that may be retained.
Connect reading, planning, writing, and readback into an evidence chain
Structured output makes results machine-readable; it does not automatically produce a business conclusion. The Agent should match resource IDs, names, owning applications, current state, and query conditions against the approved task targets. JSON suits programmatic parsing, YAML supports review of draft configuration, and table output supports quick terminal inspection. Fields still depend on the subcommand and version, as shown by current help and actual responses. Example IDs or fields in website demonstrations are not a fixed protocol.
Begin the read phase with the smallest useful scope. Confirm the target host and identity, narrow the investigation to the specified application, dataset, or data model, then inspect visible resources, definitions, and permissions. In the planning phase, specify the resources, roles, fields, or layouts to change and have the business owner confirm the definitions. Only the write phase should carry explicit resource IDs; preview high-risk actions first. During readback, use a query corresponding to the target state: recheck authorization after granting access, or inspect an object’s definition and ownership after creating or updating it. The before and after reads must use the same targets and checking dimensions to establish whether the change matches the plan.
This chain also provides a basis for exception handling. If the initial read shows that a resource does not exist, is invisible to the identity, or that the data model cannot answer the question, the Agent should stop before writing and hand over the confirmed context and missing conditions. If the state after writing differs from the previewed target, retain the minimum necessary inputs and results and investigate or roll back through the team’s change process. Structured CLI commands make these checks reusable. Business acceptance still depends on the task’s goals and the platform’s actual state.
Discover through help, then check state around the change
For an unfamiliar resource domain, start with local help to establish shared facts about commands, parameters, and risks. The following three read-only help commands inspect the installed version’s command tree and options. They do not access SENSE business resources or change BI data.
hbi --help
hbi data-model --help
hbi authorize grant --helpRoot help establishes which resource domains the installed CLI provides. data-model help further lists list, show, preview, query, lineage, tree, and join-related operations. authorize grant help shows target types, role formats, and authorization parameters. Help explains invocation. Whether resources exist and whether the current identity can read or write them must still be established through actual queries to the target instance.
A reviewable write workflow should be short and complete: establish the SENSE host and identity; use auth status and application and dataset queries to confirm that the target exists and is visible; read current configuration and permissions; preview high-risk writes with dry-run; execute within approved permissions; and read back resource state through the appropriate query commands. Retain evidence with sensitive information removed and its scope controlled. Creating dashboards, changing authorization, and adjusting data models should all follow this sequence, so that a successful command response alone is not treated as completed delivery.
Open interfaces should be composable and bounded
Agents with shell or tool-calling capabilities can incorporate hbi into their workflows. Before integration, enterprises should establish the target instance, authentication method, callable resource domains, approval points, and output-retention rules. The CLI can then bring SENSE BI capabilities into automation while preserving business definitions, read and write permissions, and delivery acceptance boundaries.