ArchSpec Inspect

ArchSpec Inspect is a small C++17 library and command-line tool that tells you what machine it is running on. It can collect structured information about the OS, CPU topology and instruction set, caches, memory and NUMA, PCI and graphics, storage, networking, thermal and power state, virtualization, and firmware.

Linux has the deepest support today. macOS has native OS and CPU collection; other macOS categories return portable data where they can and clearly mark the rest as unavailable. Windows currently uses the portable fallback. The library never fills in a value by guessing.

This project is unrelated to the Python package named archspec, which models CPU microarchitectures. The executable and Python package here use the archspec-inspect and archspec_inspect names to avoid that collision.

Build

The C++ library has no runtime dependencies. CMake is the usual way to build and install it:

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build
ctest --test-dir build --output-on-failure
cmake --install build --prefix "$HOME/.local"

For a quick local build, make -j and make test are also available.

Run it

./build/archspec-inspect
./build/archspec-inspect --format json --categories cpu,isa,memory
./build/archspec-inspect --capabilities

The CLI redacts the hostname, kernel command line, MAC addresses, and IP addresses by default. Use --include-sensitive only when the report will stay local. Collection is read-only: it does not run shell commands or use the network.

Use it from C++

After installation, add the library to a CMake target:

find_package(archspec CONFIG REQUIRED)
target_link_libraries(my_program PRIVATE archspec::archspec)

Then ask for only the information your program needs:

#include <archspec/archspec.hpp>

#include <iostream>

int main() {
  archspec::CollectOptions options;
  options.categories =
      archspec::CollectCategory::cpu |
      archspec::CollectCategory::memory;
  options.include_sensitive = false;

  const archspec::Report report = archspec::collect_report(options);
  std::cout << archspec::to_json(report) << '\n';
}

Every scalar in the report has a status. It either contains a value or explains why it does not (not_found, unsupported, perm_denied, parse_error, or redacted). The original #include <aview.hh> is still available for source compatibility.

Use it from Python

If Python development headers are installed, CMake also builds the native archspec_inspect extension:

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build
PYTHONPATH=build/python python3 - <<'PY'
import archspec_inspect

report = archspec_inspect.collect(["cpu", "isa"])
print(report["data"]["cpu"]["model_name"])
PY

Use collect_json() when you want JSON; it returns the C++ serializer’s output directly. Use collect() when a normal Python dictionary is easier. Both run natively and release the GIL while they collect the report.

import archspec_inspect

payload = archspec_inspect.collect_json("cpu,memory")
report = archspec_inspect.collect(["os", "cpu"], include_sensitive=False)

The full API, installation instructions, fixture roots, and privacy controls are in the Python API guide.

Reports and notes

JSON reports include the producer and schema versions, the categories that ran, and only the data you selected. The format lives in schema/archspec-report-v1.schema.json.

• Comparison with other introspection tools
• Packaging and release plan
• Using the CLI from LLM tools and agents

Before publishing to package repositories, the project needs an explicit open-source license.