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. 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 | ✓ | ✓ | ✓ | - |
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 | ✓ | ✓ | ✓ | - |
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. |
Creates ./<name>/: copies the default template, then the chosen template, writes project.json, hash manifest (.buildhive_manifest.json) and merge baseline (.buildhive_baseline/). Fails if the directory already contains a project.
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 project.json secrets.url (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, BuildHive version, template. 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. |
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 an init script first: repo init/sync of the Yocto manifests (first run), source edf-init-build-env, layer sync, machine generation from the SDT, copy of sw/meta-ntl-hive into the build tree, secure-boot config toggle. Repos from sw.clone are pulled in parallel unless --no-update is given. See hive-m.md.
buildhive build sw
| Flag | Description |
|---|---|
--rebuild | Wipe SW volume + bitbake linux-xlnx -c cleansstate first. |
--no-update | Skip git pull of cloned repos. |
-v, --verbose | Show container output. |
bitbake aionyx-image-minimal → images/sd.wic.
buildhive build kernel
| Flag | Description |
|---|---|
--rebuild | bitbake linux-xlnx -c cleansstate first. |
-v, --verbose | Show container output. |
bitbake linux-xlnx → images/Image.
buildhive build kernel-devsrc
Builds linux-xlnx, 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. |
--sign-timeout <s> | 3600 | Poll timeout for the signing server. |
--no-update | off | Skip 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 | tool version | Image version tag, also written to the org.opencontainers.image.version label. |
--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 to sources/sdt/. |
buildhive configure bitstream
| Flag | Required | Description |
|---|---|---|
-f, --file | yes | .bit file. Validates the header, copies to sources/sdt/. |
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 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.