iframe-proxy | Sunbelt Computer Software

ChatCLI supports a plugin system to extend its functionality. A plugin is an executable that follows a specific contract, allowing ChatCLI to discover, execute, and interact with it securely. This lets you create custom commands (such as @kind, @deploy) that can orchestrate tools, interact with APIs, or perform any logic you can program.

Tool plugin or provider plugin? This page covers tool plugins: commands the model calls during a conversation. To add a whole LLM provider — a corporate gateway or an internal SDK that ChatCLI talks to instead of a built-in vendor — see Provider Plugins.

For Users: Managing Plugins

List installed plugins

/plugin list

Shows all available plugin commands, including [builtin] plugins (such as @coder) and [remote] plugins (from connected servers).

Install a plugin

Install directly from a Git repository:

/plugin install https://github.com/usuario/meu-plugin-chatcli.git

ChatCLI will clone, compile (if it’s Go), and install the executable in ~/.chatcli/plugins/, signed with this machine’s local key so it loads with signature enforcement on. Or install a prebuilt, signed binary — from disk or from a release URL:

/plugin install ./acme-tool
/plugin install --binary https://releases.example.com/acme-tool

The first install from a publisher asks you to confirm its key’s fingerprint once; see Signature Verification.

Security: Installing a plugin involves downloading and executing third-party code. Only install plugins from sources you trust.

View plugin details

/plugin show <plugin-name>

Uninstall a plugin

/plugin uninstall <plugin-name>

Reload plugins

ChatCLI automatically monitors ~/.chatcli/plugins/ and reloads when it detects changes (creation, removal, modification). A 500ms debounce prevents multiple reloads. To force a manual reload:

/plugin reload

Develop plugins iteratively: edit the code, recompile, send it to the plugins directory — ChatCLI will detect the change automatically.

For Developers: Creating a Plugin

The plugin contract

Executable — The plugin must be an executable file (any language)
Location — Placed in ~/.chatcli/plugins/
Command name — The file name becomes the command. E.g., file kind = command @kind
Metadata (--metadata) — Required. The executable must respond to this flag with JSON:

{
  "name": "@meu-comando",
  "description": "A brief description of what the plugin does.",
  "usage": "@meu-comando <subcommand> [--flag value]",
  "version": "1.0.0"
}

Schema (--schema) — Optional. Describes the accepted parameters:

{
  "parameters": [
    {
      "name": "cluster-name",
      "type": "string",
      "required": true,
      "description": "Kubernetes cluster name"
    }
  ]
}

Communication (stdout vs stderr):
- stdout — Only the final result (returned to ChatCLI/AI)
- stderr — Progress logs, status, and warnings (displayed in real time to the user)

Example: “Hello World” Plugin in Go

package main

import (
    "encoding/json"
    "flag"
    "fmt"
    "os"
    "time"
)

type Metadata struct {
    Name        string `json:"name"`
    Description string `json:"description"`
    Usage       string `json:"usage"`
    Version     string `json:"version"`
}

// logf sends progress messages to the user (via stderr).
func logf(format string, v ...interface{}) {
    fmt.Fprintf(os.Stderr, format, v...)
}

func main() {
    metadataFlag := flag.Bool("metadata", false, "Exibe os metadados do plugin")
    schemaFlag := flag.Bool("schema", false, "Exibe o schema de parâmetros")
    flag.Parse()

    if *metadataFlag {
        meta := Metadata{
            Name:        "@hello",
            Description: "Plugin de exemplo que demonstra o fluxo stdout/stderr.",
            Usage:       "@hello [seu-nome]",
            Version:     "1.0.0",
        }
        jsonMeta, _ := json.Marshal(meta)
        fmt.Println(string(jsonMeta))
        return
    }

    if *schemaFlag {
        schema := map[string]interface{}{
            "parameters": []map[string]interface{}{
                {
                    "name":        "nome",
                    "type":        "string",
                    "required":    false,
                    "description": "Nome da pessoa a ser cumprimentada",
                    "default":     "Mundo",
                },
            },
        }
        jsonSchema, _ := json.Marshal(schema)
        fmt.Println(string(jsonSchema))
        return
    }

    // Lógica principal
    logf("Plugin 'hello' iniciado!\n")
    time.Sleep(2 * time.Second)
    logf("   - Realizando uma tarefa demorada...\n")
    time.Sleep(2 * time.Second)

    name := "Mundo"
    if len(flag.Args()) > 0 {
        name = flag.Args()[0]
    }

    logf("Tarefa concluída!\n")

    // Resultado final vai para stdout
    fmt.Printf("Olá, %s! A hora agora é %s.", name, time.Now().Format(time.RFC1123))
}

Compilation and installation

# 1. Compile
go build -o hello ./hello/main.go

# 2. Make it executable
chmod +x hello

# 3. Create the plugins directory (if it doesn't exist)
mkdir -p ~/.chatcli/plugins/

# 4. Move the executable
mv hello ~/.chatcli/plugins/

# 5. Use in ChatCLI
/agent Hello, my name is John

Capability Interfaces (opt-in)

Plugins can expose capabilities through optional Go interfaces. Legacy plugins that don’t implement them keep working unchanged — every interface is fail-closed (conservative default). When implemented, the plugin participates in orchestrator optimizations:

Interface	Method	Purpose
`ReadOnlyAware`	`IsReadOnly(args []string) bool`	Enables the capability security gate (auto-allow) and participation in parallel batches
`ConcurrencySafeAware`	`IsConcurrencySafe(args []string) bool`	Signals that multiple calls can run in parallel
`DescriberWithInput`	`DescribeCall(args []string) string`	Dynamic spinner label (“Reading: main.go” instead of “RUNNING: @read”)
`JSONSchemaAware`	`JSONSchema() string`	draft-2020-12 schema validated before dispatch — invalid input becomes `ToolResult{IsError:true, ErrorCode:"InvalidArgs"}`
`TruncationAware`	`MaxResultChars() int`	Per-tool output cap (versus the 30 000 global default)
`Prompter`	`Prompt(opts PromptOpts) (string, error)`	Contextual system-prompt slice
`StreamingInputAware`	`UpdateStreamingInput(field, value string)`	Partial-input events as the LLM streams args
`StructuredExecutor`	`ExecuteStructured(...) (StructuredResult, error)`	Typed return in place of the legacy `(string, error)`

Example — a plugin that wants auto-allow + parallelization + custom label:

func (p *MyReadOnlyPlugin) IsReadOnly(_ []string) bool        { return true }
func (p *MyReadOnlyPlugin) IsConcurrencySafe(_ []string) bool { return true }
func (p *MyReadOnlyPlugin) DescribeCall(args []string) string {
    return i18n.T("plugins.myplugin.describe", extractTarget(args))
}
func (p *MyReadOnlyPlugin) JSONSchema() string {
    return `{"type":"object","properties":{"file":{"type":"string"}},"required":["file"]}`
}

The four atomic plugins (@read, @search, @tree, @todo) — see Atomic Tools — use every relevant capability as a reference implementation.

Signature Verification

A plugin runs only when it is signed by a key this machine trusts: an Ed25519 signature over the binary’s SHA-256, in a detached <plugin>.sig next to it. The publisher’s public key can travel with the plugin as <plugin>.pub, but a bundled key is never trusted on its own — anyone can sign a binary with their own key and ship that key along, so trusting it automatically would make the signature prove nothing. A key becomes trusted through a decision made outside the bundle, in one of three ways:

Trust on first use

The first install from a publisher shows the key’s fingerprint and asks once. The key is trusted and pinned to that plugin: updates install silently, a different key is refused.

Managed keys

An administrator places the publisher’s key next to managed.env. Every user of the machine trusts it, with nothing to copy.

Built from source

/plugin install <git-url> builds on your machine after you confirm, and signs the result with this machine’s own key.

Install a signed plugin

/plugin install ./acme-tool                                   # REPL: a prebuilt binary on disk
/plugin install --binary https://releases.example.com/acme-tool
chatcli plugin install https://releases.example.com/acme-tool  # outside the REPL

ChatCLI fetches <src>, <src>.sig and <src>.pub (https only), checks them, and writes nothing to the plugins directory until the publisher is trusted:

The bundle	What happens
Signed by a key you or your administrator already trust	Installs
Signed by an unknown publisher whose key is bundled	Shows the fingerprint and asks once; on yes the key is trusted and pinned to the plugin
Same, with no person at the terminal (CI, scripts)	Refused, naming the fingerprint — repeat with `--trust SHA256:…`
Same plugin, signed by a different key than the pinned one	Refused, even if you would confirm. If the publisher really rotated its key, uninstall the plugin and install it again
Signature does not match the bundled key or any trusted key	Refused: the binary or the signature was altered
Unsigned	Refused, unless `CHATCLI_ALLOW_UNSIGNED_PLUGINS=true`

Compare the fingerprint ChatCLI shows with the one the publisher announces — on the release page or the internal portal — before you trust it. That comparison is what makes trust on first use safe.

Publish a signed plugin

Generate the publisher key once

chatcli plugin keygen --output ~/acme-signing
# plugin-signing.key (0600, keep it secret) and plugin-signing.pub,
# plus the fingerprint to announce: SHA256:…

Sign every release

chatcli plugin sign --binary dist/acme-tool --key ~/acme-signing/plugin-signing.key
# writes dist/acme-tool.sig

Ship the bundle and announce the fingerprint

Publish acme-tool, acme-tool.sig and the public key renamed acme-tool.pub side by side, and show the fingerprint where users download the plugin.

Managed keys for organizations

Put the publisher’s .pub in the managed trusted-keys directory, next to managed.env:

OS	Directory
macOS, Linux	`/etc/chatcli/trusted-keys/`
Windows	`%ProgramData%\chatcli\trusted-keys\`

Every user of the machine then trusts that publisher, including users who never created a trusted-keys directory of their own. The directory is owned by the administrator, so a user cannot remove the key.

Plugins built from source

/plugin install <git-url> clones and builds the plugin on your machine after you confirm the install. The resulting binary is signed with a local machine key — created in ~/.chatcli/local-signing/ on first use and trusted as local-machine — so it loads with signature enforcement on, with no keygen or trust step.

Inspect and manage trust

chatcli plugin trust list                          # trusted keys (user and managed) and pinned publishers
chatcli plugin trust --key ./publisher.pub         # trust a key by hand
chatcli plugin verify --binary ~/.chatcli/plugins/acme-tool

Trusted keys:
  local-machine                    SHA256:ZC681egmth0i2DM1adI+3ZmmrqXyyRvftD/bxF4dW+s  (user)
  acme                             SHA256:qVrckaw/nhbU80swrHGK9e7icHuwzZE3MkfGQlm3m+A  (managed)
Pinned publishers:
  tool:acme-tool                   SHA256:qVrckaw/nhbU80swrHGK9e7icHuwzZE3MkfGQlm3m+A

File Permissions

The plugins directory uses 0o700 permissions (owner-only read, write, and execute). ChatCLI checks permissions on startup and warns if they are more permissive.

Development Mode

For local development, you can disable signature verification:

export CHATCLI_ALLOW_UNSIGNED_PLUGINS=true
chatcli

Never enable CHATCLI_ALLOW_UNSIGNED_PLUGINS in production. Unsigned plugins can execute arbitrary code with the ChatCLI process permissions.

Remote Plugins

When connecting to a server via chatcli connect, server plugins are discovered automatically:

They appear in /plugin list with the [remote] tag
They are executed on the server (not downloaded locally by default)
Local and remote plugins coexist without conflict

Sunbelt Computer Software

PL/B Language Development and Support

Get started

Documentation

Plugin System

For Users: Managing Plugins

List installed plugins

Install a plugin

View plugin details

Uninstall a plugin

Reload plugins

For Developers: Creating a Plugin

The plugin contract

Example: “Hello World” Plugin in Go

Compilation and installation

Capability Interfaces (opt-in)

Signature Verification

Trust on first use

Managed keys

Built from source

Install a signed plugin

Publish a signed plugin

Managed keys for organizations

Plugins built from source

Inspect and manage trust

File Permissions

Development Mode

Remote Plugins

Sunbelt Computer Software

PL/B Language Development and Support

​For Users: Managing Plugins

​List installed plugins

​Install a plugin

​View plugin details

​Uninstall a plugin

​Reload plugins

​For Developers: Creating a Plugin

​The plugin contract

​Example: “Hello World” Plugin in Go

​Compilation and installation

​Capability Interfaces (opt-in)

​Signature Verification

Trust on first use

Managed keys

Built from source

​Install a signed plugin

​Publish a signed plugin

​Managed keys for organizations

​Plugins built from source

​Inspect and manage trust

​File Permissions

​Development Mode

​Remote Plugins

For Users: Managing Plugins

List installed plugins

Install a plugin

View plugin details

Uninstall a plugin

Reload plugins

For Developers: Creating a Plugin

The plugin contract

Example: “Hello World” Plugin in Go

Compilation and installation

Capability Interfaces (opt-in)

Signature Verification

Install a signed plugin

Publish a signed plugin

Managed keys for organizations

Plugins built from source

Inspect and manage trust

File Permissions

Development Mode

Remote Plugins