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. Build the web UI first - it is a Vite artifact, so a fresh clone does not have it, and an install without it serves the API only:

cd interface/web && npm ci && npm run build && cd ../..
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, web 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
• search: DuckDuckGo web search for chat
• mail: IMAP mail reading
• tui: Textual interactive chat UI (nexus with no subcommand)
• all: every optional capability at once

Common commands

nexus                              Interactive chat TUI (needs nexusos-ai[tui])
nexus tui                          Same as bare nexus
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 monitor [--once] [--json]   ASCII live dashboard (services, resources, tools)
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:

Persisted keys are the same names, minus the NEXUS_ prefix - nexus config set home /data/nexus matches NEXUS_HOME. nexus config list shows what is set; nexus config set warns when a change would point NexusOS at a database that does not exist yet (the file is never moved for you).

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.

--allow-lan widens the accepted Host headers and CORS origins to the addresses the bind actually answers on - it does not set them to *. That keeps TrustedHostMiddleware enforcing something, which is what stops a web page you visit from resolving a name it controls to your machine and driving the API through your browser. Export NEXUS_ALLOWED_HOSTS yourself if you genuinely need a blanket, and understand that anyone who can reach the port has full admin and data access.