@smarthome.exchange/cli

🧰 The shx command line interface for inspecting and operating hubs and generating typed agents and automations.

This package inspects running hubs, submits tool plans and approval decisions, and opens a verified console URL through @smarthome.exchange/api. It also creates .shx source directories, typed agent stubs, and automation files that import the SDK. Runtime commands do not import hub internals or store application state or credentials on disk.

Issue Reporting and Security

For reporting bugs, issues, or security vulnerabilities, please visit community.foss.global/. This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a code.foss.global/ account to submit Pull Requests directly.

Install

pnpm add --save-dev --save-exact @smarthome.exchange/cli
pnpm add --save-exact @smarthome.exchange/interfaces @smarthome.exchange/sdk

Node.js 22.4.0 or newer is required. The interfaces and SDK are direct project dependencies because generated source files import them. When installed locally, run the binary through pnpm exec shx.

Commands

pnpm exec shx help
pnpm exec shx init birch-lane
pnpm exec shx open
pnpm exec shx open --print
pnpm exec shx inspect snapshot
pnpm exec shx inspect devices --room office --capability light --json
pnpm exec shx inspect agents
pnpm exec shx inspect tools --owner-id device:light
pnpm exec shx inspect approvals --status pending
pnpm exec shx tool call '<tool-id-from-inspect-tools>' --input '{"value":35}' --title 'Set brightness' --reason 'Operator request'
pnpm exec shx approval '<approval-id>' approve
pnpm exec shx approval '<approval-id>' reject --json
pnpm exec shx agent new security-reviewer
pnpm exec shx automation new evening-check

Command	What it does
pnpm exec shx help	Prints the command list. shx, shx --help, and shx -h are aliases.
pnpm exec shx init [name]	Creates .shx/agents, .shx/automations, .shx/dashboards, and .shx/config.json.
pnpm exec shx open	Reads a live hub snapshot, then opens the configured console origin in the system browser. --print prints its verified URL without launching a browser.
pnpm exec shx inspect [snapshot|devices|agents|tools|approvals]	Reads the selected API surface. The default is snapshot. --json preserves the complete response envelope.
pnpm exec shx tool call <tool-id>	Submits one tool call with required --input, --title, and --reason values.
pnpm exec shx approval <approval-id> approve|reject	Submits a decision and prints its resulting approval status and audit receipt.
pnpm exec shx agent new <name>	Writes .shx/agents/<normalized-name>.ts with an IAgentDefinition stub.
pnpm exec shx automation new <name>	Writes .shx/automations/<normalized-name>.ts with an SDK automation stub.

Initialization and generators refuse to replace an existing config, agent, or automation file.

Runtime Connection and Outcomes

Runtime commands use HTTP through the public API client. Set SHX_HUB_URL or pass --hub-url with an HTTP(S) hub origin. The explicit option takes precedence; the default is http://localhost:8080. Credentials embedded in URLs, paths, query parameters, and fragments are rejected. Runtime connection settings are never written to the generated .shx source structure.

SHX_HUB_URL=https://hub.example pnpm exec shx inspect --json
pnpm exec shx open --hub-url http://localhost:8080 --print

Device inspection accepts --room and --capability. Tool inspection accepts --owner-id. Approval inspection accepts --status pending|approved|rejected|expired. Other targets reject those filters instead of ignoring them.

Tool calls use a JSON object for --input, with --confidence from 0 through 1 (default 1). --plan-id assigns a stable operator-tracked plan identifier; otherwise the CLI generates a UUID. The CLI submits each invocation once and never retries effectful calls. Use identifiers returned by inspect tools and inspect every result before deciding what to do next.

Exit code 0 means the API accepted the operation, including suggested and queuedForApproval outcomes. Code 1 means a tool failed, argument validation failed, or transport/browser execution failed. Code 2 means at least one tool result is indeterminate or an inspected/opened snapshot is stale. An indeterminate physical write may have been delivered; it requires reconciliation. A stale snapshot never launches a browser.

The current api@0.1.0 approval contract records decisions and audit receipts; it does not continue the queued tool call. Approval output reports that contract without claiming execution. Authentication, home selection, and digest-bound approval continuation depend on the forthcoming published security API; this command slice is not ready for release against an enforced hub until that migration is complete.

Generated Home Layout

.shx/
  config.json
  agents/
    comfort.ts
  automations/
    evening-check.ts
  dashboards/

Generated automation files import from @smarthome.exchange/sdk and register a manual trigger with on(...). Generated agent files import the data namespace from @smarthome.exchange/interfaces and export a typed agent definition.

Programmatic API

The package root exports the CLI helpers too:

import { createAgent, createAutomation, getHelpText, initHome, normalizeFileStem, runCli } from '@smarthome.exchange/cli';

console.log(normalizeFileStem('Evening Check!'));
console.log(getHelpText());

await initHome('birch-lane');
await createAgent('Security Reviewer');
await createAutomation('Evening Check');
await runCli(['help']);
const exitCode = await runCli(['inspect', 'devices', '--json']);
process.exitCode = exitCode;

runCli(argv, options) returns 0, 1, or 2 for completed operations and throws argument, transport, and browser errors. Runtime options accept environment, a typed createClient factory, write, and an async openBrowser callback. Tests can inject these collaborators without connecting to a hub or opening a browser. Every created client is stopped after its command settles.

Scripts

pnpm test
pnpm build
pnpm buildDocs

License and Legal Information

This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the repository license file.

Please note: The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.

Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.

Company Information

Task Venture Capital GmbH
Registered at District Court Bremen HRB 35230 HB, Germany

For any legal inquiries or further information, please contact us via email at hello@task.vc.

By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.