PROCIA CLI

A minimalist AI assistant CLI powered by PROCIA, featuring interactive chat, plan execution, and comprehensive tool integration.

🚀 Quick Start

Global Installation

npm install -g @procia/cli

First-time Setup

After installation, run the setup commands:

# Basic setup (uses pre-configured cloud database)
procia setup show

# Optional: Custom database setup
procia setup database

# Optional: Custom authentication setup  
procia setup auth

# Optional: Custom server endpoints
procia setup server

Start Using

# Start the interactive CLI
procia

# Or use specific commands
procia --help

🎯 Features

• Interactive Chat Mode: Natural language conversations with AI
• Command Mode: Structured command execution
• Plan Execution: Multi-step automated workflows
• Tool Integration: Access to external tools and APIs
• Cloud Database: Pre-configured PostgreSQL backend
• Secure Authentication: JWT-based authentication system
• 🎯 Minimalist: Simple, focused interface without complex configuration

Installation

From Source

# Clone the repository
git clone <repository-url>
cd winu-cli/packages/winu-cli

# Install dependencies
npm install

# Build the project
npm run build

# Link for global usage (optional)
npm link

MCP servers backend

npm run start:multi-tool:dev   # connect to port 3020 has multiple tools (ssh , bash , etc)

npm run start:workflows:dev   # assistant endpoint and workflow tools 

Kubernetes server

npx kubernetes-mcp-server --port 3008

GRAFANA

docker run --rm -p 8020:8000 \
  -e GRAFANA_URL=https://grafana-xcloud.winu.fr/ \
  -e GRAFANA_API_KEY=glsa_f9oXmlnbrWu16nPvjcaPItVcQixecusF_f2d68ff1 \
  -e GRAFANA_DASHBOARD_UID=rYdddlPWk \
  -e GRAFANA_DATASOURCE_UID=rYdddlPWk \
  -e PROMETHEUS_DATASOURCE_UID=f5d84164-20f6-4b02-8e09-5c0c9d116b00 \
  mcp/grafana -t streamable-http

GITLAB

dotenv -e .env -- npx -y @zereight/mcp-gitlab --port 3007

Usage

Interactive Mode

Start in Command Mode (default):

winu

The CLI starts in Command Mode where you can:

• Execute installation plans with /plan commands
• Get help with /help
• Switch to Chat Mode with /chat

Interface Modes

Command Mode (Default)

• Purpose: Execute specific commands and plans
• Commands:
  • /plan <plan_name> - Execute plan in auto mode
  • /plan <plan_name> -mode interactive - Execute with user confirmations
  • /plan <plan_name> -mode semi_assisted - Execute with step confirmations
  • /plan <plan_name> -step_id <step> - Execute specific step
  • /plan <plan_name> -step_id <step> -phase <phase> - Execute specific phase
  • /chat - Switch to Chat Mode
  • /help - Show available commands

Chat Mode

• Purpose: Conversational AI interactions
• Features: Ask questions, get coding help, workflow assistance
• Commands:
  • /exit-chat - Return to Command Mode
  • /help - Show chat-specific help
  • All plan execution commands also work in Chat Mode

Headless Mode

Process a single prompt and exit:

winu -p "What is the weather like today?"

Command Line Options

winu [options]

Options:
  -p, --prompt <prompt>    process a single prompt and exit (headless mode)
  -h, --help               display help for command

Architecture Overview

System Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        WINU CLI                                 │
├─────────────────────────────────────────────────────────────────┤
│  ┌─────────────┐    ┌──────────────┐    ┌─────────────────────┐ │
│  │ index.ts    │────│ winu-agent   │────│ winu-client         │ │
│  │ Commander   │    │ chat handeler│    │  Axios Backend      │ │
│  │ Entry Point │    │ Plan Exec    │    │ Communication      │ │
│  └─────────────┘    │ History Mgmt │    └─────────────────────┘ │
│                     └──────────────┘                │
│                            │                        │           │
│  ┌─────────────────────────▼────────────────────────▼─────────┐ │
│  │                  React + Ink UI                            │ │
│  │                                                            │ │
│  │  ┌─────────────────┐                ┌─────────────────────┐ │ │
│  │  │ Command Mode    │                │ Chat Mode           │ │ │
│  │  │                 │                │                     │ │ │
│  │  │ ┌─────────────┐ │                │ ┌─────────────────┐ │ │ │
│  │  │ │Plan Execute │ │                │ │AI Conversation  │ │ │ │
│  │  │ │Components   │ │                │ │Interface        │ │ │ │
│  │  │ └─────────────┘ │                │ └─────────────────┘ │ │ │
│  │  └─────────────────┘                └─────────────────────┘ │ │
│  └─────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
                                   │
                                   ▼
              ┌─────────────────────────────────────┐
              │         WINU BACKEND                │
              │                                     │
              │  ┌─────────────────────────────────┐│
              │  │ POST /winu-cli Endpoint         ││
              │  │                                 ││
              │  │ ┌─────────────┐ ┌─────────────┐ ││
              │  │ │ MCP Server  │ │ AI Assistant│ ││
              │  │ │ Integration │ │ Processing  │ ││
              │  │ └─────────────┘ └─────────────┘ ││
              │  └─────────────────────────────────┘│
              └─────────────────────────────────────┘

Plan Execution Architecture

User Input: /plan install_kube -mode interactive -step_id os.bootstrap
     │
     ▼
┌─────────────────────────────────────────────────────────────────┐
│                   Command Parser                                │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐ │
│  │ Parse Args  │─▶│ Validate    │─▶│ Extract Parameters      │ │
│  │ • plan_name │  │ • mode      │  │ • plan: install_kube    │ │
│  │ • mode      │  │ • step_id   │  │ • mode: interactive     │ │
│  │ • step_id   │  │ • phase     │  │ • step_id: os.bootstrap │ │
│  └─────────────┘  └─────────────┘  └─────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
     │
     ▼
┌─────────────────────────────────────────────────────────────────┐
│                     Agent Layer                                 │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │ executePlan() → Backend Call                                │ │
│  │                                                             │ │
│  │ Response: {status, response, tool_calls, reasoning}         │ │
│  └─────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
     │
     ▼
┌────────────────────────────────────────────────────────────────┐
│                 Plan Execution UI                              │
│                                                                │
│  Mode: Interactive                                             │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐ │
│  │ 1. Confirmation │─▶│ 2. Live Results │─▶│ 3. Step Summary│ │
│  │                 │  │                 │  │                 │ │
│  │ Show step info  │  │ Phase execution │  │ Success/failure │ │
│  │ [Continue]/[Abort] │  │ Real-time logs  │  │ Next step ready│ 
│  └─────────────────┘  └─────────────────┘  └─────────────────┘ │
└────────────────────────────────────────────────────────────────┘

Configuration

The CLI is pre-configured to connect to http://localhost:3006 - no additional configuration needed.

Backend Integration

This CLI connects to the Winu backend's AI assistant endpoint:

• Endpoint: POST /winu-cli
• Default URL: http://localhost:3006
• Response Format: The backend returns structured responses with {status, response, tool_calls, reasoning}
• MCP Integration: Backend integrates with Model Context Protocol (MCP) servers for enhanced capabilities

Make sure your Winu backend server is running before using the CLI.

Keyboard Shortcuts

Command Mode & Chat Mode

• Enter: Send command/message
• Ctrl+C: Exit application
• ↑/↓: Navigate command history
• ←/→: Move cursor within input
• Backspace: Delete character

Plan Execution

• Enter: Confirm plan execution steps
• ←/→: Select options (Continue/Abort) during confirmations
• Space: Continue through phase results and step summaries

Development

Scripts

• npm run dev - Run in development mode with tsx
• npm run build - Build TypeScript to JavaScript
• npm run start - Run the built application
• npm run lint - Run ESLint
• npm run typecheck - Run TypeScript type checking

Project Structure

src/
├── index.ts                     # Main CLI entry point with Commander.js
├── client/                      # HTTP client for backend communication
│   └── winu-client.ts          # Axios-based HTTP client for Winu backend
├── agent/                       # Agent wrapper layer
│   └── winu-agent.ts           # Agent with plan execution and history management
├── ui/                          # React + Ink TUI components
│   ├── app.tsx                 # Main app entry point
│   └── components/             # UI components
│       ├── interface-router.tsx      # Routes between Command and Chat modes
│       ├── command-interface.tsx     # Command mode interface with plan execution
│       ├── chat-interface.tsx        # Chat mode interface
│       ├── plan-execution/           # Plan execution UI components
│       │   ├── confirmation-prompt.tsx    # Pre-execution confirmations
│       │   ├── execution-results.tsx      # Phase result displays
│       │   └── step-summary.tsx           # Step completion summaries
│       └── loading-spinner.js        # Loading states
├── hooks/                       # Custom React hooks
│   ├── use-input-handler.ts    # Input handling with mode support
│   ├── use-plan-execution.ts   # Plan execution state management
│   └── use-input-history.ts    # Command history navigation
└── utils/                       # Utility functions
    └── command-parser.ts       # Parse /plan commands and help system

Technical Implementation

• Dual Interface Architecture: Separate Command and Chat modes with interface routing
• Plan Execution System: Interactive, semi-assisted, and auto execution modes with real-time confirmations
• React + Ink: Terminal UI framework with optimized memoization to prevent re-renders
• State Management: Dedicated hooks for plan execution state and command history

Examples

Command Mode (Default)

$ winu
🖥️  Command Mode
Type /help for commands, /chat to enter chat mode

winu> /plan install_min4 -step_id os.bootstrap -phase prechecks
🚀 Plan Execution: install_docker
📋 Step: system.setup
🎯 Target: localhost

Phase: prechecks
✅ Docker not installed - OK to proceed
✅ System requirements met
✅ Network connectivity verified

Action: [Continue] [Abort]

Chat Mode

$ winu
🖥️  Command Mode

winu> /chat
💬 Chat Mode

Tips for getting started:
1. Ask questions about anything
2. Request help with coding tasks  
3. Get workflow assistance
4. /exit-chat to return to command mode

❯ How do I troubleshoot Docker installation issues?

Plan Execution Modes

# Auto mode - no confirmations
winu> /plan install_docker

# Interactive mode - confirm each phase
winu> /plan install_docker -mode interactive

# Semi-assisted mode - confirm each step
winu> /plan install_docker -mode semi_assisted

# Execute specific step
winu> /plan install_docker -step_id system.setup

# Execute specific phase
winu> /plan install_docker -step_id system.setup -phase prechecks