@wirechunk/cli 0.0.9 → 0.1.1

package/README.md

@@ -0,0 +1,75 @@
+# 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.