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:

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

From the package index after a release is published:

```bash
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

```text
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:

```bash
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:

```bash
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:

```bash
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:

```text
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.