@dcyfr/ai-cli

A portable, cross-platform command-line interface for DCYFR AI framework - supported on Windows, macOS, and Linux.

This is a standalone CLI tool extracted from the dcyfr-ai-nodejs starter template, designed to be lightweight, portable, and easy to use across all operating systems.

✨ Features

• 🖥️ Cross-Platform - Works seamlessly on Windows, macOS, and Linux
• 🚀 Portable - Single binary/package installation
• 🤖 DCYFR AI Integration - Full framework support with validation and telemetry
• 📘 TypeScript Strict Mode - Full type safety with strict compiler options
• ⚡ Modern Node.js - ESM modules, Node.js 20+
• 🔧 Developer Experience - Hot reload, source maps, path aliases
• 📊 Structured Logging - JSON-based logging with multiple levels
• ✅ Code Quality - ESLint, Prettier, strict validation

🚀 Quick Start

Prerequisites

• Node.js ≥ 20.0.0
• npm ≥ 10.0.0

Installation

npm (Global)

npm install -g @dcyfr/ai-cli
dcyfr --help

npm (Project)

npm install @dcyfr/ai-cli
npx dcyfr --help

Manual from Source

git clone https://github.com/dcyfr/dcyfr-ai-cli.git
cd dcyfr-ai-cli
npm install
npm run build
npm link  # Install globally (optional)
dcyfr --help

Platform-Specific Notes

Windows

# Global installation (PowerShell as Administrator)
npm install -g @dcyfr/ai-cli

# Or use in your project
npm install @dcyfr/ai-cli
npx dcyfr status

macOS

# Global installation
npm install -g @dcyfr/ai-cli

# Or use in your project
npm install @dcyfr/ai-cli
npx dcyfr status

Linux

# Global installation
npm install -g @dcyfr/ai-cli

# Or use in your project
npm install @dcyfr/ai-cli
npx dcyfr status

📖 Usage

Available Commands

dcyfr status      # Show framework status
dcyfr validate    # Run validation checks
dcyfr telemetry   # Show telemetry configuration
dcyfr init        # Show initialization help
dcyfr --help      # Show all commands
dcyfr --version   # Show version

Examples

Check Framework Status

$ dcyfr status

🚀 DCYFR AI Framework Status

Validation: ✅ Enabled
Telemetry:  ✅ Enabled

Node Version: v22.10.0
Platform:     darwin (arm64)
Memory:       45MB / 256MB

Run Validation Checks

$ dcyfr validate

🔍 Running Validation Checks

Mode: Enabled
Parallel: Yes

✅ Validation framework initialized
✅ Configuration loaded
✅ System checks passed

Show Telemetry Info

$ dcyfr telemetry

📊 Telemetry Configuration

Status:  ✅ Enabled
Storage: file
Path:    .dcyfr/telemetry

⚙️ Configuration

The CLI looks for configuration in the following order (first found is used):

1. .dcyfr.json in current directory
2. config.json in current directory
3. config.json in config directory:
   • Windows: %APPDATA%\.dcyfr\
   • macOS/Linux: ~/.dcyfr/

Example Configuration

{
  "telemetry": {
    "enabled": true,
    "level": "info",
    "endpoints": [
      {
        "type": "console",
        "level": "info"
      }
    ]
  },
  "validation": {
    "enabled": true,
    "strict": true
  },
  "cli": {
    "verboseLogging": false,
    "colorOutput": true
  }
}

🔧 Development

Build from Source

# Install dependencies
npm install

# Build TypeScript
npm run build

# Watch mode
npm run build:watch

# Development
npm run dev

Testing & Linting

# Run tests
npm test

# Watch mode
npm run test:watch

# Coverage
npm run test:coverage

# Lint
npm run lint
npm run lint:fix

# Format code
npm run format

🗂️ Project Structure

src/
├── cli.ts              # Main CLI entry point
├── commands/           # Command implementations
│   ├── status.ts       # Status command
│   ├── validate.ts     # Validation command
│   ├── telemetry.ts    # Telemetry command
│   └── init.ts         # Initialization command
└── lib/
    ├── logger.ts       # Logging utilities
    └── config.ts       # Configuration loading (cross-platform)

🔄 Cross-Platform Compatibility

This CLI is specifically designed for cross-platform support:

• Path Handling: Uses Node.js path module for proper OS path handling
• Home Directory: Uses os.homedir() for platform-specific home directory resolution
• Config Locations: Different config directories for Windows, macOS, and Linux
• Executable Wrapper: Proper shebang (#!/usr/bin/env node) for Unix-like systems and npm bin wrapper for Windows
• Environment Variables: Respects platform-specific env vars (e.g., APPDATA on Windows)

📚 Documentation

• AGENTS.md - AI agent guidance and patterns
• CONTRIBUTING.md - Contribution guidelines
• LICENSE - MIT License

🐛 Troubleshooting

Command not found on macOS/Linux

If dcyfr is not found after global installation:

# Check npm global path
npm config get prefix

# Add to PATH if needed
export PATH="$(npm config get prefix)/bin:$PATH"

# Add to ~/.bashrc or ~/.zshrc permanently:
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.bashrc

PowerShell execution policy on Windows

If you get execution policy errors on Windows PowerShell:

# Use cmd or npm scripts instead
npm install @dcyfr/ai-cli
npx dcyfr status

# Or set execution policy (use with caution)
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Configuration not found

Check configuration paths:

# Windows
echo %APPDATA%

# macOS/Linux
echo ~

# Then verify config file exists in: ~/.dcyfr/config.json
# Or in current directory: .dcyfr.json

🤝 Contributing

See CONTRIBUTING.md for contribution guidelines.

📄 License

MIT - See LICENSE for details.

🔗 Related

• DCYFR AI Framework
• Node.js Starter Template
• DCYFR Labs

---

Built with ❤️ by DCYFR