Command reference

Commands are resolved against the project in the current working directory (project.json, not searched upward). Without a project, only the common commands exist, plus the app commands when buildhive-app.json is present (apps.md). With one, the template field selects the Hive-S or Hive-M command set.

Any command segment may be abbreviated to a unique prefix (buildhive dep fl = buildhive deploy flash). Exact matches win over prefixes; ambiguous prefixes error.

Overview

Commandhive-shive-mDockerOther prerequisites
create✓✓✓-
releases✓✓--
gui✓✓--
upgrade✓✓-secrets server login (GitHub token), Windows for the install
login / logout✓✓-project with secrets (login only), browser
info project✓✓-project
info secrets✓✓-project
info flash✓--project, built .fbi files
configure project✓✓-project
configure linux✓✓✓interactive terminal
configure buildroot✓-✓interactive terminal
configure uboot-✓✓interactive terminal
configure bitstream✓✓-.bit file
configure xsa-✓-.xsa file
configure dts-✓-.dtsi file
build sw✓✓✓git access
build hw✓-✓Vivado on PATH
build flash✓--images/bitstream.bin + built components
build kernel-✓✓-
build kernel-devsrc-✓✓-
build kernel-oot-✓✓build kernel-devsrc first
build module <name>-✓✓build kernel-devsrc first, drivers repo cloned
build update-✓✓signing: buildsign config, BUILDSIGN_TOKEN, NTL VPN
export sw-✓✓-
packages list / add / remove-✓-project
packages index-✓✓-
packages search-✓-packages index first
secure-boot keygen-✓--
secure-boot ppk-hash-✓✓keygen + prior build sw
code-✓✓code CLI on PATH
shell-✓✓interactive terminal
deploy flash✓--Vivado on PATH, connected device
clean✓✓✓-

App repos (buildhive-app.json in the current directory, no project.json):

CommandDockerOther prerequisites
app init-none, works in any directory
app build✓SDK image (pulled from ghcr.io), VPN for signing
app sign-package in out/, VPN
app license-license in the config, VPN

Common commands

buildhive create

FlagRequiredDescription
-n, --nameyesProject name. Letters, digits, -, _; max 128 chars.
-t, --templateyeshive-s or hive-m.
-r, --releasenoTemplate release, e.g. ntl-v2026.1. Default: newest shipped.

Creates ./<name>/: copies the default template, then <template>/<release>, writes project.json (release, version from the template), hash manifest (.buildhive_manifest.json) and merge baseline (.buildhive_baseline/). Fails if the directory already contains a project.

buildhive releases

Lists the template releases shipped with this BuildHive per template, newest marked. No project needed.

buildhive gui

Launches the desktop GUI (PySide6); running the exe without arguments does the same. Pages, button-to-command mapping and settings location: gui.md.

buildhive login / buildhive logout

login: OIDC login to the secrets server from secrets.url in project.json or buildhive-app.json (see configuration.md). Opens the browser (company SSO), waits for the callback on http://localhost:8250/oidc/callback, caches the OpenBao token in the OS config dir (token.json, plain text, next to gui.json). Builds log in on demand when a secret is needed and no valid token is cached, so an explicit login is only needed to switch users. logout: deletes the cached token. BAO_TOKEN env (CI machine token) bypasses both.

buildhive upgrade

FlagDescription
--checkOnly report installed vs. latest version.
--silentInstaller without the wizard (Inno Setup /SILENT).

Looks up the newest buildhive_v<x.y.z> release in NetTimeLogic/Tools (draft and pre-release skipped). The repo is private: the GitHub token comes from GITHUB_TOKEN env or the secrets server (buildhive/github, key GITHUB_TOKEN; browser login if no token is cached, no project needed). Newer release: downloads BuildHive_<x.y.z>_Setup.exe to the temp dir and starts it two seconds after the CLI exits, so the installer can replace bin/. The installer removes the old version and installs per user, no admin. Up to date: OK: BuildHive x.y.z is up to date. Linux/macOS: prints the releases page. Exit 1 on token, network or download errors. The GUI has the same check at start plus an update button, see gui.md.

buildhive info secrets

Prints the secrets server, the logged-in email and, per secret (SSTATE_MIRROR_AUTH, BUILDSIGN_TOKEN), the source a build would use: environment variable, <mount>/users/<email>/<secret>, <mount>/<secret> or not available (<reason>). Never prints values, never opens the browser.

buildhive info project

Prints name, ID, template, release, firmware version, BuildHive version. Hive-S: Buildroot repo/branch. Hive-M: Yocto manifest repo/branch and additional clone repos.

buildhive configure project

FlagDescription
-n, --nameRename the project.
--version <x.y.z>Firmware version, must start with the release number (ntl-v2026.1 → 2026.1.N). Carried by update archives (HIVE_VERSION), default SDK tag.
--release <id>Bind the project to another shipped release (buildhive releases). Resets version to the template's, logs the template branches; the next command runs the template update. sw.* branches in project.json are never merged, adjust them by hand.

buildhive app ...

app init, app build, app sign, app license: see apps.md.

Hive-S commands

buildhive build hw

FlagDescription
-d, --debugAppend hw.debug_args (RISC-V JTAG debug).
-v, --verboseShow container output.

Generates the LiteX/VexRiscv SoC in the HW container (make.py <hw.args>), rewrites the generated Vivado tcl to host paths, runs vivado -mode batch to build IP, copies the IP repo to ip/.

buildhive build sw

FlagDescription
--rebuildWipe work volumes, build from scratch.
-v, --verboseShow container output.

Clones and builds UWM (out/hive-s_full_tls → images/uwm.xz, uwm-loader into the rootfs overlay), then Buildroot (ntl_defconfig) → kernel Image.lzma, rootfs.cpio.xz, u-boot.bin, opensbi.bin in images/.

buildhive build flash

FlagDescription
-v, --verboseAlso print the flash info table.

No Docker. Wraps each flash mapping entry with a length+CRC32 header (.fbi), builds mapping_table.bin, assembles images/flash.bin (bitstream at offset 0, components at their src offsets, mapping table at 0x3F0000). See hive-s.md.

buildhive info flash

Prints the flash mapping table and image structure (offsets/sizes from .fbi files in images/).

buildhive configure linux / configure buildroot

Interactive make linux-menuconfig / make menuconfig inside the SW container.

buildhive configure bitstream

FlagRequiredDescription
-f, --fileyesBitstream file, copied to images/bitstream.bin.

buildhive deploy flash

Runs vivado -mode gui -source tools/flash_device.tcl to program the SPI flash over JTAG. Requires Vivado on PATH and a connected device.

buildhive clean

Removes and recreates the HW and SW Docker volumes. Fails if a container is using them.

Hive-M commands

All container-based Hive-M commands run src/scripts/hive-m/init.sh first: repo init (first run) and repo sync of the Yocto manifests, source edf-init-build-env, layer sync, machine generation from the SDT, copy of sw/meta-ntl-hive into the build tree, secure-boot and sstate-mirror config. --no-update skips both the repo sync and the pull of the sw.clone repos. local.conf and bblayers.conf are rewritten only when their content changes, so bitbake's parse cache stays valid. See hive-m.md.

buildhive build sw

FlagDescription
--rebuildWipe SW volume first.
--no-updateSkip repo sync and the git pull of cloned repos.
-v, --verboseShow container output.

bitbake aionyx-image-minimal → images/sd.wic.

buildhive build kernel

FlagDescription
--rebuildbitbake virtual/kernel -c cleansstate first.
-v, --verboseShow container output.

bitbake virtual/kernel → images/Image.

buildhive build kernel-devsrc

Builds virtual/kernel, resolves source/build paths via bitbake -e, copies kernel source, build artifacts and .config into the case-sensitive kdevsrc Docker volume, writes env.sh (ARCH, CROSS_COMPILE, toolchain PATH). Prerequisite for kernel-oot, module, shell --module, code.

buildhive build kernel-oot

FlagDescription
--cleanmake clean instead of build.

Rebuilds the kernel Image directly from /kernel-devsrc (make -j Image modules), no bitbake → images/Image.

buildhive build module <name>

FlagDescription
name (positional)Driver under sources/drivers/staging/ntl/<name>/. C identifier, max 64 chars.
--cleanClean before build.

Scaffolds oot/<name>/Makefile if absent, cross-compiles the module against /kernel-devsrc → oot/<name>/*.ko.

buildhive build update

FlagDefaultDescription
--legacy-migrationoffBuild hive-m-migration-*.tar.gz (0.3.9 upgrade path) instead. Unsigned.
--include <csv>allComponents: raucb,kernel,dtb,bootscr,bootbin,fitimage,bitstream,dtbo.
--selectoffInteractive component picker.
--bitstream <file>-PL bitstream (.bit/.bin) for uwm import via /data/firmware/import.
--dtbo <file>-DT overlay (.dtso compiled with dtc, .dtbo as-is); requires --bitstream.
--no-signoffSkip remote signing (archive not installable by uwm).
--sign-onlyoffSign the newest existing images/hive-m-update-*.tar.gz, no build.
--version <x.y.z>project.json versionFirmware version of this archive (HIVE_VERSION), must belong to the project's release.
--sign-timeout <s>3600Poll timeout for the signing server.
--no-updateoffSkip repo sync and repo pulls.
-v, --verboseoffShow container output.

Selecting the bitstream/dtbo component (via --include/--select) without the matching flag opens a file-picker dialog instead; conversely, a given flag adds its component to the selection automatically.

bitbake update-archive → images/update.raucb + images/hive-m-update-<version>.tar.gz, then remote-signs the archive → images/signed_hive-m-update-<version>.bin. See updates.md.

buildhive export sw

bitbake aionyx-image-minimal -c populate_sdk - builds the cross SDK and copies the installer (*.sh) plus Image to images/.

FlagDefaultDescription
--imageoffBuild the SDK Docker image from the installer (sdk/Dockerfile). Tags <tag>:<version> and <tag>:latest.
--pushoffdocker push both tags. Implies --image. Needs docker login ghcr.io.
--tagghcr.io/nettimelogic/hive-m-sdkImage repository.
--versionproject.json versionImage version tag, also written to the org.opencontainers.image.version label. Default keeps SDK and firmware paired.
--no-buildoffSkip populate_sdk, use the newest *.sh in images/.

See hive-m.md for the image layout and usage.

buildhive configure xsa

FlagRequiredDescription
-f, --fileyes.xsa file. Extracts the .bit, validates the header, copies it to sources/sdt/AionyxBaseTop.bit.

buildhive configure bitstream

FlagRequiredDescription
-f, --fileyes.bit file. Validates the header, copies it to sources/sdt/AionyxBaseTop.bit.

buildhive configure dts

FlagRequiredDescription
-f, --fileyesDTS include, copied to sw/meta-ntl-hive/recipes-bsp/device-tree/files/ntl-custom.dtsi.

buildhive configure linux / configure uboot

Interactive bitbake virtual/kernel|virtual/bootloader -c menuconfig; the resulting diffconfig fragment is saved as a timestamped user_*.cfg in meta-ntl-hive so it persists across builds.

buildhive packages list / add <name>... / remove <name>...

Edit IMAGE_INSTALL:append in sw/meta-ntl-hive/conf/layer.conf. Names: lowercase letters, digits, + . _ -. The block is rewritten in the template layout, the rest of the file is untouched, so info project updates still 3-way merge it. Applied on the next build sw.

buildhive packages index

FlagDescription
-v, --verboseShow container output.

Scans every .bb under /work/sources in the SW container (name, layer, SUMMARY, DESCRIPTION, SECTION, RDEPENDS, fields also taken from required .inc files) and writes build/recipe-index.json. Host-only recipes are skipped: *-native, *-cross*, nativesdk-* and anything inheriting native, nativesdk, cross, crosssdk, cross-canadian, image, core-image. Re-run after changing the Yocto manifest.

buildhive packages search [term]

FlagDescription
-n, --limitMaximum results (default 30).
-g, --packagegroupsOnly packagegroup-* recipes. Without a term lists them all.
-l, --layerOnly recipes from this layer, e.g. poky. Without a term lists the layer.

Case-insensitive search over the index, ranked: exact name, term as a whole word in RDEPENDS (gcc lists packagegroup-core-buildessential right after gcc), name prefix, whole word in summary/description, substrings. Lists recipes, not split runtime packages. The GUI Configure page has the same list/search under "Image packages".

buildhive secure-boot keygen

FlagDescription
--forceOverwrite existing keys. Fused devices keyed to the old PSK become unbootable.

Generates keys/ (gitignored): psk.pem, ssk.pem (RSA-4096, BOOT.bin auth), fit.key/fit.crt (RSA-2048, FIT signing). See secure-boot.md.

buildhive secure-boot ppk-hash

Runs bootgen -efuseppkbits against the deployed FSBL → images/ppk0_hash.txt for eFUSE provisioning. Requires keys and a prior build sw.

buildhive shell

FlagDescription
--module <name>Source /kernel-devsrc/env.sh, cd oot/<name> (must exist).
--no-updateSkip repo sync and repo pulls.
-v, --verboseShow container output.

Interactive bash in the SW container with the Yocto environment sourced.

buildhive code

FlagDescription
--stopStop and remove the background dev container.

Starts a detached dev container (/kernel-devsrc, oot/, sources/drivers/ mounted) and attaches VS Code to it. Requires the code CLI on PATH.

buildhive clean

FlagDescription
-a, --allAlso remove the shared ntl_buildhive_sstate volume (Yocto sstate + downloads).

Removes and recreates the project SW volume.