Skip to content

CLI Reference

← API Documentation

The Nexus command-line interface provides comprehensive access to all Nexus operations. The CLI mirrors the Python API and is ideal for shell scripts, automation, and interactive use.

Quick Start

# Install Nexus
pip install nexus-ai-fs

# Verify installation
nexus --version

# Get help
nexus --help
nexus <command> --help

Command Categories

File Operations

Commands for reading, writing, and manipulating files.

  • write - Write file content
  • cat - Display file contents
  • rm - Delete files
  • cp/copy - Copy files
  • move - Move/rename files

→ Full File Operations Reference

Directory Operations

Commands for managing directories and listing files.

  • mkdir - Create directories
  • rmdir - Remove directories
  • ls - List directory contents
  • tree - Display directory tree

→ Full Directory Operations Reference

Search Operations

Commands for finding and searching files.

  • glob - Find files by pattern
  • grep - Search file contents

→ Full Search Operations Reference

Version Tracking

Commands for version history and time-travel.

→ Full Versioning Reference

Workspace Management

Commands for workspace snapshots and management.

→ Full Workspace Reference

Memory Management

Commands for memory storage and retrieval.

→ Full Memory Reference

Commands for AI-powered semantic search.

→ Full Semantic Search Reference

LLM Document Reading

Commands for AI-powered document question answering.

  • llm read - Ask questions about documents

→ Full LLM Document Reading Reference

Permissions (ReBAC)

Commands for relationship-based access control.

→ Full Permissions Reference

Backend Mounts

Commands for managing storage backend mounts.

→ Full Mounts Reference

Server & Mounting

Commands for server management and FUSE mounting.

  • serve - Start RPC server
  • mount - Mount as FUSE filesystem
  • unmount - Unmount filesystem

→ Full Server Reference

Model Context Protocol (MCP)

Commands for MCP server to integrate with AI agents and tools.

  • mcp serve - Start MCP server for Claude Desktop and other MCP clients

→ Full MCP Reference

Advanced Operations

Advanced commands for operation tracking, analysis, and sync.

→ Full Advanced Operations Reference

Global Options

Most commands support these global options:

Configuration

  • --config PATH - Path to Nexus config file (nexus.yaml)
  • --data-dir PATH - Path to Nexus data directory (or use NEXUS_DATA_DIR env var)
  • --backend [local|gcs] - Backend type (default: local)

Remote Mode

  • --remote-url URL - Remote Nexus server URL (or use NEXUS_URL env var)
  • --remote-api-key KEY - API key for authentication (or use NEXUS_API_KEY env var)

Multi-Tenancy & Identity

  • --tenant-id TEXT - Tenant ID for multi-tenant isolation (or use NEXUS_TENANT_ID env var)
  • --subject TEXT - Subject in format 'type:id' (e.g., 'user:alice') (or use NEXUS_SUBJECT env var)

Admin Operations

  • --is-admin - Run operation with admin privileges
  • --admin-capability TEXT - Grant specific admin capability (can specify multiple times)

Remote Mode - Two Ways to Connect

1. Environment Variables (Recommended - Works for ALL commands): 

export NEXUS_URL=http://localhost:8765
export NEXUS_API_KEY=your-api-key
# Now all commands use remote mode
nexus ls /
nexus write /file.txt "data"

2. Command-line Flags (Works for most commands): 

nexus --remote-url http://localhost:8765 --remote-api-key key ls /

Note: Memory commands and some workspace commands only support remote mode via NEXUS_URL environment variable.

Environment Variables

Key environment variables for configuration:

Remote Mode (takes priority over local)

export NEXUS_URL=http://localhost:8765
export NEXUS_API_KEY=your-api-key

Local Mode

export NEXUS_DATA_DIR=/path/to/data

Multi-Tenancy & Identity

export NEXUS_TENANT_ID=org_acme
export NEXUS_SUBJECT=user:alice

Database

export NEXUS_DATABASE_URL=postgresql://user:pass@localhost/nexus

GCS Configuration

export GCS_PROJECT_ID=my-project
export GCS_BUCKET_NAME=my-bucket

Priority: If NEXUS_URL is set, all commands use remote mode. Otherwise, commands use local mode with NEXUS_DATA_DIR.

Configuration File

Create nexus.yaml for persistent configuration:

# Backend configuration
backend:
  type: local
  data_dir: ./nexus-data

# Or use GCS
backend:
  type: gcs
  gcs_bucket: my-bucket
  gcs_project: my-project

# Multi-tenant
tenant_id: org_acme

# Subject identity
subject: user:alice

# Permissions
enforce_permissions: true

# Database (optional)
database_url: postgresql://user:pass@localhost/nexus

Use it: 

nexus --config nexus.yaml ls /workspace

CLI vs Python API

Every CLI command has a Python API equivalent:

CLI Command Python API
nexus write /file.txt "data" nx.write("/file.txt", b"data")
nexus cat /file.txt nx.read("/file.txt")
nexus ls /workspace nx.list("/workspace")
nexus glob "*.py" nx.glob("*.py")
nexus grep "TODO" nx.grep("TODO")
nexus versions history /file.txt nx.list_versions("/file.txt")
nexus workspace snapshot /ws nx.workspace_snapshot("/ws")
nexus search query "auth" await nx.semantic_search("auth")
nexus llm read /doc.pdf "Question" await nx.llm_read("/doc.pdf", "Question")

See individual command references for detailed Python API examples.

Common Workflows

1. Initialize and use Nexus

# Set data directory
export NEXUS_DATA_DIR=./my-nexus

# Write files
nexus write /docs/README.md "# My Project"
nexus write /src/main.py "print('hello')"

# List files
nexus ls / --recursive

# Search
nexus grep "hello" /src

2. Version tracking workflow

# Write initial version
nexus write /config.json '{"version": "1.0"}'

# Update file
nexus write /config.json '{"version": "2.0"}'

# View history
nexus versions history /config.json

# Rollback
nexus versions rollback /config.json --version 1

3. Workspace snapshot workflow

# Register workspace
nexus workspace register /my-project --name main

# Make changes
nexus write /my-project/file.txt "changes"

# Create snapshot
nexus workspace snapshot /my-project --description "Before refactor"

# Make more changes
nexus write /my-project/file.txt "more changes"

# Restore if needed
nexus workspace restore /my-project --snapshot 1

4. Remote server workflow

# Terminal 1: Start server
nexus serve --host 0.0.0.0 --port 8765 --api-key secret123

# Terminal 2: Set environment and use remote mode
export NEXUS_URL=http://localhost:8765
export NEXUS_API_KEY=secret123

nexus write /workspace/file.txt "remote data"
nexus cat /workspace/file.txt
nexus memory store "Important fact" --scope user

5. Multi-backend workflow

# Use local backend
nexus --backend local ls /

# Use GCS backend
nexus --backend gcs --gcs-bucket my-bucket ls /

6. LLM document reading workflow

# Set up API key
export ANTHROPIC_API_KEY=sk-ant-...

# Index documents for semantic search
nexus search init --provider openai
nexus search index /docs

# Ask questions
nexus llm read /docs/**/*.md "How does authentication work?"

# Get detailed output with citations
nexus llm read /reports/q4.pdf "What were the challenges?" --detailed

# Stream long analysis
nexus llm read /data/**/*.csv "Analyze trends" --stream

See Also