Wirechunk CLI

The Wirechunk CLI (wirechunk) is the official command-line tool for Wirechunk. It provides essential utilities for platform management and is the primary tool for developing Wirechunk extensions.

Installation

npm install -D @wirechunk/cli

Getting Started with Extension Development

The CLI simplifies the extension development workflow by allowing you to run a local instance of the Wirechunk core platform that loads your extension code directly.

Prerequisites

• Node.js: Must be version 24+.
• Docker: Required for running the core development server.

Development Workflow

1. Configure Environment: Ensure you have a .env file with the necessary configuration, including a core database URL (e.g., WIRECHUNK_CORE_DATABASE_URL). You can override the core dev server image with WIRECHUNK_CORE_DEV_SERVER_IMAGE; otherwise the CLI uses the latest.

2. Start the Core Server: Run the development server which spins up a Docker container with the Wirechunk platform. It mounts your current working directory inside the container, allowing hot reload for frontend code as you develop.

   wirechunk ext-dev start-core

   • Adds -d to run in detached mode.
   • Exposes port 8080 (Web) and 9001 (Vite).

3. Create Extension: Register your extension with the platform to generate an ID and configure your environment. If your extension.json enables a database, this command will set up the connection details automatically.

   wirechunk create-extension --dev

Key Commands

Extension Management

• wirechunk create-extension: Register a new extension on the platform.
• wirechunk create-extension-version: Publish a new version of an extension. Uploads configuration and code.

Platform & User Management

• wirechunk bootstrap: Initialize a new platform.
• wirechunk create-user: Create a new user account. Useful for setting up test users or initial admins.
• wirechunk edit-admin: Grant or revoke admin privileges for a user on a platform.

Development Utilities (ext-dev)

• wirechunk ext-dev start-core: Starts the local Docker-based development server.
• wirechunk ext-dev init-db: Initializes a development database for an extension.
• wirechunk ext-dev get-db-url: writes DATABASE_URL to .env.local (or .env.<env-mode>.local) with the extension’s development database connection string.

Utility

• wirechunk version: Prints the CLI version.

Configuration

The CLI automatically loads environment variables from .env and .env.local files in your current directory.

You can specify a custom environment mode using the --env-mode flag:

wirechunk --env-mode test create-user ...

This will load variables from .env.test and .env.test.local in addition to the standard files.