NexusOS/docs/CLI.md

NexusOS CLI

The Python package installs three equivalent command names: nexus, ncp, and nexusos. New documentation uses nexus; ncp remains available for existing desktop installs and scripts. Legacy spellings such as ncp web, ncp start -b, ncp refresh, ncp backup, and ncp restore remain supported; checkout-specific operations report a clear error when invoked from a wheel.

Install

From a source checkout:

python -m pip install -e ".[standard]"
nexus init
nexus doctor

From the package index after a release is published:

python -m pip install "nexusos-ai[standard]"
nexus init
nexus serve

The base install contains the backend, memory service, compiled web UI, CLI, and seed playbooks. Extras keep platform-sensitive dependencies optional:

• standard: documents, vector search, and process control
• documents: PDF and DOCX ingestion
• vector: sqlite-vec semantic indexes
• voice: local faster-whisper transcription
• process: psutil-backed process and port inspection
• desktop: desktop process support and Windows pywebview

Common commands

nexus init                         Create writable state and seed playbooks
nexus doctor [--fix] [--json]     Diagnose the install and provider
nexus paths [--json]              Show package, state, and asset locations
nexus status [--json]             Show services and provider reachability
nexus serve                       Run backend + memory in the foreground
nexus start|stop|restart           Manage background services
nexus open                         Open the compiled web interface
nexus logs [service] --follow      Tail service logs
nexus models list|pull|remove      Manage Ollama-compatible models
nexus config list|get|set|unset    Manage persistent settings

API commands are also available directly:

nexus chat send "Hello"
nexus history list
nexus memory list
nexus playbook list

Run nexus COMMAND --help for command-specific arguments.

Providers

Local desktop installs can allow NexusOS to start and stop a local Ollama:

nexus provider use local

For Termux, containers, or a separate inference machine, configure a remote Ollama-compatible endpoint. NexusOS probes it but never manages its process:

nexus provider use remote --url http://192.168.1.20:11434
nexus provider show --json

State and configuration

Installed wheels never write into site-packages. Writable files use the platform data directory, while configuration uses the platform config directory. Inspect the exact locations with nexus paths.

Environment variables override persisted settings. The most useful are:

NEXUS_HOME                 Override the complete writable state root
NEXUS_CONFIG_DIR           Override the config directory
NEXUS_PROVIDER             ollama or ollama-remote
NEXUS_PROVIDER_URL         Ollama-compatible API base URL
NEXUS_BIND_HOST            Backend bind address (loopback by default)
NEXUS_BACKEND_PORT         Backend/web port (default 8000)
NEXUS_MEMORY_PORT          Memory service port (default 8001)

The REST APIs are unauthenticated. nexus serve refuses non-loopback binds unless --allow-lan is given; that flag is an explicit acknowledgement, not an authentication layer.