> ## Documentation Index > Fetch the complete documentation index at: https://docs.neuralcleave.com/llms.txt > Use this file to discover all available pages before exploring further. # CLI Reference > All neuralcleave command-line commands. ## Global flags ``` neuralcleave [-c/--config PATH] COMMAND ``` | Flag | Default | Description | | ---------------- | ----------------------------- | ------------------- | | `-c`, `--config` | `~/.neuralcleave/config.toml` | Path to config file | ## Gateway lifecycle ### `start` Start the gateway and all enabled channel adapters. ```bash theme={null} neuralcleave start neuralcleave start --background # detached process neuralcleave start --bind 0.0.0.0 --port 8000 neuralcleave start --voice-mode # start with voice always listening ``` ### `stop` Stop a gateway previously started with `--background`. ```bash theme={null} neuralcleave stop ``` ### `open` Open the web UI in the default browser (starts the gateway first if not already running). ```bash theme={null} neuralcleave open ``` ### `tray` Start the gateway in the background and open the web UI — the typical one-command way to launch NeuralCleave. ```bash theme={null} neuralcleave tray ``` ### `chat` Interactive chat session directly in the terminal, no channel adapter required. ```bash theme={null} neuralcleave chat ``` ### `status` Show agent config, enabled channels, and memory stats at a glance. ```bash theme={null} neuralcleave status ``` ## Config ### `config show` Print the resolved config (merged defaults + config.toml + env overrides). ### `config init` Write a starter `config.toml` to `~/.neuralcleave/`. ### `config edit` Open `config.toml` in `$EDITOR`. ## Backup & restore State (config, memory database, privacy audit log, skills) lives entirely under `~/.neuralcleave/` — these commands tar/verify/restore that one directory. ```bash theme={null} neuralcleave backup create # -> ~/.neuralcleave-backups/neuralcleave-backup-.tar.gz neuralcleave backup list neuralcleave backup verify neuralcleave backup restore --target /fresh/restore/path neuralcleave backup restore --target /existing/path --force # only if the target isn't empty ``` Restore refuses a non-empty target directory unless `--force` is passed, and archive extraction rejects path traversal / unsafe members. ## Usage & cost tracking ### `usage` Show accumulated LLM token usage and estimated cost per model. Proxies through a running gateway's `GET /api/v1/usage` (the same pattern `approvals`/`hub install` use) so it reflects the gateway's actual counters, not this CLI invocation's own — falling back to this process's own, necessarily-empty local registry only if no gateway is reachable. ```bash theme={null} neuralcleave usage ``` ``` NeuralCleave Usage (since gateway start) ┌────────────────────┬──────────────┬───────────────┬─────────────────┐ │ Model │ Input Tokens │ Output Tokens │ Est. Cost (USD) │ ├────────────────────┼──────────────┼───────────────┼─────────────────┤ │ claude-opus-4-8 │ 4,210 │ 1,340 │ $0.1642 │ │ Total │ 4,210 │ 1,340 │ $0.1642 │ └────────────────────┴──────────────┴───────────────┴─────────────────┘ ``` This is a live view of counters recorded since the gateway started, not a persisted historical ledger — it resets when the gateway restarts. Scrape `/api/v1/metrics` into a real time-series store for long-term history. ## Providers ### `models list` List every supported provider and whether credentials are configured (no network calls). ```bash theme={null} neuralcleave models list ``` ### `models status` Same as `list`, plus (with `--live`) an actual HTTP reachability probe — only for providers with a documented, stable check (OpenAI-compatible `GET /v1/models` for OpenAI/Mistral/xAI/Moonshot/OpenRouter/Groq/Together/Fireworks/DeepSeek, Ollama's `GET /api/tags`). Every other provider reports "not supported" rather than a guess. ```bash theme={null} neuralcleave models status neuralcleave models status --live ``` `--live` makes real network calls — it's not run automatically. ## Exec approvals Set `[security] require_shell_approval = true` in `config.toml` (or toggle it live via `POST /api/v1/approvals/policy`) to gate the `shell`/`browser` tools behind a persistent allowlist + security policy — see [Configuration](/configuration). ```bash theme={null} neuralcleave approvals pending # commands awaiting a decision neuralcleave approvals approve neuralcleave approvals approve --always # also allowlist this command's program neuralcleave approvals deny neuralcleave approvals allowlist list neuralcleave approvals allowlist add git --arg-pattern "^git log" neuralcleave approvals allowlist remove ``` `pending`/`approve`/`deny` first try the REST API of a gateway running at the configured `[gateway]` bind/port — the same live queue the channel-forwarded chat reply and web UI use. If no gateway is reachable there (nothing running, or a different bind/port), they fall back to this CLI process's own in-memory queue instead, printing a note when that happens — that fallback can never see a separately running gateway's pending requests, since `ApprovalQueue` has no persistence or IPC of its own. `allowlist add/list/remove` don't need any of this — the allowlist is SQLite-backed and genuinely shared across processes either way. Security/ask modes (`deny|allowlist|full` and `off|on-miss|always`) and `require_shell_approval` are all set via `GET`/`POST /api/v1/approvals/policy` — see [API Reference → Approvals](/api-reference/approvals). Pending approvals are also forwarded as a plain-text message in the channel that triggered them — reply `approve ` or `deny ` directly in chat. ## Skills Skills are Python modules the agent can write for itself at `~/.neuralcleave/skills//skill.py`. ```bash theme={null} neuralcleave skills write --file code.py # trusted path — writes and loads immediately neuralcleave skills list neuralcleave skills show neuralcleave skills delete neuralcleave skills validate # check syntax + blocked imports without writing neuralcleave skills quarantine # unload without deleting the file ``` ### Agent-authored skills go through review When the **agent itself** writes a skill (via the `write_skill` tool), it no longer loads immediately — it's queued as a pending proposal for a human to decide: ```bash theme={null} neuralcleave skills review pending neuralcleave skills review show neuralcleave skills review approve # writes to disk, loads, and wires its tools in neuralcleave skills review reject # never written to disk ``` `neuralcleave skills write` (above) is the separate, trusted, immediate-load path — used for e.g. code you wrote yourself or installed from the skills gallery, not for reviewing agent output. ## Hub `neuralcleave hub` installs skill packages from a URL, scans them with `PackageScanner`, and registers them the same way `skills write` does. ```bash theme={null} neuralcleave hub install --name my-skill neuralcleave hub install --force # install even if the scanner flags it neuralcleave hub remove neuralcleave hub search neuralcleave hub scan # scan only, don't install neuralcleave hub enable/disable ``` `install`/`remove` try a running gateway's REST API first — that's the only way an install becomes callable by a *live* agent, since this CLI process has no connection to a separately running gateway's tool registry. If no gateway is reachable at the configured `[gateway]` bind/port, they fall back to writing/loading into this process's own local hub state instead (a note is printed either way telling you which happened). `--force` only overrides the Hub's own scanner — it does not bypass the underlying skill writer's independent blocked-import check (`subprocess`, `ctypes`, etc.), which has no override anywhere in NeuralCleave. There is no remote/curated package catalog today — `hub search` only searches packages you've already installed. Hub currently means "fetch a URL, scan it, install it," not a marketplace with discovery. ## Plugins Plugins are `pip`-installed packages that declare a `NeuralCleave.plugins` entry point. ```bash theme={null} neuralcleave plugins list neuralcleave plugins install some-plugin # PyPI name or local path — no --force needed neuralcleave plugins install git+https://github.com/x/y.git --force # non-PyPI sources need --force neuralcleave plugins uninstall some-plugin neuralcleave plugins enable neuralcleave plugins disable # stays discovered, but its tools stop loading neuralcleave plugins reload # hot-reload all, no gateway restart neuralcleave plugins reload # hot-reload one ``` ## Channels ```bash theme={null} neuralcleave channels list neuralcleave channels add neuralcleave channels remove ``` ## Memory ```bash theme={null} neuralcleave memory prune --threshold 0.2 neuralcleave memory clear --session neuralcleave memory edit --content "..." --importance 0.9 neuralcleave memory archive --days 30 neuralcleave memory search "" ``` ## Voice ```bash theme={null} neuralcleave voice listen # always-on, no wake word neuralcleave voice wake # wake-word detection loop neuralcleave voice clone file1.wav file2.wav # voice cloning, if the TTS backend supports it ``` ## Migration ```bash theme={null} neuralcleave migrate openclaw --source ~/.openclaw --dry-run neuralcleave migrate openclaw --source ~/.openclaw ``` Imports an OpenClaw installation's channel/provider config into a NeuralCleave `config.toml`. ## Cloud deployment ```bash theme={null} neuralcleave cloud check # verify Docker + Compose neuralcleave cloud generate # write Dockerfile, docker-compose.yml, railway.toml, render.yaml neuralcleave cloud status ``` ## Autostart ```bash theme={null} neuralcleave autostart enable neuralcleave autostart disable neuralcleave autostart status ``` ## Tools ```bash theme={null} neuralcleave tools list # every registered tool + description ``` ## Orchestrator ```bash theme={null} neuralcleave orchestrate list neuralcleave orchestrate add --name node-a --model anthropic/claude-opus-4-8 --task-types code_generation neuralcleave orchestrate remove node-a neuralcleave orchestrate route --content "some task" --task-type code_generation neuralcleave orchestrate status ``` `list`/`add`/`remove`/`route`/`status` try a running gateway's REST API first (reusing its live, shared orchestrator instance) and fall back to a local, throwaway one only if no gateway is reachable — a note is printed either way. Against a running gateway, `route` generates a real response via the selected node's `model_override` (`ModelRouter.generate()` directly — no memory retrieval, reflection, or tool calls, so it's a lighter-weight one-shot generation rather than a full conversational turn). Against the local fallback orchestrator (no gateway reachable), routing only selects a node and prints a placeholder, since a bare CLI invocation has no provider credentials to build a real router from. Node-selection logic (priority, keyword, channel, task-type matching) is real everywhere. Full `CognitivePipeline` integration (memory, reflection, tool calls) for a routed task is still future work — routing a task is not the same as a normal chat turn through any channel adapter. ## Version & updates ```bash theme={null} neuralcleave version neuralcleave update --check # check PyPI without installing neuralcleave update # install if a newer version exists ```