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:

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

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

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

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

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).

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

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