Athena KaminskyandClaude Opus 5
9104c724c4
The CLI shipped from `management/`, which also holds desktop-only pieces (the Tk control panel, the XFCE panel wiring, the shell wrappers). Packaging that directory meant the wheel either dragged in tkinter or shipped a broken import. Split it: `nexusos_cli/` is what the wheel ships and what `nexus`/`ncp`/ `nexusos` dispatch to, `management/` keeps the desktop half. Alongside the move: * hatch_build.py decides the interface/web/dist include at build time. dist/ is gitignored, so a static force-include aborts `pip install -e .` on a fresh clone - before the reader reaches the `npm run build` step. Editable installs now skip a missing dist; wheels and sdists hard-error naming the command to run. * synapse/proc_util.py gives frontend_manager and ncp process inspection and termination without psutil, which became an optional extra when the wheel landed. It routes around Windows having no signals, where os.kill(pid, 15) is an unblockable TerminateProcess rather than a polite request. * nexusos_cli/monitor.py adds `ncp monitor`, an ASCII dashboard with no curses or rich dependency so it works in Termux, plain SSH and Windows Terminal. Collector and renderer are separate so tests feed fixtures, no stack needed. * tests/test_packaging_deps.py fails the gate when synapse or nexusos_cli import a distribution pyproject does not declare, and when an optional dependency is imported at module scope instead of lazily. * bin/check.sh now builds the wheel, twine-checks it, and asserts the compiled UI and seed playbooks are actually inside it. A wheel that builds but ships no dist/ serves a blank page, which only shows up after release. tests/test_nexus_api.py moves to tests/ with the module it covers. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
119 lines
4.4 KiB
Markdown
119 lines
4.4 KiB
Markdown
# 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
|
|
- `all`: every optional capability at once
|
|
|
|
## 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 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.
|
GitNexus · part of the Nexus stack