HomeBox Skill

Use the HomeBox REST API to manage your home inventory. This skill provides a cross-platform Node.js CLI script and references the full API spec.

Self-Signed TLS Certificate

If your HomeBox instance uses a self-signed cert (like a Docker .nas.io domain), set NODE_TLS_REJECT_UNAUTHORIZED=0 in the environment before running any commands. The script relies on Node.js fetch which respects this env var.

# PowerShell
$env:NODE_TLS_REJECT_UNAUTHORIZED = 0
node scripts/homebox.js ...

# Bash
NODE_TLS_REJECT_UNAUTHORIZED=0 node scripts/homebox.js ...

This disables TLS verification globally — use with caution and only in trusted networks.

Prerequisites

Requires Node.js >= 18 and two environment variables:

The script auto-detects API version by probing GET /api/v1/entities:

• v1 (hay-kot): uses /api/v1/items, /api/v1/locations, /api/v1/labels
• v2 (sysadminsmedia): uses /api/v1/entities, /api/v1/tags, /api/v1/entity-types

Set HOMEBOX_API_VERSION=v1 or HOMEBOX_API_VERSION=v2 to skip auto-detect.

Getting a token: Login via the script: node {baseDir}/scripts/homebox.js login <username> (will prompt for password). Then set HOMEBOX_TOKEN to the returned token.

Using the CLI Script

All operations use the cross-platform Node.js script at {baseDir}/scripts/homebox.js:

node {baseDir}/scripts/homebox.js <command> [options]

Run node {baseDir}/scripts/homebox.js --help for full usage.

Core Operations

Search Examples

Natural language queries should be mapped to search terms:

• "Where are my keys?" → homebox.js search keys
• "What electronics do I have?" → homebox.js search --tags <electronics-tag-id>
• "What's in my desk drawer?" → homebox.js search --parents <desk-drawer-id>

Adding Items with Full Details

node {baseDir}/scripts/homebox.js add "MacBook Pro" \
  --description "14-inch M3 Pro" \
  --manufacturer "Apple" \
  --modelNumber "MRXJ3LL/A" \
  --serialNumber "FVLK..." \
  --purchasePrice 1999.00 \
  --purchaseDate "2024-03-15" \
  --purchaseFrom "Apple Store" \
  --insured true \
  --lifetimeWarranty false \
  --warrantyExpires "2025-03-15" \
  --warrantyDetails "AppleCare+" \
  --tagIds "tag-id-1,tag-id-2" \
  --parentId "location-id"

Response Fields

Fields vary by API version:

Paginated queries return: items[], total, page, pageSize, totalPrice.

Location management: v1 has a separate /api/v1/locations resource. v2 treats locations as entities with entityType.isLocation = true; the tree endpoint is /api/v1/entities/tree.

Interaction Philosophy

The goal is natural, low-friction inventory management — not filling out forms.

Core Principles

1. Accept any input style. A sentence ("add my AirPods I bought last month for 1299"), fragments ("AirPods bedroom"), or structured flags — all fine. Parse what's given, ignore what's not.

2. Ask only what's essential. For adding an item, the only must-have is a name. Everything else (location, description, tags, price, dates, brand, serial) is optional. Don't walk through fields one by one.

3. Batch updates naturally. If the user gives multiple details in one message ("price 1299, Apple, bought Feb 2025"), merge them into a single update — don't process each field separately.

4. Proactive, not pushy. After adding an item, briefly note what else could be filled in (e.g., "serial number and warranty can be added too") and let the user decide. If they say no, move on.

5. Confirm writes, but don't over-confirm. Summarize what will be done and ask once. Don't ask "confirm?" for every individual field.

   • Delete is the only hard rule: never execute without explicit, unambiguous confirmation.
   • Add / update / patch need user sign-off, but a single "Proceed?" after summarizing the changes is sufficient.

6. Match the user's language. This skill documentation is in English for universal access, but all conversation with the user should be in whatever language they use — don't switch to English just because the skill file is.

7. Be conversational, not mechanical. Instead of replying with rigid structured messages or error codes, reply naturally in the user's language — guide them, offer suggestions, and keep the interaction feeling like a helpful person, not a robot.

Search & Query

• Interpret natural language ("where are my keys?" → search keys). Try partial/fuzzy matches first.
• After showing results, optionally note items with missing useful fields (no brand, no price, no warranty).

Operational Notes

• Always fetch fresh IDs. HomeBox UUIDs (labels, locations, items) may change if the database is reset between sessions. Never rely on IDs cached earlier in the conversation.
• PUT 500 with labelIds? Most likely a stale label UUID. Re-fetch labels and retry.
• Self-signed TLS cert? Set NODE_TLS_REJECT_UNAUTHORIZED=0 (see above).
• Missing token? Drive the setup yourself: when env vars are missing, ask once for URL + credentials, run login, and proceed — no commentary, no "shall I save?", and advise setting HOMEBOX_TOKEN. Note that login returns a token with "Bearer " prefix — strip it before setting HOMEBOX_TOKEN since the script prepends its own "Bearer ".

Search & Query

• Script mechanics? The script requires Node.js >= 18. Resolve all script mechanics by reading source files directly.

Detailed API Reference

For all available endpoints, request/response schemas, and advanced operations (attachments, maintenance logs, exports, group management, etc.), see {baseDir}/references/api-reference.md.