### Configuration File Example (Host)

Source: https://github.com/indieisaconcept/homeyscriptkit/blob/main/HSK_CLI.md

Example JSON configuration for the HomeyScriptKit CLI using a host URL for tunnels.

```json
{
  "host": "https://your-tunnel.example.com",
  "apiKey": "your-api-key-here"
}
```

--------------------------------

### Install Dependencies

Source: https://github.com/indieisaconcept/homeyscriptkit/blob/main/HSK_CLI.md

Install the necessary dependencies for the HomeyScriptKit CLI after cloning the repository.

```bash
npm install
```

--------------------------------

### Configuration File Example (IP)

Source: https://github.com/indieisaconcept/homeyscriptkit/blob/main/HSK_CLI.md

Example JSON configuration for the HomeyScriptKit CLI using IP address and HTTP.

```json
{
  "https": false,
  "ip": "192.168.1.100",
  "apiKey": "your-api-key-here"
}
```

--------------------------------

### Install and Use Node.js Version

Source: https://github.com/indieisaconcept/homeyscriptkit/blob/main/CREATING_SCRIPTS.md

Installs the Node.js version specified in .nvmrc and switches to it.

```bash
nvm install
nvm use
```

--------------------------------

### Install NVM (Node Version Manager)

Source: https://github.com/indieisaconcept/homeyscriptkit/blob/main/CREATING_SCRIPTS.md

Installs NVM using a curl script. Restart your terminal after installation.

```bash
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
```

--------------------------------

### Example Usage for Multiple Commands

Source: https://github.com/indieisaconcept/homeyscriptkit/blob/main/CREATING_SCRIPTS.md

Illustrates how to invoke different commands defined in a HomeyScriptKit script using their respective URLs.

```bash
hsk://my-service/start?timeout=30
hsk://my-service/stop
hsk://my-service/status
```

--------------------------------

### CLI Flags Example (Host)

Source: https://github.com/indieisaconcept/homeyscriptkit/blob/main/HSK_CLI.md

Example of using CLI flags to provide Homey connection details with a host URL. This supersedes IP and HTTPS flags.

```bash
npx hsk list --apiKey your-api-key --host https://your-tunnel.example.com
```

--------------------------------

### CLI Flags Example (IP)

Source: https://github.com/indieisaconcept/homeyscriptkit/blob/main/HSK_CLI.md

Example of using CLI flags to provide Homey connection details with an IP address and HTTPS enabled.

```bash
npx hsk list --apiKey your-api-key --ip 192.168.1.100 --https
```

--------------------------------

### Toggle Surround Sound Example

Source: https://github.com/indieisaconcept/homeyscriptkit/blob/main/packages/sonos/README.md

Example of toggling surround sound using the standard result key. Ensure the soundbar's IP address is correctly provided.

```shell
hsk://sonos/toggleSurround?ip=192.168.1.1
```

--------------------------------

### Example Debugging Approach in HomeyScriptKit

Source: https://github.com/indieisaconcept/homeyscriptkit/blob/main/CREATING_SCRIPTS.md

Illustrates a common debugging pattern using console logging and try-catch blocks within an async HomeyScriptKit function.

```typescript
await hsk(async (event: Event<'debug-example', MyParams>) => {
  console.log('Received event:', event);
  console.log('Parameters:', event.params);

  try {
    const result = await someOperation(event.params);
    console.log('Operation result:', result);
    return result;
  } catch (error) {
    console.error('Operation failed:', error.message);
    throw error;
  }
});
```

--------------------------------

### Example Vitest Test Structure

Source: https://github.com/indieisaconcept/homeyscriptkit/blob/main/CREATING_SCRIPTS.md

A basic structure for writing unit tests using Vitest, including imports, describe blocks, and it blocks.

```typescript
import { describe, expect, it } from 'vitest';

import { yourFunction } from './your-script';

describe('YourScript', () => {
  it('should do something', () => {
    const result = yourFunction();
    expect(result).toBe(expectedValue);
  });
});
```

--------------------------------

### Toggle Home Theater with Custom Result Key

Source: https://github.com/indieisaconcept/homeyscriptkit/blob/main/packages/sonos/README.md

Example of toggling home theatre mode with a custom result key 'homeTheatre'. The soundbar's IP address is required.

```shell
hsk://sonos/toggleHomeTheatre/homeTheatre?ip=192.168.1.1
```

--------------------------------

### Calling Scripts from HomeyScript Flows

Source: https://github.com/indieisaconcept/homeyscriptkit/blob/main/README.md

Use this URL format to call your installed HomeyScript scripts from Homey flows. Script results are accessible via tags.

```text
hsk://script-name/command?parameter1=value1&parameter2=value2
```

--------------------------------

### Call HSK Script in Homey Flows

Source: https://github.com/indieisaconcept/homeyscriptkit/blob/main/CREATING_SCRIPTS.md

Example of how to invoke a deployed HSK script from Homey flows using the HSK URL format. This specifies the script, command, and parameters.

```url
hsk://my-script/execute?name=John&action=greet
```

--------------------------------

### HomeyScriptKit Custom Result Key

Source: https://github.com/indieisaconcept/homeyscriptkit/blob/main/README.md

Example of using the HomeyScriptKit URL structure with a custom result key. This allows for more specific naming of the script's output.

```plaintext
hsk://sonos/toggleSurround/livingRoom?ip=192.168.1.1
```

--------------------------------

### Pull Remote Scripts Locally

Source: https://github.com/indieisaconcept/homeyscriptkit/blob/main/HSK_CLI.md

Downloads all current scripts from your Homey and saves them locally. Useful for starting local management of existing scripts.

```bash
npx hsk pull
```

--------------------------------

### Implement Parameter Validation in a Script

Source: https://github.com/indieisaconcept/homeyscriptkit/blob/main/CREATING_SCRIPTS.md

Ensure script robustness by validating required parameters before executing script logic. This example checks for the presence of 'deviceId' and 'action' parameters.

```typescript
await hsk(async (event: Event<'process', MyParams>) => {
  const { params } = event;

  // Validate required parameters
  const required = ['deviceId', 'action'];
  const missing = required.filter((param) => !params[param]);

  if (missing.length > 0) {
    throw new Error(`Missing required parameters: ${missing.join(', ')}`);
  }

  // Your script logic here
  return processDevice(params.deviceId, params.action);
});
```

--------------------------------

### HSK Script with Parameter Validation

Source: https://github.com/indieisaconcept/homeyscriptkit/blob/main/CREATING_SCRIPTS.md

An example HSK script that defines custom parameters, validates required input, and returns a dynamic message. It demonstrates basic error handling and parameter usage.

```typescript
// packages/my-script/index.ts
import hsk, { type BaseParams, type Event } from '@hsk';

interface MyScriptParams extends BaseParams {
  name: string;
  action?: string;
}

await hsk(async (event: Event<'execute', MyScriptParams>) => {
  const { params } = event;

  if (!params.name) {
    throw new Error('Name parameter is required');
  }

  const action = params.action || 'default';
  const message = `Hello ${params.name}, executing ${action} action!`;

  console.log(message);

  return {
    message,
    timestamp: new Date().toISOString(),
    success: true,
  };
});
```

--------------------------------

### Sync Scripts from Directory

Source: https://github.com/indieisaconcept/homeyscriptkit/blob/main/HSK_CLI.md

Push scripts from a local directory to Homey. Ensure the specified directory exists.

```bash
npx hsk sync --dir ./scripts
```

--------------------------------

### Running Tests in HomeyScriptKit

Source: https://github.com/indieisaconcept/homeyscriptkit/blob/main/CREATING_SCRIPTS.md

Commands to execute tests once or in watch mode using npm scripts.

```bash
# Run tests once
npm run test:run

# Run tests in watch mode (automatically re-runs when files change)
npm test
# or
npm run test:watch
```

--------------------------------

### Build HSK Script

Source: https://github.com/indieisaconcept/homeyscriptkit/blob/main/CREATING_SCRIPTS.md

Commands to build your HSK script for development or production. Use 'build-debug' for easier debugging and 'build' for an optimized, minified version.

```bash
# For development (unminified, easier to debug)
npm run build-debug

# For production (minified, optimized)
npm run build
```

--------------------------------

### Clone HomeyScriptKit Repository

Source: https://github.com/indieisaconcept/homeyscriptkit/blob/main/CREATING_SCRIPTS.md

Clones the HomeyScriptKit repository and navigates into the project directory.

```bash
git clone https://github.com/indieisaconcept/homeyscriptkit.git
cd homeyscriptkit
```

--------------------------------

### Sonos Configuration URL Format

Source: https://github.com/indieisaconcept/homeyscriptkit/blob/main/packages/sonos/README.md

Use this format to execute Sonos actions with HomeyScript. Specify the action and optionally a custom result key, along with the soundbar's IP address.

```shell
hsk://sonos/<action>/<result:optional>?ip=<ip-address-of-soundbar>
```

--------------------------------

### Create Script Directory

Source: https://github.com/indieisaconcept/homeyscriptkit/blob/main/CREATING_SCRIPTS.md

Command to create a new directory for your HSK script within the 'packages' folder. This is the first step in organizing your script.

```bash
mkdir packages/my-script
```

--------------------------------

### Local Development Commands

Source: https://github.com/indieisaconcept/homeyscriptkit/blob/main/CREATING_SCRIPTS.md

Commands to run during local development for continuous rebuilding, debug builds, and linting checks.

```bash
# Watch mode for continuous rebuilding during development
npm run watch

# Run with debug output
npm run build-debug

# Check for linting issues
npm run lint
```

--------------------------------

### Sync Scripts to Remote

Source: https://github.com/indieisaconcept/homeyscriptkit/blob/main/HSK_CLI.md

Pushes local scripts to your Homey, updating existing ones or creating new ones if they don't exist. Safe for initial deployment and updates.

```bash
npx hsk sync [script]
```

--------------------------------

### Skip Confirmation Prompts

Source: https://github.com/indieisaconcept/homeyscriptkit/blob/main/HSK_CLI.md

Automate workflows by skipping interactive confirmation prompts during sync or restore operations. Use with caution.

```bash
npx hsk sync --skipConfirmation
```

```bash
npx hsk restore --skipConfirmation
```

--------------------------------

### Run HomeyScriptKit CLI Command

Source: https://github.com/indieisaconcept/homeyscriptkit/blob/main/HSK_CLI.md

The basic command structure for executing HomeyScriptKit CLI commands.

```bash
npx hsk <command> [options]
```

--------------------------------

### Backup Homey Scripts

Source: https://github.com/indieisaconcept/homeyscriptkit/blob/main/HSK_CLI.md

Creates a backup of your Homey scripts in JSON file format. Specify a script name to back up a single script.

```bash
npx hsk backup [script]
```

--------------------------------

### List Remote Homey Scripts

Source: https://github.com/indieisaconcept/homeyscriptkit/blob/main/HSK_CLI.md

Lists all available remote Homey scripts. Use this to see what scripts are currently deployed on your Homey.

```bash
npx hsk list
```

--------------------------------

### Handle Multiple Commands in a Single Script

Source: https://github.com/indieisaconcept/homeyscriptkit/blob/main/CREATING_SCRIPTS.md

Define and execute multiple distinct commands within a single HomeyScriptKit script. This pattern is useful for creating services with various operations.

```typescript
import hsk, { type Event } from '@hsk';

const commands = {
  start: async (params: any) => {
    console.log('Starting...', params);
    return { status: 'started' };
  },

  stop: async (params: any) => {
    console.log('Stopping...', params);
    return { status: 'stopped' };
  },

  status: async (params: any) => {
    return { status: 'running', uptime: '5 minutes' };
  },
};

await hsk(async (event: Event<keyof typeof commands>) => {
  const { command, params } = event;

  if (!commands[command]) {
    throw new Error(`Unknown command: ${command}`);
  }

  return commands[command](params);
});
```

--------------------------------

### Write Unit Tests for Script Logic

Source: https://github.com/indieisaconcept/homeyscriptkit/blob/main/CREATING_SCRIPTS.md

Utilize testing frameworks like Vitest to write unit tests for your script functions, ensuring they behave as expected.

```typescript
// my-script.test.ts
import { describe, expect, it } from 'vitest';

import { myScriptFunction } from './index';

describe('MyScript', () => {
  it('should process parameters correctly', () => {
    const result = myScriptFunction({ name: 'test' });
    expect(result.success).toBe(true);
  });
});
```

--------------------------------

### Pull Scripts to Custom Directory

Source: https://github.com/indieisaconcept/homeyscriptkit/blob/main/HSK_CLI.md

Download scripts from Homey to a specified local directory. This allows for local backup or modification.

```bash
npx hsk pull --dir ./my-scripts
```

--------------------------------

### HomeyScriptKit URL Structure

Source: https://github.com/indieisaconcept/homeyscriptkit/blob/main/README.md

This is the general structure for passing arguments to HomeyScriptKit scripts using a URL-like format. It defines how to specify the script, command, optional result key, and query arguments.

```plaintext
hsk://<script>/<command>/<result:optional>?<args>
```

--------------------------------

### Use Host URL for Remote Access

Source: https://github.com/indieisaconcept/homeyscriptkit/blob/main/HSK_CLI.md

Connect to Homey using a custom host URL, suitable for tunnels or remote access scenarios. Requires an API key.

```bash
npx hsk list --apiKey your-api-key --host https://your-tunnel.example.com
```

```bash
npx hsk sync --apiKey your-api-key --host https://your-tunnel.example.com
```

--------------------------------

### Implement Robust Error Handling

Source: https://github.com/indieisaconcept/homeyscriptkit/blob/main/CREATING_SCRIPTS.md

Wrap device control logic in a try-catch block to handle potential errors gracefully and provide meaningful error messages.

```typescript
await hsk(async (event: Event<'control', DeviceParams>) => {
  try {
    const result = await controlDevice(event.params);
    return result;
  } catch (error) {
    throw new Error(`Device control failed: ${error.message}`);
  }
});
```

--------------------------------

### Document Script Parameters

Source: https://github.com/indieisaconcept/homeyscriptkit/blob/main/CREATING_SCRIPTS.md

Use JSDoc comments to document the purpose, required, and optional parameters of your script functions.

```typescript
/**
 * Controls a smart device
 *
 * Required parameters:
 * - deviceId: The device identifier
 * - action: The action to perform (on/off/toggle)
 *
 * Optional parameters:
 * - brightness: Brightness level (0-100) for dimmable devices
 */
```

--------------------------------

### HTTP API Integration Script

Source: https://github.com/indieisaconcept/homeyscriptkit/blob/main/CREATING_SCRIPTS.md

Integrates with external HTTP APIs by fetching data based on provided URL and method. Handles JSON responses and returns status, data, and a timestamp.

```typescript
await hsk(async (event: Event<'fetch', { url: string; method?: string }>) => {
  const { url, method = 'GET' } = event.params;

  const response = await fetch(url, { method });
  const data = await response.json();

  return {
    status: response.status,
    data,
    timestamp: new Date().toISOString(),
  };
});
```

--------------------------------

### Basic HSK Script Structure

Source: https://github.com/indieisaconcept/homeyscriptkit/blob/main/CREATING_SCRIPTS.md

Defines the core structure of an HSK script, including parameter types and the main asynchronous function for script logic. Use this as a template for new scripts.

```typescript
import hsk, { type BaseParams, type Event } from '@hsk';

// Define your parameter types (optional but recommended)
interface MyScriptParams extends BaseParams {
  requiredParam: string;
  optionalParam?: string;
}

// Your script logic
await hsk(async (event: Event<'myCommand', MyScriptParams>) => {
  const { command, params, script, result } = event;

  // Your script implementation here
  console.log(`Executing ${command} on ${script}`);
  console.log('Parameters:', params);

  // Return any data you want to make available to subsequent flow cards
  return { success: true, message: 'Script executed successfully' };
});
```

--------------------------------

### Restore Homey Scripts from Backup

Source: https://github.com/indieisaconcept/homeyscriptkit/blob/main/HSK_CLI.md

Restores scripts from backup files. This operation deletes all existing scripts on your Homey before restoring. Script IDs may change, requiring flow updates.

```bash
npx hsk restore [script]
```

--------------------------------

### Specify Custom Result Tag Names

Source: https://github.com/indieisaconcept/homeyscriptkit/blob/main/CREATING_SCRIPTS.md

Customize the storage location for script results by defining a custom tag name in the script's invocation URL. This overrides the default naming convention.

```bash
hsk://my-script/execute/customResult?name=John
```

--------------------------------

### Validate Required Parameters

Source: https://github.com/indieisaconcept/homeyscriptkit/blob/main/CREATING_SCRIPTS.md

Implement a parameter validation function to check for the presence of all required parameters before proceeding with script execution.

```typescript
const validateParams = (params: any, required: string[]) => {
  const missing = required.filter((param) => !params[param]);
  if (missing.length > 0) {
    throw new Error(`Missing required parameters: ${missing.join(', ')}`);
  }
};
```

--------------------------------

### Conditional Logic Script

Source: https://github.com/indieisaconcept/homeyscriptkit/blob/main/CREATING_SCRIPTS.md

Executes different processing logic based on a 'mode' parameter. Supports 'automatic' and 'manual' modes, throwing an error for invalid modes.

```typescript
await hsk(async (event: Event<'process', ProcessParams>) => {
  const { params } = event;

  if (params.mode === 'automatic') {
    return await automaticProcess(params);
  } else if (params.mode === 'manual') {
    return await manualProcess(params);
  } else {
    throw new Error('Invalid mode. Use "automatic" or "manual"');
  }
});
```

--------------------------------

### Define Parameter Interfaces for Type Safety

Source: https://github.com/indieisaconcept/homeyscriptkit/blob/main/CREATING_SCRIPTS.md

Use TypeScript interfaces to define expected parameters for your scripts, enhancing the development experience and preventing runtime errors.

```typescript
interface DeviceParams extends BaseParams {
  deviceId: string;
  action: 'on' | 'off' | 'toggle';
  brightness?: string;
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.