BotNexus CLI Reference

The botnexus command-line tool is the stable interface for configuration and agent management. Its configuration commands work with both JSON-backed and SQLite-backed BotNexus homes, so scripts and runbooks do not need to know which backend is active.

Setting up the `botnexus` alias

There is no globally installed botnexus binary yet. To use the CLI, create a shell alias that runs dotnet run against the CLI project and forwards your arguments.

PowerShell (Windows / cross-platform)

Add this to your PowerShell profile ($PROFILE):

function botnexus { dotnet run --project D:\repos\botnexus\src\gateway\BotNexus.Cli -- @args }

Replace D:\repos\botnexus with the path where you cloned the repository.

Reload the profile:

. $PROFILE

Bash / Zsh (macOS / Linux)

Add this to ~/.bashrc, ~/.zshrc, or equivalent:

alias botnexus='dotnet run --project ~/repos/botnexus/src/gateway/BotNexus.Cli --'

Reload:

source ~/.bashrc   # or source ~/.zshrc

Verify

botnexus --help

You should see the root command help listing all available subcommands.

Tip: The -- separator is required so that arguments like --verbose are passed to the CLI app and not interpreted by dotnet run.

Global Options
install — Clone the repository
build — Build the solution
serve — Start a service (gateway or probe)
validate — Validate configuration
init — Initialize home directory
agent list — List configured agents
agent add — Add an agent
agent show — Show a single agent's resolved config
agent remove — Remove an agent
agent wizard — Create an agent interactively
agent export — Export an agent as a redacted template
agent import — Import an agent from a redacted template
agent exec — Run an agent once, headlessly
conversation — Manage conversations via the gateway REST API
session — List, archive, and delete sessions via the session store
config get — Read a config value
config set — Set a config value
config schema — Generate JSON schema
config backups list — List retained config.json backups
config restore — Validate and restore a config.json backup
config store - Manage the SQLite configuration store
secret - Manage the sqlite: secret store
gateway — Manage the gateway lifecycle
provider — Show or set up providers
provider setup — Interactive provider setup wizard
provider list — List configured providers
provider add — Add or update a provider non-interactively (scripts and CI)
provider remove — Remove a provider non-interactively
provider copilot — GitHub Copilot diagnostics and auth helpers
provider ollama — Ollama local model diagnostics
prompt — Manage prompt templates
prompt list — List available prompt templates
prompt render — Render a prompt template
prompt run — Render and execute a prompt template
satellite — Manage satellite nodes
doctor — Run the complete CLI diagnostic suite
doctor config — Guided config migration
doctor agents — Reconcile persistent agent workspaces
locations — Manage configured locations
update — Pull, build, and restart the gateway
memory — Backfill agent memory stores
cron — Manage cron jobs from the CLI
subagent workspace — Inspect and prune sub-agent workspaces
debug sessions — Inspect session SQLite database
debug logs — Inspect log files
debug memory — Inspect agent memory directories
debug db — Inspect raw databases
debug gateway — Live gateway diagnostics
debug cron — Cron scheduler diagnostics
Examples

Global Options

All commands support these options:

`--target <DIR>`

Override the BotNexus home directory (where config, workspaces, and extensions live). Defaults to ~/.botnexus or the BOTNEXUS_HOME environment variable.

This enables managing multiple BotNexus instances from a single CLI installation.

# Use a custom home directory
botnexus --target D:\my-botnexus agent list

# Validate config for a different instance
botnexus --target /opt/botnexus-prod validate

`--verbose` (or `-v`)

Show additional command output, including file paths and full JSON responses.

botnexus init --verbose
botnexus agent list --verbose

install

Clone the BotNexus repository and optionally build it. There is no separate install process — BotNexus runs directly from a cloned repository.

Usage

botnexus install [OPTIONS]

Options

Option	Default	Description
`--path <DIR>`	`%USERPROFILE%\botnexus`	Target directory for the clone.
`--repo <URL>`	GitHub repo URL	Git repository URL to clone.
`--build`	off	Build the solution in Release configuration after cloning.
`--verbose`	—	Show detailed output from git and build.

Examples

Clone to the default location:

botnexus install

Clone and build in one step:

botnexus install --build

Clone to a custom directory:

botnexus install --path D:\projects\botnexus

If the repository already exists at the target path, the command prints a message and skips the clone.

build

Build the BotNexus source projects in Release configuration. Test projects are skipped to keep the build fast. Always produces a Release build so that output assemblies don't conflict with Debug builds used during local development and testing.

Usage

botnexus build [OPTIONS]

Options

Option	Default	Description
`--path <DIR>`	Install location	Path to the repository root.
`--dev`	off	Use the current working directory as the repo root instead of the install location.
`--verbose`	—	Show full build output.

Repo resolution

The build command resolves the repo root in this order:

--path — explicit path always wins
--dev — uses the current working directory (for working in a separate dev clone)
Default — %USERPROFILE%\botnexus (the install location)

Examples

Build from the default install location:

botnexus build

Build from a dev clone (current directory):

cd D:\repos\botnexus
botnexus build --dev

Build a specific repo path:

botnexus build --path D:\repos\botnexus

serve

Start a BotNexus service. Defaults to the gateway if no subcommand is specified. The serve command builds the source projects (Release, skipping tests), deploys extensions to ~/.botnexus/extensions/, checks port availability, and starts the process.

If the process exits or crashes, serve waits 5 seconds and restarts automatically. Press q during the countdown to quit instead.

Usage

botnexus serve [OPTIONS]
botnexus serve gateway [OPTIONS]
botnexus serve probe [OPTIONS]

serve / serve gateway

Start the BotNexus Gateway.

Option	Default	Description
`--port <PORT>`	`5005`	Port to listen on.
`--path <DIR>`	Install location	Path to the repository root.
`--dev`	off	Use the current working directory as the repo root.
`--verbose`	—	Show detailed output.

serve probe

Start the BotNexus Probe diagnostic tool.

Option	Default	Description
`--port <PORT>`	`5050`	Port for the Probe web UI.
`--path <DIR>`	Install location	Path to the repository root.
`--dev`	off	Use the current working directory as the repo root.
`--gateway-url <URL>`	`http://localhost:5005`	URL of a running BotNexus Gateway.
`--verbose`	—	Show detailed output.

Examples

Start the gateway from the install location:

botnexus serve

Start the gateway from a dev clone:

cd D:\repos\botnexus
botnexus serve --dev

Start the gateway on a custom port:

botnexus serve gateway --port 8080

Start the probe connected to a running gateway:

botnexus serve probe --gateway-url http://localhost:5005

Production vs. development

Scenario	Command
Run from the default install clone	`botnexus serve`
Run from your active dev repo	`botnexus serve --dev`
Build and serve in one flow	`botnexus build --dev && botnexus serve --dev`

Both modes produce Release builds so the gateway DLLs don't collide with Debug builds from your IDE or test runner.

validate

Validate the BotNexus configuration file.

Usage

botnexus validate [OPTIONS]

Options

Option	Description
`--remote`	Validate using the running gateway `/api/config/validate` endpoint instead of local files.
`--gateway-url <URL>`	Override the gateway base URL for remote validation (default: `http://localhost:5005`).
`--token <CREDENTIAL>`	Gateway API credential. Required when `--gateway-url` is not the local gateway (issue #2747).
`--verbose`	Show detailed validation output.

Examples

Local validation (offline):

botnexus validate

Expected output (success):

Configuration is valid.

Remote validation (requires running gateway):

botnexus validate --remote

Custom gateway URL:

botnexus validate --remote --gateway-url http://api.example.com:8080 --token $env:REMOTE_GATEWAY_KEY

The credential configured for the local gateway is never sent to a URL supplied on the command line. A non-loopback --gateway-url without --token is refused rather than contacted unauthenticated (issue #2747).

init

Initialize ~/.botnexus/ with a default configuration and required directories.

Creates:

~/.botnexus/config.json — default platform configuration
~/.botnexus/agents/ — agent workspace directories
~/.botnexus/sessions/ — session storage
~/.botnexus/tokens/ — OAuth token storage
~/.botnexus/logs/ — log directory

Usage

botnexus init [OPTIONS]

Options

Option	Description
`--force`	Overwrite existing `config.json`. Use with caution.
`--listen-all-interfaces`	Bind the gateway to every network interface (`http://0.0.0.0:5005`) instead of loopback.
`--verbose`	Show the full default configuration in JSON format.

Loopback by default (issue #2798). A fresh init writes gateway.listenUrl as http://localhost:5005, so the portal UI, the SignalR hub, the agent REST API and the gateway admin endpoints are reachable only from the machine the gateway runs on. Binding every interface is an explicit operator decision: pass --listen-all-interfaces to have init emit http://0.0.0.0:5005 instead. An existing wildcard bind is never rewritten - doctor config reports it as a read-only advisory.

Examples

First-time initialization:

botnexus init

Expected output:

Initialized BotNexus home at: C:\Users\<YourName>\.botnexus
Created config: C:\Users\<YourName>\.botnexus\config.json
Next steps:
  - botnexus validate
  - botnexus agent list

See the default config:

botnexus init --verbose

Displays the JSON configuration that was created (or would be created if --force is used).

Reinitialize (overwrite existing):

botnexus init --force

agent list

List all configured agents from config.json.

Usage

botnexus agent list [OPTIONS]

Options

Option	Description
`--verbose`	Show the full config file path.

Examples

List agents:

botnexus agent list

Expected output:

Agents:
  assistant  provider=copilot  model=gpt-4.1  enabled=true
  coder      provider=openai           model=gpt-4    enabled=true
  reviewer   provider=anthropic        model=claude-3-sonnet  enabled=false

Verbose output (shows config file path):

botnexus agent list --verbose

Agents:
  assistant  provider=copilot  model=gpt-4.1  enabled=true
Loaded from: C:\Users\<YourName>\.botnexus\config.json

agent add

Add a new agent to the configuration.

Usage

botnexus agent add <ID> [OPTIONS]

Arguments

Argument	Description
`<ID>`	Unique agent identifier (e.g., `assistant`, `coder`, `reviewer`).

Options

Option	Default	Description
`--provider`	`github-copilot`	Agent provider name (must match a configured provider; e.g. `github-copilot`, `openai`, `anthropic`, or any provider added via `botnexus provider add`).
`--model`	`gpt-4.1`	Model name for this agent (e.g., `gpt-4o`, `claude-3-sonnet`).
`--enabled`	`true`	Whether the agent is enabled (`true` or `false`).
`--verbose`	—	Show the updated configuration.

Examples

Add an agent with defaults:

botnexus agent add coder

Output:

Added agent 'coder'.

Add an agent with custom provider and model:

botnexus agent add researcher --provider openai --model gpt-4o

Add a disabled agent:

botnexus agent add experimental --provider anthropic --model claude-3-sonnet --enabled false

Verbose output (see updated config):

botnexus agent add assistant --verbose

agent show

Show the resolved configuration for a single agent.

Usage

botnexus agent show <ID> [OPTIONS]

Arguments

Argument	Description
`<ID>`	Agent ID to inspect.

Options

Option	Description
`--json`	Emit raw JSON instead of a formatted table. Useful for scripts and CI.
`--target <DIR>`	BotNexus home directory. Defaults to `~/.botnexus`.
`--verbose`	Print the source config path under the table.

Examples

Inspect an agent in table form:

botnexus agent show assistant

Pipe agent config to jq:

botnexus agent show assistant --json | jq .model

Exit codes

Code	Meaning
`0`	Agent found and printed.
`1`	Config missing/invalid or agent ID not found.

agent remove

Remove an agent from the configuration.

Usage

botnexus agent remove <ID> [OPTIONS]

Arguments

Argument	Description
`<ID>`	Agent identifier to remove.

Options

Option	Description
`--verbose`	Show the updated configuration.

Examples

Remove an agent:

botnexus agent remove experimental

Output:

Removed agent 'experimental'.

Warning if removing the default agent:

botnexus agent remove assistant

Output (warning):

Warning: removing default agent 'assistant'. Update gateway.defaultAgentId if needed.
Removed agent 'assistant'.

agent wizard

Interactively create a new agent using a step-by-step wizard. The wizard prompts for the agent id, provider, model, and other settings, then writes the agent to config.json. Use this when you want a guided experience instead of the non-interactive agent add.

Usage

botnexus agent wizard [OPTIONS]

Options

Option	Description
`--target <DIR>`	BotNexus home directory. Defaults to `~/.botnexus`.
`--verbose`	Show the updated configuration after the wizard completes.

Examples

botnexus agent wizard

agent export

Export a configured agent as a versioned, redacted agentTemplate/v1 JSON template that is safe to share. The template contains only descriptor fields (displayName, description, emoji, modelId, apiProvider, systemPrompt, toolIds, thinking, contextWindow) and never includes secret values such as API keys, tokens, or PEMs.

Instead of secrets, the template carries a requiredSecrets manifest enumerating the provider credential keys the importing environment must supply (for example the provider's apiKey).

Usage

botnexus agent export <ID> [OPTIONS]

Options

Option	Description
`--output <PATH>`	Output file path. Defaults to `<id>.agent.json` in the current directory.
`--target <DIR>`	BotNexus home directory. Defaults to `~/.botnexus`.
`--verbose`	Show the schema and required-secret count after export.

Examples

botnexus agent export assistant

botnexus agent export assistant --output ./templates/assistant.agent.json

Output shape

{
  "schema": "agentTemplate/v1",
  "agent": {
    "displayName": "Assistant",
    "description": "A helpful assistant.",
    "modelId": "gpt-4.1",
    "apiProvider": "copilot",
    "toolIds": ["read", "write"],
    "contextWindow": 128000
  },
  "requiredSecrets": [
    {
      "provider": "copilot",
      "key": "apiKey",
      "description": "API key / credential for provider 'copilot'."
    }
  ]
}

agent import

Import an agent from a redacted agentTemplate/v1 template, reconstructing the agent definition into the target config.json and restoring its system prompt into the agent workspace. This is the symmetric inverse of agent export.

Because a template is portable across environments, import never silently reuses the exporter's id or overwrites an existing agent. You supply the target id (via --id, --set id=, or the template file name) and any per-environment overrides via repeatable --set key=value flags.

Usage

botnexus agent import <FILE> [OPTIONS]

Options

Option	Description
`--id <ID>`	Target agent id. Defaults to the `--set id=` override, then the template file name (`<id>.agent.json` -> `<id>`).
`--set <KEY=VALUE>`	Override a descriptor field before the agent is materialized. Repeatable. Supported keys: `id`, `displayName`, `description`, `emoji`, `model`, `provider`, `systemPrompt`, `thinking`, `contextWindow`.
`--overwrite`	Replace an existing agent with the resolved id. Without this flag an id collision is refused (no silent overwrite).
`--target <DIR>`	BotNexus home directory. Defaults to `~/.botnexus`.
`--verbose`	Show the schema and applied-override count after import.

Examples

Import a template as-is (id derived from the file name):

botnexus agent import ./templates/assistant.agent.json

Import as a differently-named copy with per-environment overrides:

botnexus agent import ./templates/assistant.agent.json --set id=copybot --set displayName="Copy Bot" --set model=gpt-5

Replace an existing agent from an updated template:

botnexus agent import ./templates/assistant.agent.json --id assistant --overwrite

Required secrets

Because the template is redacted, imported agents cannot run until you re-provide the credentials named in the template's requiredSecrets manifest (for example providers.<provider>.apiKey). Import prints the required-secret list on completion.

agent exec

Run an agent once, headlessly, and print its answer. This is the only agent subcommand that makes an agent run rather than editing its configuration — see the Automation guide for scripting recipes.

Syntax

botnexus agent exec <agentId> <prompt> [OPTIONS]

Options

Option	Default	Description
`--json`	off	Emit a structured JSON result (text, tool calls, token usage, session id) on stdout.
`--timeout <seconds>`	`300`	Wall-clock budget before the run is abandoned.
`--model <id>`	agent default	Per-run model override (`model-id` or `provider/model-id`).
`--thinking <level>`	agent default	`minimal`, `low`, `medium`, `high`, `xhigh`, or `max`.
`--conversation <id>`	fresh session	Run inside an existing session instead of a new one.
`--url <url>`	local gateway	Gateway base URL.
`--token <value>`	—	Gateway credential. Required when `--url` is not the local gateway.

The agent's answer is written to stdout; diagnostics and errors go to stderr, so the command is pipeable.

Exit codes

Code	Meaning
`0`	Run completed, all tool calls succeeded.
`1`	Usage error, unreachable gateway, refused credential, or unclassified gateway error.
`2`	The named agent is not registered.
`3`	The run exceeded `--timeout`.
`4`	Run completed, but at least one tool call reported an error.

Examples

botnexus agent exec farnsworth "summarise the last 10 commits on main"
botnexus agent exec farnsworth "list the blockers" --json --timeout 900

Approval posture

The run is submitted to the gateway over the same REST endpoint every other non-streaming caller uses, so it inherits the gateway's tool policy and approval behaviour unchanged. There is deliberately no --yes, --auto-approve, or --force flag: the CLI has no authority to waive a policy decision made inside the gateway. A run blocked on an approval nobody grants will hit --timeout and exit 3 rather than proceeding unapproved.

conversation

Manage conversations through a running gateway's REST API. Unlike the offline debug subcommands, these operations require a reachable gateway and make HTTP requests to its /api/conversations endpoints.

Usage

botnexus conversation <COMMAND> [OPTIONS]

Shared options

These options apply to every conversation subcommand:

Option	Default	Description
`--url <URL>`	`http://localhost:5005`	Gateway base URL.
`--token <CREDENTIAL>`	(ambient)	Gateway API credential. Required when `--url` is not the local gateway.
`--format <FORMAT>`	`table`	Output format: `table` or `json`.

Credentials are never sent to a remote host implicitly (issue #2747). The CLI's ambient credential is attached only when the target is loopback. Point --url at any non-loopback host and the command is refused unless you supply --token explicitly, so a local gateway secret cannot leak to an overridden URL.

Subcommands

Command	Description
`list`	List conversations (optionally filtered by agent).
`inspect <ID>`	Show metadata, participants, and bindings for a conversation.
`archive <ID>`	Archive a conversation.

conversation list

List conversations known to the gateway. Pass --agent to restrict the list to a single agent.

botnexus conversation list
botnexus conversation list --agent assistant
botnexus conversation list --format json

Option	Default	Description
`--agent <ID>`	(all)	Filter conversations by agent ID.

Table output shows the (truncated) conversation ID, owning agent, title, and last-updated timestamp.

conversation inspect

Show full details for one conversation, including status, timestamps, participants, and binding count.

botnexus conversation inspect c_7d3196db3c8940959c8c1a19456cc1e4
botnexus conversation inspect c_7d3196db3c8940959c8c1a19456cc1e4 --format json

Argument	Description
`<ID>`	Conversation ID to inspect.

If the conversation does not exist, the command prints a warning and exits with code 1.

conversation archive

Archive a conversation. Archived conversations are removed from the active list but their history is preserved.

botnexus conversation archive c_7d3196db3c8940959c8c1a19456cc1e4

Argument	Description
`<ID>`	Conversation ID to archive.

Returns exit code 1 if the conversation is not found or the gateway is unreachable.

session

Manage the lifecycle of sessions — the durable transcript records the platform accumulates.

Every session subcommand operates through the gateway's session store abstraction, the same seam the gateway itself writes through, resolved from gateway.sessionStore in config.json. It does not open sessions.db directly and it does not require a running gateway. This matters: the store enforces invariants a hand-written SQL statement cannot — archiving drains any agent run bound to the session before sealing it, and deleting removes the transcript rows alongside the session row.

botnexus debug sessions is a different command and stays a read-only offline dump that opens the SQLite file directly for diagnostics. Use session for anything that changes state.

Usage

botnexus session <COMMAND> [OPTIONS]

Subcommand	Description
`list`	List sessions via the session store.
`archive <ID>`	Archive (seal) a session, preserving its transcript.
`delete <ID>`	Permanently delete a session and its transcript.

Archive vs. delete

These are not two strengths of the same operation — they have different outcomes and different reversibility:

	`session archive <ID>`	`session delete <ID>`
Transcript	Preserved.	Removed.
Session row	Sealed — kept, no longer accepts new turns.	Gone.
Still visible to `session list`	Yes, with status `Sealed`.	No.
Reversible	Effectively — the data is still there.	No.
Repeating the command	Idempotent: succeeds and changes nothing.	Reports not found, exit code `1`.

Archive when a conversation is finished but its history still matters. Delete only when the transcript itself must not survive.

session list

botnexus session list
botnexus session list --agent farnsworth
botnexus session list --limit 50 --format json

Option	Default	Description
`--agent <ID>`	(all)	Filter by agent ID.
`--limit <N>`	`20`	Maximum sessions to show, newest-updated first.
`--format <FMT>`	`table`	`table` or `json`.

session archive

Seals the session in place. The transcript is retained and the session stops accepting new turns.

botnexus session archive s_09e5891862a14a4c91dd61a2046df733

Argument	Description
`<ID>`	Exact session ID to archive.

Idempotent. Archiving a session that is already archived succeeds (exit code 0) and leaves the session exactly as it was, including its UpdatedAt timestamp — safe to run from a retrying script.

session delete

Permanently removes the session and its transcript. There is no undo.

botnexus session delete s_09e5891862a14a4c91dd61a2046df733

Argument	Description
`<ID>`	Exact session ID to delete.

Delete requires one explicit id and refuses ambiguous selectors. An empty or whitespace-only id, an id containing a wildcard or pattern character (*, ?, %), a comma-separated list, or any id containing whitespace is rejected with exit code 2 and nothing is deleted. Bulk and pattern-based deletion is deliberately unsupported: an over-matching glob against session transcripts is not recoverable.

Exit codes

Code	Meaning
`0`	Succeeded (including an already-archived session).
`1`	Session not found, or the config/session store could not be opened.
`2`	Refused — empty or ambiguous selector. Nothing was changed.

config get

Read a configuration value by its dotted key path. The command resolves the active backend automatically: it works for a legacy JSON-only home, a SQLite-backed home with no JSON file, and a transitional home containing both.

Usage

botnexus config get <KEY> [OPTIONS]

Arguments

Argument	Description
`<KEY>`	Dotted path to config value (e.g., `gateway.listenUrl`, `agents.assistant.model`).

Options

Option	Description
`--verbose`	Show additional context.

Examples

Get the gateway listen URL:

botnexus config get gateway.listenUrl

Output:

http://localhost:5005

Get an agent's model:

botnexus config get agents.assistant.model

Output:

gpt-4.1

Get a nested value:

botnexus config get gateway.defaultAgentId

Output:

assistant

config set

Set a configuration value by its dotted key path. The value is type-checked against the platform model, then written through the shared configuration writer to whichever persistent backend is active. The command syntax is identical for JSON and SQLite.

Usage

botnexus config set <KEY> <VALUE> [OPTIONS]

Arguments

Argument	Description
`<KEY>`	Dotted path to config value (e.g., `gateway.listenUrl`).
`<VALUE>`	New value (as a string). For booleans, use `true` or `false`.

Options

Option	Description
`--verbose`	Show the updated value after setting.

Examples

Change the default agent:

botnexus config set gateway.defaultAgentId coder

Output:

Set gateway.defaultAgentId = coder

Change the gateway listen URL:

botnexus config set gateway.listenUrl http://localhost:8080

Output:

Set gateway.listenUrl = http://localhost:8080

Enable an agent:

botnexus config set agents.coder.enabled true

Output:

Set agents.coder.enabled = true

Disable an agent:

botnexus config set agents.reviewer.enabled false

Output:

Set agents.reviewer.enabled = false

config backups list

List the retained config.json backups with a validity verdict. Every mutation of config.json - through the CLI, the portal, or the gateway - first copies the current document into ~/.botnexus/backups/; the newest 50 are retained. Before this command those artefacts were write-only: visible on disk with no supported way to evaluate them.

Usage

botnexus config backups list [OPTIONS]

Options

Option	Default	Description
`--target`	-	Home directory to read the backups of, instead of the default `~/.botnexus`.
`--verbose`	-	Verbose output.

Each row carries the backup id, its timestamp, the trigger reason, its size, and a verdict describing whether the snapshot still loads against the current schema:

Verdict	Meaning
`valid`	Parses and passes current-schema validation. Safe to restore.
`needs-migration`	Parses, but only validates after the legacy-key migration pipeline runs. Still restorable - `config restore` migrates before it validates - so the bytes on disk are not what gets written.
`unloadable`	Does not parse as JSON, or fails validation even after migration. Cannot be restored; the restore path refuses it rather than writing a file the gateway cannot load.

Examples

botnexus config backups list

An empty backups directory is a normal state, not a failure: the command prints No config backups found. and exits 0.

config restore

Validate and restore a config.json backup produced by the automatic backup path.

Usage

botnexus config restore <id> [OPTIONS]

Arguments

Argument	Description
`id`	Backup id as printed by `botnexus config backups list`.

Options

Option	Default	Description
`--commit`	(off)	Actually perform the restore. Without this the restore is previewed and nothing is written.
`--target`	-	Home directory whose `config.json` is restored.
`--verbose`	-	Print the resolved config path after a successful restore.

Restore is a dry run unless you pass --commit. The commit flag is opt-in rather than a --dry-run opt-out because this is the one config command whose stated purpose is to discard the current document: a mistyped id yields a preview, not an overwritten config.

The restore is validated, not a file copy, and that difference is the point:

A snapshot that fails validation is refused. Nothing is written and config.json is left byte-for-byte unchanged, so a bad backup cannot leave the gateway unable to start.
Redacted secrets do not overwrite live ones. A snapshot taken from a redacted view can contain *** placeholders; the restore resolves each back to the value currently on disk.
The pre-restore document is backed up first, so a restore is itself undoable.
The write goes through the normal config writer, so it is atomic and holds the cross-process config lock. When another process holds that lock the command refuses rather than writing without it.

Exit codes

Code	Condition
`0`	The restore succeeded, or the dry run completed and reported what would happen.
`1`	The restore was refused - unknown id, an `unloadable` snapshot, or the config lock was held by another process. In every case the existing config is unmodified.

Examples

Preview (default):

botnexus config restore config-20260101-101500-before-provider-update

Perform the restore:

botnexus config restore config-20260101-101500-before-provider-update --commit

Only config.json is covered. Sessions, the cron store, and memory are separate stores with their own lifecycles and are not restored by this command. Copying a file out of ~/.botnexus/backups/ by hand skips every protection above - use this command instead.

config schema

Generate a JSON schema file for the platform configuration model.

Usage

botnexus config schema [OPTIONS]

Options

Option	Default	Description
`--output`	`docs\botnexus-config.schema.json`	Output file path for the generated schema.
`--verbose`	—	Show the generated schema content.

Examples

Generate schema (default path):

botnexus config schema

Output:

Generated schema: docs\botnexus-config.schema.json

Custom output path:

botnexus config schema --output my-schema.json

config store

Manage the SQLite configuration store (config.db). When the store is enabled it serves configuration to the gateway and its values win over config.json; the file stays on disk and is never modified by these commands.

Usage

botnexus config store <COMMAND> [OPTIONS]

Subcommands

Subcommand	Description
`enable`	Create `config.db` from the current `config.json`. The store then serves configuration, with its values winning over the file.
`status`	Report whether the store exists and how many entries it holds.
`disable`	Delete `config.db`. The gateway returns to file-only configuration on the next start.

Options

Option	Default	Description
`--target`	resolved config directory	Directory holding `config.json`; the store is placed alongside it.

Behaviour

enable reads the raw JSON document rather than a bound config object. Binding collapses "key absent" and "key present and null" into the same null, and the store records those two states distinctly — populating from a bound object would silently rewrite every deliberate null as an absence.
enable reports how many entries were imported and requires a gateway restart to take effect. It exits 1 if config.json is missing (run botnexus init first) or is not a JSON object.
status exits 0 in both states: it prints Configuration store not enabled. when config.db is absent, and the entry count plus the store-wins note when it is present.
disable needs no --commit flag and prompts for nothing — unlike config restore, which overwrites the source document. The store is a derived copy of config.json, which is left untouched, so a disable discards nothing that config store enable cannot regenerate. Disabling an absent store is a no-op that exits 0.

Examples

Enable the store:

botnexus config store enable

Output:

Configuration store enabled. ~/.botnexus/config.db
  184 entries imported from config.json.
  Restart the gateway for the store to take effect.

Check status:

botnexus config store status

Return to file-only configuration:

botnexus config store disable

secret

Manage the built-in sqlite: secret store — the only credential backend BotNexus itself owns, and therefore the only one it can populate. Secrets stored here are referenced from a location's credentialRef as sqlite:<name>.

Aliased as secrets.

Usage

botnexus secret <subcommand> [name] [--target <path>]

Subcommands

Subcommand	Description
`set <name>`	Store a secret, reading the value from stdin. Overwrites an existing entry of the same name.
`list`	List stored secret names and their last-updated timestamps. Never prints values.
`remove <name>`	Remove a stored secret. Aliased as `rm`.

Options

Option	Description
`--target <path>`	BotNexus home directory to operate on. Defaults to the resolved home. The store lives beside it.
`--verbose`	Verbose output.

The value is never an argument

set takes only a name on the command line. The value is read from stdin — piped, or prompted for without echo when attached to a terminal. This is deliberate: anything passed as an argument lands in shell history, in ps output for the life of the process, and in any CI log that echoes its commands.

# piped (scripts, CI)
'my-api-key' | botnexus secret set contoso-api

# prompted, no echo (interactive)
botnexus secret set contoso-api

There is deliberately no `get`

BotNexus resolves a secret at the moment it needs one. A command whose entire purpose is to print a credential to a terminal is a facility for exfiltrating it, so none is provided. Use the platform's own tooling if you genuinely need to read a value back.

list shows names and timestamps only:

botnexus secret list

Secrets (~/.botnexus/secrets.db)
  contoso-api  2026-08-28T09:14:02.1234567Z

File permissions

The store file is narrowed to owner-only access when it is first created — before any value is written into it — and the restriction is re-applied after every write, because SQLite recreates journal siblings as it goes and a guard-rail that only held for the file's first version would be worthless. list additionally warns when the store is readable by other users.

Exit codes

Code	Condition
`0`	Success. `list` also returns `0` when no store exists yet or the store is empty.
`1`	Empty name, no value supplied, `remove` of a name that is not present, no store for `remove`, or a SQLite read/write failure.

Servers, credentials and agents — the credentialRef model and the other resolver schemes (env:, file:, keyring:)
locations — registering the servers that reference these secrets

gateway

Manage the BotNexus Gateway lifecycle: start, stop, status, restart. For foreground/development mode, use serve or serve gateway instead.

Usage

botnexus gateway <COMMAND> [OPTIONS]

Subcommands

Command	Description
`start`	Start the gateway process (detached by default)
`stop`	Stop the gateway process
`status`	Check gateway process status
`restart`	Restart the gateway process
`install`	Install the gateway as an OS service
`uninstall`	Remove the OS service registration

gateway start

Start the gateway process in detached (background) mode. Builds the solution first unless --skip-build is passed.

Option	Default	Description
`--port <PORT>`	`5005`	Port to listen on
`--source <DIR>`	`~/botnexus`	Path to the BotNexus repository root
`--attached`	off	Run in foreground instead of detached mode
`--skip-build`	off	Skip the implicit solution rebuild before starting

# Start detached on default port
botnexus gateway start

# Start on custom port, skip build
botnexus gateway start --port 8080 --skip-build

# Start in foreground (like serve)
botnexus gateway start --attached

Detached startup waits up to 60 seconds for the effective --port health endpoint to become ready. With --verbose, readiness diagnostics include the endpoint, timeout, elapsed duration, and whether the process became healthy, exited, or remained alive but unhealthy.

gateway stop

Stop the running gateway process.

botnexus gateway stop

gateway status

Check whether the gateway process is running.

botnexus gateway status

gateway restart

Stop and restart the gateway process.

Option	Default	Description
`--port <PORT>`	`5005`	Port to listen on
`--source <DIR>`	`~/botnexus`	Path to the BotNexus repository root

botnexus gateway restart
botnexus gateway restart --port 8080

gateway install

Install the gateway as an OS-managed service for automatic startup. Supports:

Windows — Windows Service (via sc.exe)
Linux — systemd unit file
macOS — launchd plist

Option	Default	Description
`--port <PORT>`	`5005`	Port for the service to listen on
`--source <DIR>`	`~/botnexus`	Path to the BotNexus repository root

# Install as Windows Service
botnexus gateway install

# Install with custom port
botnexus gateway install --port 8080

After installation, manage the service with standard OS tools (sc, systemctl, launchctl).

Service environment variables — what BotNexus owns

The service environment is a shared surface. Operators legitimately add entries to it (on Windows, the Environment REG_MULTI_SZ value under HKLM\SYSTEM\CurrentControlSet\Services\BotNexus; on Linux, Environment= lines in /etc/systemd/system/botnexus.service) — typically to supply a secret without putting it in config.json.

BotNexus owns only these keys, and rewrites them on every install or repair:

Key	Platform	Value written
`BOTNEXUS_HOME`	Windows, Linux, macOS	The resolved BotNexus home directory
`ASPNETCORE_URLS`	Windows, Linux, macOS	`http://localhost:<port>`
`DOTNET_ENVIRONMENT`	Linux (systemd unit)	`Production`

Every other environment entry is preserved. Installation reads the existing value first, replaces only the owned keys in place (never duplicating them), and writes back the union — so an operator-set entry such as a provider API key survives reinstallation. If the environment write fails (for example, reg.exe returns non-zero because the command was not run elevated), the install reports failure rather than silently continuing with a partially configured service.

gateway uninstall

Remove the OS service registration.

botnexus gateway uninstall

provider

Show provider status or start the setup wizard. When run without a subcommand, shows configured providers if any exist, otherwise launches the setup wizard.

Usage

botnexus provider [OPTIONS]

Options

Option	Description
`--verbose`	Show full provider configuration JSON.

Examples

Check provider status:

botnexus provider

If no providers are configured, this automatically starts the setup wizard.

provider setup

Interactive wizard that walks you through adding and authenticating a new LLM provider.

The wizard:

Asks which provider to configure (GitHub Copilot, OpenAI, or Anthropic)
Authenticates — OAuth device code flow for Copilot, API key prompt for others
Presents available models and lets you pick a default
Saves the provider through the active configuration backend (and OAuth tokens to auth.json)

Usage

botnexus provider setup [OPTIONS]

Options

Option	Description
`--target <DIR>`	BotNexus home directory (config, workspace, extensions). Defaults to `~/.botnexus`.
`--provider <NAME>`	Pre-select the provider (`github-copilot`, `openai`, or `anthropic`) and skip the interactive provider-selection prompt. Useful for scripting and integration tests where the rest of the flow (API-key prompt, OAuth device-code flow) is still exercised but the first prompt is suppressed.
`--verbose`	Show the saved provider configuration in JSON.

Examples

Set up GitHub Copilot (OAuth):

botnexus provider setup

Example session:

? Which provider do you want to configure?
> GitHub Copilot (OAuth — free with GitHub account)
  OpenAI (API key required)
  Anthropic (API key required)

Configuring github-copilot...

──────────── GitHub Authorization Required ────────────
  1. Open: https://github.com/login/device
  2. Enter code: ABCD-1234
────────────────────────────────────────────────────────

✓ OAuth credentials saved to auth.json

? Select a default model:
> gpt-4.1 — GPT-4.1
  claude-sonnet-4.5 — Claude Sonnet 4.5
  gpt-5.4 — GPT-5.4
  ...

Default model: gpt-4.1

✓ Provider github-copilot configured successfully.
  Config saved to: C:\Users\<YourName>\.botnexus\config.json

Set up OpenAI (API key):

botnexus provider setup

Select "OpenAI" and enter your API key when prompted. The provider setting is written through the active configuration backend.

provider list

List all configured providers in a table.

Usage

botnexus provider list [OPTIONS]

Options

Option	Description
`--verbose`	Show additional detail.

Examples

List providers:

botnexus provider list

Example output:

┌─────────────────┬─────────┬───────┬───────────────┬─────────┐
│ Provider        │ Enabled │ Auth  │ Default Model │ Base URL│
├─────────────────┼─────────┼───────┼───────────────┼─────────┤
│ github-copilot  │ Yes     │ OAuth │ gpt-4.1       │ default │
│ openai          │ Yes     │ sk-…  │ gpt-4o        │ default │
└─────────────────┴─────────┴───────┴───────────────┴─────────┘

provider add

Add or update a provider entry in config.json non-interactively. Designed for scripts, CI, and integration tests that need to configure providers without the interactive wizard.

When a provider with the given --name already exists, only the flags you pass are updated; unspecified fields preserve their previous values. To clear a previously-set value, pass an empty string explicitly.

Usage

botnexus provider add --name <NAME> [OPTIONS]

Options

Option	Description
`--name <NAME>`	Required. Provider name (e.g. `openai`, `integration-mock`).
`--api <API>`	API contract this provider handles. One of `openai-completions` (default), `openai-responses`, `anthropic-messages`, `integration-mock`.
`--api-key <KEY>`	API key value, or `auth:<name>` to reference an OAuth entry in `auth.json`.
`--base-url <URL>`	Base URL for OpenAI-compatible endpoints, or catalog file path for `integration-mock`.
`--default-model <ID>`	Default model id for this provider.
`--model <ID>`	Allowed model id. Repeatable. Omit to allow all models registered for this provider.
`--disabled`	Add the provider in disabled state. Disabled providers are hidden from the API.
`--target <PATH>`	BotNexus home directory. Defaults to `~/.botnexus`.
`--verbose`	Print the serialized provider entry after save.

Examples

Add an OpenAI provider:

botnexus provider add --name openai --api-key sk-... --default-model gpt-4o

Add the integration-mock provider for tests (uses built-in HELLO_WORLD catalog):

botnexus provider add --name integration-mock --api integration-mock --default-model integration-mock-echo

Add an OpenAI-compatible local endpoint with a restricted model list:

botnexus provider add --name local-vllm `
    --api openai-completions `
    --base-url http://localhost:8000/v1 `
    --api-key not-needed `
    --model llama-3-8b --model llama-3-70b `
    --default-model llama-3-8b

provider remove

Remove a provider entry from config.json non-interactively. Returns exit code 0 even if the named provider does not exist (idempotent).

Usage

botnexus provider remove --name <NAME> [OPTIONS]

Options

Option	Description
`--name <NAME>`	Required. Provider name to remove.
`--target <PATH>`	BotNexus home directory. Defaults to `~/.botnexus`.
`--verbose`	Print remaining provider count after removal.

Examples

botnexus provider remove --name integration-mock

provider copilot

Diagnostic and auth helper subcommands for the GitHub Copilot provider. These give operators a fast surface to check authentication, list entitled models, inspect quota, and confirm end-to-end connectivity without round-tripping through the gateway. Useful for debugging the GitHub Copilot Provider integration.

Usage

botnexus provider copilot <COMMAND> [OPTIONS]

Subcommands

Command	Description
`login`	Authenticate to GitHub Copilot via the device code flow (alias for `provider setup --provider github-copilot`)
`whoami`	Show the authenticated Copilot user, plan, endpoint, and token expiry
`models`	List the Copilot models the authenticated user is entitled to invoke
`quota`	Show current Copilot quota snapshots (chat, completions, premium interactions)
`test`	Round-trip a single request through the Copilot provider to confirm connectivity

All subcommands accept the global --target <PATH> option to point at a non-default BotNexus home directory.

provider copilot login

Authenticate via GitHub's device code flow. This is an alias for botnexus provider setup --provider github-copilot, so the device-code flow stays authoritative in one place.

botnexus provider copilot login

provider copilot whoami

Show the authenticated user, plan, SKU, API endpoint, and session token expiry. Run this first if models reports no cached endpoint.

botnexus provider copilot whoami

provider copilot models

List the models your account is entitled to, including vendor, family, and capability flags (streaming, tools, vision, premium).

botnexus provider copilot models

provider copilot quota

Show current quota snapshots with remaining percentage, entitlement, and reset date.

botnexus provider copilot quota

provider copilot test

Send a single prompt through the Copilot provider end-to-end and report latency (total and time-to-first-token).

botnexus provider copilot test
botnexus provider copilot test --model gpt-5-mini --prompt "Respond with the single word: ok."

Option	Default	Description
`--model <ID>`	`gpt-5-mini`	Copilot model id to round-trip
`--prompt <TEXT>`	`Respond with the single word: ok.`	Prompt to send

See GitHub Copilot Provider for full setup and configuration details.

provider ollama

Diagnostic subcommands for local Ollama instances. Verifies connectivity, lists pulled models, and tests inference without requiring a running gateway.

Usage

botnexus provider ollama <COMMAND> [OPTIONS]

Subcommands

Command	Description
`status`	Check Ollama server connectivity and version
`models`	List models available on the local instance
`test`	Send a test prompt to verify model inference

provider ollama status

botnexus provider ollama status
botnexus provider ollama status --url http://192.168.1.100:11434

Option	Default	Description
`--url <URL>`	`http://localhost:11434`	Ollama server URL

provider ollama models

botnexus provider ollama models

Option	Default	Description
`--url <URL>`	`http://localhost:11434`	Ollama server URL

provider ollama test

Send a simple chat completion request to verify end-to-end inference.

botnexus provider ollama test --model llama3

Option	Default	Description
`--url <URL>`	`http://localhost:11434`	Ollama server URL
`--model <ID>`	(required)	Model to test

See Ollama Provider for full setup and configuration details.

prompt

Manage prompt templates — define reusable, parameterized prompts in configuration and execute them through the CLI or cron scheduler.

Getting Started: Run botnexus prompt create samples to copy bundled sample templates into ~/.botnexus/prompts/, then customize them for your workflows.

Format Guide:

.prompt.md (recommended for multi-line prompts) — YAML front matter + Markdown body for readable, maintainable templates
.prompt.json (supported for compatibility and machine-generated) — Single-file JSON format for simple prompts

Usage

botnexus prompt [COMMAND] [OPTIONS]

Subcommands

list — List available prompt templates
render — Render a template to stdout (substitute parameters)
run — Render and execute a template against the gateway
create samples — Copy bundled sample templates into ~/.botnexus/prompts/

prompt list

List all available prompt templates for an agent.

Displays templates from two sources:

Configuration-based templates — Defined in config.json under promptTemplates
File-based templates — Stored in ~/.botnexus/prompts/ directory as .prompt.md or .prompt.json files

Usage

botnexus prompt list [OPTIONS]

Options

Option	Description
`--agent <ID>`	Target agent ID. Falls back to `gateway.defaultAgentId` if not specified.
`--config <PATH>`	Explicit path to `config.json`. Defaults to `~/.botnexus/config.json`.
`--target <DIR>`	BotNexus home directory (config, workspace, extensions). Defaults to `~/.botnexus/`.
`--verbose`	Show full paths and template metadata.

Examples

List templates for the default agent:

botnexus prompt list

Output:

daily-standup
weekly-status
code-review-summary
customer-feedback-analysis

List templates for a specific agent:

botnexus prompt list --agent analyst

Verbose output with descriptions:

botnexus prompt list --verbose

prompt render

Render a template to stdout, substituting parameters with caller-provided values or defaults.

Use this to preview what a template will produce before executing it through the gateway.

Usage

botnexus prompt render <TEMPLATE> [OPTIONS]

Arguments

Argument	Description
`<TEMPLATE>`	Template name to render.

Options

Option	Description
`--param <KEY=VALUE>`	Template parameter as `key=value`. Repeat for multiple values.
`--agent <ID>`	Target agent ID. Falls back to `gateway.defaultAgentId` if not specified.
`--config <PATH>`	Explicit path to `config.json`. Defaults to `~/.botnexus/config.json`.
`--target <DIR>`	BotNexus home directory (config, workspace, extensions). Defaults to `~/.botnexus/`.
`--verbose`	Show rendering metadata (agent, parameters used).

Examples

Render a template with default parameters:

botnexus prompt render daily-standup

Output:

Provide a brief status update for the engineering team.
Project: BotNexus
Owner: Development Team
Format: Markdown

Render with custom parameter values:

botnexus prompt render weekly-status --param project=Infrastructure --param owner="Leela"

Output:

Provide a weekly status update for the Infrastructure team.
Project: Infrastructure
Owner: Leela

Multiple parameters:

botnexus prompt render code-review-summary `
  --param repo=botnexus `
  --param prNumber=242 `
  --param reviewer=Hermes

Capture rendered template to a file:

botnexus prompt render daily-standup > prompt.txt

prompt run

Render a template and send the result to the gateway for agent execution.

Combines template rendering with agent invocation in a single command. Useful for triggering agent workflows from scripts or cron jobs.

Usage

botnexus prompt run <TEMPLATE> [OPTIONS]

Arguments

Argument	Description
`<TEMPLATE>`	Template name to render and execute.

Options

Option	Description
`--param <KEY=VALUE>`	Template parameter as `key=value`. Repeat for multiple values.
`--agent <ID>`	Target agent ID. Falls back to `gateway.defaultAgentId` if not specified. Supplying the flag with a blank value is an error (issue #3739).
`--session <ID>`	Optional session ID for conversation continuity. If omitted, a new session is created. Supplying the flag with a blank value is an error (issue #3739).
`--config <PATH>`	Explicit path to `config.json`. Defaults to `~/.botnexus/config.json`.
`--target <DIR>`	BotNexus home directory (config, workspace, extensions). Defaults to `~/.botnexus/`.
`--gateway-url <URL>`	Override gateway URL. Defaults to `gateway.listenUrl` from config (or `http://localhost:5005`).
`--token <CREDENTIAL>`	Gateway API credential. Required when `--gateway-url` is not the local gateway (issue #2747).
`--verbose`	Show rendering and execution details.

Examples

Execute a template with default parameters:

botnexus prompt run daily-standup

Output:

[Agent response...]
Engineering team is on track with all Q1 deliverables. 
Three items in progress, two completed this week.

Execute with custom parameters:

botnexus prompt run weekly-status --param project=Gateway --param owner=Bender

Execute within an existing session (conversation continuity):

botnexus prompt run daily-standup --session my-session-123

Blank selectors are rejected, not ignored:

Omitting --agent or --session is fine and keeps the fallback behaviour above. Passing either flag with an empty or whitespace-only value - what an unset shell variable expands to - fails with a non-zero exit before the turn is dispatched, rather than silently running against the default agent or a freshly minted session the caller has no id for.

# $SESSION_ID is unset: refused instead of starting an invisible new session
botnexus prompt run daily-standup --session "$SESSION_ID"
# Error: --session was supplied but is blank. Pass a value, or omit the flag entirely.

Execute against a non-default gateway:

botnexus prompt run daily-standup --gateway-url http://production.example.com:5005 --token $env:REMOTE_GATEWAY_KEY

As with every gateway-facing command, the ambient local credential is attached only for a loopback target. An overridden, non-loopback --gateway-url requires an explicit --token (issue #2747).

Verbose execution:

botnexus prompt run code-review-summary --param repo=botnexus --verbose

Output includes:

[dim]Rendering template 'code-review-summary' with agent 'assistant'...[/]
[dim]Rendered template and invoked http://localhost:5005/api/chat[/]
[Agent response...]

satellite

Manage satellite nodes — remote presence points that extend BotNexus to additional machines (desktop notifications, canvas windows, remote command execution).

Usage

botnexus satellite <COMMAND> [OPTIONS]

Subcommands

Command	Description
`list`	List all registered satellites
`register`	Register a new satellite and generate its API key
`remove`	Remove a satellite registration

satellite list

List all registered satellites with their status and capabilities.

botnexus satellite list

satellite register

botnexus satellite register <NAME> --owner <USER_ID> [OPTIONS]

Argument/Option	Required	Description
`<NAME>`	Yes	Satellite ID (e.g., `sat_desktop_home`)
`--owner <ID>`	Yes	Owner user ID
`--display-name <NAME>`	No	Human-readable display name
`--platform <OS>`	No	Platform: `windows`, `macos`, `linux` (default: `windows`)
`--capabilities <LIST>`	No	Comma-separated capabilities: `notify`, `canvas`, `exec` (default: `notify,canvas`)

# Register a Windows desktop satellite
botnexus satellite register sat_desktop_home --owner jon --display-name "Home Desktop"

# Register with exec capability
botnexus satellite register sat_workstation --owner jon --capabilities notify,canvas,exec

The generated API key is displayed once after registration. Store it securely — it cannot be retrieved later.

satellite remove

Remove a satellite registration. The satellite's API key is immediately invalidated.

botnexus satellite remove <NAME>

doctor

Run the complete CLI diagnostic suite against your BotNexus configuration, providers, and environment. The bare command executes every registered check in a deterministic order, prints a section per check, and ends with a healthy/warning/error summary plus a script-friendly aggregate exit code (0 = all healthy, 1 = any warning, 2 = any error). Independent checks always run to completion even after one reports a finding. Focused subcommands remain for targeted runs.

Usage

botnexus doctor [OPTIONS]

Options

Option	Description
`--target <DIR>`	BotNexus home directory. Defaults to `~/.botnexus`.
`--verbose`	Show detailed check output.
`--cleanup-orphans`	After the diagnostic suite, reconcile persistent agent workspaces and delete orphaned directories. Prompts when interactive; in a non-interactive terminal nothing is deleted without this flag.

Subcommands

Command	Description
`locations`	Check that every resolved BotNexus location (config, logs, sessions, agents) is accessible.
`config`	Guided config migration — detect and optionally apply missing settings. See doctor config.
`agents`	Reconcile persistent agent workspaces with the configured agents. See doctor agents.

Examples

# Run all diagnostics
botnexus doctor

# Check a specific instance
botnexus doctor --target /opt/botnexus-prod

# Verify location accessibility
botnexus doctor locations

# Run diagnostics, then reconcile and delete orphaned agent workspaces
botnexus doctor --cleanup-orphans

Checks in the aggregate suite

The suite is the ordered registry below - cheap configuration checks first, then filesystem and reconciliation checks - so scripted output and the final summary are stable across runs. Adding a check to the registry automatically includes it in the bare doctor run, so a diagnostic can never be silently omitted by a hardcoded parent handler.

Check	Id	Reports
Configuration health	`config`	Validity of `config.json` and the settings the migration checks cover.
World identity	`world-identity`	The resolved world ID alongside the resolved home path, so several gateways on one machine can be told apart. A home that has not started yet has no ID; that is reported as a warning, not an error, because one is generated on next start. This check never writes.
Secret file permissions	`secret-file-permissions`	Whether secret files are readable by more than their owner.
Location accessibility	`locations`	That every resolved location (config, logs, sessions, agents) is accessible. Also available on its own as `doctor locations`.
Persistent agent folders	`agent-folders`	That persistent agent workspaces match the configured agents. Also available on its own as `doctor agents`.
Sub-agent workspaces	`subagent-workspaces`	Health of the sub-agent workspace root.

The id column is not decoration: it is the id the check reports, and a test fence diffs these ids against the generated registry, so a check added to the code without a row here fails the build.

doctor config

Guided config migration. Compares your existing config.json against a set of built-in checks, reports any missing or outdated settings, and optionally applies the fixes in place. Operates offline — no running gateway required.

Current checks are:

Check	Id	Reports
Extensions block	`extensions-block`	The `gateway.extensions` block is absent or has extensions disabled.
Skills world default	`skills-world-default`	The Skills extension has no world-level default in `gateway.extensions.defaults`.
Cron configuration	`cron-enabled`	The cron scheduler block is absent from config.
Memory agent default	`memory-agent-default`	The `agents.defaults.memory` block is absent, so memory indexing is not enabled by default.
Compaction model	`compaction-model`	`gateway.compaction.summarizationModel` names an expensive reasoning model, which may fail or waste tokens on a summarization call.
Compaction model missing	`compaction-model-missing`	`gateway.compaction.summarizationModel` is not configured, so the compactor falls back to the default model waterfall.
Dev-mode origin enforcement	`devmode-origin-enforcement`	The gateway runs keyless (dev mode) with the browser-Origin guard disabled, leaving the `gateway-dev` admin identity reachable from any web origin.
Feature flag seeding	`feature-flags-explicit`	One or more declared feature flags are absent from config, so their state is an unstated decision that cannot be read back from the file. Seeding writes the documented default, so applying it changes no behaviour.

Advisories

Separately from the checks above, doctor config reports advisories: findings an operator should see but which the tool must never rewrite. Advisories have no fix to apply and are unaffected by --yes.

Advisory	Reports
`gateway-wildcard-bind`	`gateway.listenUrl` binds a wildcard address (`0.0.0.0`, `*`, `+`, `::`), publishing the portal UI, the SignalR hub, the agent REST API and the gateway admin endpoints to every reachable network. A wildcard bind can be a deliberate choice for remote or mesh access, so it is reported and left unchanged.
`feature-flags-unknown-key`	The `featureManagement` block contains a key that matches no declared feature flag - typically a misspelling or a flag that has since been retired. An unrecognised key evaluates as absent, so the setting reads as configured while doing nothing. Not removed automatically: the right correction is to fix the spelling or delete the key, and only its author knows which.

Usage

botnexus doctor config [OPTIONS]

Options

Option	Description
`--yes`	Apply all applicable fixes without prompting.
`--dry-run`	Report what would change but do not write anything.
`--target <DIR>`	BotNexus home directory. Defaults to `~/.botnexus`.
`--verbose`	Show detailed output for each check.

Without --yes or --dry-run, the command prompts before applying each fix. The config file is only modified when a fix is applied.

Examples

# Detect gaps and prompt before each fix
botnexus doctor config

# Preview changes without writing
botnexus doctor config --dry-run

# Apply every applicable fix non-interactively
botnexus doctor config --yes

doctor agents

Reconcile the persistent agent workspaces under the resolved agents root against the enabled agents declared in config.json. The command prints the reconciliation plan — which workspace directories correspond to configured agents and which are orphaned — and only deletes orphans when deletion has been explicitly approved.

The same read-only reconciliation check runs as part of the aggregate doctor suite, so drift is always reported even when nothing is removed.

Usage

botnexus doctor agents [OPTIONS]

Options

Option	Description
`--cleanup-orphans`	Delete orphaned persistent agent workspaces. Prompts for confirmation when interactive; without this flag a non-interactive run is strictly non-destructive.
`--target <DIR>`	BotNexus home directory. Defaults to `~/.botnexus`.

Without --cleanup-orphans, the command reports the plan and exits without deleting anything.

Each directory is listed with its total size on disk and the date of its newest file, so an orphan can be judged before it is deleted, and the orphan lines are followed by a total. Deletion always re-derives registration from config.json at deletion time and refuses any directory whose id is registered, so a stale or hand-built plan can never remove a live agent's workspace or memory store.

Examples

# Report workspace drift without deleting anything
botnexus doctor agents

# Reconcile and remove orphaned workspaces
botnexus doctor agents --cleanup-orphans

locations

Manage the locations entries in config.json — named references to filesystem paths, APIs, MCP servers, databases, and remote nodes that agents and extensions can resolve by name. The command has the alias location.

Usage

botnexus locations <COMMAND> [OPTIONS]

Subcommands

Command	Description
`list`	List all registered locations.
`add`	Add a location to `config.json`.
`update`	Update an existing location.
`delete`	Delete a location from `config.json` (alias `remove`).

Options

Option	Applies to	Description
`name` (argument)	`add`, `update`, `delete`	The location name.
`--type <TYPE>`	`add`	Location type: `filesystem`, `api`, `mcp-server`, `database`, `remote-node`. Required.
`--path <PATH>`	`add`, `update`	Filesystem path or primary location path. Required on `add`.
`--endpoint <URL>`	`add`, `update`	Endpoint URL for `api`/`mcp-server`/`remote-node` locations.
`--connection-string <STR>`	`add`	Connection string for `database` locations (redacted in `list` output).
`--description <TEXT>`	`add`, `update`	Human-readable description.
`--target <DIR>`	all	BotNexus home directory. Defaults to `~/.botnexus`.
`--verbose`	all	Show the resolved config file path.

Examples

# List configured locations
botnexus locations list

# Add a filesystem location
botnexus locations add docs --type filesystem --path "C:\repos\docs" --description "Docs repo"

# Add an MCP-server location
botnexus locations add weather --type mcp-server --path "weather" --endpoint "http://localhost:9000"

# Update a location's path
botnexus locations update docs --path "D:\repos\docs"

# Delete a location
botnexus locations delete docs

To see the resolved paths for BotNexus home directories (config, logs, sessions), use debug gateway config or inspect ~/.botnexus directly.

update

Pull the latest source, build, deploy extensions, and restart the BotNexus gateway. Run without a subcommand to perform the full update; use the check subcommand to see whether updates are available without applying them.

Usage

botnexus update [COMMAND] [OPTIONS]

Subcommands

Command	Description
`check`	Check whether updates are available from `origin/main` (does not apply them).

Options

Option	Applies to	Description
`--source <DIR>`	`update`, `check`	Path to the BotNexus repository root. Defaults to `~/botnexus`.
`--port <PORT>`	`update`	Gateway port to restart against. Defaults to `5005`.
`--stash`	`update`	If the repo has uncommitted changes, stash them to a named, recoverable stash and continue.
`--force`	`update`	If the repo has uncommitted changes, discard tracked-file changes and continue. Destructive.
`--verbose`	`update`, `check`	Show detailed update output.

--stash and --force cannot be combined (exit code 2).

Uncommitted changes in the deployment repo

The repo that update pulls into (~/botnexus by default) is a deployed artifact, not a development worktree, so local edits there are usually accidental. Before pulling, update runs git status --porcelain and acts on the result:

Clean - proceeds normally. Untracked files are reported but never block the update.
Dirty, interactive - lists every dirty path and prompts: stash / discard / abort.
Dirty, non-interactive - exits 3 with the dirty file list and copy-pasteable remediation. Nothing is modified.

--stash saves the work as botnexus-update-<timestamp> and prints the git stash apply command to restore it. The stash is not re-applied automatically after the pull, because a silent re-apply is how you get a surprise conflict in the middle of a gateway restart.

Pull failures are classified (dirty tree / diverged / auth / network / other) and each gets its own remediation line instead of a raw git error.

Exit Codes (for `update`)

Code	Meaning
`0`	Update applied
`2`	Conflicting options (`--stash` with `--force`)
`3`	Deployment repo has uncommitted changes; nothing was modified
`130`	Cancelled

Exit Codes (for `update check`)

Code	Meaning
`0`	Up to date
`1`	Updates available
`2`	Check failed

Examples

# Check for updates without applying
botnexus update check

# Pull, build, and restart the gateway
botnexus update

# Update when the deployment repo has local edits you want to keep
botnexus update --stash

# Update and throw away local edits in the deployment repo
botnexus update --force

memory

Memory store operations from the CLI.

Usage

botnexus memory <COMMAND> [OPTIONS]

Subcommands

Command	Description
`backfill`	Index conversation turns from existing sessions into the per-agent memory stores.

Options

Option	Description
`--agent <ID>`	Backfill only this agent. If omitted, backfill all agents.
`--target <DIR>`	BotNexus home directory. Defaults to `~/.botnexus`.
`--verbose`	Show detailed (debug-level) indexing output.

The session store type is resolved from gateway.sessionStore in config.json; only Sqlite and File session stores support backfill.

Examples

# Backfill memory for all agents from existing sessions
botnexus memory backfill

# Backfill a single agent
botnexus memory backfill --agent assistant

To browse memory files on disk for an agent, use debug memory.

cron (command) {#cron-command}

Manage cron jobs from the CLI.

Usage

botnexus cron <COMMAND> [OPTIONS]

Subcommands

Command	Description
`list`	List all configured cron jobs.
`get`	Show details for a single cron job.
`run`	Manually trigger a job immediately.
`enable`	Enable a disabled job.
`disable`	Disable a job.
`delete`	Delete a cron job.

Each subcommand takes a --url <URL> option pointing at the running gateway (defaults to http://localhost:5005) and a --token <CREDENTIAL> option; get, run, enable, disable, and delete take the job ID as their positional argument.

Jobs are addressed by ID, never by name. The argument is passed straight through to GET|PUT|DELETE /api/cron/{jobId}; there is no name lookup, so a job's name is a display label only and passing one returns not found. IDs created through the cron tool or the API are generated 32-character hex GUIDs; jobs declared in config.json use their cron.jobs map key as the ID, which is why a config-declared job can have a readable ID such as morning-briefing. Run botnexus cron list and copy the value from its ID column.

As with every gateway-facing command, the ambient credential is attached only for a loopback --url. An overridden, non-loopback --url requires an explicit --token (issue #2747).

Examples

# List all cron jobs - the ID column holds the value every other subcommand takes
botnexus cron list

# Show details for a single job (job ID, not name)
botnexus cron get 8f2c1d4ea77b4f039c5e6b81a0d2f7c3

# Trigger a job manually
botnexus cron run 8f2c1d4ea77b4f039c5e6b81a0d2f7c3

# Disable then delete a job
botnexus cron disable 8f2c1d4ea77b4f039c5e6b81a0d2f7c3
botnexus cron delete 8f2c1d4ea77b4f039c5e6b81a0d2f7c3

For offline scheduler diagnostics (status, history, missed runs) that do not need a running gateway, use debug cron.

subagent workspace

Inspect and reclaim temporary workspace directories left by completed or interrupted sub-agent runs. The command reconciles directories under the OS temporary folder with persisted sub_agent_sessions records; it never deletes a workspace belonging to a running sub-agent. Persisted session records and transcripts are retained.

The top-level command also accepts the alias subagents, and workspace accepts the alias workspaces.

Usage

botnexus subagent workspace <COMMAND> [OPTIONS]

Subcommands

Command	Description
`list`	List sub-agent workspace directories, their persisted status, and whether each is prunable.
`prune`	Delete workspaces for terminal sub-agents (`completed`, `failed`, `killed`, or `timed-out`) and orphaned directories with no persisted record. Running workspaces are retained.

Options

Option	Applies to	Description
`--dry-run`	`prune`	Show which directories would be deleted without deleting them.
`--target <DIR>`	all	BotNexus home directory used to locate the session store. Defaults to `~/.botnexus`. When omitted, the configured data directory (`BOTNEXUS_DATA_DIR`) is searched first, since that is where the gateway writes `sessions.sqlite`. Both `sessions.sqlite` and legacy `sessions.db` are accepted.

Examples

# Inspect accumulated sub-agent workspaces
botnexus subagent workspace list

# Preview safe reclamation
botnexus subagent workspace prune --dry-run

# Delete terminal and orphaned workspaces
botnexus subagent workspace prune

debug sessions

Directly inspect the sessions SQLite database without requiring a running gateway. Useful for offline diagnostics.

Usage

botnexus debug sessions <COMMAND> [OPTIONS]

Subcommands

Command	Description
`list`	List all sessions with summary info
`get`	Show details for a specific session
`compaction`	Show compaction history for a session
`stats`	Database-wide statistics

Options

Option	Default	Description
`--target <DIR>`	`~/.botnexus`	BotNexus home directory
`--format`	`table`	Output format: `table` or `json`

Examples

# List sessions
botnexus debug sessions list

# Get session details
botnexus debug sessions get --id "session-abc123"

# Show compaction history
botnexus debug sessions compaction --id "session-abc123"

# Database statistics
botnexus debug sessions stats

# JSON output for scripting
botnexus debug sessions list --format json

debug logs

Directly inspect log files without requiring a running gateway. Reads the hourly Serilog structured log files.

Usage

botnexus debug logs <COMMAND> [OPTIONS]

Subcommands

Command	Description
`tail`	Show the most recent log entries
`errors`	Filter to ERROR and FATAL entries
`search`	Search log content by text
`session <SESSION-ID>`	Filter logs for a specific session

Global options

Option	Default	Description
`--target <DIR>`	`~/.botnexus`	BotNexus home directory
`--format`	`table`	Output format: `table` or `json`

Per-subcommand options

--limit is the entry cap and its default differs per subcommand. There is no --lines option.

Subcommand	Option	Default	Description
`tail`	`--limit <N>`	`50`	Maximum lines to return
`tail`	`--level <LEVEL>`	(none)	Filter by level: `debug`, `info`, `warn`, `error`
`errors`	`--limit <N>`	`20`	Maximum error lines to return
`search`	`--term <TEXT>`	required	Keyword to search for
`search`	`--since <ISO>`	(none)	Only search log files after this datetime
`search`	`--limit <N>`	`50`	Maximum matching lines to return
`session`	`<session-id>`	required	Positional argument: the session ID to search for
`session`	`--limit <N>`	`100`	Maximum matching lines to return

Examples

# Tail recent logs
botnexus debug logs tail

# Tail the last 200 warnings
botnexus debug logs tail --limit 200 --level warn

# Show recent errors
botnexus debug logs errors

# Search for a pattern
botnexus debug logs search --term "timeout"

# Search only recent log files
botnexus debug logs search --term "timeout" --since 2026-09-01T00:00:00

# Filter by session (positional argument, not an option)
botnexus debug logs session "session-abc123"

debug memory

Inspect agent memory directories — daily notes, the consolidated MEMORY.md, and on-disk usage — without requiring a running gateway. Reads each agent's workspace/memory/ folder and workspace/MEMORY.md file directly.

Usage

botnexus debug memory [OPTIONS]

Options

Option	Default	Description
`--target <DIR>`	`~/.botnexus`	BotNexus home directory
`--agent <ID>`	(all)	Show a detailed view for a single agent, including a per-file daily-note breakdown
`--format`	`table`	Output format: `table` or `json`

The summary view lists every agent that has a memory directory or MEMORY.md, with the MEMORY.md size, daily-note count, most recent note, and total size. Passing --agent switches to a detailed per-agent view.

Examples

# Summary of memory usage across all agents
botnexus debug memory

# Detailed view for a single agent
botnexus debug memory --agent assistant

# JSON output for scripting
botnexus debug memory --format json

debug db

Directly inspect raw SQLite databases in the BotNexus home directory. Useful for understanding schema and diagnosing storage issues.

Discovery covers every registered platform store, not just files ending in .db. BotNexus mixes two SQLite file extensions — .db (sessions, data/skill-usage) and .sqlite (cron, webhooks, per-agent memory) — and keeps some databases in a data/ subfolder. All of these are enumerated automatically, so debug db tables should be your first-line investigation tool instead of hand-rolled sqlite3 scripts.

Usage

botnexus debug db <COMMAND> [OPTIONS]

Subcommands

Command	Description
`tables`	List tables in a database
`schema`	Show column definitions for a table
`size`	Show database file sizes

Options

Option	Default	Description
`--target <DIR>`	`~/.botnexus`	BotNexus home directory
`--db <NAME>`	(all)	Filter to a specific database by name — `sessions`, `cron`, `webhooks`, `skill-usage` (extension optional)
`--include-agents`	off	Also include per-agent memory databases (`agents/<id>/data/memory.sqlite`)
`--format`	`table`	Output format: `table` or `json`

--format is a debug db group option, so it goes before the subcommand: botnexus debug db --format json tables.

Examples

# List all registered databases and their sizes (cron, webhooks, sessions, skill-usage)
botnexus debug db size

# List every table with row counts across all registered databases
botnexus debug db tables

# Show tables in a single database (bare name works for .db and .sqlite alike)
botnexus debug db tables --db cron

# Include per-agent memory stores in the sweep
botnexus debug db tables --include-agents

# Dump schema as JSON for scripting
botnexus debug db --format json schema --db sessions

debug gateway

Connect to a running BotNexus gateway and query live diagnostics via its REST API.

Usage

botnexus debug gateway <COMMAND> [OPTIONS]

Subcommands

Command	Description
`status`	Show gateway health, thread-pool diagnostics, and last-activity info
`sessions`	Show session statistics (totals and per-agent breakdown)
`providers`	List registered providers and their model counts
`config`	Dump resolved gateway configuration (secrets redacted)

Options

These options apply to every debug gateway subcommand:

Option	Default	Description
`--url <URL>`	`http://localhost:5005`	Gateway base URL
`--token <CREDENTIAL>`	(ambient)	Gateway API credential. Required when `--url` is not the local gateway (issue #2747).
`--format`	`table`	Output format: `table` or `json`

Per-subcommand options:

Subcommand	Option	Default	Description
`sessions`	`--agent <ID>`	(all)	Filter session stats by agent ID
`sessions`	`--limit <N>`	`20`	Maximum sessions to return
`config`	`--section <NAME>`	(all)	Filter output to a single config section

Examples

# Check if the gateway is reachable and healthy
botnexus debug gateway status

# Show session statistics in JSON
botnexus debug gateway sessions --format json

# Session stats for one agent
botnexus debug gateway sessions --agent assistant

# Dump only the gateway config section
botnexus debug gateway config --section gateway

# Query a remote gateway
botnexus debug gateway providers --url http://192.168.1.100:5005

debug cron

Inspect the cron scheduler state including job status, execution history, and missed runs.

Usage

botnexus debug cron <COMMAND> [OPTIONS]

Subcommands

Command	Description
`status`	Show scheduler state and per-job next/last run
`history`	Show execution history for a job
`missed`	List runs detected as missed on startup

Options

Option	Default	Description
`--target <DIR>`	`~/.botnexus`	BotNexus home directory
`--job <ID>`	(all)	Filter to a specific job
`--limit <N>`	20	Maximum history entries
`--format`	`table`	Output format: `table` or `json`

Examples

# Show all job status
botnexus debug cron status

# View history for a specific job (filters on cron_runs.job_id - job ID, not name)
botnexus debug cron history --job 8f2c1d4ea77b4f039c5e6b81a0d2f7c3 --limit 10

# List missed runs
botnexus debug cron missed

Examples

Quick Setup Flow

1. Clone and build:

botnexus install --build

2. Initialize home directory:

botnexus init

3. Set up a provider:

botnexus provider setup

4. List default agents:

botnexus agent list

5. Validate configuration:

botnexus validate

6. Start the gateway:

botnexus serve

Configuration Workflow

Change the listening port:

# Update config
botnexus config set gateway.listenUrl http://localhost:8080

# Validate
botnexus validate

# Restart gateway (required for port changes)
.\scripts\start-gateway.ps1 -Port 8080

Manage multiple agents:

# List current agents
botnexus agent list

# Add a new agent
botnexus agent add researcher --provider openai --model gpt-4o

# Switch the default agent
botnexus config set gateway.defaultAgentId researcher

# Verify
botnexus agent list
botnexus validate

Tips & Tricks

Dotted Key Paths

Configuration keys use dotted notation: section.subsection.key

# Gateway settings
botnexus config get gateway.listenUrl
botnexus config get gateway.defaultAgentId

# Agent settings
botnexus config get agents.assistant.model
botnexus config get agents.assistant.enabled

Hot Reload

Most config changes are applied immediately when the Gateway is running:

Agent properties (enabled, model, provider)
Provider settings
Default agent ID

⚠️ Requires restart:

gateway.listenUrl (port binding)

Config File Location

config.json lives in the BotNexus home directory, and the path is the same on every platform:

Resolution step	Path
1. Explicit `--target <PATH>`	`<PATH>/config.json`
2. `BOTNEXUS_HOME` environment variable	`$env:BOTNEXUS_HOME/config.json`
3. Default	`~/.botnexus/config.json` (`%USERPROFILE%\.botnexus\config.json` on Windows)

The first match wins. There is no Windows-specific %LOCALAPPDATA% config location — %LOCALAPPDATA%\BotNexus is where the release installer puts binaries, not configuration.

config.json is a flat top-level document with camelCase keys and no BotNexus wrapper — the same shape the dotted keys above address (gateway.listenUrl → {"gateway": {"listenUrl": ...}}). See Canonical document shape and location for the binding rules.

Override with environment variable:

$env:BOTNEXUS_HOME = "C:\custom\botnexus"
botnexus agent list

Exit Codes

Most commands return:

0 — Success
1 — Error (check console output for details)

botnexus update check uses status-style exit codes for automation:

0 — Up to date
1 — Updates available
2 — Check failed (for example, git fetch error)

FilesExpand file tree

cli-reference.md

Latest commit

History

cli-reference.md

File metadata and controls

BotNexus CLI Reference

Setting up the botnexus alias

PowerShell (Windows / cross-platform)

Bash / Zsh (macOS / Linux)

Verify

Table of Contents

Global Options

--target <DIR>

--verbose (or -v)

install

Usage

Options

Examples

build

Usage

Options

Repo resolution

Examples

serve

Usage

serve / serve gateway

serve probe

Examples

Production vs. development

validate

Usage

Options

Examples

init

Usage

Options

Examples

agent list

Usage

Options

Examples

agent add

Usage

Arguments

Options

Examples

agent show

Usage

Arguments

Options

Examples

Exit codes

agent remove

Usage

Arguments

Options

Examples

agent wizard

Usage

Options

Examples

agent export

Usage

Options

Examples

Output shape

agent import

Usage

Options

Examples

Required secrets

agent exec

Syntax

Options

Exit codes

Examples

Approval posture

conversation

Usage

Setting up the `botnexus` alias

`--target <DIR>`

`--verbose` (or `-v`)

There is deliberately no `get`