hxtp-cli

Go CLI for device management — primary production CLI.

Installation

From Release

# Linux/macOS
curl -sL https://github.com/hestialabs/hxtp/releases/latest/download/hxtp-linux-amd64 -o hxtp
chmod +x hxtp

# macOS
brew install hxtp

From Source

git clone https://github.com/hestialabs/hxtp
cd hxtp/cli/hxtp-cli
go build -o hxtp ./cmd/hxtp

Quick Start

# Login (browser-based OAuth)
hxtp login

# Provision a device interactively (Generates Ed25519 Identity)
hxtp device create

# Send command (Signed with Cloud Root Key)
hxtp send <device-id> toggle_led -p value=true

Commands

hxtp login

Initiates OAuth handshake or manual token input:

hxtp login [--url https://api.hestialabs.in/api/v1]

Flow:

1. Generates 256-bit handshake ID
2. Opens browser to /auth/cli?code={id}
3. Polls for JWT token
4. Stores in system keyring

Environment: HXTP_TOKEN for CI/CD

hxtp send

Send an Ed25519 signed command to a device:

hxtp send <device-id> <action> [-p key=value] [--transport rest|mqtt|ws] [--dry-run]

Example:

# Send via native MQTT for sub-millisecond latency
hxtp send abc123 toggle_led -p value=true --transport mqtt

Options:

• -p, --param — Key-value parameters (can be specified multiple times)
• --transport — Network delivery mechanism (REST is default, MQTT for low-latency)
• --dry-run — Preview action without execution against safety rules

hxtp confirm

Confirm and execute a critical action that returned dry_run_required during a dry run:

hxtp confirm <device-id> <dry-run-token>

hxtp device create

Starts an interactive TUI to provision a new device on the network. In HxTP/3.1, this initiates the Ed25519 identity generation.

hxtp device create [--type <manifest-type>] [--home-id <uuid>]

Configuration

Keyring Storage

Credentials stored in OS keyring:

Service	Account
io.hxtp.cli	main-token
io.hxtp.cli	client-id
io.hxtp.cli	cloud-root-key

Config File

~/.hxtp/config.json:

{
  "api_url": "https://api.hestialabs.in",
  "tenant_id": "tenant-uuid",
  "client_id": "unique-client-id",
  "last_login": "2026-01-01T00:00:00Z"
}

Mode: 0600 (user-only)

Security

• Credentials in OS keyring (never plaintext)
• Config in ~/.hxtp/ (600 perms)
• HTTPS-only API
• Bit-perfect HxTP/3.1 Ed25519 signing
• Supports CI/CD via HXTP_TOKEN

TUI

Interactive prompts use Charmbracelet libraries:

• charmbracelet/huh — prompts
• charmbracelet/lipgloss — styling

# Verbose output
hxtp --verbose login

Global Flags

Flag	Description
--url	API base URL
--transport	Network transport (rest, mqtt, ws)
--verbose	Verbose output
--version	Show version

JavaScript CLI (@hxtpctl-js)

A lightweight, Bun/Node-based alternative to the Go CLI, optimized for frontend developers and automation scripts.

Installation

bun add -g @hestialabs/hxtpctl

Usage

The JS CLI follows the same command patterns as the Go CLI:

# Send command via WebSockets
hxtpctl send <device-id> toggle_led --transport ws

# List devices
hxtpctl list

Features

• Native Bun Support: Ultra-fast startup and execution.
• Protocol Parity: Uses hxtp-js for bit-perfect HxTP/3.1 signing.
• Cross-Platform: Works anywhere Node.js or Bun is available.

---

CI/CD

# Using environment variable
HXTP_TOKEN=eyJhbGci... hxtp device list

# Logout (clear keyring)
hxtp logout