create

mixlar-sdk create scaffolds a new plugin package from one of four starter templates. Run it bare in a terminal and you get a friendly, guided wizard; pass a name (or --yes) and it scaffolds straight from flags — which is also exactly what CI and scripts get, since the wizard only ever runs on an interactive TTY.

mixlar-sdk create [name] --dir DIR --template {macro,slider,widget,full} \
              --id PLUGIN_ID --author AUTHOR --yes --force

The wizard

If you run mixlar-sdk create with no name and no --yes, and you’re on an interactive terminal, you get the wizard:

1. Plugin name — the display name shown on the plugin card. Defaults to "My Plugin".
2. Plugin ID — the lowercase id and output folder name. Defaults to a slug of the name you just typed.
3. Availability check (optional) — the wizard offers to check whether that id is already taken on the Mixlar registry before you commit to it.
4. Author — you or your organization. Written into plugin.json.
5. Description — one line, optional. If you leave it blank, a sensible default is filled in based on the template you pick next.
6. Template — pick one of full, macro, slider, or widget from a menu (full is the default/first option).

A transcript looks like this:

Create a Mixlar plugin

? Plugin name › My Plugin
? Plugin ID (lowercase id + folder name) › my_plugin
? Check if 'my_plugin' is available on registry.mixlar.net? › Yes
  Searching…
  ✓ 'my_plugin' is available
? Author (you or your organization) › Jane Dev
? Description (one line (optional)) › ›
? Template ›
  ❯ full     macros + slider + device widget + settings
    macro    just macro actions
    slider   just a slider mode
    widget   a plugin paired to a device widget

My Plugin created  🎉

Next steps
  cd C:\...\my_plugin
  mixlar-sdk validate
  mixlar-sdk emulate --render preview.png
  mixlar-sdk pack

Learn more: https://mixlar.net/developer/introduction/getting-started/

Tip

The wizard is entirely skippable. Anything you type interactively is just a friendlier way of filling in the same flags described below — so once you know what you want, create with flags is faster for repeat use.

The flag-driven form

Pass a name positional argument, or --yes/-y, and create skips the wizard and scaffolds immediately from flags and defaults. This is also what happens automatically in non-TTY environments (CI, piped output).

mixlar-sdk create "Weather Widget" --template widget --author "Jane Dev"

$ mixlar-sdk create "Weather Widget" --template widget --author "Jane Dev"
[ok] created 'widget' plugin 'Weather Widget' (weather_widget) at C:\...\weather_widget
Next steps:
  cd C:\...\weather_widget
  mixlar-sdk validate
  mixlar-sdk emulate --render preview.png
  mixlar-sdk pack

flag	default	meaning
name (positional)	wizard, or "My Plugin"	display name; omit to trigger the wizard
--dir	.	directory to create the package folder in
--template	full	macro / slider / widget / full
--id	slug of name	plugin id (also the output folder name)
--author	""	written into plugin.json
--yes / -y	off	skip the wizard even on a TTY (scripts/CI)
--force	off	overwrite an existing folder of the same name

Note

The output folder is named after the id, not the display name — "My Plugin" becomes ./my_plugin/. The id is slugified automatically (lowercase letters, digits, and underscores, starting with a letter) if you don’t pass --id explicitly.

Caution

If the destination folder already exists, create refuses and exits with an error unless you pass --force, which deletes and recreates it. There’s no merge — --force is destructive to whatever was there.

Templates

Every template lives under mixlar_cli/templates/<template>/ and gets copied into <dir>/<id>/, with placeholders substituted throughout every text file (.py, .json, .txt, .md) and the entry .py renamed to match your plugin id.

template	contains	default description
macro	two sample macro actions	“A starter Mixlar plugin with two sample macro actions.”
slider	one sample slider mode	“A starter Mixlar plugin with a sample slider mode.”
widget	a plugin paired with a bundled device widget	“A Mixlar plugin paired with a bundled device widget.”
full	macros + a slider mode + a device widget + settings — the showcase template	“The showcase Mixlar plugin: macros, a slider mode, and a bundled device widget.”

full is the default when --template is omitted, since it’s the most complete starting point to trim down from.

What gets substituted

Inside the copied template, these placeholders are replaced everywhere they appear — in file contents and in file/folder names:

placeholder	filled with
__PLUGIN_NAME_CLASS__	a CamelCase Python class name derived from the display name (e.g. Weather Widget → WeatherWidgetPlugin)
__PLUGIN_ID__	the plugin id
__PLUGIN_NAME__	the display name
__AUTHOR__	the author string, or empty
__DESCRIPTION__	your description, or the template’s default if left blank
__ENTRY__	the plugin id (used to name the entry module)

The template’s __ENTRY__.py file is renamed to <plugin_id>.py as part of the copy.

Next steps

Every successful create run — wizard or flags — prints the same next steps, because they’re the same regardless of how you got here:

cd <your-plugin-folder>
mixlar-sdk validate
mixlar-sdk emulate --render preview.png
mixlar-sdk pack

See validate and emulate for what those two commands check and render, and pack, sign, and publish for turning your finished package into a .mixplugin archive. For a broader tour of the whole CLI, start at CLI overview; if you’d rather learn by following a complete plugin from scratch, see the Getting Started guide.