Authentication & Connection

Configure the target instance first

Before CLI can perform any business action, it needs to know which HENGSHI SENSE instance it is talking to.

export HBI_API_URL="https://<your-everest-instance>"

When switching between multiple environments, store this in a clear shell profile, CI secret, or agent runtime configuration instead of guessing the target instance at execution time. Public documentation now uses HBI_* as the primary environment-variable namespace; CLI still reads legacy EVEREST_* during migration.

Option 1: Log in with client credentials

This is the most common path for local terminals, service accounts, and most agent runtimes.

hbi auth login --client-id <client_id> --client-secret <client_secret>
hbi auth status

After a successful login, CLI stores the access token in a local cache for automatic reuse.

Option 2: Interactive login

If you prefer to enter credentials interactively on the current machine and store them in the system keyring, use:

hbi auth login --interactive

This path is better suited for human-operated desktop environments.

Option 3: Provide client credentials and let CLI acquire tokens automatically

In agent runtimes, CI, or background jobs, you can also provide client credentials directly:

export HBI_CLIENT_ID="<client_id>"
export HBI_CLIENT_SECRET="<client_secret>"

For authenticated business commands, CLI can obtain an access token automatically and cache it locally for reuse.

Option 4: Inject an access token directly

If you already have an access token, you can provide it directly:

export HBI_TOKEN="<token>"

This path fits:

• Environments that already distribute short-lived tokens
• Temporary automation tasks
• Runtimes that should not keep client credentials locally

Common auth commands

# Inspect current auth state
hbi auth status --output json

# Refresh the access token
hbi auth refresh

# Log out
hbi auth logout

# List supported auth methods
hbi auth methods

# Show the active auth method
hbi auth active

Public usage recommendations

Local desktop usage

Prefer:

hbi auth login --interactive

This works well for long-lived local usage and fits desktop credential-management expectations.

Agent runtimes / CI

Prefer:

export HBI_CLIENT_ID="<client_id>"
export HBI_CLIENT_SECRET="<client_secret>"

If the runtime should avoid the system keyring, environment variables plus the local token cache are usually enough.

Existing access token workflows

Prefer:

export HBI_TOKEN="<token>"

Credential-safety recommendations

• Do not hardcode tokens or client secrets into scripts, docs, or repositories
• For automation, prefer secrets or environment-variable injection
• For local desktop usage, prefer interactive login
• Do not paste full auth status output into public channels

If a container or restricted runtime should avoid the system keyring entirely, you can explicitly set:

export HBI_DISABLE_KEYRING=true

Common connection issues

HBI_API_URL is not set

CLI does not know which instance to target and will usually fail on the first request. Check:

echo "$HBI_API_URL"

Login succeeded but the expected resources are missing

Check these first:

1. The CLI is pointing to the wrong instance
2. The current identity lacks access to the target app, dataset, connection, or space
3. The agent runtime inherited a different set of environment variables than your shell

Tokens expire or auth feels unstable

Start with:

hbi auth status --output json
hbi auth refresh

If you rely on client credentials, also confirm that HBI_CLIENT_ID and HBI_CLIENT_SECRET are still valid.