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
| Command | hive-s | hive-m | Docker | Other 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):
| Command | Docker | Other 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
| Flag | Required | Description |
|---|---|---|
-n, --name | yes | Project name. Letters, digits, -, _; max 128 chars. |
-t, --template | yes | hive-s or hive-m. |
-r, --release | no | Template 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
| Flag | Description |
|---|---|
--check | Only report installed vs. latest version. |
--silent | Installer 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
| Flag | Description |
|---|---|
-n, --name | Rename 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
| Flag | Description |
|---|---|
-d, --debug | Append hw.debug_args (RISC-V JTAG debug). |
-v, --verbose | Show 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
| Flag | Description |
|---|---|
--rebuild | Wipe work volumes, build from scratch. |
-v, --verbose | Show 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
| Flag | Description |
|---|---|
-v, --verbose | Also 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
| Flag | Required | Description |
|---|---|---|
-f, --file | yes | Bitstream 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
| Flag | Description |
|---|---|
--rebuild | Wipe SW volume first. |
--no-update | Skip repo sync and the git pull of cloned repos. |
-v, --verbose | Show container output. |
bitbake aionyx-image-minimal → images/sd.wic.
buildhive build kernel
| Flag | Description |
|---|---|
--rebuild | bitbake virtual/kernel -c cleansstate first. |
-v, --verbose | Show 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
| Flag | Description |
|---|---|
--clean | make clean instead of build. |
Rebuilds the kernel Image directly from /kernel-devsrc (make -j Image modules), no bitbake → images/Image.
buildhive build module <name>
| Flag | Description |
|---|---|
name (positional) | Driver under sources/drivers/staging/ntl/<name>/. C identifier, max 64 chars. |
--clean | Clean before build. |
Scaffolds oot/<name>/Makefile if absent, cross-compiles the module against /kernel-devsrc → oot/<name>/*.ko.
buildhive build update
| Flag | Default | Description |
|---|---|---|
--legacy-migration | off | Build hive-m-migration-*.tar.gz (0.3.9 upgrade path) instead. Unsigned. |
--include <csv> | all | Components: raucb,kernel,dtb,bootscr,bootbin,fitimage,bitstream,dtbo. |
--select | off | Interactive 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-sign | off | Skip remote signing (archive not installable by uwm). |
--sign-only | off | Sign the newest existing images/hive-m-update-*.tar.gz, no build. |
--version <x.y.z> | project.json version | Firmware version of this archive (HIVE_VERSION), must belong to the project's release. |
--sign-timeout <s> | 3600 | Poll timeout for the signing server. |
--no-update | off | Skip repo sync and repo pulls. |
-v, --verbose | off | Show 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/.
| Flag | Default | Description |
|---|---|---|
--image | off | Build the SDK Docker image from the installer (sdk/Dockerfile). Tags <tag>:<version> and <tag>:latest. |
--push | off | docker push both tags. Implies --image. Needs docker login ghcr.io. |
--tag | ghcr.io/nettimelogic/hive-m-sdk | Image repository. |
--version | project.json version | Image version tag, also written to the org.opencontainers.image.version label. Default keeps SDK and firmware paired. |
--no-build | off | Skip populate_sdk, use the newest *.sh in images/. |
See hive-m.md for the image layout and usage.
buildhive configure xsa
| Flag | Required | Description |
|---|---|---|
-f, --file | yes | .xsa file. Extracts the .bit, validates the header, copies it to sources/sdt/AionyxBaseTop.bit. |
buildhive configure bitstream
| Flag | Required | Description |
|---|---|---|
-f, --file | yes | .bit file. Validates the header, copies it to sources/sdt/AionyxBaseTop.bit. |
buildhive configure dts
| Flag | Required | Description |
|---|---|---|
-f, --file | yes | DTS 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
| Flag | Description |
|---|---|
-v, --verbose | Show 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]
| Flag | Description |
|---|---|
-n, --limit | Maximum results (default 30). |
-g, --packagegroups | Only packagegroup-* recipes. Without a term lists them all. |
-l, --layer | Only 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
| Flag | Description |
|---|---|
--force | Overwrite 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
| Flag | Description |
|---|---|
--module <name> | Source /kernel-devsrc/env.sh, cd oot/<name> (must exist). |
--no-update | Skip repo sync and repo pulls. |
-v, --verbose | Show container output. |
Interactive bash in the SW container with the Yocto environment sourced.
buildhive code
| Flag | Description |
|---|---|
--stop | Stop 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
| Flag | Description |
|---|---|
-a, --all | Also remove the shared ntl_buildhive_sstate volume (Yocto sstate + downloads). |
Removes and recreates the project SW volume.