@lanonasis/cli v3.9.13 - Auth Refresh Reliability

🎉 NEW IN v3.9.13: JWT/password CLI sessions now refresh through the real auth-gateway OAuth token contract, password login persists refresh metadata correctly, the MCP client no longer uses stale refresh routes, and the bundled @lanonasis/mem-intel-sdk is updated to 2.1.0 for scoped intelligence query support.

🚀 Quick Start

Installation

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

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

First Steps

# 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"

✨ 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:

# 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:

# 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:

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.

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 |

# 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):

# 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:

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:

onasis login  # Will prompt for email and password

Authentication Status & Profile

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

onasis completion  # Shows installation instructions for all shells

Direct Installation

# 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

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

# 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

# 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

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:

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

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

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)

# 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:

# 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

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

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

# 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

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

Environment Variables

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

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

🔧 Development & Debugging

Verbose Mode

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

Configuration Debugging

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

MCP Debugging

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:

# 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

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

API Integration Testing

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

🚨 Troubleshooting

Common Issues

Authentication Failures

# Check authentication status
onasis auth status

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

Connection Issues

# Check system health
onasis health --verbose

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

MCP Connection Issues

# Check MCP status
onasis mcp status --verbose

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

Debug Mode

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

🤝 Contributing

Development Setup

# 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

# Test build
npm run build

# Test CLI functionality
onasis --help
onasis health

📝 Version History

v2.0.0 (Current)

• 🎯 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 for details.

🔗 Related Links

• NPM Package: https://www.npmjs.com/package/@lanonasis/cli
• Main Repository: https://github.com/lanonasis/lanonasis-maas
• Documentation: https://docs.lanonasis.com/cli
• API Documentation: https://api.lanonasis.com/docs
• Service Discovery: https://api.lanonasis.com/.well-known/onasis.json
• 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:

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:

# 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.