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

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:

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:

🔍 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:

# 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.

# 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.

# 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.

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

App Info

Get detailed information about a specific app.

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

npm Scripts

Add to your package.json:

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

Then run:

# 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:

  // 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:

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:

# 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

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

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

juuno-cli logout

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

Whoami Command

juuno-cli whoami

Shows current authentication status.

Deploy Command

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

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

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

# 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

# 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)

# 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):

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

One-off commands (email/password):

npx juuno-cli deploy --email [email protected] --password yourpassword

Explicit token override:

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:

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

Module Not Found

Ensure your app exports the required components:

// 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 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

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

// Login and save credentials
await login({
  email: '[email protected]',
  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 for local development, building, and publishing guidelines.