Platform

Plugins and CLI

Vigilo ships with two extensibility surfaces. The Plugin SDK (WD.9) lets you add custom field types, dashboard widgets, integration adapters, and Celery…

Last updated

Overview

Vigilo ships with two extensibility surfaces. The Plugin SDK (WD.9) lets you add custom field types, dashboard widgets, integration adapters, and Celery tasks without forking the core. The Vigilo CLI (WC.14) is a small Python click app under tools/vigilo_cli/ that talks to the Django API for scripted operations — workspace lifecycle, member invites, audit tail, cert listing, playbook execution, plugin listing.

Plugins register through an in-process registry at app startup; the CLI talks to the same REST API the React app does. Neither requires touching the core codebase.

Plugin SDK

Plugin ABC + PluginRegistry

Every plugin subclasses the abstract base in vigilo_django.plugins.base:

class Plugin(ABC):
    name: str            # globally unique, e.g. "datepicker_with_holidays"
    kind: PluginKind     # see enum below
    version: str         # semver string

    @abstractmethod
    def register(self, registry: PluginRegistry) -> None: ...

PluginKind is an enum with four values:

  • field_type — A custom value/widget pair for CustomField definitions (e.g. a date picker that excludes holidays).
  • dashboard_widget — A reusable tile that can be added to any workspace dashboard.
  • integration_adapter — A Slack/Jira/etc. adapter implementing the integration protocol.
  • celery_task — A periodic task that runs alongside core tasks.

PluginRegistry is a singleton with register_field_type, register_widget, register_adapter, register_task methods. Plugins call these from their register() method.

INSTALLED_PLUGINS setting

Add plugins to Django settings:

INSTALLED_PLUGINS = [
    "myorg.vigilo_plugins.datepicker_with_holidays",
    "myorg.vigilo_plugins.kanban_overview",
]

At Django startup, apps.py for the plugins app iterates this list, imports each module, instantiates the Plugin subclass found there, and calls register() on the global registry. Failures during plugin load log a warning but do not break startup — the plugin simply isn't available.

Example plugins

Two reference plugins live under backend/vigilo_django/plugins/examples/:

  • datepicker_with_holidays — a field_type plugin. Adds a holiday_aware_date field type to CustomField. The widget renders a date picker that disables weekends and dates in a configurable holiday list (per workspace, stored in Workspace.settings['holidays']). Useful for change windows that must avoid stat holidays.
  • kanban_overview — a dashboard_widget plugin. Adds a "Kanban overview" tile that shows count-by-status across changes, incidents, and tasks for the current workspace. Drop it into any dashboard via Settings → Dashboard → Add widget.

Both examples are well-commented and serve as the recommended starting point for your own plugin.

Plugin SDK README

The full developer guide is tools/plugin-sdk/README.md. It covers:

  • Project skeleton (pyproject.toml, entry-point declaration)
  • Each PluginKind's contract and lifecycle
  • How to ship a frontend half (each plugin can include a frontend/ subdir with JS/CSS that the React app loads on startup)
  • Testing helpers (PluginTestHarness)
  • Publishing to PyPI and installing into a Vigilo deployment
  • Compatibility versioning (the registry checks Plugin.compatible_with against VIGILO_VERSION)

Vigilo CLI

The CLI lives under tools/vigilo_cli/. Install it with pip install -e tools/vigilo_cli from a checkout, or pin a release with pip install vigilo-cli. Configure it with vigilo configure — the wizard asks for the API base URL, an API token, and the active workspace slug, then writes ~/.vigilo/config.toml.

Commands (WC.14)

workspace

  • vigilo workspace list — lists every workspace your token has access to, including the platform-admin-only ones if applicable.
  • vigilo workspace create --name "Platform" --slug platform --region us — creates a new workspace. Optional --template flag to stamp from a WorkspaceTemplate.
  • vigilo workspace export --slug acme — dumps a workspace's structural config (settings, policies, playbooks, custom fields) as JSON. Useful for backup, diff, or feeding into the template engine.

member

  • vigilo member invite --email alice@acme.com --role engineer — sends a single invite.
  • vigilo member bulk-invite --csv invites.csv — bulk path. CSV columns: email,role,custom_role_name. Returns a per-row success/failure report.

audit

  • vigilo audit tail — streams the audit log to stdout. Default is the active workspace; --all requires platform_admin. --filter action=change.approve to narrow.
  • vigilo audit verify — runs the hash-chain integrity check (see the audit log article) and reports any breaks.

cert

  • vigilo cert list --expiring-within 30 — lists certs expiring in the next N days. Output is a table; pipe through --json for scripting.

playbook

  • vigilo playbook run <id> — manually triggers a playbook. Optional --dry-run to evaluate steps without executing side effects.

plugin

  • vigilo plugin list — lists every plugin loaded into the connected Vigilo installation, with kind, version, and compatible_with.

Auth

Every CLI call attaches a Bearer token from ~/.vigilo/config.toml. Generate a token from Settings → API tokens → New token in the UI. Tokens carry the issuer's permissions — a Viewer's token cannot run workspace create.

Common workflows

1. Add a custom field type for an industry-specific date format

Build a field_type plugin following the SDK README, list it in INSTALLED_PLUGINS, restart Django. The new type appears as an option in Settings → Custom fields → Type dropdown.

2. Bulk-invite a new team

vigilo member bulk-invite --csv onboarding.csv

Where onboarding.csv is:

email,role,custom_role_name
alice@acme.com,engineer,
bob@acme.com,approver,
carol@acme.com,viewer,

The CLI returns a per-row report and exits non-zero if any row failed.

3. Verify audit integrity on a schedule

vigilo audit verify --all

Wire this into a nightly cron and alert if exit code is non-zero. See the audit log article for what the verify covers.

4. Export a workspace before a risky change

vigilo workspace export --slug acme > acme-backup-$(date +%F).json

The JSON is structurally identical to a WorkspaceTemplate.snapshot and can be restored via the platform templates feature.

Permissions

Plugin loading is a server-config concern — only installation operators (people with shell access to the Django host) can add plugins. CLI commands inherit the permissions of the token they run with: a workspace owner can run workspace export for their workspace but not for a peer workspace.

Troubleshooting

Plugin does not appear in vigilo plugin list. Check the Django startup log for plugin load warnings. Most common cause: the plugin module path in INSTALLED_PLUGINS is wrong or the class does not subclass Plugin.

CLI returns 401 Unauthorized. Token expired or was revoked. Run vigilo configure and paste a fresh token.

vigilo workspace create returns 403. The token holder is not a platform admin. Get the platform admin to run it, or generate a token under a platform-admin account.

Plugin works on my dev machine but not in prod. VIGILO_VERSION differs; the registry refuses to load a plugin whose compatible_with does not match the running version. Bump compatible_with or pin the plugin to the prod version.

Related articles