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

Testing: App Simulator

Test your app locally before deployment.

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

# Or point to a deployed URL
npx juuno-cli dev --app https://cdn.example.com/my-app/

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": "vite",
    "build": "vite build",
    "test:player": "juuno-cli dev --app http://localhost:3000",
    "deploy": "juuno-cli deploy"
  }
}

Then run:

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

# Terminal 1: Your app dev server
npm run dev

# Terminal 2: Simulator
npm run test:player

# Deploy to production
npm run build
npm run deploy

How It Works

1. Your App: Runs on your dev server (e.g., localhost:3000)
2. Simulator: Loads at localhost:5004
3. Import Maps: Simulator loads your app via ES module import
4. Live Updates: Changes in your app reflect immediately

Requirements

Your app must:

• Export ES modules
• Provide player and config components
• Build with externalized dependencies:

  // vite.config.ts
  export default {
    build: {
      lib: {
        entry: './src/index.ts',
        formats: ['es'],
        fileName: 'index',
      },
      rollupOptions: {
        external: ['vue', '@juuno-sdk/app-sdk'],
      },
    },
  };

Development Workflow

The simulator works with built app bundles to match the production architecture.

Terminal 1: Auto-rebuild your app

cd my-juuno-app
npm run build:watch
# Watches for changes and rebuilds automatically

Terminal 2: Serve your app bundle

cd my-juuno-app
npx serve dist -l 3000 --cors
# Serves the built bundle at localhost:3000

Terminal 3: Start the simulator

npx juuno-cli dev --app http://localhost:3000/index.js
# → localhost:5004

Development Flow:

1. Edit your app's source code
2. Auto-rebuild happens in background (100-500ms)
3. Manually refresh browser at http://localhost:5004
4. See changes reflected in the simulator

Note: This workflow matches production closely (import maps + static bundles) but doesn't support HMR.

CLI Options

Simulator (dev command)

juuno-cli dev [options]

Options:
  --app <url>       URL of your external app (required)
  --port <number>   Port for simulator (default: 5004)
  --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.