MacroDeck.Plugin.Cli 3.0.0-preview.10

MacroDeck.Plugin.Cli

macrodeck-plugin, the developer CLI for Macro Deck plugins: validate a manifest, inspect or pack a .macroDeckPlugin artifact, run a plugin against the running host (or a disposable stub) with production-shaped shutdown, and run the plugin conformance suite - all without installing Macro Deck itself.

Install

dotnet tool install --global MacroDeck.Plugin.Cli --prerelease

--prerelease is required today: only -preview versions are published ahead of the 3.0 release. Drop the flag once a stable 3.0 build ships.

Requires the ASP.NET Core shared framework (not just the .NET runtime): this tool pulls MacroDeck.Plugin.Testing transitively, whose loopback test host is a real Kestrel server. Install the ASP.NET Core runtime (or SDK) alongside the .NET runtime if macrodeck-plugin run or macrodeck-plugin test reports it cannot find Microsoft.AspNetCore.App.

Commands

Run macrodeck-plugin <command> --help for every command's options.

Exit codes

1 and 3 are deliberately distinct - a missing file is an environment problem, not a verdict about the plugin - which is what makes this tool usable as a CI gate.

Every command reports a failure as one line, error <kebab-case-code>: <message>, and a non-fatal observation the same way as warning <code>: <message> - neither suppressed by --verbosity quiet. Both go to stderr, except validate's own report, which is the command's result rather than its error channel and stays on stdout. This unified shape is new, but it changes only how a result is printed: every code above still means exactly what it did before. See the CLI documentation for the full shape.

Examples

# Build every platform the manifest declares and package the result.
macrodeck-plugin build --output ./artifacts

# Validate a manifest sitting next to your build output.
macrodeck-plugin validate --manifest bin/Release/net10.0/manifest.json

# Pack it into a distributable artifact.
macrodeck-plugin pack --source bin/Release/net10.0 --output MyPlugin-1.0.0.macroDeckPlugin

# See exactly what installing that artifact would find.
macrodeck-plugin inspect --artifact MyPlugin-1.0.0.macroDeckPlugin

# Run it against the running Macro Deck host, which the CLI discovers on its own.
macrodeck-plugin run --project MyPlugin.csproj

# Or against a disposable stub host - no Macro Deck installation required.
macrodeck-plugin run --project MyPlugin.csproj --stub-host

# Run the conformance suite against the packed artifact and write a Markdown report.
macrodeck-plugin test --artifact MyPlugin-1.0.0.macroDeckPlugin --report markdown --output conformance.md

# Verify a signed artifact, e.g. as a CI gate.
macrodeck-plugin verify MyPlugin-1.0.0.signed.macroDeckPlugin

Signing and the Store

Artifacts published to the Macro Deck Store are signed by the Creator Portal, server-side, after it verifies the publishing workflow's identity and provenance. Plugin developers and their CI workflows never generate, receive or hold signing keys or certificates, and there is no manual upload step. keygen and sign are for artifacts distributed outside the Store and for Macro Deck's own infrastructure - they are not a step on the way to publishing. See Publishing to the Store.

See the plugin development documentation.

Licensed under Apache-2.0.