Hantera CLI

Hantera CLI is provided for developers and Hantera system maintainers to simplify working with Hantera from the command line as well as authoring apps.

You can install the CLI using npm:

> npm install -g @hantera/cli

Once installed, you can use it's alias h_:

> h_ --help

Commands:
  h_ app <command>     Commands for authoring apps
  h_ manage <command>  Commands for managing tenant

Options:
  --help     Show help
  --version  Show version number
  --verbose  Enable verbose logging

The CLI has two top-level command groups:

• h_ app — authoring apps: create a new app, develop it against a development tenant, package it, and run its API test suite.
• h_ manage — managing a tenant: log in, work with resource manifests, install and activate apps, maintain search indices, and watch system signals.

Sessions and authentication

Most commands talk to a Hantera tenant. Which tenant is decided by your sessions. Sessions are stored securely and reused automatically while valid.

Log in

> h_ manage login <tenant>

Opens your browser to authenticate with the tenant. After authentication completes, the CLI saves a session and asks whether to set that tenant as the default session.

List, use, and remove sessions

Command	Description
h_ manage sessions	Lists your active (non-expired) sessions.
h_ manage use [session]	Gets or sets the default session used when no -s is passed.
h_ manage logout <session>	Removes a saved session.

TIP

Commands that talk to a tenant accept -s <session> (or --session) and fall back to the default session when it is omitted. h_ manage use sets that default.

Authoring apps

Commands:
  h_ app new                     Creates a new app
  h_ app dev [path]              Starts an app in development mode with live reload
  h_ app pack [path] [-v 1.0.0]  Builds and package the app
  h_ app test [path]             Runs the app's API test suite (tests/*.test.mjs) against a live session

All app commands run against an app directory — the folder containing the app manifest h_app.yaml. [path] defaults to the current directory.

To develop or test an app, you need access to a Hantera development or test tenant with the permissions required by the app. Your Hantera administrator can provide the tenant and access.

h_ app new

Creates a new app: an h_app.yaml manifest, a portal workspace with TypeScript setup, and a .gitignore. The command prompts for the app id and the target path.

> h_ app new

h_ app dev [path]

Develops the app from the local folder against a selected development tenant:

> h_ app dev
> h_ app dev ./my-app -s <development-tenant>

Option	Description
-s, --session	Session (tenant) to install the dev app into. Defaults to the default session.
--watch	File watching for auto-reload. Enabled by default.
--portal	Portal-only mode: develop the portal extension without synchronizing app components.
-v, --verbose	Verbose logging.
-l, --trace	Write Filtrera evaluation traces to a file — pass a path, or omit to use the default h_dev.trace.

The development session synchronizes the current app manifest and components to the tenant, watches the app directory, and updates changed components as you save. To see portal-extension changes in Hantera, enable development mode in the Portal. See Development Workflow & Troubleshooting.

Only one development session per app can be active in a tenant — stop an existing session before starting another.

h_ app pack [path]

Builds the portal package (with a vue-tsc --noEmit type check) and packages the app into a distributable <id>-<version>.hapk archive:

> h_ app pack
> h_ app pack ./my-app -v 2.1.0

Option	Description
-v, --package-version	The version written into the package manifest and file name. Defaults to 1.0.0.

Only files declared in the manifest ship in the package — anything not declared (including the app's tests/ directory) is excluded. Install the archive into a tenant with h_ manage apps install.

h_ app test [path]

Runs the app's API test suite against a live session:

> h_ app test
> h_ app test ./my-app -s <test-tenant>
> h_ app test --filter "delay lifecycle" -s <test-tenant>
> h_ app test --list

Option	Description
-s, --session	Session (tenant) to run the suite against. Defaults to the default session.
--filter	Only run tests whose names match the pattern (passed to node --test as --test-name-pattern).
--list	List the discovered test files without running them.

How it targets a tenant

The command runs against the selected tenant session (-s, or the default session). The test tenant must have the app available — either as an installed app version or as the current development version. The suite creates and mutates real resources in that tenant, so use a dedicated development or test tenant and clean up test data.

For CI, authenticate once with h_ manage login, select the intended test tenant, and run h_ app test as a build step.

The suite convention: API-based, black-box

Apps are tested as black boxes through their public API — HTTP ingresses, the resources API (POST /resources/jobs scheduling, raw actor messages), and Graph queries. The observable contract is the API, so that is what the suite exercises.

Test files live in the app repository as tests/*.test.mjs (or .js) — plain Node test files using node:test and node:assert:

import { describe, it } from 'node:test';
import assert from 'node:assert/strict';
import { ingress, uuid7 } from '@hantera/cli/test';

describe('my feature', () => {
  it('creates a thing', async () => {
    const startNodeId = uuid7();
    const created = await ingress('my-app/things', { name: 'test', startNodeId });
    assert.ok(created?.id);
  });
});

The runner executes the discovered files with Node's built-in test runner and propagates its exit code — 0 when everything passes, non-zero on any failure — which makes the command a drop-in CI gate.

Shared test utilities

Import the bundled test helpers directly in a test or an optional app-specific helper module:

import {
  actorMessages,
  errorCode,
  graph,
  ingress,
  poll,
  scheduleJob,
  sleep,
  uuid7,
  waitForRow,
} from '@hantera/cli/test';

The helpers call the selected test tenant through the same authenticated session as h_ app test.

Apps may add tests/helpers.mjs for shared fixtures, app-specific Graph queries, polling, and cleanup, but this is optional. Test files can import the bundled helpers directly.

Worked example

# Develop the app against the development tenant
> cd apps/my-app
> h_ app dev -s <development-tenant>

# Run the suite against the same tenant
> h_ app test -s <development-tenant>

Suites are expected to clean up after themselves through the API (for example, disabling the automations an integration test created); retention jobs own the rest.

Managing a tenant

Commands:
  h_ manage login <host>             Command logging in to a Hantera tenant
  h_ manage logout <session>         Logs out of a session
  h_ manage sessions                 Lists active sessions
  h_ manage use [session]            Gets or sets the default session to use for management commands
  h_ manage get <resource>           Gets the manifest for the given resource (if supported)
  h_ manage apply [file]             Applies the given manifest file or glob pattern to the remote Hantera installation
  h_ manage remove <resource>        Removes the given resource (if supported)
  h_ manage apps <command>          Commands for managing apps
  h_ manage update-search <node...>  Update/rebuild search indices
  h_ manage signals [path]           Displays system signals

h_ manage get <resource>

Prints the manifest (YAML) of a resource. Supported resource adapters:

components, registry, rules, actors, job-definitions, jobs, ingresses, egresses, connections.

> h_ manage get components/my-component
> h_ manage get rules -o my-rule.yaml

Option	Description
-s, --session	The session to use. Defaults to the default session.
-o, --out	Write the output to a file instead of stdout.

h_ manage apply [file]

Applies YAML manifests to the tenant — a single file, a glob pattern (e.g. *.yaml, **/*.yml), or stdin when no file is given. Each document is a { uri, spec } manifest, dispatched to the resource adapter matching its uri (see get for the supported resource classes).

> h_ manage apply my-manifests.yaml
> h_ manage apply "manifests/**/*.yaml"
> cat my-manifest.yaml | h_ manage apply

Option	Description
-s, --session	The session to use. Defaults to the default session.

h_ manage remove <resource>

Removes a resource by path, using the same resource adapters as get. Supports -s, --session like the other manage commands.

h_ manage apps <command>

Commands:
  h_ manage apps list                        Lists installed apps
  h_ manage apps details <appId>             Gets details of an app
  h_ manage apps install <hapk file>        Installs an app package
  h_ manage apps activate <appId> [-v]      Activate a deactivated app or change active version
  h_ manage apps deactivate <appId>          Deactivates an app

• install <hapk file> uploads a .hapk archive (built with h_ app pack) to the tenant.
• activate <appId> [-v <version>] activates a specific installed version — or the latest installed version when -v is omitted.
• All sub-commands support -s, --session.

h_ manage update-search <node...>

Schedules an update (or rebuild) of one or more Graph search indices — pass the node names, or all for every node. Asks for confirmation before scheduling.

Option	Description
-s, --session	The session to use. Defaults to the default session.
-r, --rebuild	Clear the indices before refreshing them. Faster, but leaves search partially inoperable during the build.

Use h_ manage signals to watch the progress.

h_ manage signals [path]

Displays system signals — severity-tagged status messages reported by the tenant — optionally filtered by a registry path prefix.

Option	Description
-s, --session	The session to use. Defaults to the default session.
-w, --watch	Refresh the signal list every second.

TIP

After update-search, h_ manage signals graph -w shows index build progress.