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@latest

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 (or auto multi-customer)
newo pull    # Uses default customer OR pulls from all customers if no default set
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

Makefile Commands

The project includes a comprehensive Makefile for streamlined development:

Quick Commands

make help           # Show all available commands
make setup          # Initial project setup
make build          # Build TypeScript
make test           # Run tests
make dev            # Development mode
make publish        # Publish to GitHub and NPM

Development Workflow

make fresh-start    # Clean + install + build + test
make dev-pull       # Test pull command in development
make dev-push       # Test push command in development
make test-local     # Comprehensive local testing

Publishing Workflow

make pre-publish    # Complete validation before publishing
make publish-github # Publish to GitHub with release
make publish-npm    # Publish to NPM
make publish        # Publish to both platforms

Quality Assurance

make typecheck      # TypeScript type checking
make lint           # Code linting
make check-all      # All quality checks
make deps-audit     # Security audit

Local Testing

After making changes to the CLI code, proper testing is essential to ensure functionality works correctly.

Quick Testing Commands

# Build and test core functionality
npm run build                                    # Compile TypeScript
node ./dist/cli.js --help                       # Test CLI loads correctly
node ./dist/cli.js list-customers                # Test customer configuration

# Test single customer operations
node ./dist/cli.js pull --customer=CUSTOMER_IDN  # Test specific customer pull
node ./dist/cli.js status --customer=CUSTOMER_IDN # Test specific customer status

# Test multi-customer operations (if multiple API keys configured)
node ./dist/cli.js pull                          # Test auto multi-customer pull
node ./dist/cli.js pull --verbose                # Test with detailed logging

Complete Testing Workflow

1. Environment Setup

   # Ensure clean environment
   cp .env.example .env
   # Edit .env with your API key(s)

2. Build & Syntax Check

   npm run build              # Must complete without TypeScript errors
   npm run typecheck          # Verify type safety

3. Basic CLI Tests

   node ./dist/cli.js --help                    # Should show updated help text
   node ./dist/cli.js list-customers            # Should show configured customers

4. Authentication Tests

   # Test API key exchange and token generation
   node ./dist/cli.js meta --verbose            # Forces authentication

5. Pull Operation Tests

   # Single customer (if specific customer configured)
   node ./dist/cli.js pull --customer=YOUR_CUSTOMER_IDN --verbose
   
   # Multi-customer (if multiple API keys configured)
   node ./dist/cli.js pull --verbose            # Should pull from all customers
   
   # Check file structure was created correctly
   ls -la newo_customers/                       # Should show customer folders

6. Status & Push Tests

   node ./dist/cli.js status --verbose          # Should show no changes initially
   
   # Make a test change to a .guidance or .jinja file
   echo "# Test comment" >> newo_customers/*/projects/*/*/*/*.guidance
   
   node ./dist/cli.js status                    # Should detect the change
   node ./dist/cli.js push --verbose            # Should upload the change

Testing Multi-Customer Functionality

If you have multiple API keys configured, test the new auto-pull behavior:

# Test that pull works without specifying customer
node ./dist/cli.js pull                          # Should pull from ALL customers

# Test individual customer selection still works
node ./dist/cli.js pull --customer=CUSTOMER_A    # Should pull from specific customer
node ./dist/cli.js push --customer=CUSTOMER_B    # Should push to specific customer

Common Testing Issues & Solutions

Issue: "Multiple customers configured but no default specified" error

• Cause: You're using npx newo instead of the local build
• Solution: Use node ./dist/cli.js instead of npx newo

Issue: Changes not reflected in CLI behavior

• Cause: TypeScript not compiled or using cached version
• Solution: Run npm run build first, then test with node ./dist/cli.js

Issue: Authentication errors during testing

• Cause: Invalid API keys or network issues
• Solution: Verify API keys in .env, test with --verbose flag for details

Issue: File permission errors

• Cause: Insufficient permissions in project directory
• Solution: Ensure write permissions: chmod 755 . and check disk space

Performance Testing

For testing with large projects or multiple customers:

# Test with timeout to avoid hanging
timeout 30s node ./dist/cli.js pull --verbose   # Should complete or show progress

# Test memory usage
node --max-old-space-size=512 ./dist/cli.js pull # Test with limited memory

Integration Testing

Test complete workflows that users would actually perform:

# Complete development workflow
node ./dist/cli.js pull                          # Download latest
# Edit some .guidance/.jinja files
node ./dist/cli.js status                        # Check changes
node ./dist/cli.js push                          # Upload changes

# Multi-customer workflow
node ./dist/cli.js list-customers                # See available customers
node ./dist/cli.js pull --customer=CUSTOMER_A    # Work with specific customer
# Make changes
node ./dist/cli.js push --customer=CUSTOMER_A    # Push to specific customer

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

Publishing & Release Management

The project includes automated scripts for publishing to GitHub and NPM with proper validation and release management.

Prerequisites for Publishing

1. GitHub Setup

   # Ensure GitHub remote is configured
   git remote -v  # Should show origin pointing to sabbah13/newo-cli
   
   # Install GitHub CLI (optional, for automatic releases)
   brew install gh  # macOS
   # or
   sudo apt install gh  # Ubuntu

2. NPM Setup

   # Login to NPM
   npm login
   npm whoami  # Verify you're logged in

Publishing Workflow

Option 1: Full Automated Publishing (Recommended)

# Complete validation and publish to both platforms
make publish

This command will:

• Run all tests and quality checks
• Build the project
• Prompt for version bump (patch/minor/major)
• Publish to GitHub with release notes
• Publish to NPM with proper tags
• Verify publication success

Option 2: Step-by-Step Publishing

# 1. Validate everything is ready
make pre-publish

# 2. Publish to GitHub first
make publish-github

# 3. Publish to NPM
make publish-npm

Option 3: Manual Publishing

# Run individual scripts
./scripts/publish-github.sh
./scripts/publish-npm.sh

Version Management

Use semantic versioning with the Makefile helpers:

make version-patch  # 1.5.2 → 1.5.3 (bug fixes)
make version-minor  # 1.5.2 → 1.6.0 (new features)
make version-major  # 1.5.2 → 2.0.0 (breaking changes)

Pre-Release Publishing

For beta/alpha releases:

# Set pre-release version manually
npm version 1.6.0-beta.1 --no-git-tag-version

# Publish with beta tag
make publish-npm  # Automatically detects pre-release and uses beta tag

Publishing Checklist

Before publishing, ensure:

• ✅ All tests pass (make test)
• ✅ TypeScript compiles without errors (make build)
• ✅ Local testing completed (make test-local)
• ✅ Documentation is up to date
• ✅ CHANGELOG.md is updated (if exists)
• ✅ Version number is appropriate
• ✅ No uncommitted changes (or committed)

Automated Validation

The publish scripts include comprehensive validation:

• TypeScript compilation and type checking
• Test suite execution with coverage requirements
• Package size analysis and content verification
• Authentication verification for GitHub and NPM
• Version conflict detection to prevent duplicate publishes
• Security audit of dependencies

GitHub Release Features

The GitHub publish script automatically:

• Creates semantic version tags (v1.5.3)
• Generates comprehensive release notes
• Marks releases as "latest" on GitHub
• Links to NPM package and documentation
• Includes installation instructions

NPM Package Features

The NPM publish script ensures:

• Proper package.json validation
• Binary CLI availability verification
• File inclusion/exclusion validation
• Pre-release tag detection (beta, alpha, rc)
• Post-publish verification

Rollback Procedures

If issues are discovered after publishing:

NPM Rollback:

# Deprecate problematic version
npm deprecate newo@1.5.3 "Version has known issues, use 1.5.2 instead"

# Publish fixed version immediately
make version-patch
make publish-npm

GitHub Rollback:

# Delete tag and release (if needed)
git tag -d v1.5.3
git push origin :refs/tags/v1.5.3
gh release delete v1.5.3

Monitoring Post-Publication

After publishing, monitor:

• NPM downloads: https://npmjs.com/package/newo
• GitHub releases: https://github.com/sabbah13/newo-cli/releases
• Issue reports: https://github.com/sabbah13/newo-cli/issues
• Badge updates: README badges should reflect new version

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