plugin-cmd

Placement	compiled-in (in-process)
Source	github.com/opencharly/plugin-cmd/candy/plugin-cmd
Version	2026.209.0000
Candy	plugin-cmd

This plugin is listed in charly/charly.yml’s compiled_plugins:, so its providers are compiled into the charly binary and register in-process.

Providers

The reserved words this plugin serves:

• cmd — command class

What it does

COMPILED-IN charly COMMAND-class plugin owning the externalized charly cmd command (#118 loader+check-tail cone) — run a single command in a running container with an optional desktop notification on completion.

The plugin owns the command end to end: the kong grammar (CmdCmd), the container resolve (deploykit.ResolveContainer / ResolveSidecarContainer), and –notify (the venue’s gdbus session-bus call, driven directly on the deploykit.ContainerChain executor — a plugin drives gdbus itself, the boundary law’s host-object-is-never-permanence rule). The ONE thing it cannot do is the interactive exec, which is deploy-lifecycle machinery (dispatchLifecycleTarget → OpAttach): it dispatches the op=“cmd” pod-lifecycle action over the reverse channel with INHERITED stdio, so the -i interactive stream reaches the operator. The former hidden charly __cmd core reentry is DELETED (K-wave 2) — the op=“cmd” dispatch is plugin-side, so no charly-core symbol crosses the boundary; the plugin imports the sdk module alone.

cmd is COMPILED-IN (listed in charly/charly.yml compiled_plugins) BECAUSE its Invoke(OpRun) needs the in-proc reverse channel — threaded by dispatchInProcCommand — to drive HostBuild(“cli”). The out-of-process CliMain path has no reverse channel, so it errors. command:cmd is a FLAT command (Box + Command positionals), so NewMeta declares no Subcommands and ships no plugin_input.

Parameter schema

The CUE schema below is the authoritative grammar for this plugin’s input. It is the same single source that generates the plugin’s Go parameter types and answers the runtime Describe RPC, so this page cannot disagree with either.

schema/cmd.cue

// plugin-cmd's OWN self-contained CUE schema — the plugin's declaration
// surface, used two ways exactly like every other plugin's schema (there is
// no schema-less plugin):
//
//  1. SERVE over Describe — the host splices `base ++ plugin` at the load gate, so the
//     plugin's declarations travel WITH it and a self-contained schema that will not
//     splice is a LOUD load failure.
//  2. DOCUMENT the plugin's published surface — the reference site's per-plugin page is
//     rendered from its providers, this schema, and the candy description.
//
// command:cmd's authored input is its pass-through CLI grammar (Box + Command
// positionals, the OpRun `{args: [...]}` envelope), so this schema DOCUMENTS the command
// contract rather than a structured plugin_input. SELF-CONTAINED: it references no base
// def, so it compiles STANDALONE (the property that lets the SDK compile it serve-side).
#CmdPlugin: {
  // The declared capability words (the plugin.providers surface), recorded here as
  // part of the plugin's published declaration surface.
  providers: [...string]

  // The command word the plugin serves.
  command: "cmd"

  // What the command does, in one line (the public-docs surface).
  contract: string & !=""

  // The configuration surface: env var names the plugin reads, recorded here as part
  // of the plugin's published declaration surface.
  config?: [string]: string
}

---

See also the candy reference for this candy’s install surface.