feat: add portable NexusOS CLI and packaging

2026-08-26 08:11:39 -05:00
parent 2ebe93b4f7
commit d579502a5b
21 changed files with 1624 additions and 94 deletions
@@ -0,0 +1,99 @@
+# 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.