Streamdeck CLI

Stream Deck CLI — Command Reference

Prerequisite: Read streamdeck-general first for installation and the overall edit/build/test loop. This skill is the exhaustive flag-by-flag reference for every streamdeck (alias sd) subcommand.

Purpose

Reference everything the streamdeck CLI can do so an agent can stop guessing flag names. Useful when wiring CI pipelines, writing npm scripts, or troubleshooting an unexpected CLI message.

Install / verify

npm install -g @elgato/cli@latest
streamdeck -v                # prints CLI version
streamdeck                   # prints top-level help

Aliases: sd is identical to streamdeck. All examples below use the long form for clarity.

Top-level commands

1. streamdeck create

Interactive wizard. No arguments, no flags.

streamdeck create

Prompts:

1. Author name — free text, becomes manifest.Author.
2. Plugin name — display name.
3. Plugin UUID — reverse-DNS, lowercase a-z 0-9 . -. Permanent after publish.
4. Description — short summary.
5. Open in VS Code? — convenience.

After completion:

• Scaffolds project directory named after the plugin.
• Runs npm install (or yarn/pnpm/bun depending on config packageManager).
• Auto-links the new .sdPlugin/ to Stream Deck.
• Enables streamdeck dev mode for the PI debugger.
• Builds once so the plugin appears in Stream Deck immediately.

💡 If the wizard fails after creating the folder, you can cd into it, run npm install, then streamdeck link manually.

2. streamdeck link [path]

Registers a plugin directory with the local Stream Deck app. Symlinks under the hood — no file copy, edits reflect immediately.

streamdeck link                              # link current working directory
streamdeck link com.yourhandle.hello-world.sdPlugin

The directory name must equal <PLUGIN_UUID>.sdPlugin. If you renamed the UUID, also rename the folder.

Use cases:

• After git clone of an existing plugin repo, to register it.
• After streamdeck stop (followed by edit) to re-register.
• Recovering from a botched pack/uninstall.

3. streamdeck restart <uuid> / streamdeck r <uuid>

Stops the plugin if running, then starts it. Reloads manifest.json, imgs/, ui/, and bin/.

streamdeck restart com.yourhandle.hello-world
streamdeck r       com.yourhandle.hello-world   # alias

Used by the npm run watch script under the hood — typically you won't call this directly during development.

Common gotcha: if you renamed the UUID, the old UUID's plugin is still registered. streamdeck stop <old> then re-link with the new UUID.

4. streamdeck stop <uuid> / streamdeck s <uuid>

Stops a running plugin and unloads its resources. The plugin remains installed and can be restarted.

streamdeck stop com.yourhandle.hello-world
streamdeck s    com.yourhandle.hello-world      # alias

Useful before attaching a Node debugger with --inspect-brk semantics, or before manually deleting the .sdPlugin/ directory.

5. streamdeck dev

Toggles developer mode. When enabled:

• Property-inspector remote debugger is exposed at http://localhost:23654/.
• Plugins receive a Node --inspect=<port> flag (or the configured port).
• Stream Deck shows additional diagnostics in its own logs.

streamdeck dev              # enable
streamdeck dev --disable    # disable

create enables this automatically. Disable on a shared workstation if you don't want random programs hitting your localhost debug port.

6. streamdeck validate [path]

Schema-check a plugin's manifest.json and project structure. Required as the first step before pack.

streamdeck validate                                       # cwd
streamdeck validate com.yourhandle.hello-world.sdPlugin   # explicit path
streamdeck validate --force-update-check
streamdeck validate --no-update-check                     # CI mode

Checks:

• Manifest is valid against https://schemas.elgato.com/streamdeck/plugins/manifest.json.
• Required files exist (CodePath, action Images, PI HTML).
• File extensions are correct (e.g. Icon must be extension-less in the field; the file on disk needs .png/.svg).
• UUIDs are reverse-DNS and properly nested under the plugin UUID.

Non-zero exit on any error. Use it as a pre-commit / pre-push hook.

7. streamdeck pack [path] / streamdeck bundle [path]

Builds the .streamDeckPlugin installer file users will double-click to install. Internally: validate → strip files matched by .sdignore → zip into .streamDeckPlugin.

streamdeck pack com.yourhandle.hello-world.sdPlugin/ --output dist/
streamdeck pack --version 0.8.2.12
streamdeck pack --dry-run
streamdeck pack --force --output dist/                    # overwrite

.sdignore

Same syntax as .gitignore, applied at pack time. Default exclusions:

.git/
/.env*
*.log
*.js.map

Common additions:

# Source — only ship compiled bin/
src/
*.test.*
__tests__/
# Dev-only docs
README.md
CONTRIBUTING.md
.vscode/

Do NOT exclude bin/, imgs/, ui/, or manifest.json — those are what the user actually needs.

8. streamdeck config

Manages CLI-wide configuration (stored in your home directory, not the project). Useful when you want all streamdeck create runs to use yarn, or to silence the gif-style ASCII recordings.

streamdeck config list                              # show current
streamdeck config set packageManager=yarn
streamdeck config set reduceMotion=true
streamdeck config unset packageManager              # back to default
streamdeck config reset                             # back to all defaults

9. Useful package.json scripts

The scaffold gives you build and watch. Recommended additions:

{
  "scripts": {
    "build":        "rollup -c",
    "watch":        "rollup -c -w --watch.onEnd=\"streamdeck restart com.yourhandle.hello-world\"",
    "validate":     "streamdeck validate com.yourhandle.hello-world.sdPlugin --no-update-check",
    "pack":         "streamdeck pack com.yourhandle.hello-world.sdPlugin --output dist --force --no-update-check",
    "pack:dry":     "streamdeck pack com.yourhandle.hello-world.sdPlugin --dry-run --no-update-check",
    "lint":         "eslint . --max-warnings 0 && prettier . --check",
    "format":       "eslint . --fix && prettier . --write",
    "release":      "npm run lint && npm run validate && npm run build && npm run pack"
  }
}

10. Quick troubleshooting

See Also

• Official CLI intro: https://docs.elgato.com/streamdeck/cli/intro
• Per-command docs: https://docs.elgato.com/streamdeck/cli/commands/<name>
• Sibling skills: streamdeck-general (workflow), streamdeck-publishing (uses pack for marketplace submission)