NEWO CLI

NEWO CLI - Sync NEWO AI Agent skills between the NEWO platform and your local development environment. Supports multi-customer workspaces, Git-first workflows, and comprehensive project management.

Mirror NEWO "Project → Agent → Flow → Skills" structure to local files with:

• 🔄 Two-way synchronization - Pull from NEWO, push local changes back
• 🏢 Multi-customer support - Work with multiple NEWO accounts simultaneously
• 📁 Multi-project workspaces - Manage multiple projects in organized folder structure
• 🔐 Secure authentication - API key-based auth with automatic token refresh
• ⚡ Change detection - SHA256-based efficient sync of only modified files
• 🧠 AI skill formats - Support for .guidance (AI prompts) and .jinja (NSL templates)
• 📊 Knowledge base import - Bulk import AKB articles from structured text files
• 🔧 CI/CD ready - GitHub Actions integration for automated deployments

Quick Start

Installation

Option 1: Global Installation (Recommended)

npm install -g newo

Option 2: Local Project Installation

npm install newo

Option 3: Development from Source

git clone https://github.com/sabbah13/newo-cli.git
cd newo-cli
npm install && npm run build

Basic Setup

1. Get your NEWO API key from app.newo.ai → Integrations → API Integration → Create Connector
2. Configure environment:

   cp .env.example .env
   # Edit .env with your API key

3. Start syncing:

   newo pull    # Download all projects
   newo push    # Upload changes back
   newo status  # See what's modified

Configuration

Single Customer Setup

For working with one NEWO account:

# .env file
NEWO_API_KEY=your_api_key_here
NEWO_PROJECT_ID=project_uuid_here  # Optional: specific project only

Multi-Customer Setup

Work with multiple NEWO accounts simultaneously using three flexible approaches:

Method 1: JSON Array (Recommended)

# .env file
NEWO_API_KEYS=["api_key_customer_1", "api_key_customer_2", "api_key_customer_3"]
NEWO_DEFAULT_CUSTOMER=NEWO_ABC123  # Optional: set after first pull

Method 2: JSON Array with Project IDs

# .env file
NEWO_API_KEYS=[
  {"key":"api_key_1","project_id":"project_uuid_1"},
  {"key":"api_key_2","project_id":"project_uuid_2"},
  {"key":"api_key_3"}
]

Method 3: Individual Environment Variables

# .env file
NEWO_CUSTOMER_ACME_API_KEY=acme_api_key_here
NEWO_CUSTOMER_BETA_API_KEY=beta_api_key_here
NEWO_CUSTOMER_GAMMA_API_KEY=gamma_api_key_here

Getting Your NEWO API Keys

1. Login to app.newo.ai
2. Navigate to Integrations page
3. Find API Integration in the list
4. Create a new Connector
5. Copy the API key (format: 458663bd41f2d1...)

Advanced Configuration

# .env file
NEWO_BASE_URL=https://app.newo.ai          # NEWO platform URL
NEWO_DEFAULT_CUSTOMER=NEWO_ABC123          # Default customer for operations
NEWO_ACCESS_TOKEN=direct_access_token      # Alternative to API key
NEWO_REFRESH_TOKEN=refresh_token_here      # For token refresh
NEWO_REFRESH_URL=custom_refresh_endpoint   # Custom refresh endpoint

Commands

Core Commands

Multi-Customer Commands

# List all configured customers
newo list-customers

# Pull projects from specific customer
newo pull --customer=NEWO_ABC123

# Push changes to specific customer
newo push --customer=NEWO_XYZ789

# Work with default customer (all projects)
newo pull    # Uses default or prompts for selection
newo push    # Pushes to appropriate customers based on file origin

Command Options

• --customer=<customer_idn> - Target specific customer
• --project=<project_uuid> - Target specific project
• --verbose / -v - Detailed output with debugging info
• --help / -h - Show command help

Project Structure

File Organization

Multi-Customer Workspace

newo_customers/                         # Root folder for all customers
├── NEWO_ABC123/                        # Customer folder (auto-detected IDN)
│   └── projects/                       # Customer's projects
│       ├── flows.yaml                  # Customer's flows export
│       └── ProjectAlpha/               # Individual project folder
│           ├── metadata.json           # Project metadata
│           ├── agent_support/          # Agent folder
│           │   ├── flow_onboarding/    # Flow folder
│           │   │   ├── skill_welcome.guidance  # AI prompt skill
│           │   │   └── skill_setup.jinja       # NSL template skill
│           │   └── flow_help/
│           │       └── skill_faq.guidance
│           └── agent_sales/
│               └── flow_demo/
│                   └── skill_pitch.jinja
├── NEWO_XYZ789/                        # Another customer
│   └── projects/
│       ├── flows.yaml
│       └── ProjectBeta/
│           └── ...
└── .newo/                              # CLI state directory (hidden)
    ├── NEWO_ABC123/                    # Customer-specific state
    │   ├── map.json                    # NEWO ID mappings
    │   └── hashes.json                 # Change detection hashes
    ├── NEWO_XYZ789/
    │   ├── map.json
    │   └── hashes.json
    └── tokens.json                     # Authentication tokens

File Types

• .guidance - AI prompt skills (natural language instructions)
• .jinja - NSL template skills (Jinja2 templating with NEWO extensions)
• metadata.json - Project info (title, description, version, team)
• flows.yaml - Complete project structure export for external tools

Customer & Project Identification

• Customer IDN: Auto-detected from API response (e.g., NEWO_ABC123)
• Project folders: Named as {CustomerIDN}_{ProjectIDN} for clarity
• Change tracking: SHA256 hashes prevent unnecessary uploads
• Automatic mapping: .newo/map.json maintains NEWO platform relationships

Key Features

🏢 Multi-Customer Support

• Multiple NEWO accounts - Work with different customers/organizations
• Flexible configuration - JSON arrays, individual env vars, or mixed approaches
• Customer isolation - Separate authentication and project spaces
• Auto-detection - Customer IDNs automatically resolved from API responses
• Default customer - Set preferred customer for streamlined workflows

📁 Multi-Project Management

• Workspace organization - All accessible projects in structured folders
• Project metadata - Complete project info with metadata.json
• Selective sync - Target specific projects or sync everything
• Project structure export - flows.yaml for external tooling integration
• Cross-project operations - Commands work across entire workspace

🔄 Intelligent Synchronization

• Two-way sync - Pull from NEWO platform, push local changes back
• Change detection - SHA256 hashing prevents unnecessary uploads
• Incremental sync - Only modified files are transferred
• Conflict resolution - Safe handling of concurrent changes
• Batch operations - Efficient bulk file processing

🔐 Enterprise Security

• API key authentication - Secure token-based authentication
• Automatic token refresh - Seamless session management
• Multi-customer isolation - Separate auth contexts per customer
• Environment protection - Secure credential management
• Audit logging - Comprehensive operation tracking

🛠️ Developer Experience

• TypeScript implementation - Full type safety and IDE support
• Comprehensive testing - 500+ test cases with 90%+ coverage
• Error handling - User-friendly messages with troubleshooting
• Verbose debugging - Detailed logging with --verbose flag
• CI/CD integration - GitHub Actions workflows included
• Cross-platform - Windows, macOS, Linux support

Robustness & Error Handling

NEWO CLI v1.5.1+ includes comprehensive error handling and validation:

User-Friendly Error Messages

• Authentication Errors: Clear guidance when API keys are invalid or missing
• Network Issues: Helpful tips for connection problems and timeouts
• Configuration Errors: Step-by-step setup instructions for common issues
• File System Errors: Actionable guidance for permission and path problems

Verbose Debugging

Use the --verbose or -v flag with any command for detailed technical information:

npx newo pull --verbose     # Detailed pull operation logs
npx newo push -v           # Verbose push with full error context

Enhanced Validation

• API Key Validation: Format and length validation with specific error messages
• Token Security: Automatic sanitization of sensitive data in logs
• Network Timeouts: 30-second request timeouts with proper error handling
• Input Validation: Comprehensive validation for all user inputs and configuration

Troubleshooting Tips

When errors occur, NEWO CLI provides:

• 🔍 Problem diagnosis with specific error categories
• 💡 Solution suggestions for common configuration issues
• 📋 Step-by-step guidance for resolving authentication and network problems
• 🔧 Configuration validation to ensure proper setup

CI/CD Integration

Single Customer CI/CD

# .github/workflows/deploy.yml
name: Deploy NEWO Skills
on:
  push:
    branches: [ main ]
    paths:
      - 'projects/**/*.guidance'
      - 'projects/**/*.jinja'

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npm run build && node ./dist/cli.js push
        env:
          NEWO_BASE_URL: https://app.newo.ai
          NEWO_API_KEY: ${{ secrets.NEWO_API_KEY }}
          NEWO_PROJECT_ID: ${{ secrets.NEWO_PROJECT_ID }}  # Optional

Multi-Customer CI/CD

# .github/workflows/deploy-multi.yml
name: Deploy Multi-Customer NEWO Skills
on:
  push:
    branches: [ main ]
    paths:
      - 'projects/**/*.guidance'
      - 'projects/**/*.jinja'

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npm run build && node ./dist/cli.js push
        env:
          NEWO_BASE_URL: https://app.newo.ai
          # Multi-customer API keys as JSON array
          NEWO_API_KEYS: ${{ secrets.NEWO_API_KEYS }}
          # Example: '["customer1_api_key", "customer2_api_key"]'
          
          # Or individual customer keys
          NEWO_CUSTOMER_ACME_API_KEY: ${{ secrets.NEWO_CUSTOMER_ACME_API_KEY }}
          NEWO_CUSTOMER_BETA_API_KEY: ${{ secrets.NEWO_CUSTOMER_BETA_API_KEY }}
          
          # Optional default customer
          NEWO_DEFAULT_CUSTOMER: ${{ secrets.NEWO_DEFAULT_CUSTOMER }}

GitHub Secrets Setup

Add these secrets to your repository:

Single Customer:

• NEWO_API_KEY - Your NEWO API key
• NEWO_PROJECT_ID - (Optional) Specific project UUID

Multi-Customer:

• NEWO_API_KEYS - JSON array: ["key1", "key2", "key3"]
• NEWO_CUSTOMER_<IDN>_API_KEY - Individual customer keys
• NEWO_DEFAULT_CUSTOMER - (Optional) Default customer IDN

Advanced CI/CD Workflows

# Customer-specific deployment
- name: Deploy to specific customer
  run: node ./dist/cli.js push --customer=NEWO_ABC123

# Verbose deployment with logging
- name: Deploy with detailed logs
  run: node ./dist/cli.js push --verbose

# Pull before push (sync workflow)
- name: Sync and deploy
  run: |
    node ./dist/cli.js pull
    node ./dist/cli.js push

AKB Import

Import knowledge base articles from structured text files into NEWO personas:

npx newo import-akb akb.txt da4550db-2b95-4500-91ff-fb4b60fe7be9

AKB File Format

---
# r001
## Category / Subcategory / Description
## Summary description of the category
## Keywords; separated; by; semicolons

<Category type="Category Name">
Item Name: $Price [Modifiers: modifier1, modifier2]
Another Item: $Price [Modifiers: modifier3]
</Category>
---

Each article will be imported with:

• topic_name: The descriptive category title
• source: The article ID (e.g., "r001")
• topic_summary: The full category content with pricing
• topic_facts: Array containing category, summary, and keywords
• confidence: 100
• labels: ["rag_context"]

Use --verbose flag to see detailed import progress.

Examples

Basic Usage

# Single customer workflow
newo pull                    # Download all accessible projects
newo status                  # See what files are modified
newo push                    # Upload changes back to NEWO

# Multi-customer workflow
newo list-customers          # See configured customers
newo pull --customer=ACME    # Pull from specific customer
newo push --customer=BETA    # Push to specific customer

Working with Projects

# Pull specific project
newo pull --project=b78188ba-0df0-46a8-8713-f0d7cff0a06e

# Get project metadata
newo meta --project=b78188ba-0df0-46a8-8713-f0d7cff0a06e

# Verbose operations for debugging
newo pull --verbose
newo push --verbose --customer=ACME

Knowledge Base Import

# Import AKB articles from structured text file
newo import-akb articles.txt da4550db-2b95-4500-91ff-fb4b60fe7be9

# With verbose output
newo import-akb articles.txt persona_id --verbose

Development

Prerequisites

• Node.js 18+ - For runtime environment
• TypeScript 5.6+ - For type safety and compilation
• Git - For version control and CI/CD integration

Development Setup

# Clone repository
git clone https://github.com/sabbah13/newo-cli.git
cd newo-cli

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run development commands
npm run dev pull    # Build and run pull
npm run dev push    # Build and run push

Development Commands

Project Architecture

src/
├── cli.ts              # Main CLI entry point
├── api.ts              # NEWO API client
├── auth.ts             # Authentication management
├── customer.ts         # Multi-customer configuration
├── customerAsync.ts    # Async customer operations
├── sync.ts             # Project synchronization
├── akb.ts              # Knowledge base import
├── types.ts            # TypeScript definitions
└── fsutil.ts           # File system utilities

test/
├── auth.test.js        # Authentication tests
├── customer.test.js    # Multi-customer tests
├── sync.test.js        # Sync operation tests
├── api.test.js         # API client tests
└── integration.test.js # End-to-end tests

Testing

NEWO CLI includes comprehensive test coverage:

• 500+ test cases covering all major functionality
• 90%+ code coverage with detailed reporting
• Multi-customer scenarios including auth and sync
• Error handling validation for edge cases
• Integration tests for end-to-end workflows

TypeScript Features

• Strict type checking with comprehensive interfaces
• Modern ES2022 target with ESNext modules
• Complete API typing for all NEWO endpoints
• Enhanced IntelliSense support in IDEs
• Automatic compilation with source maps

Contributing

We welcome contributions to NEWO CLI! Here's how to get involved:

Reporting Issues

• Bug reports: Use GitHub Issues
• Feature requests: Describe your use case and proposed solution
• Security issues: Email security@newo.ai for private disclosure

Development Workflow

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Write tests for new functionality
4. Ensure all tests pass: npm test
5. Commit with clear messages: git commit -m 'feat: add amazing feature'
6. Push to branch: git push origin feature/amazing-feature
7. Create a Pull Request

Code Standards

• TypeScript for all source code
• Comprehensive tests for new features
• JSDoc comments for public APIs
• Semantic versioning for releases
• Conventional commits for clear history

API Reference

NEWO CLI integrates with these NEWO platform endpoints:

Authentication

• POST /api/v1/auth/api-key/token - Exchange API key for access tokens

Project Management

• GET /api/v1/designer/projects - List all accessible projects
• GET /api/v1/designer/projects/by-id/{projectId} - Get project metadata
• GET /api/v1/bff/agents/list?project_id=... - List project agents

Skills & Flows

• GET /api/v1/designer/flows/{flowId}/skills - List skills in flow
• GET /api/v1/designer/skills/{skillId} - Get skill content
• PUT /api/v1/designer/flows/skills/{skillId} - Update skill content
• GET /api/v1/designer/flows/{flowId}/events - List flow events
• GET /api/v1/designer/flows/{flowId}/states - List flow states

Knowledge Base

• POST /api/v1/akb/append-manual - Import AKB articles to persona

License

MIT License - see LICENSE file for details.

Support

• 📖 Documentation: GitHub Repository
• 🐛 Bug Reports: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 📧 Email: support@newo.ai

Built with ❤️ by the NEWO team