CLI Reference

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.

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.

neuralcleave stop

`open`

Open the web UI in the default browser (starts the gateway first if not already running).

neuralcleave open

`tray`

Start the gateway in the background and open the web UI — the typical one-command way to launch NeuralCleave.

neuralcleave tray

`chat`

Interactive chat session directly in the terminal, no channel adapter required.

neuralcleave chat

`status`

Show agent config, enabled channels, and memory stats at a glance.

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.

neuralcleave backup create                          # -> ~/.neuralcleave-backups/neuralcleave-backup-<timestamp>.tar.gz
neuralcleave backup list
neuralcleave backup verify <archive-path>
neuralcleave backup restore <archive-path> --target /fresh/restore/path
neuralcleave backup restore <archive-path> --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.

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

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.

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.

neuralcleave approvals pending                       # commands awaiting a decision
neuralcleave approvals approve <id>
neuralcleave approvals approve <id> --always          # also allowlist this command's program
neuralcleave approvals deny <id>

neuralcleave approvals allowlist list
neuralcleave approvals allowlist add git --arg-pattern "^git log"
neuralcleave approvals allowlist remove <entry-id>

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. Pending approvals are also forwarded as a plain-text message in the channel that triggered them — reply approve <id-prefix> or deny <id-prefix> directly in chat.

Skills

Skills are Python modules the agent can write for itself at ~/.neuralcleave/skills/<name>/skill.py.

neuralcleave skills write <name> --file code.py       # trusted path — writes and loads immediately
neuralcleave skills list
neuralcleave skills show <name>
neuralcleave skills delete <name>
neuralcleave skills validate <file>                   # check syntax + blocked imports without writing
neuralcleave skills quarantine <name>                 # 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:

neuralcleave skills review pending
neuralcleave skills review show <id>
neuralcleave skills review approve <id>               # writes to disk, loads, and wires its tools in
neuralcleave skills review reject <id>                # 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.

neuralcleave hub install <source-url> --name my-skill
neuralcleave hub install <source-url> --force              # install even if the scanner flags it
neuralcleave hub remove <name>
neuralcleave hub search <query>
neuralcleave hub scan <source-url>                          # scan only, don't install
neuralcleave hub enable/disable <name>

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.

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 <name>
neuralcleave plugins disable <name>                   # stays discovered, but its tools stop loading
neuralcleave plugins reload                            # hot-reload all, no gateway restart
neuralcleave plugins reload <name>                      # hot-reload one

Channels

neuralcleave channels list
neuralcleave channels add <name>
neuralcleave channels remove <name>

Memory

neuralcleave memory prune --threshold 0.2
neuralcleave memory clear --session <id>
neuralcleave memory edit <entry-id> --content "..." --importance 0.9
neuralcleave memory archive --days 30
neuralcleave memory search "<query>"

Voice

neuralcleave voice listen                             # always-on, no wake word
neuralcleave voice wake                                # wake-word detection loop
neuralcleave voice clone <name> file1.wav file2.wav    # voice cloning, if the TTS backend supports it

Migration

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

neuralcleave cloud check                              # verify Docker + Compose
neuralcleave cloud generate                            # write Dockerfile, docker-compose.yml, railway.toml, render.yaml
neuralcleave cloud status

Autostart

neuralcleave autostart enable
neuralcleave autostart disable
neuralcleave autostart status

Tools

neuralcleave tools list                                # every registered tool + description

Orchestrator

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

neuralcleave version
neuralcleave update --check                            # check PyPI without installing
neuralcleave update                                    # install if a newer version exists

Getting Started

Core Concepts

Voice

Operations

Changelog

Global flags

Gateway lifecycle

`start`

`stop`

`open`

`tray`

`chat`

`status`

Config

`config show`

`config init`

`config edit`

Backup & restore

Usage & cost tracking

`usage`

Providers

`models list`

`models status`

Exec approvals

Skills

Agent-authored skills go through review

Hub

Plugins

Channels

Memory

Voice

Migration

Cloud deployment

Autostart

Tools

Orchestrator

Version & updates

​Global flags

​Gateway lifecycle

​start

​stop

​open

​tray

​chat

​status

​Config

​config show

​config init

​config edit

​Backup & restore

​Usage & cost tracking

​usage

​Providers

​models list

​models status

​Exec approvals

​Skills

​Agent-authored skills go through review

​Hub

​Plugins

​Channels

​Memory

​Voice

​Migration

​Cloud deployment

​Autostart

​Tools

​Orchestrator

​Version & updates

Global flags

Gateway lifecycle

`start`

`stop`

`open`

`tray`

`chat`

`status`

Config

`config show`

`config init`

`config edit`

Backup & restore

Usage & cost tracking

`usage`

Providers

`models list`

`models status`

Exec approvals

Skills

Agent-authored skills go through review

Hub

Plugins

Channels

Memory

Voice

Migration

Cloud deployment

Autostart

Tools

Orchestrator

Version & updates