npm package: @juuno-sdk/cli
Description: Official CLI for Juuno external app development - simulator, deployment, and tools
Author: Juuno
Latest version: 1.0.11

# Juuno CLI

Official CLI for Juuno external app development - simulator, deployment, and tools.

## What This Does

The App Simulator loads your external app and displays it in a split-screen view:

- **Left**: Player view (how your app appears on screens)
- **Right**: Configuration UI (your app's settings interface)

This simulates the real Juuno platform environment using import maps, just like production.

## Installation

```bash
npm install --save-dev @juuno-sdk/cli
```

## Commands

### Development: Unified Dev Command (Recommended)

The easiest way to develop your app - just run one command from your app directory:

```bash
cd my-juuno-app
npx juuno-cli dev
```

This automatically:

1. Detects your app structure (Vite config, package.json)
2. Starts the Vite dev server with HMR (Hot Module Replacement)
3. Launches the simulator pointing to the dev server

**Output:**

```text
🔍 Detecting app structure...

  Package manager: pnpm
  Vite config:     found
  Dev server:      http://localhost:3000

🚀 Starting Vite dev server...
⏳ Waiting for Vite dev server...
✅ Vite dev server ready at http://localhost:3000

🎮 Starting simulator...
🌍 Simulator: http://localhost:5004
```

### Manual Mode: Point to External URL

If you prefer to manage the build and server yourself:

```bash
# Point to your dev server
npx juuno-cli dev --app http://localhost:3000
```

### Authentication

Login once to authenticate with Juuno. Your token will be saved and reused automatically.

```bash
# Login (one-time setup)
npx juuno-cli login

# Check authentication status
npx juuno-cli whoami

# Logout when needed
npx juuno-cli logout
```

### Deployment

Deploy your app to Juuno.

```bash
# Deploy (uses saved credentials from login)
npx juuno-cli deploy

# Specify build directory
npx juuno-cli deploy --build-dir ./build
```

### List Apps

View all your deployed apps.

```bash
# List all apps (uses saved credentials)
npx juuno-cli list
```

### App Info

Get detailed information about a specific app.

```bash
# Show app details (uses saved credentials)
npx juuno-cli info app_abc123
```

### npm Scripts

Add to your `package.json`:

```json
{
  "scripts": {
    "dev": "juuno-cli dev",
    "build": "vite build",
    "deploy": "juuno-cli deploy"
  }
}
```

Then run:

```bash
# One-time setup: Login to Juuno
npx juuno-cli login

# Start development (one command does everything!)
npm run dev

# Deploy to production
npm run build
npm run deploy
```

## How It Works

1. **Your App**: Served by Vite dev server (e.g., `localhost:3000`) with HMR
2. **Simulator**: Loads at `localhost:5004`
3. **Import Maps**: Simulator loads your app via ES module import
4. **HMR**: Vite's Hot Module Replacement provides instant updates without full page reloads

## Requirements

Your app must:

- Export ES modules
- Provide player and config components
- Use `@juuno/vite-plugin-app-dev` for development:

  ```js
  // vite.config.ts
  import { defineConfig } from 'vite';
  import vue from '@vitejs/plugin-vue';
  import { juunoAppDev } from '@juuno/vite-plugin-app-dev';

  export default {
    plugins: [
      vue(),
      juunoAppDev(), // Enables dev server entry point routing
    ],
    build: {
      lib: {
        entry: {
          player: './src/player/index.ts',
          config: './src/config/index.ts',
        },
        formats: ['es'],
      },
      rollupOptions: {
        external: ['vue', '@juuno-sdk/app-sdk'],
      },
    },
  };
  ```

## Development Workflow

### Recommended: Unified Dev Command

The simplest workflow - one command handles everything:

```bash
cd my-juuno-app
npx juuno-cli dev
```

**Development Flow:**

1. Edit your app's source code
2. Vite's HMR instantly updates the browser (no full page reload!)
3. See changes reflected in the simulator immediately

### Alternative: Manual Mode

If you prefer more control, you can point the simulator to your own dev server:

```bash
# Start your own dev server
cd my-juuno-app
npm run dev  # or: npx vite

# In another terminal, start the simulator pointing to your server
npx juuno-cli dev --app http://localhost:3000
```

**Note:** For the best experience, use `@juuno/vite-plugin-app-dev` in your Vite config to enable proper entry point routing during development.

## CLI Options

### Dev Command

```bash
juuno-cli dev [options]

# Unified mode (recommended) - run from your app directory:
juuno-cli dev

# Manual mode - point to external URL:
juuno-cli dev --app <url>

Options:
  --app <url>           URL of external app (omit for unified mode)
  --port <number>       Port for simulator (default: 5004)
  --serve-port <number> Port for Vite dev server in unified mode (default: 3000)
  --help                Show help
```

### Login Command

```bash
juuno-cli login [options]

Options:
  --email <email>   Your Juuno email (will prompt if not provided)
  --password <pwd>  Your Juuno password (will prompt if not provided)
  --help            Show help
```

Saves credentials to `~/.juuno/credentials.json` for automatic reuse.

### Logout Command

```bash
juuno-cli logout
```

Removes stored credentials from `~/.juuno/credentials.json`.

### Whoami Command

```bash
juuno-cli whoami
```

Shows current authentication status.

### Deploy Command

```bash
juuno-cli deploy [options]

Options:
  --build-dir <dir> Build directory to deploy (default: ./dist)
  --token <token>   Override with specific token (for CI/CD)
  --email <email>   Login with email instead of using saved credentials
  --password <pwd>  Use with --email
  --help            Show help
```

### List Command

```bash
juuno-cli list [options]

Options:
  --token <token>   Override with specific token (for CI/CD)
  --email <email>   Login with email instead of using saved credentials
  --password <pwd>  Use with --email
  --help            Show help
```

### Info Command

```bash
juuno-cli info <app-id> [options]

Arguments:
  <app-id>          The app ID to get information about

Options:
  --token <token>   Override with specific token (for CI/CD)
  --email <email>   Login with email instead of using saved credentials
  --password <pwd>  Use with --email
  --help            Show help
```

## Environment Variables

```bash
# API endpoint (defaults to production)
export JUUNO_API_URL=https://api.juuno.co

# For staging
export JUUNO_API_URL=https://api.stage.juuno.co

# Authentication token (for CI/CD, overrides saved credentials)
export JUUNO_API_TOKEN=your-auth-token
```

## Deployment Workflow

### Quick Start

```bash
# 1. Login once
npx juuno-cli login

# 2. Build and deploy
npm run build
npx juuno-cli deploy

# Deploy again anytime (no re-authentication needed)
npm run build
npx juuno-cli deploy
```

### Complete Flow

1. **Login**: Authenticate once with `juuno-cli login`
2. **Build**: Run your build command to generate the dist bundle
3. **Deploy**: Use `juuno-cli deploy` - automatically uses saved credentials
4. **Success**: Your app is deployed and ready to use

The CLI saves your authentication token to `~/.juuno/credentials.json` and reuses it automatically for subsequent commands.

## Authentication

### Primary Method: Login Command (Recommended)

```bash
# Login once
npx juuno-cli login

# All subsequent commands use saved credentials
npx juuno-cli deploy
npx juuno-cli list
npx juuno-cli info app_abc123

# Check login status
npx juuno-cli whoami

# Logout when needed
npx juuno-cli logout
```

### Alternative Methods

**For CI/CD (environment variable):**

```bash
export JUUNO_API_TOKEN=your-auth-token
npx juuno-cli deploy
```

**One-off commands (email/password):**

```bash
npx juuno-cli deploy --email user@example.com --password yourpassword
```

**Explicit token override:**

```bash
npx juuno-cli deploy --token your-auth-token
```

### Authentication Priority

The CLI checks for credentials in this order:

1. `--token` flag (explicit override)
2. `JUUNO_API_TOKEN` environment variable (CI/CD)
3. Saved credentials from `~/.juuno/credentials.json` (from `juuno-cli login`)
4. `--email` and `--password` flags (one-off login)
5. Error: "Not logged in"

## Troubleshooting

### CORS Errors

If you see CORS errors, your dev server needs to enable CORS:

```js
// vite.config.ts
export default {
  server: {
    cors: true,
  },
};
```

### Module Not Found

Ensure your app exports the required components:

```ts
// src/index.ts
export { MyAppSlide } from './MyAppSlide.vue';
export { MyAppConfig } from './MyAppConfig.vue';
export { defaultMeta } from './settings';
```

### Import Map Issues

The simulator uses import maps to load dependencies. If you see import errors, check that your app properly externalizes `vue` and `@juuno-sdk/app-sdk`.

### Authentication Errors

If you get authentication errors:

1. Run `juuno-cli login` to authenticate
2. Check login status with `juuno-cli whoami`
3. Verify your email and password are correct
4. Check that you have developer access to your Juuno account
5. Ensure `JUUNO_API_URL` points to the correct environment (if using staging)
6. If credentials are corrupted, run `juuno-cli logout` then `juuno-cli login` again

## Example

See [@juuno-sdk/app-sdk-example](../app-sdk-example) for a complete working example.

## Related Packages

- **@juuno-sdk/app-sdk**: SDK for building external apps
- **@juuno-sdk/app-sdk-example**: Example external app demonstrating the workflow

## Package Exports

The CLI provides both programmatic and command-line interfaces:

- **CLI Commands**: `juuno-cli login`, `juuno-cli logout`, `juuno-cli whoami`, `juuno-cli dev`, `juuno-cli deploy`, `juuno-cli list`, `juuno-cli info`
- **Programmatic API**: Import functions for custom workflows

```typescript
import { deployApp, login, logout } from '@juuno-sdk/cli';

// Login and save credentials
await login({
  email: 'user@example.com',
  password: 'yourpassword',
});

// Deploy (uses saved credentials automatically)
await deployApp({
  buildDir: './dist',
});

// Or override with specific token
await deployApp({
  buildDir: './dist',
  token: process.env.JUUNO_API_TOKEN,
});
```

## Development

See [DEVELOPMENT.md](./DEVELOPMENT.md) for local development, building, and publishing guidelines.