Command-Line Tools
The host command-line tools are for direct USB tag operations and scripting.
From v4.0 the tag tools (tag-info, tag-start, tag-stop, tag-reset,
tag-test, tag-cal, tag-dwnld, tag-flash and base-flash) are written
in Rust, in host/commandline-rs. They keep the names and output of
the C++ tools they replace. dataprocessing and tag-txt-import are C++, in
host/commandline.
A tool given an option it does not know, or a bad value, prints the problem and its usage and exits with status 2. Other failures exit with status 1.
In the macOS and Linux releases they are in tag_tools/bin; put that
directory on your PATH to run them by name. In the Windows release they are in tag_tools
beside the applications.
These are command-line programs: run them from a terminal, such as Terminal on macOS. Double-clicking one in the macOS Finder does not work, and Finder may report that the program cannot be opened or used. That message does not mean the release is damaged or blocked; the same program runs normally when you type its name in a terminal.
Use these pages as working templates. Fill in the purpose, preconditions, examples, expected output, and troubleshooting details as each tool is reviewed against the current workflow.
Common Options
Most tag-attached tools share these options:
| Option | Value | Function |
|---|---|---|
-d, --debug |
none | Enables debug logging. Without this option, the tools use error-level logging. |
-b, --base |
BUS:DEVICE |
Selects a specific USB device by bus and device address. Use this when more than one compatible base/tag interface is connected. |
-h, --help |
none | Prints command usage and exits. |
Tool Pages
| Tool | Template page | Starting point |
|---|---|---|
tag-dwnld |
tag-dwnld | Download finished or aborted tag logs to text or SQLite files. |
tag-info |
tag-info | Print tag information, firmware metadata, status/configuration details. |
tag-reset |
tag-reset | Stop a running/hibernating tag and erase completed log data. |
tag-start |
tag-start | Start logging when a tag is idle. |
tag-stop |
tag-stop | Stop active logging states and print the resulting tag status. |
tag-cal |
tag-cal | Start calibration mode and stream raw calibration samples. |
dataprocessing |
dataprocessing | Copy SQLite logs and add derived sensor streams for later analysis. |
tag-txt-import |
tag-txt-import | Convert old BitTag and PresTag .txt logs to SQLite, checking each conversion. |
tag-test |
tag-test | Run RTC checks and tag self-tests. |
tag-flash |
tag-flash | Program, erase or read a tag's flash through its base, without STM32CubeProgrammer. |
base-flash |
base-flash | Update a base's firmware over USB through its bootloader. |
Developer and bench programs, such as tag-peek, tag-attach-cycle and
tag-log-import, are built with the tools but are not part of a release, so
they have no pages here. They are described in host/commandline-rs/README.md.
Fill-In Checklist
Use the same structure on each tool page:
- Replace the placeholder description with the user-facing job the tool performs.
- Add preconditions such as required tag state, firmware support, calibration setup, or expected hardware connection.
- Add one or more known-good commands.
- Paste representative output or describe the output fields.
- Add troubleshooting notes for common failure messages.