@lanonasis/cli

Version:
Professional CLI for LanOnasis Memory as a Service (MaaS) with MCP support, seamless inline editing, and enterprise-grade security
docs.lanonasis.com
lanonasis/lanonasis-maas
731 lines (538 loc) • 21.7 kB
Markdown
View Raw
# @lanonasis/cli v3.11.0 - Advanced CLI Suite

[![NPM Version](https://img.shields.io/npm/v/@lanonasis/cli)](https://www.npmjs.com/package/@lanonasis/cli)
[![Downloads](https://img.shields.io/npm/dt/@lanonasis/cli)](https://www.npmjs.com/package/@lanonasis/cli)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Golden Contract](https://img.shields.io/badge/Onasis--Core-v0.1%20Compliant-gold)](https://api.lanonasis.com/.well-known/onasis.json)

🎉 **NEW IN v3.11.0**: Expanded command suite with REPL session management (`onasis repl`), service/deployment orchestration commands (`service`, `deploy`, `dashboard`, `api`), and enhanced MCP auto-connect.

## 🚀 Quick Start

### Installation

```bash
# Global installation (recommended)
npm install -g @lanonasis/cli

# Verify installation
lanonasis --version  # or onasis --version
```

### First Steps

```bash
# Interactive guided setup (recommended for new users)
onasis guide

# Quick manual setup
onasis init                                      # Initialize configuration
onasis login --vendor-key <your-vendor-key>      # Authenticate with vendor key
onasis health                                   # Verify system health

# Create your first memory
onasis memory create --title "Welcome" --content "My first memory"
```

## 🔍 Secret Prescan (v3.10.1+)

Scan files and directories for secrets and PII before MIRA context extraction. Reports are value-stripped — no raw secrets ever appear in output.

```bash
# Scan a directory tree
lanonasis prescan run ./src

# Save a local report for `prescan status`
lanonasis prescan run ./src --save

# CI-friendly gate (exit codes: 0=safe 1=flagged 2=quarantined)
lanonasis prescan run ./src --ci --fail-on flagged

# Show the latest saved local report
lanonasis prescan status
```

**Machine-parseable output** for piping and CI integration:
```
---PRESCAN SUMMARY---
total_files:42
safe:40
flagged:1
quarantined:1
total_detections:3
report_path:/Users/example/.lanonasis/security/prescan/report-2026-06-12T00-00-00-000Z.json
---QUARANTINED FILES---
QUARANTINED:src/config/prod.ts
```

**No authentication required** — runs entirely locally.

## ✨ Professional CLI UX (v3.9.0+)

### Seamless Inline Text Editing
No more external editor dependencies! Create and update memories with a professional inline text editor:

```bash
# Create memory with inline multi-line editor
onasis memory create --inline
# Type your content directly in the terminal
# Use arrow keys to navigate, Enter for new lines
# Ctrl+D to save, Ctrl+C to cancel

# Update existing memory
onasis memory update <id> --inline
# Your existing content is preserved and editable
```

**Features**:
- ✨ Multi-line editing with visual feedback
- 🎯 Line numbers and cursor indicators
- ⌨️ Full keyboard navigation (arrows, backspace, etc.)
- 💾 Auto-preserves existing content when updating
- 🚫 No external editor configuration needed

### Intelligent MCP Connection
Automatic MCP server discovery and configuration:

```bash
# Connect to local MCP server (auto-configured)
onasis mcp connect --local
# Server path detected automatically
# Configuration persisted for next time

# Check connection status
onasis mcp status
```

**Features**:
- 🔍 Auto-detects embedded MCP server
- 💾 Saves configuration automatically
- 🔄 Health monitoring and auto-reconnection
- ✅ Connection verification before operations
- 🛠️ Clear error messages with fix suggestions

### First-Run Onboarding
Interactive setup for new users:

```bash
onasis init
# Guided setup walks you through:
# - API configuration
# - Connectivity testing
# - Input mode preferences
# - Troubleshooting if needed
```

**Features**:
- 📋 Step-by-step guided setup
- 🧪 Automatic connectivity tests
- ⚙️ Smart default configuration
- 💡 Context-aware troubleshooting
- 📖 Interactive help and tips

## 🤖 Claude Desktop Integration

For instant Claude Desktop MCP integration with OAuth2 authentication, see our [Claude Desktop Setup Guide](./CLAUDE_DESKTOP_SETUP.md).

**Quick Links**:
- **Authorization Endpoint**: `https://auth.lanonasis.com/oauth/authorize`
- **Client ID**: `claude-desktop`
- **Scopes**: `mcp:full memories:read memories:write`

The guide includes complete OAuth2 configuration, available MCP tools, and troubleshooting steps.

## 🎯 Command Aliases

The CLI supports multiple command aliases for different use cases:

| Command     | Purpose                             | Golden Contract |
| ----------- | ----------------------------------- | --------------- |
| `onasis`    | Golden Contract compliant interface | ✅ Yes          |
| `lanonasis` | Standard LanOnasis interface        | ✅ Yes          |
| `memory`    | Memory-focused operations           | ✅ Yes          |
| `maas`      | Memory as a Service operations      | ✅ Yes          |

```bash
# All of these are equivalent:
onasis memory list
lanonasis memory list
memory list
maas memory list
```

## 🔐 Security & Authentication

### Enterprise-Grade API Key Handling

The CLI uses secure local storage and sends credentials in the expected wire format:

- ✅ **Encrypted At Rest**: Vendor keys are stored in encrypted local storage (keytar when available, encrypted file fallback otherwise).
- ✅ **Correct On-Wire Format**: Vendor key auth sends the raw vendor key in `X-API-Key` over HTTPS.
- ✅ **Single Server-Side Hash Validation**: The API validates keys with server-side hashing and does not require client-side hashing.
- ✅ **Token-First Sessions**: OAuth/JWT sessions use `Authorization: Bearer <token>` and refresh automatically before expiry.

### Authentication Methods

> Transport note: for memory commands, keep `manualEndpointOverrides=false` so requests route through `https://api.lanonasis.com`.

### 1. Vendor Key Authentication (Recommended)

Best for API integrations and automation. Copy the vendor key value exactly as shown in your LanOnasis dashboard (keys may vary in format):

```bash
# Full option
onasis auth login --vendor-key <your-vendor-key>

# Short form (for scripts and CI/CD)
onasis auth login -k <your-vendor-key>
```

### 2. OAuth Browser Authentication

Secure browser-based authentication for MCP integration:

```bash
onasis login --oauth
```

> **Note**: OAuth authentication enables MCP integration features (real-time updates, WebSocket connections). For direct CLI memory commands (`memory list`, `memory create`, etc.), use vendor key or credentials authentication.

### 3. Interactive Credentials

Traditional username/password authentication:

```bash
onasis login  # Will prompt for email and password
```

### Authentication Status & Profile

```bash
onasis auth status    # Check current authentication (probes live memory API access)
onasis auth logout    # Logout from current session
onasis whoami         # Display full authenticated user profile
```

`auth status` now performs a live end-to-end check:
1. Validates the local credential (vendor key probe hits a real protected endpoint, not `/health`)
2. Fetches and displays your user profile from `GET /v1/auth/me`
3. Issues a real memory list request to confirm API access is working
4. Warns if manual endpoint overrides are active

`onasis whoami` displays:
- Email address and display name
- Role (admin, user, authenticated)
- Plan tier (free, pro, enterprise)
- OAuth provider (if applicable)
- Project scope
- Last login time

**Auth Login Options:**
| Short | Long | Description |
|-------|------|-------------|
| `-k` | `--vendor-key <key>` | Authenticate with vendor key (non-interactive) |
| `-e` | `--email <email>` | Email for credentials login |
| `-p` | `--password <pass>` | Password for credentials login |

## 💻 Shell Completions

### Installation Guide

```bash
onasis completion  # Shows installation instructions for all shells
```

### Direct Installation

```bash
# Bash
echo 'source <(onasis --completion bash)' >> ~/.bashrc

# Zsh
echo 'source <(onasis --completion zsh)' >> ~/.zshrc

# Fish
echo 'onasis --completion fish | source' >> ~/.config/fish/config.fish
```

### Features

- ✅ Command and subcommand completion
- ✅ Option and flag completion
- ✅ Context-aware suggestions
- ✅ Dynamic completion data via JSON API
- ✅ Support for all command aliases

## 📚 Core Commands

### System Management

```bash
onasis health           # Comprehensive system health check
onasis status          # Quick status overview
onasis whoami          # Display authenticated user profile (email, role, plan, provider)
onasis init            # Initialize CLI configuration
onasis guide           # Interactive setup guide
onasis quickstart      # Essential commands reference
```

### Memory Management

```bash
# List memories
onasis memory list                        # or: onasis memory ls
onasis memory list --type context --limit 20

# Create memories (non-interactive)
onasis memory create -t "Project Notes" -c "Important information"
onasis memory create -t "Reference" --type reference --tags "docs,api"

# Create memory via JSON payload
onasis memory create --json '{"title":"Design decisions","type":"project","content":"Summary...","tags":["architecture","design"]}'

# Create memory from a file
onasis memory create -t "Session notes" --content-file ./notes.md

# Create memories (interactive)
onasis memory create -i                   # Interactive mode with inline editor
onasis memory create                      # Prompts for missing fields

# Search memories
onasis memory search "api integration"
onasis memory search "meeting notes" --type context
onasis memory search "gateway parity" --no-fallback --json
onasis memory search "gateway parity" --ci
onasis memory search "gateway parity" --fail-on-fallback

# Memory operations
onasis memory get <id>                    # Get specific memory
onasis memory update <id> -t "New Title"  # Update title
onasis memory update <id> -i              # Interactive update
onasis memory delete <id>                 # Delete memory
onasis memory stats                       # Memory statistics
```

#### `onasis memory save-session`

Save the current CLI session context (CWD + git branch/status + changed files) as a memory entry so you can persist what you worked on and pick it up later.

- `--test-summary`: Stores a human-readable test result summary (e.g., `Vitest: 53 passed, 1 skipped`) in the saved session memory.
- `--title`: Sets the memory title (default: `Session summary`).
- `--type`: Sets the memory type (default: `project`).
- `--tags`: Comma-separated tags for session metadata (default: `session,cli`).

**Examples**
```bash
onasis memory save-session --test-summary "Vitest: 53 passed, 1 skipped"
onasis memory save-session --title "API client fixes" --type project --tags "session,cli,testing"
```

See **Session management** below for related commands.

#### Session management

Sessions are stored as memory entries (tagged `session,cli` by default). Related commands:

```bash
onasis memory save-session
onasis memory list-sessions
onasis memory load-session <id>
onasis memory delete-session <id>
```

**Create/Update Options:**
| Short | Long | Description |
|-------|------|-------------|
| `-t` | `--title` | Memory title |
| `-c` | `--content` | Memory content |
| `-i` | `--interactive` | Interactive mode |
| | `--type` | Memory type (context, project, knowledge, etc.) |
| | `--tags` | Comma-separated tags |
| | `--json` | JSON payload (title, content, type/memory_type, tags, topic_id) |
| | `--content-file` | Read content from a file |

### Topic Management

```bash
onasis topic list                         # List all topics
onasis topic create --name "Development" --color blue --icon "💻"
onasis topic get <id>                     # Get specific topic
onasis topic update <id> --description "New description"
onasis topic delete <id>                  # Delete topic
```

### API Key Management

```bash
onasis api-keys list                      # List API keys
onasis api-keys create --name "Integration Key" --scope "memory:read"
onasis api-keys revoke <id>               # Revoke API key
onasis api-keys rotate <id>               # Rotate API key
```

### MCP Integration (Enhanced in v2.0.9)

```bash
# Connection Management
onasis mcp status                         # MCP server status with health info
onasis mcp connect --remote              # Connect to remote MCP server
onasis mcp connect --local               # Connect to local MCP server
onasis mcp disconnect                     # Disconnect from MCP
onasis mcp list-servers                   # List all connected servers

# Tool & Resource Management
onasis mcp tools                          # List available MCP tools
onasis mcp resources                      # List MCP resources
onasis mcp call <tool> --args             # Execute MCP tool directly

# Advanced Features (v3.0)
onasis mcp health                         # Detailed health check with latency
onasis mcp server start                   # Start local MCP server
onasis mcp server stop                    # Stop local MCP server
```

### 🆕 MCP Server Mode (v3.0)

Run the CLI as a standalone MCP server:

```bash
# Start MCP server for IDE integrations
lanonasis-mcp-server --verbose

# Use with environment variables
LANONASIS_API_URL=https://api.lanonasis.com \
LANONASIS_TOKEN=your-token \
lanonasis-mcp-server
```

### Configuration Management

```bash
onasis config list                        # List all configuration
onasis config get <key>                   # Get configuration value
onasis config set <key> <value>           # Set configuration value
onasis config reset                       # Reset configuration
```

### Service Management

```bash
onasis service list                       # List all services
onasis service status                     # Service status overview
onasis service restart <service>          # Restart specific service
onasis deploy status                      # Deployment status
onasis deploy health                      # Deployment health check
```

## ⚙️ Global Options

```bash
# Available for all commands
--help              # Show command help
--version           # Show version information
--verbose           # Enable verbose logging
--output <format>   # Output format: table, json, yaml, csv
--api-url <url>     # Override API URL
--no-mcp           # Disable MCP and use direct API
```

## 🎯 Advanced Usage

### JSON Output for Automation

```bash
onasis memory list --output json | jq '.data[].title'
onasis health --output json | jq '.status'
```

### Environment Variables

```bash
export MEMORY_API_URL="https://api.lanonasis.com/api/v1"
export CLI_OUTPUT_FORMAT="json"
export CLI_VERBOSE="true"
```

### Configuration File

Location: `~/.maas/config.json`

```json
{
  "apiUrl": "https://api.lanonasis.com/api/v1",
  "defaultOutputFormat": "table",
  "mcpPreference": "auto",
  "vendorKey": "<your-vendor-key>"
}
```

## 🔧 Development & Debugging

### Verbose Mode

```bash
onasis --verbose memory list    # Detailed operation logs
onasis -V health               # Short flag version
```

### Configuration Debugging

```bash
onasis config list             # Check current configuration
onasis auth status            # Verify authentication
onasis health --verbose       # Detailed health information
```

### MCP Debugging

```bash
onasis mcp status --verbose    # Detailed MCP diagnostics
onasis --no-mcp memory list   # Bypass MCP, use direct API
```

## 🌐 Golden Contract Compliance

### Onasis-Core v0.1 Standards

- ✅ Service discovery via `/.well-known/onasis.json`
- ✅ Vendor key authentication (`pk_*.sk_*` format)
- ✅ Request correlation with UUID tracking
- ✅ Enhanced CORS security compliance
- ✅ Uniform error envelope standardization
- ✅ WebSocket path alignment (`/mcp/ws`)

### Service Discovery Integration

The CLI automatically discovers service endpoints:

```bash
# Service discovery happens automatically
onasis health  # Uses discovered endpoints for health checks
```

### Request Correlation

Every API request includes correlation headers:

- `X-Request-ID`: UUID for request tracking
- `X-Project-Scope`: Project scope validation
- `X-Auth-Method`: Authentication method used

## 🧪 Testing & Quality

### Command Validation

```bash
onasis --help                  # Validate CLI installation
onasis completion              # Test completion system
onasis guide                   # Test interactive guidance
```

### API Integration Testing

```bash
onasis health                  # Test API connectivity
onasis memory list --limit 1  # Test memory service
onasis mcp status             # Test MCP integration
```

## 🚨 Troubleshooting

### Common Issues

#### Authentication Failures

```bash
# Check authentication status
onasis auth status

# Re-authenticate
onasis auth logout
onasis login --vendor-key <your-vendor-key>
```

#### Connection Issues

```bash
# Check system health
onasis health --verbose

# Test API connectivity
onasis --api-url https://api.lanonasis.com/api/v1 health
```

#### MCP Connection Issues

```bash
# Check MCP status
onasis mcp status --verbose

# Disable MCP temporarily
onasis --no-mcp memory list
```

### Debug Mode

```bash
# Enable maximum verbosity
CLI_VERBOSE=true onasis --verbose health
```

## 🤝 Contributing

### Development Setup

```bash
# Clone CLI source
git clone https://github.com/lanonasis/lanonasis-maas.git
cd lanonasis-maas/cli

# Install dependencies
npm install

# Build CLI
npm run build

# Link for local development
npm link
```

### Testing Changes

```bash
# Test build
npm run build

# Test CLI functionality
onasis --help
onasis health
```

## 📝 Version History

### v3.10.1 (Current)

- 🔍 **Secret Prescan**: Local secret/PII scanning before MIRA context extraction
- 🧩 **Lazy Runtime Loading**: Prescan packages load only when prescan commands run
- 📦 **Aligned Release Metadata**: Version displays and package metadata are synchronized
- 📊 **Saved Report Status**: `prescan status` summarizes the latest `prescan run --save`

### v2.0.0

- 🎯 **Interactive Dashboard**: Central command center for all operations
- 🎉 **Welcome Experience**: Guided onboarding for new users
- ⚡ **Power Mode**: Streamlined interface for expert users
- 🤖 **Smart Suggestions**: Context-aware command recommendations
- 🏆 **Achievement System**: Gamification to track progress
- 🛡️ **Enhanced Error Handling**: Intelligent error messages with recovery
- 📊 **Progress Indicators**: Visual feedback for operations

### v1.5.2

- ✅ Golden Contract compliance (Onasis-Core v0.1)
- ✅ Professional shell completions (bash/zsh/fish)
- ✅ Enhanced authentication (vendor keys, OAuth, credentials)
- ✅ Interactive user guidance system
- ✅ Dual command support (lanonasis/onasis)
- ✅ Service discovery integration
- ✅ Request correlation and enhanced security

### Previous Versions

- v1.4.x: Basic CLI functionality
- v1.3.x: MCP integration
- v1.2.x: Memory management
- v1.1.x: Initial authentication
- v1.0.x: Core CLI framework

## 📄 License

MIT License - see [LICENSE](../LICENSE) for details.

## 🔗 Related Links

- **NPM Package**: [https://www.npmjs.com/package/@lanonasis/cli](https://www.npmjs.com/package/@lanonasis/cli)
- **Main Repository**: [https://github.com/lanonasis/lanonasis-maas](https://github.com/lanonasis/lanonasis-maas)
- **Documentation**: [https://docs.lanonasis.com/cli](https://docs.lanonasis.com/cli)
- **API Documentation**: [https://api.lanonasis.com/docs](https://api.lanonasis.com/docs)
- **Service Discovery**: [https://api.lanonasis.com/.well-known/onasis.json](https://api.lanonasis.com/.well-known/onasis.json)
- **Dashboard**: [https://api.lanonasis.com/dashboard](https://api.lanonasis.com/dashboard)

---

_Professional CLI for Enterprise Memory as a Service - Golden Contract Compliant_

## OAuth2 Authentication (v3.5.0+)

### Browser Login with OAuth2 PKCE

The CLI now supports secure OAuth2 authentication with PKCE (Proof Key for Code Exchange) for browser-based login:

```bash
onasis auth login
# Choose: 🌐 Browser Login (Get token from web page)
```

**How it works:**
1. CLI starts a local callback server on port 8888
2. Opens your browser to the OAuth2 authorization page
3. You authenticate in the browser
4. Authorization code is sent back to the CLI
5. CLI exchanges code for access and refresh tokens
6. Tokens are securely stored locally

**Benefits:**
- ✅ More secure (PKCE prevents code interception)
- ✅ Automatic token refresh
- ✅ Revocable access
- ✅ Industry-standard OAuth2 flow

### Authentication Methods

The CLI supports three authentication methods:

1. **🔑 Vendor Key** (Recommended for API access)
   - Long-lived API key from dashboard
   - Best for automation and CI/CD

2. **🌐 Browser Login** (OAuth2 PKCE)
   - Secure browser-based authentication
   - Automatic token refresh
   - Best for interactive use

3. **⚙️ Username/Password** (Direct credentials)
   - Traditional email/password login
   - Returns JWT token
   - Legacy method

### Token Management

OAuth2 tokens are automatically refreshed when expired:

```bash
# Check authentication status
onasis auth status

# Force re-authentication
onasis auth logout
onasis auth login
```

### Troubleshooting

**Port 8888 already in use:**
The CLI needs port 8888 for the OAuth callback. If it's in use, close the application using it or use the Vendor Key method instead.

**Browser doesn't open:**
The CLI will show the authorization URL - copy and paste it into your browser manually.

**Token refresh failed:**
Run `onasis auth login` to re-authenticate.