BotNexus CLI Reference

The botnexus command-line tool provides quick access to configuration and agent management without editing config.json manually.

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 remove — Remove an agent
config get — Read a config value
config set — Set a config value
config schema — Generate JSON schema
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
prompt — Manage prompt templates
prompt list — List available prompt templates
prompt render — Render a prompt template
prompt run — Render and execute a prompt template
Examples

Global Options

All commands support these options:

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

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.
`--verbose`	Show the full default configuration in JSON format.

Examples

First-time initialization:

botnexus init

Expected output:

Initialized BotNexus home at: C:\Users\<YourName>\AppData\Local\BotNexus
Created config: C:\Users\<YourName>\AppData\Local\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>\AppData\Local\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'.

config get

Read a configuration value by its dotted key path.

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.

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

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 to config.json (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 key is stored directly in config.json.

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

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.
`--session <ID>`	Optional session ID for conversation continuity. If omitted, a new session is created.
`--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`).
`--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

Execute against a non-default gateway:

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

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

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

OS	Default Path
Windows	`%LOCALAPPDATA%\BotNexus\config.json`
macOS/Linux	`~/.botnexus/config.json`
Custom	`$env:BOTNEXUS_HOME/config.json`

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

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

config get

Usage

Arguments

Options

Examples

config set

Usage

Arguments

Options

Examples

config schema

Usage

Options

Examples

provider

Usage

Options

Examples

provider setup

Usage

Options

Examples

provider list

Setting up the `botnexus` alias

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