README
¶
Astrolabe CLI
Astrolabe is a command-line tool for capturing QA run data from serial devices, TCP sources, and existing files, then validating and uploading those runs to your backend.
Installation
Prerequisites
- Go 1.25.0 (or use
misewith the includedmise.toml)
Option 1: Build from source
git clone <your-repo-url>
cd astrolabe
go build -o astrolabe ./cmd/astrolabe
Option 2: Use mise tasks
mise trust
mise install
mise run build
This creates the binary as astrolabe.
First-time configuration
Astrolabe reads config from ~/.astrolabe/connection.yml and environment variables.
Common environment variables:
ASTROLABE_API_URLASTROLABE_PROJECT_IDASTROLABE_AUTH_TOKEN
You can also set metadata defaults:
astrolabe config set operator "Jane Doe"
astrolabe config set location "Bench A"
astrolabe config set device-id "dev-001"
astrolabe config get operator
Features
- Capture from multiple sources:
- Serial (
astrolabe capture serial) - TCP (
astrolabe capture tcp) - Files: CSV, JSONL, raw logs (
astrolabe capture file)
- Serial (
- Interactive workflows via TUI (
astrolabe tui,astrolabe config edit) - Local offline run cache (defaults to
~/.astrolabe/runs) - Run validation before upload (
astrolabe validate <run_dir>) - Upload one run or all pending cached runs (
astrolabe upload) - JSON output mode for automation (
--json)
Examples
Show help
astrolabe help
Capture from serial
astrolabe capture serial --port /dev/ttyUSB0 --baud 115200 --test-plan smoke --tag lab
Capture from TCP
astrolabe capture tcp --host 192.168.1.50 --port 9000 --test-plan burnin --attr station=west
Ingest an existing file
astrolabe capture file ./data/results.csv --format csv --operator "Jane Doe" --location "Bench A"
Validate a run before upload
astrolabe validate ~/.astrolabe/runs/<run-id>
Upload runs
# upload all pending runs
astrolabe upload
# upload a specific run
astrolabe upload --run-id <run-id>
Machine-readable output
astrolabe validate ~/.astrolabe/runs/<run-id> --json
Documentation
Detailed guides are in docs/:
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
astrolabe
command
|
|
|
astrolabe/root
Package root wires together all CLI subcommands and provides the top-level Execute entry point used by main.
|
Package root wires together all CLI subcommands and provides the top-level Execute entry point used by main. |
|
internal
|
|
|
config
Package config loads and exposes application configuration via Viper, including API connection settings, upload tuning, and telemetry options.
|
Package config loads and exposes application configuration via Viper, including API connection settings, upload tuning, and telemetry options. |
|
core
Package core defines the shared domain types used across all astrolabe packages.
|
Package core defines the shared domain types used across all astrolabe packages. |
|
logging
Package logging provides lightweight structured logging helpers that write timestamped key-value lines to stdout.
|
Package logging provides lightweight structured logging helpers that write timestamped key-value lines to stdout. |
|
normalize
Package normalize provides normalizers that convert raw source bytes into structured core.Record values ready for storage.
|
Package normalize provides normalizers that convert raw source bytes into structured core.Record values ready for storage. |
|
sources
Package sources provides capture.Source implementations for serial ports, TCP connections, and local files.
|
Package sources provides capture.Source implementations for serial ports, TCP connections, and local files. |
|
telemetry
Package telemetry provides a global metrics registry with pluggable backends (expvar, Prometheus, or no-op) for recording anonymous usage statistics.
|
Package telemetry provides a global metrics registry with pluggable backends (expvar, Prometheus, or no-op) for recording anonymous usage statistics. |
|
tui
Package tui is a placeholder for a future Bubble Tea TUI.
|
Package tui is a placeholder for a future Bubble Tea TUI. |
|
validate
Package validate checks run directories for structural and data integrity before they are submitted for upload.
|
Package validate checks run directories for structural and data integrity before they are submitted for upload. |
Click to show internal directories.
Click to hide internal directories.