@wityai/root2-cli

Command-line interface for Root2 - the vector memory layer of Wity Ai.

This CLI provides a command-line interface to all the functionality of the @wityai/root2-api-client library, allowing you to manage vector memory blocks, convert data into computable knowledge, and supply dynamic memory context to your AI workflows.

📦 Installation

# Install globally
npm install -g @wityai/root2-cli

# Or run without installing
npx @wityai/root2-cli

🔑 Getting API Credentials

Before you can use Root2 CLI, you'll need to get your API credentials:

1. Visit Wity API Clients
2. Create a new API client
3. Copy your Client ID and API Key

🚀 Quick Start

Setup

1. Initialize CLI

   root2 init

   This will prompt you to enter your API credentials.

2. Import Content

   # Import a file
   root2 import-file ./document.pdf
   
   # Import a directory
   root2 import-dir ./docs --recursive
   
   # Import a webpage
   root2 import-web https://example.com

3. Query Your Vector Memory

   root2 query "What are the main topics discussed?"

📋 Commands

Setup & Configuration

# Interactive initialization (recommended for first-time setup)
root2 init

# Set individual values
root2 config set --client-id YOUR_ID --api-key YOUR_KEY

# View current configuration
root2 config get

# Clear configuration
root2 config clear

# Show system status
root2 status

Import Content

Import Files

# Basic file import
root2 import-file document.pdf

# With custom name and metadata
root2 import-file report.pdf --name "Q4 Report" --metadata '{"department":"sales","quarter":"Q4"}'

# Interactive import
root2 import-file-interactive

Import Directories

# Import directory (non-recursive)
root2 import-dir ./documents

# Recursive import with file filtering
root2 import-dir ./docs --recursive --include "*.{pdf,md,txt}"

# Exclude certain files
root2 import-dir ./project --recursive --exclude "*.tmp"

# Limit number of files
root2 import-dir ./large-folder --max-files 50

# Interactive import
root2 import-dir-interactive

Import Webpages

# Basic webpage import
root2 import-web https://example.com

# Include linked pages
root2 import-web https://docs.example.com --include-links --max-depth 2

# With metadata
root2 import-web https://blog.example.com --metadata '{"source":"blog","category":"tech"}'

# Interactive import
root2 import-web-interactive

Query Vector Memory

# Basic query
root2 query "What is machine learning?"

# Structured output
root2 query "List all projects" --format structured --max-results 20

# Include metadata in results
root2 query "Find documents about AI" --include-metadata

# Different output formats
root2 query "Summarize findings" --output json
root2 query "Show recent updates" --output table

# Interactive query session
root2 ask

Utility Commands

# Show help
root2 help
root2 help query  # Help for specific command

# Show version info
root2 version

# Check configuration status
root2 status

🎛️ Configuration

Environment Variables

You can also configure Root2 CLI using environment variables:

export ROOT2_CLIENT_ID="your-client-id"
export ROOT2_API_KEY="your-api-key"
export ROOT2_API_HOST="https://api.wity.ai"  # Optional
export ROOT2_VERBOSE="true"  # Optional

Configuration File

Configuration is stored in ~/.root2/config.json:

{
  "clientId": "your-client-id",
  "apiKey": "your-api-key",
  "apiHost": "https://api.wity.ai",
  "verbose": false,
  "outputFormat": "text"
}

📊 Output Formats

Query Results

Text Format (default)

📄 Result 1:
Machine learning is a subset of artificial intelligence that focuses on algorithms...

   Relevance: 95.2%
   Source: ml-guide.pdf

JSON Format

[
  {
    "content": "Machine learning is a subset of artificial intelligence...",
    "score": 0.952,
    "source": "ml-guide.pdf",
    "metadata": {}
  }
]

Table Format

│ #  │ Content                                    │ Score  │
├────┼───────────────────────────────────────────┼────────┤
│ 1  │ Machine learning is a subset of AI...     │ 95.2%  │
│ 2  │ Deep learning uses neural networks...     │ 87.1%  │

🎯 Examples

Content Management Workflow

# 1. Set up CLI
root2 init

# 2. Import research papers
root2 import-dir ./research-papers --recursive --include "*.pdf" \
  --metadata '{"type":"research","year":"2024"}'

# 3. Import company documentation
root2 import-dir ./company-docs --recursive --include "*.{md,txt,docx}"

# 4. Import relevant web content
root2 import-web https://industry-report.com --include-links --max-depth 1

# 5. Query the knowledge base
root2 query "What are the latest trends in AI research?" --max-results 10

# 6. Interactive session for deeper exploration
root2 ask

Metadata Usage

# Add structured metadata for better organization
root2 import-file contract.pdf --metadata '{
  "type": "legal",
  "department": "contracts",
  "status": "active",
  "priority": "high"
}'

# Query with metadata filtering
root2 query "show active contracts" --filters '{"metadata.status":"active"}'

Batch Operations

# Import multiple directories with different metadata
root2 import-dir ./2024-reports --metadata '{"year":"2024","type":"report"}'
root2 import-dir ./policies --metadata '{"type":"policy","department":"hr"}'
root2 import-dir ./presentations --metadata '{"type":"presentation"}'

# Query across different content types
root2 query "company policies on remote work" --include-metadata

🔧 Advanced Usage

Dry Run Mode

Test imports without actually importing:

root2 import-file document.pdf --dry-run
root2 import-dir ./docs --recursive --dry-run
root2 import-web https://example.com --dry-run

Verbose Mode

Get detailed information about operations:

root2 query "AI applications" --verbose
root2 import-file document.pdf --verbose

Interactive Sessions

Use interactive mode for guided operations:

root2 import-file-interactive
root2 import-dir-interactive
root2 import-web-interactive
root2 ask  # Interactive query session

🛠️ Troubleshooting

Common Issues

Authentication Errors

# Check configuration
root2 config get

# Reconfigure if needed
root2 init

Import Failures

# Use dry-run to test
root2 import-file document.pdf --dry-run

# Check file permissions and format
ls -la document.pdf

No Query Results

# Check if content was imported
root2 status

# Try broader search terms
root2 query "general topic" --max-results 50

Debug Mode

Enable verbose logging for detailed troubleshooting:

export ROOT2_VERBOSE=true
root2 query "test" --verbose

🔒 Security

• API keys are stored securely in your home directory (~/.root2/config.json)
• Configuration file permissions are set to user-only access
• API keys are never logged or displayed in plain text (masked as ********)
• Use environment variables in CI/CD environments

🔗 Related Packages

This CLI is built on top of the @wityai/root2-api-client library. If you need programmatic access to Root2 functionality in your Node.js applications, check out the API client library documentation.

🤝 Support

• Documentation: https://root2.ai/docs
• API Reference: https://api.wity.ai/docs
• Support: https://root2.ai/support
• Get API Keys: https://account.wity.ai/api-clients

📝 License

MIT License - see LICENSE file for details.

Root2 CLI - Transform your documents, web content, and files into computable vector memory from the command line.