PepperDash Toolkit

A VS Code extension for managing Crestron systems running PepperDash Essentials. Track and update package versions against live GitHub releases, deploy files to Crestron processors and touch panels over SSH, and build release bundles — all from one sidebar panel.

Ships with the public PepperDash org configured out of the box. Private orgs and any GitHub Enterprise sources are added manually via the Sources panel — once added, they persist in your VS Code user settings across restarts and updates.

🎥 Watch the demo video — a quick walkthrough of the extension in action.

Contents

• PepperDash Toolkit
  • Contents
  • Quick Start
  • Track & update package versions
  • Manage GitHub sources
  • Deploy to a processor or touch panel
  • Build a release bundle
  • Reference
    • Requirements
    • Installation from a VSIX
    • Settings
  • License

Quick Start

1. Install the extension from the Marketplace — open the Extensions view (Cmd+Shift+X / Ctrl+Shift+X), search PepperDash Toolkit, click Install.

2. Open a workspace containing a *configurationFile*.json (e.g. a PepperDash super-project folder). The extension activates automatically.

3. Click the PepperDash Toolkit icon in the Activity Bar to open its sidebar.

   

4. From the sidebar's welcome screen, click Open System Config Folder and pick your system's folder. This picks up any *configurationFile*.json (opens the Versions tab) and deploy.json (opens the System Deployments / Bundle tabs) found in the folder or its subfolders.

   

   The folder picker recognizes a super-project's per-system layout:

   

5. The panel opens beside the editor with three tabs: Versions, System Deployments, and Bundle.

   

The first time you need authenticated GitHub access, you'll be prompted to sign in — see Requirements for details.

Track & update package versions

The Versions tab reads the versions block of your *configurationFile*.json and groups entries into four sections: Essentials (core framework), Packages (plugins), User Interfaces, and Touchpanel Wrapper.

Each card shows the entry's Name (click to rename inline), Package ID, current Version with a badge for the latest GitHub release, and a clickable Repo link.

Check for updates:

• Click Check on a single card, or Check all in the toolbar to fetch latest releases for every entry in parallel.

Apply an update:

• Click Update → <tag> on a card (see epi-lg-display above), or Update all in the toolbar to apply every available update in one edit.
• The JSON file goes dirty in the editor — save with Ctrl+S / Cmd+S to persist. Nothing writes to disk until you save.

Add a new package or UI entry:

1. Click Add package / Add UI.
2. Choose Search or Paste URL (any GitHub repo URL).

In Search mode, check every configured source you want to search — they're listed in priority order (PepperDash's own orgs first, then any other sources you've added) and run in parallel. Type a query and press Enter or click Search. Results from every checked source are merged into one deduped list; a repo that shows up under more than one source displays a small badge per source. If a checked source actually fails (auth/network), it's called out just below the query field — a source simply having no matches is not treated as an error. Your checked-source selection is remembered (per user, across workspaces) so you don't have to re-check them every time.

Set the Essentials / Touchpanel Wrapper core version:

• Click Essentials or Touchpanel Wrapper in the Core section header to pick a release, including pre-releases.

  

Compare against a live processor:

• Click Fetch from processor in the toolbar to connect to a Crestron processor and diff its installed package manifest against the file. Changes are grouped and badged New / Changed / Unchanged — click Apply to update the JSON in one edit.

  

Other toolbar actions: Restore (revert to last saved state), Open / Save, Reload (re-read from disk), Log (open the output channel to see every GitHub API call), and Sources (see below).

All writes go through WorkspaceEdit — the JSON file goes dirty in the editor and you save explicitly. No surprise disk writes.

Opening a config file with no versions block (predates version tracking): the extension asks whether to Use this file or Create packages.json. Use this file doesn't add an empty versions object up front — it's written automatically the first time you add an entry, and the tab shows a hint until then:

Dismissing the prompt leaves the file untouched and asks again next time.

Opening a system folder missing a *configurationFile*.json or deploy.json: a target is required for both the Versions and Deploy tabs, so neither keeps showing a stale, previously-opened system's data. Each missing file shows a modal prompt to Create packages.json / Create deploy.json; declining cancels opening the folder.

Manage GitHub sources

Toggle the Sources panel from the Versions toolbar to manage the GitHub sources used when searching for packages, and see live authentication status per host.

• Add source / edit / delete — each source has a label, host, org, and kind (public, private, or onprem).
• Authentication status per host:
  • github.com — Sign in with GitHub opens the VS Code account flow; sign out via the VS Code Accounts menu.
  • GitHub Enterprise hosts — Set personal access token prompts for a PAT (stored in secret storage); Clear token removes it.
  • Public-only hosts show a Public access only badge with an option to sign in for private-repo access.
• Re-check — re-runs the auth check for a host.

Deploy to a processor or touch panel

The System Deployments tab handles SSH-based file deployment, backed by a per-workspace deploy.json (separate from configurationFile.json).

1. Set the super-project root — browse to your super-project's root folder. This anchors every mapping's local-root path and is also required by the Bundle tab.

2. Add a device — click Add device, choose Processor or Touch Panel. Click the device name to rename it inline; collapse the card body with the chevron to keep the panel tidy. On a touch panel card, click the clone icon to create a copy directly below it with the same credentials and file mappings, then adjust the differing path(s) — 1Password vault/item UUIDs carry over fully; manual (session-only) passwords are never stored and must be re-entered. Not yet available for processors.

   

   

3. Set credentials — 1Password (Vault UUID + Item UUID; host IP read from the item's saved URLs; requires the op CLI) or Manual (session only) (prompted each time, nothing stored). The SSH Port field defaults to 22 and applies to both sources; it is saved in deploy.json as credential.port (omitted at 22). Entering host:port in the manual Host field — or a port in the 1Password item URL — is also honored, with the explicit SSH Port field taking precedence.

4. Test connection — click Test connection to verify SSH access before deploying; a "Connected" badge confirms success.

5. Configure file mappings — each mapping has a pattern (glob), a local root folder, and a remote directory. .cpz/.lpz patterns auto-expand to include supporting files (config JSON, plugins, IR files, mobile control zips) with correct remote paths for the chosen program slot. Click a mapping row to edit it, or use the upload icon to deploy just that mapping.

6. Deploy — click Deploy all to push every mapping for the device in order, streaming progress to the log panel below the card.

   

Build a release bundle

The Bundle tab builds release artifacts for a system into the super-project root's output folder (set on the System Deployments tab).

Four artifact types, each independently selectable:

1. Solution — Solution ID and name; auto-detected from packages.json at the project root when present, or entered manually (required for System bundles).

2. Version — a X.Y.Z version string plus an optional suffix (e.g. RC1).

3. Output folder — relative to the super-project root; artifacts land in <output>/bundles/, <output>/assets/, and <output>/cpz/.

4. Preview — shows the exact file tree each selected artifact will contain before building.

   

5. Build bundles — runs the bundle, streaming progress (staging, zipping, done/error) to the log below.

Reference

Requirements

• VS Code ^1.90.0
• GitHub authentication — no gh CLI required:
  • github.com sources use VS Code's built-in GitHub sign-in (prompted the first time you need authenticated access, or triggered manually from the Sources panel).
  • GitHub Enterprise (on-prem) sources use a personal access token, stored in VS Code's encrypted secret storage via the Sources panel or the PepperDash Toolkit: Set GHE PAT command.
• 1Password CLI (op) (optional) — required only if you use 1Password as your deploy credential source.

Installation from a VSIX

For pre-release or local builds instead of the Marketplace:

1. Download the VSIX from the Releases page.
2. Open the Extensions view, click the … menu → Install from VSIX… → select the downloaded file.

# or from the terminal
code --install-extension pepperdash-toolkit-<version>.vsix

To update a VSIX install, install the newer file over the existing one — settings are preserved.

Settings

Default sources:

For a GitHub Enterprise source, use the GHE hostname and "kind": "onprem".

License

MIT