This package inspects running hubs, submits tool plans and approval decisions, and constructs the owner-configured console URL. 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

Use the Node.js version required by the installed API and transport dependencies (Node 25 for current verification). 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 --browser
pnpm exec shx inspect snapshot
pnpm exec shx inspect devices --room office --capability light --json
pnpm exec shx inspect agents
pnpm exec shx inspect catalog --owner-id device:light
pnpm exec shx inspect activity --json
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 --expected-action-digest '<reviewed-sha256-digest>'
pnpm exec shx approval '<approval-id>' reject --expected-action-digest '<reviewed-sha256-digest>' --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`	Prints the configured console origin without requesting credentials, contacting a hub or launching a browser. `--browser` explicitly launches it; `--print` is an explicit print alias.
`pnpm exec shx inspect [snapshot\|devices\|agents\|catalog\|tools\|approvals\|activity]`	Reads the selected API surface. The default is `snapshot`; `catalog` and `tools` inspect tool descriptors. Activity projects snapshot audit receipts. `--json` prints the public projection with availability where supplied.
`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 --expected-action-digest <digest>`	Submits the exact reviewed digest, then reports decision state, continuation state 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

Network commands use the published @smarthome.exchange/api 1.0.1 authenticated HTTP client with @smarthome.exchange/interfaces 2.1.0, including native tcp inventory. Configure both SHX_HUB_URL and SHX_HOME_ID, or supply --hub-url and --home-id; explicit flags take precedence. There is no implicit hub or home. URLs must be HTTP(S) origins without credentials, path, query or fragment. Remote connections require HTTPS; loopback permits HTTP. open requires the same owner-selected origin and home but only prints or launches the origin; it does not verify reachability or configure the console's authenticated bootstrap.

For hub 3.0, inspect the current tool catalog before calling a write. The hub owner explicitly enables integration control domains, each adapter requires its own permissions, and authenticated scopes must also allow the action. CLI scopes, scaffolding and approval decisions cannot configure or enable native adapter controls.

The native CLI reads the complete Authorization header from owner-provided SHX_AUTHORIZATION in its process environment. Supply it through your credential manager's child-process environment, never through command-line arguments or shell history. Embedded callers can instead supply an asynchronous authorizationHeaderProvider. The CLI creates no login, OIDC registration, cookie ticket, credential file, or token persistence flow. Missing or malformed native authentication fails before constructing a client; an invalid or failed asynchronous provider sends no request. Home selection is a resource selector; the hub derives identity and scopes from authentication and enforces current home grants.

# SHX_AUTHORIZATION is supplied by the owner's credential manager.
SHX_HUB_URL=https://hub.example SHX_HOME_ID=home:primary pnpm exec shx inspect --json
pnpm exec shx open --hub-url http://localhost:8080 --home-id home:primary

All inspection output, including --json, uses explicit projections. It includes device descriptors, agent configuration restrictions and status counts, tool identifiers/revisions/scopes, approval digests/continuation state, and receipt identifiers. It omits arbitrary metadata, device state values, prompts, model configuration, action input and identity, audit summaries, tool output, and untrusted error text. Full private action review belongs to the authenticated owner application; inspection is not a substitute for reviewing the complete immutable action there. Obtain the digest of the action you actually reviewed, then supply that value explicitly to approval. The CLI never fetches, computes or replaces a decision's digest with the latest action. A server mismatch fails closed.

Device inspection accepts --room and --capability. Catalog/tool inspection accepts --owner-id. Approval inspection accepts --status pending|approved|rejected|expired. Other targets reject those filters.

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 and prints the returned plan identifier. Caller IDs are attribution and grant no authority. The hub determines the required scopes of the selected tool. Each invocation submits once without retries; inspect the authoritative outcome before another invocation after uncertainty.

--timeout-ms bounds the complete network command, including credential preparation (default 10000, maximum 300000). Embedded callers may pass an abortSignal; SIGINT and SIGTERM also cancel network work. Cancellation reaches the API provider and transport, the settled request is drained before client stop, and all command-owned deadlines and signal listeners are removed. A provider owns its resources and must cooperate with its signal. No socket, polling watcher, or persisted runtime state is created.

Exit code 0 means an accepted operation, including suggested and queuedForApproval. Code 1 means failed tool/approval execution, argument errors, or transport/browser/cleanup errors. Code 2 means stale snapshot/activity data, an indeterminate or dispatching approval, an indeterminate tool, cancellation, or timeout. Approved decision state alone does not establish physical execution. Cancellation and deadlines cannot undo an admitted physical action; reconcile its durable outcome before invoking again. Transport and provider errors are sanitized before reaching the binary error handler.

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'], {
  environment: { SHX_HUB_URL: 'https://hub.example', SHX_HOME_ID: 'home:primary' },
  authorizationHeaderProvider: async ({ abortSignal }) => {
    // The application's configured credential manager owns refresh and cleanup.
    return credentialManager.getAuthorizationHeader({ abortSignal });
  },
});
process.exitCode = exitCode;

credentialManager is the embedding application's native credential service, not a CLI export. runCli(argv, options) returns 0, 1, or 2 for completed operations and throws sanitized argument, transport, browser and cleanup errors. Options accept environment, authorizationHeaderProvider, abortSignal, a typed createClient factory, write, and an async openBrowser callback. Injection supports deterministic tests; production uses the published API implementation. Every constructed client is stopped after its request 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.

readme.md

@smarthome.exchange/cli