CLI Reference

The aihummer command-line tool manages a host-native install: it starts and updates the gateway (the installation itself is done via the personal install link from your account portal), controls the gateway systemd service, runs diagnostics, handles backups, reads and writes control-plane settings, and signs licenses. This page lists every command.

Commands

Command	What it does
`up` / `install`	Start the gateway systemd service (`systemctl start`). It installs nothing — installation is done by the install script from your personal link.
`update [--check]`	Update to the latest release (verify signature + swap binary + restart); `--check` only reports whether an update is available.
`restart`	Restart the gateway service (`systemctl restart`).
`stop`	Stop the gateway service (`systemctl stop`).
`logs [unit]`	Follow one systemd unit’s journal (`journalctl -u`); defaults to the gateway unit.
`status`	Query the gateway’s readiness (`/readyz`).
`doctor`	Run diagnostics (service active + gateway ready).
`backup [dir]`	`pg_dump` the PostgreSQL state plane to a file; a default directory is used when omitted.
`restore <file>`	Restore PostgreSQL from a dump file produced by `backup`.
`uninstall [flags]`	Remove the install (see flags below). Requires root — run it with `sudo`.
`set-password` / `admin-password`	Set/generate the local admin password (`[--login admin] [--password X]`).
`settings {set\|get\|list}`	Read/write control-plane settings in the database — this is how Settings-catalog knobs are configured from the CLI instead of `gateway.env`.
`license {keygen\|sign\|show <token>}`	Manage licenses: generate a key, sign, decode + verify a given token.
`loadtest`	Run a load test against the gateway.
`plugin {init\|validate\|keygen\|package\|sign\|publish}`	Plugin SDK: scaffold, validate, keys, package, sign and publish (private/public).
`version`	Print the version.
`help`	Show help.

`uninstall` flags

Flag	Effect
`--purge`	Also remove data (full removal).
`--yes`	Skip the confirmation prompt.
`--no-backup`	Do not take a backup before removing.
`--backup-dir <dir>`	Write the pre-uninstall backup to this directory.

Usage examples

Install and bring up

Installation is done via the personal install link from your account portal (see Installation); after that the CLI starts and checks the service:

sudo aihummer up
aihummer status

Update

# Only check whether a newer release exists
aihummer update --check

# Apply the update
sudo aihummer update

Service control and logs

The commands act on the single gateway systemd unit (AIHUMMER_SERVICE, default aihummer-gateway); logs accepts any systemd unit name.

sudo aihummer restart
aihummer logs                 # the gateway unit's journal (default)
aihummer logs aihummer-stt    # another systemd unit's journal
sudo aihummer stop

Diagnostics

aihummer doctor

Backup and restore

backup runs a pg_dump of the PostgreSQL state plane into a file; restore takes that dump file.

aihummer backup /var/backups/aihummer
aihummer restore /var/backups/aihummer/aihummer-2026-07-05.sql

[!TIP] Postgres is the source of truth, but your AIHUMMER_MASTER_KEY and the blob directory must be backed up separately — without the master key, encrypted secrets cannot be recovered.

Set the admin password

The command accepts [--login admin] [--password X] and needs AIHUMMER_DATABASE_URL — normally picked up from gateway.env when run as the install user or via sudo.

sudo aihummer set-password --login admin

Control-plane settings

settings reads and writes Settings-catalog knobs directly in the database — the same store the web admin UI (Management → Settings) edits. This is how catalog knobs are configured from the CLI: gateway.env values are ignored for them.

aihummer settings set AIHUMMER_STT_URL http://127.0.0.1:8001
aihummer settings get AIHUMMER_STT_URL
aihummer settings list

settings list shows only the user-facing catalog keys (system and internal keys are hidden); each key is tagged with its source — [db] for values you set, [unset] with the catalog default otherwise.

Licenses

license show requires a <token> argument and the AIHUMMER_LICENSE_PUBKEY variable: it decodes and verifies the given token — it does not display the instance’s current license.

aihummer license keygen                # generate a signing key
aihummer license sign                  # sign a license
aihummer license show <token>          # decode + verify a token

Load test

aihummer loadtest

Plugins

aihummer plugin init <kind>            # scaffold a manifest (connector|service|openapi|mcp)
aihummer plugin validate manifest.json # validate a manifest against the contract
aihummer plugin keygen                 # ed25519 author key (.key + .pub)
aihummer plugin package ./my-plugin    # build a tarball + .sha256
aihummer plugin sign --key author.key --manifest ./my-plugin/manifest.json my-plugin-1.0.0.tar.gz

# Publish: privately (to your instance) or publicly (PR to the catalog)
aihummer plugin publish --private --instance https://host --token <admin> my-plugin-1.0.0.tar.gz
aihummer plugin publish --public --dir ./my-plugin --key author.key \
  --artifact-url https://you.example/my-plugin-1.0.0.tar.gz --publisher you \
  --description "..." --icon https://you.example/icon.svg

For the full SDK and both publishing modes see Plugin SDK and Publishing a plugin.

[!WARNING] uninstall requires root: run sudo aihummer uninstall. And sudo aihummer uninstall --purge --yes removes data and skips the confirmation prompt — make sure you have a verified backup first.

Environment

Variables the aihummer tool itself reads:

Variable	Purpose
`AIHUMMER_SERVICE`	The gateway systemd unit name (default `aihummer-gateway`) — the target of `up`/`restart`/`stop`/`logs`.
`AIHUMMER_GATEWAY_URL`	Gateway URL for `status`/`doctor`/`loadtest` (default `http://127.0.0.1:8780`).
`AIHUMMER_DATABASE_URL`	Postgres DSN — required by `backup`/`restore`/`set-password`/`settings`.
`AIHUMMER_REPO`	Release repository for `update` (fallback when no `AIHUMMER_DOWNLOAD_BASE_URL` CDN is configured).

Most commands need root (systemctl) — run them with sudo.

Where to next

Configure the instance: Environment variables.
Decide what tools the agent can use: Tools catalog.