Stream Deck CLI

https://docs.elgato.com/streamdeck/
Admin
Stream Deck CLI is a command-line interface tool for building, managing, and packaging Stream Deck...
Tokens:101,139
Snippets:944
Trust Score:10
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Install latest SDK and CLI

Source: https://docs.elgato.com/streamdeck/sdk/releases/upgrading/v3

Install the latest versions of the SDK and CLI.

```bash
npm i @elgato/streamdeck@latest @elgato/cli@latest
```

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

### Install @elgato/prettier-config

Source: https://docs.elgato.com/streamdeck/sdk/style-guide/linting

Install the @elgato/prettier-config package as a devDependency.

```bash
npm install @elgato/prettier-config --save-dev
```

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

### Install Elgato ESLint and Prettier Configurations

Source: https://docs.elgato.com/streamdeck/sdk/style-guide/linting

Install the Elgato ESLint and Prettier configurations as dev dependencies.

```bash
npm install @elgato/eslint-config @elgato/prettier-config --save-dev
```

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

### Install Stream Deck CLI from npm

Source: https://docs.elgato.com/streamdeck/cli/intro

Install the Stream Deck CLI globally from npmjs using the @elgato/cli package.

```bash
npm install -g @elgato/cli@latest
```

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

### Install and verify Node.js with nvm

Source: https://docs.elgato.com/streamdeck/sdk/introduction/getting-started

Install Node.js version 24 using nvm, switch to it, and verify the installed version. Run these commands in sequence in your terminal.

```bash
nvm install 24
```

```bash
nvm use 24
```

```bash
node -v
```

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

### Install @elgato/eslint-config

Source: https://docs.elgato.com/streamdeck/sdk/style-guide/linting

Install the @elgato/eslint-config package as a dev dependency.

```bash
npm install @elgato/eslint-config --save-dev
```

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

### Install @elgato/streamdeck v2

Source: https://docs.elgato.com/streamdeck/sdk/releases/upgrading/v2

Install the latest version of the @elgato/streamdeck package.

```bash
npm i @elgato/streamdeck@latest
```

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

### Log file format example

Source: https://docs.elgato.com/streamdeck/sdk/guides/logging

Shows the format of log entries: <iso_date> <log_level> [[scope]: ]<message>. The example shows a log entry with an ISO date, INFO level, and message.

```text
<iso_date> <log_level> [[scope]: ]<message>
```

```text
2024-05-05T12:35:13.000Z INFO  Hello world
```

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

### Install Stream Deck CLI with npm, yarn, or pnpm

Source: https://docs.elgato.com/streamdeck/sdk/introduction/getting-started

Install the Stream Deck CLI globally using npm, yarn, or pnpm. Choose one package manager; they are alternatives.

```bash
npm install -g @elgato/cli
```

```bash
yarn global add @elgato/cli
```

```bash
pnpm add -g @elgato/cli
```

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

### Stream Deck CLI overview output

Source: https://docs.elgato.com/streamdeck/cli/intro

Example output of running `streamdeck` to see available commands and options.

```text
Usage: streamdeck [options] [command]

Options:
  -v                            display CLI version
  -h, --help                    display help for command

Commands:
  create                        Stream Deck plugin creation wizard.
  link [path]                   Links the plugin to Stream Deck.
  restart|r <uuid>              Starts the plugin in Stream Deck; if the plugin is already running, it is stopped first.
  stop|s <uuid>                 Stops the plugin in Stream Deck.
  dev [options]                 Enables developer mode.
  validate [options] [path]     Validates the Stream Deck plugin.
  pack|bundle [options] [path]  Creates a .streamDeckPlugin file from the plugin.
  config                        Manage the local configuration.
  help [command]                display help for command

Alias:
  streamdeck
  sd
```

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

### Miscellaneous Utilities Import: Before and After

Source: https://docs.elgato.com/streamdeck/sdk/releases/upgrading/v2

Before and after examples for importing miscellaneous utilities. These are now imported from `@elgato/utils` instead of `@elgato/streamdeck`.

```typescript
import {
	Enumerable,
	EventEmitter,
	type EventsOf,
} from "@elgato/streamdeck";
```

```typescript
import {
	Enumerable,
	EventEmitter,
	type EventsOf,
} from "@elgato/utils";
```

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

### Start development watch command

Source: https://docs.elgato.com/streamdeck/sdk/introduction/getting-started

Run this command to start watching for changes. Changes to manifest.json or src are automatically reflected in Stream Deck; press Ctrl+C to stop.

```bash
npm run watch

```

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

### Verify Stream Deck CLI installation

Source: https://docs.elgato.com/streamdeck/cli/intro

Verify the Stream Deck CLI installation by printing its version.

```bash
streamdeck -v
```

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

### Example deep-link URL to send

Source: https://docs.elgato.com/streamdeck/sdk/guides/deep-linking

Example deep-link URL sent to the plugin with identifier com.elgato.hello-world. The path is URL-encoded and a fragment is included.

```text
streamdeck://plugins/message/com.elgato.hello-world/Hello%20world#Testing
```

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

### Install Node.js version 24 with nvm

Source: https://docs.elgato.com/streamdeck/cli/intro

Install Node.js version 24 using nvm (or nvm-windows) as a prerequisite for the Stream Deck CLI.

```bash
nvm install 24
```

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

### Expected log output from deep-link example

Source: https://docs.elgato.com/streamdeck/sdk/guides/deep-linking

Expected log output from the example event handler when receiving the deep-link URL streamdeck://plugins/message/com.elgato.hello-world/Hello%20world#Testing.

```text
Path = /Hello%20world
Fragment = Testing
```

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

### Annotated deep-link URL example

Source: https://docs.elgato.com/streamdeck/sdk/guides/deep-linking

Annotated example of a deep-link URL showing the path, query, and fragment components. The URL uses the plugin identifier com.elgato.hello-world.

```text
                                                              href
                                                   ┌───────────┴───────────┐
streamdeck://plugins/message/com.elgato.hello-world/hello?name=Elgato#waving
                                                   └─┬──┘ └────┬────┘ └─┬──┘
                                                    path      query    fragment
```

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

### Pack a plugin with streamdeck pack

Source: https://docs.elgato.com/streamdeck/sdk/introduction/distribution

Packages a plugin directory into a .streamDeckPlugin installer file. The pack command validates your plugin, bundles the contents of the *.sdPlugin directory, and outputs the installer file.

```bash
# Pack the *.sdPlugin directory
streamdeck pack com.elgato.hello-world.sdPlugin
```

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

### Switch to Node.js version 24 with nvm

Source: https://docs.elgato.com/streamdeck/cli/intro

Switch to the installed Node.js version 24 using nvm (or nvm-windows).

```bash
nvm use 24
```

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

### fr.json with custom Localization strings

Source: https://docs.elgato.com/streamdeck/sdk/guides/i18n

Updated version of the fr.json example that includes a Localization object with custom strings. Note: the file is named fr.json but contains German text; the example is for demonstration.

```json
{
    "Name": "Lautstärkeregler",
    "Description": "Übernehmen Sie die Kontrolle über Ihre Audiolautstärke",
    "com.example.volume.adjust": {
        "Name": "Lautstärkeregelung",
        "Tooltip": "Kontrollieren Sie Ihre Lautstärke",
        "States": [
            {
                "Name": "Stummschaltung aufheben"
            },
            {
                "Name": "Stumm"
            }
        ],
        "Encoder": {
            "TriggerDescription": {
                "LongTouch": "Stumm",
                "Push": "Stummschaltung umschalten",
                "Rotate": "Anpassen",
                "Touch": "Stummschaltung umschalten"
            }
        }
    },

    "Localization": {
        "More info": "Weitere Informationen",
        "Save": "Speichern",
        "Reset": "Zurücksetzen"
    }
}
```

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

### JSON Types Import: Before and After

Source: https://docs.elgato.com/streamdeck/sdk/releases/upgrading/v2

Before and after examples for importing JSON types. The types are now imported from `@elgato/utils` instead of `@elgato/streamdeck`.

```typescript
import type {
	JsonObject,
	JsonPrimitive,
	JsonValue
} from "@elgato/streamdeck";
```

```typescript
import type {
	JsonObject,
	JsonPrimitive,
	JsonValue
} from "@elgato/utils";
```

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

### Layout JSON file with $schema

Source: https://docs.elgato.com/streamdeck/sdk/references/layouts

Example layout JSON file that references the schema URL using the $schema property.

```json
{
	"$schema": "https://schemas.elgato.com/streamdeck/plugins/layout.json",
	"id": "CustomLayout",
	"items": [
		// ...
	]
}
```

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

### streamdeck list - Show linked plugins

Source: https://docs.elgato.com/streamdeck/cli/commands/list

Displays a list of installed plugins and their source paths. This is the default behavior when no options are provided.

```terminal
streamdeck list
```

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

### Get global settings in plugin

Source: https://docs.elgato.com/streamdeck/sdk/guides/settings

Retrieves global settings using streamDeck.settings.getGlobalSettings. The result is a JsonObject without type inference, so cast or provide a type when needed. This example reads settings inside a deep-link event handler.

```typescript
import streamDeck from "@elgato/streamdeck";

streamDeck.system.onDidReceiveDeepLink(async (ev) => {
	// Get the settings.
	const settings = await streamDeck.settings.getGlobalSettings();
});

streamDeck.connect();
```

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

### Using types with global settings

Source: https://docs.elgato.com/streamdeck/sdk/guides/settings

Shows how to use TypeScript generics with getGlobalSettings to get type safety. The example defines a Settings type with a count field, reads it with a default, increments, and writes it back. Note that type safety does not guarantee runtime types.

```typescript
import streamDeck from "@elgato/streamdeck";

// Define a type that represents the settings.
type Settings = {
	count: number;
};

streamDeck.system.onDidReceiveDeepLink(async (ev) => {
	// When getting the settings, supply the type.
	let { count = 0 } = await streamDeck.settings.getGlobalSettings<Settings>();

	count++;
	await streamDeck.settings.setGlobalSettings({ count });
});

streamDeck.connect();
```

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

### Create a Stream Deck plugin with output

Source: https://docs.elgato.com/streamdeck/cli/commands/create

Run the create command and observe the wizard's interactive prompts and output. The example shows a successful creation of a plugin named 'Counter' with UUID 'com.elgato.counter'. The scaffolded plugin is written to a directory named 'counter' in the current working directory.

```bash
streamdeck create
```

```text
.___ _                        ___         _
/ __| |_ _ _ ___ __ _ _ __   |   \ ___ __| |__
\__ \  _| '_/ -_) _` | '  \  | |) / -_) _| / /
|___/\__|_| \___\__,_|_|_|_| |___/\___\__|_\_\

Welcome to the Stream Deck Plugin creation wizard.

This utility will guide you through creating a local development environment for a plugin.
For more information on building plugins see https://docs.elgato.com.

Press ^C at any time to quit.

? Author: Elgato
? Plugin Name: Counter
? Plugin UUID: com.elgato.counter
? Description: A simple counter that increments on each press

? Create Stream Deck plugin from information above? Yes

Creating Counter...
✔ Enabling developer mode
✔ Generating plugin
✔ Installing dependencies
✔ Building plugin
✔ Finalizing setup

Successfully created plugin!

? Would you like to open the plugin in VS Code? (Y/n)

```

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

### streamdeck create command

Source: https://docs.elgato.com/streamdeck/cli/commands/create

Run the Stream Deck plugin creation wizard. You will be prompted for Author, Plugin Name, Plugin UUID, and Description. After completion, the plugin is automatically installed in Stream Deck.

```bash
streamdeck create
```

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

### streamdeck list --all - Show all plugins

Source: https://docs.elgato.com/streamdeck/cli/commands/list

Displays all installed plugins, including those not linked. The `--all` option overrides the default of showing only linked plugins.

```terminal
streamdeck list --all
```

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

### Pack current directory with version

Source: https://docs.elgato.com/streamdeck/cli/commands/pack

Creates a `.streamDeckPlugin` file from the current working directory, specifying a new plugin version.

```bash
streamdeck pack --version "0.8.2.12"
```

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

### Active deep-link example

Source: https://docs.elgato.com/streamdeck/sdk/guides/deep-linking

Example of an active deep-link that brings Stream Deck's window to the foreground. This is the default behavior and is recommended for OAuth flows.

```text
streamdeck://plugins/message/com.elgato.hello-world/hello
```

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

### Restart plugin with streamdeck CLI

Source: https://docs.elgato.com/streamdeck/sdk/introduction/your-first-changes

Restart the plugin in Stream Deck using the streamdeck CLI. The first command shows the general syntax with a placeholder; the second shows an example using the plugin UUID 'com.elgato.hello-world'.

```bash
streamdeck restart <plugin_uuid>
```

```bash
streamdeck restart com.elgato.hello-world
```

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

### Manifest with localizable strings (volume controller)

Source: https://docs.elgato.com/streamdeck/sdk/guides/i18n

Example manifest for a volume controller plugin showing the strings that can be localized, including action-specific strings indexed by UUID.

```json
{
    // Some properties omitted for brevity...
    "Name": "Volume Controller",
    "Description": "Take control of your audio volume",
    "Actions": [
        {
            "UUID": "com.example.volume.adjust",
            "Name": "Volume control",
            "Tooltip": "Control your volume",
            "States": [
                {
                    "Name": "Unmute"
                },
                {
                    "Name": "Mute"
                }
            ],
            "Encoder": {
                "TriggerDescription": {
                    "LongTouch": "Mute",
                    "Push": "Toggle mute",
                    "Rotate": "Adjust",
                    "Touch": "Stummschaltung umschalten"
                }
            }
        }
    ]
}
```

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

### Passive deep-link example with streamdeck=hidden

Source: https://docs.elgato.com/streamdeck/sdk/guides/deep-linking

Example of a passive deep-link that does not bring Stream Deck's window to the foreground. Requires the query string parameter streamdeck=hidden and Stream Deck 7.0 or higher.

```text
streamdeck://plugins/message/com.elgato.hello-world/hello?streamdeck=hidden
                                                          └───────┬───────┘
                                                          Passive deep-link
```

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

### Get macOS app CFBundleIdentifier with osascript

Source: https://docs.elgato.com/streamdeck/sdk/guides/app-monitoring

Finds the CFBundleIdentifier of a macOS application using osascript in the terminal. Replace "Application Name" with the actual app name to get the identifier used in ApplicationsToMonitor.

```bash
osascript -e 'id of app "Application Name"'
```

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

### getSettings

Source: https://docs.elgato.com/streamdeck/sdk/guides/actions

Gets the settings associated with this action instance.

```APIDOC
## getSettings

### Description
Gets the settings associated with this action instance.

### Method
function getSettings(): Promise<TSettings>

### Parameters
None.

### Returns
Promise<TSettings> - A promise that resolves to the settings associated with the action instance.
```

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

### GetSettings

Source: https://docs.elgato.com/streamdeck/sdk/references/websocket/ui

Gets the settings associated with an instance of an action. Causes `didReceiveSettings` to be emitted.

```APIDOC
## GetSettings

### Description
Gets the settings associated with an instance of an action. Causes `didReceiveSettings` to be emitted.

### Command
`getSettings`

### Parameters
- **action** (string) - Required - Identifies the action type, as specified by the UUID within the manifest.
- **context** (string) - Required - The action instance identifier.
- **event** ("getSettings") - Required - Name of the command.
- **id** (string) - Optional - Optional identifier that can be used to identify the response to this request.

### Request Example
```json
{
  "action": "com.example.action",
  "context": "actionInstanceId",
  "event": "getSettings",
  "id": "optionalId"
}
```
```

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

### GetGlobalSettings

Source: https://docs.elgato.com/streamdeck/sdk/references/websocket/ui

Gets the global settings associated with the plugin. Causes `didReceiveGlobalSettings` to be emitted.

```APIDOC
## GetGlobalSettings

### Description
Gets the global settings associated with the plugin. Causes `didReceiveGlobalSettings` to be emitted.

### Command
`getGlobalSettings`

### Parameters
- **context** (string) - Required - The plugin's identifier, as provided by Stream Deck.
- **event** ("getGlobalSettings") - Required - Name of the command.
- **id** (string) - Optional - Optional identifier that can be used to identify the response to this request.

### Request Example
```json
{
  "context": "pluginIdentifier",
  "event": "getGlobalSettings",
  "id": "optionalId"
}
```
```

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

### Create eslint.config.js with Recommended Config

Source: https://docs.elgato.com/streamdeck/sdk/style-guide/linting

Create an eslint.config.js file at the root of your project to use the recommended ESLint configuration.

```javascript
import { config } from "@elgato/eslint-config";

export default config.recommended;
```

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

### getResources

Source: https://docs.elgato.com/streamdeck/sdk/guides/actions

Gets the resources (files) associated with this action. Available from Stream Deck 7.1.

```APIDOC
## getResources

### Description
Gets the resources (files) associated with this action; these resources are embedded into the action when it is exported, either individually, or as part of a profile. Available from Stream Deck 7.1.

### Method
function getResources(): Promise<Resources>

### Parameters
None.

### Returns
Promise<Resources> - A promise that resolves to the resources associated with the action.
```
Tokens:
Raw