npm package: @nextsummer33/toolbox-cli
Description: CLI for scaffolding, building, and publishing Toolbox mini-apps
Latest version: 1.0.0

# @nextsummer33/toolbox-cli

CLI for scaffolding, building, and publishing [Toolbox](https://github.com/nextsummer33/toolbox) mini-apps.

## Installation

```bash
npm install -g @nextsummer33/toolbox-cli
# or
bun add -g @nextsummer33/toolbox-cli
```

## Quick Start

```bash
# 1. Scaffold a new app
toolbox init

# 2. Develop your app
cd my-app
npm run dev

# 3. Package it
toolbox build

# 4. Publish to your Toolbox instance
toolbox publish --host http://localhost:3001 --api-key <token>
```

---

## Commands

### `toolbox init`

Interactive wizard that scaffolds a new mini-app project.

```bash
toolbox init [--template <react|vue|vanilla>]
```

**What it does:**

1. Prompts for app name, ID (reverse-domain), description, and template
2. Creates a project directory with the selected template
3. Generates a `toolbox.json` manifest pre-filled with your answers

```
🧰 Toolbox — Create Mini-App
│
◆ App name: My Dashboard
◆ App ID: com.myname.dashboard
◆ Short description: A custom analytics dashboard
◆ Template: ⚛️  React + Vite + TypeScript
◆ Output directory: ./
│
◇ Done!
│
│  Next steps
│  cd dashboard
│  toolbox build
│  toolbox publish --host http://localhost:3001 --api-key <token>
│
└ Happy building! 🛠️
```

**Templates:**

| Template | Stack |
|----------|-------|
| `react` (default) | React + Vite + TypeScript |
| `vue` | Vue 3 + Vite |
| `vanilla` | Plain HTML + JavaScript |

---

### `toolbox build`

Packages your mini-app into a distributable `.zip` file.

```bash
toolbox build [--out <dir>]
```

- Reads `toolbox.json` for the app ID and version
- Zips the project directory (excluding `node_modules`, `.git`, `.env`, etc.)
- Outputs `<app-id>-v<version>.zip` in the current directory

```
🔨 Toolbox — Build Mini-App
◇ Built → com.myname.dashboard-v1.0.0.zip
└ Ready to publish: toolbox publish --host <url> -k <token> -f com.myname.dashboard-v1.0.0.zip
```

---

### `toolbox publish`

Uploads a built `.zip` to a running Toolbox instance.

```bash
toolbox publish --host <url> --api-key <key> [--file <path>]
```

| Option | Required | Description |
|--------|----------|-------------|
| `-h, --host <url>` | ✅ | Base URL of the Toolbox instance |
| `-k, --api-key <key>` | ✅ | Admin Bearer token for authentication |
| `-f, --file <path>` | — | Path to the ZIP file (default: `dist.zip`) |

```
🚀 Toolbox — Publish Mini-App
◐ Publishing...
◇ Published!
│
│  App Published
│  Name: My Dashboard
│  ID: com.myname.dashboard
│  Version: 1.0.0
│
└ ✓ Successfully published to http://localhost:3001
```

---

## The `toolbox.json` Manifest

Every mini-app needs a `toolbox.json` in its root. `toolbox init` generates one for you:

```json
{
  "id": "com.myname.dashboard",
  "name": "My Dashboard",
  "version": "1.0.0",
  "description": "A custom analytics dashboard",
  "iconUrl": "/icon.png",
  "startUrl": "/",
  "permissions": [],
  "features": {
    "offline": false,
    "resizable": true
  }
}
```

**Available permissions:** `network`, `localStorage`, `hubStorage`

> 💡 You can also create manifests visually in **Admin Hub → Manifest Editor**.

---

## Related Packages

| Package | Description |
|---------|-------------|
| [`@nextsummer33/toolbox-sdk`](https://www.npmjs.com/package/@nextsummer33/toolbox-sdk) | TypeScript types for `window.Toolbox` — gives your mini-app autocompletion |
| [`@nextsummer33/toolbox-ui-kit`](https://www.npmjs.com/package/@nextsummer33/toolbox-ui-kit) | Shared UI component library (98+ components) |

## License

MIT