shelly-forge

Shelly project workflow

Use this skill for the host-side CLI and simulator. Follow shelly-scripting for device language rules, APIs, resource limits, and automation patterns. The MCP server was removed in 0.4.0.

Start with the project and target

Use Node.js 22.12 or newer. Inspect package.json, solutions.config.json, the selected source and test, and existing changes before editing. Work from the project root or pass --cwd <dir>. Confirm the selected device before a deploy or an RPC that changes state. Deployment stops, replaces, and starts that script.

For a new project, run:

npx shelly-forge init my-home
cd my-home
npm install
cp .env.example .env
npx shelly-forge --json create lighting hallway

Set DEVICE_HOSTNAME in the new .env to the intended host. Set SHELLY_PASSWORD there if the device requires authentication. Never echo or include credentials in reports. Keep SHELLY_PUBLIC_GREETING set for the starter scripts; an empty value uses their fallback. Public build values enter the artifact, so never use them for secrets. Existing process environment values override .env values.

create writes src/lighting/hallway.ts, its .test.ts, and a config entry. The template also includes src/example/hello.ts and its test. An omitted selector can deploy both entries. Use an explicit solution/script selector for device work.

Edit, test, check, deploy, inspect

1. Write device code under src/<solution>/ and update its test. Follow shelly-scripting, not Node runtime assumptions.
2. Run the tests and both TypeScript configurations. Keep the device and Node test configurations separate. Keep moduleDetection: "force" in both configurations so scripts without imports or exports do not share a global scope. See simulator tests.
3. Run check. Fix type errors and artifact findings before deployment.
4. Deploy only to the confirmed target. Default deployment builds, uploads, starts, and verifies the script throughout the full 3000 ms window. At least one healthy poll must complete within it. Every returned status must be healthy, including late responses. After a healthy poll, a later request cut off by the deadline does not fail verification. A failed health check attempts rollback when a different last-good artifact exists. A successful rollback still returns exit 5.
5. Inspect status and bounded logs. A simulator pass or a successful upload alone does not prove that the device runs correctly.