Skip to content

8.7. CLI Reference

The bgo CLI tool provides command-line access to the Backend.AI GO Management API. Use this tool to manage local models, control inference servers, monitor system resources, and interact with loaded models from the terminal.

Installation

The CLI is included with the Backend.AI GO distribution. If you are building from source:

cd cli
cargo install --path .

Usage

bgo [OPTIONS] <COMMAND>

Global Options

Option Short Environment Variable Description
--endpoint -e BACKEND_AI_GO_ENDPOINT Management API endpoint (URL or configured name).
--token -t BACKEND_AI_GO_TOKEN API authentication token.
--output -o BACKEND_AI_GO_OUTPUT Output format: console, json, yaml.
--quiet -q Suppress non-essential output.
--verbose -v Enable verbose output.
--no-verify-ssl Skip SSL certificate verification.

Commands

config - Configuration Management

Manage CLI configuration settings.

  • bgo config path: Show configuration file path.
  • bgo config get <KEY>: Get a configuration value.
  • bgo config set <KEY> <VALUE>: Set a configuration value.
  • bgo config list: List all configuration values.
  • bgo config reset: Reset configuration to defaults.

model - Local Model Management

Manage models stored on the local disk.

  • bgo model list: List all local models.
  • bgo model info <MODEL_ID>: Get detailed information about a specific model.
  • bgo model refresh: Refresh the model index (scan for new files).

loaded - Loaded Model Operations

Control models currently loaded into memory for inference.

  • bgo loaded list: List currently loaded models.
  • bgo loaded info <ID>: Get details of a loaded model instance.
  • bgo loaded load [OPTIONS] <MODEL_ID>: Load a model into memory.
    • Options:
      • -c, --context-length <INT>: Override context length.
      • -g, --gpu-layers <INT>: Number of layers to offload to GPU (-1 for all).
      • -t, --threads <INT>: Number of threads to use.
      • -a, --alias <STRING>: Model alias for routing.
      • --tool-calling: Enable tool calling capabilities.
      • --mmproj <PATH>: Path to mmproj file for vision models.
  • bgo loaded unload <ID>: Unload a model to free resources.
  • bgo loaded health <ID>: Check the health status of a loaded model.

router - Router Control

Manage the Continuum Router service.

  • bgo router status: Get the current status of the router.
  • bgo router start: Start the router service.
  • bgo router stop: Stop the router service.
  • bgo router restart: Restart the router service.

system - System Monitoring

Monitor hardware resources and API status.

  • bgo system info: Get general system information (OS, Architecture).
  • bgo system metrics: Get current system metrics (CPU, RAM usage).
  • bgo system gpu: Get detailed GPU information.
  • bgo system health: Check the overall API health.
  • bgo system version: Get the API server version.

Examples

List all available models in JSON format: 

bgo model list -o json

Load a model with custom GPU layers: 

bgo loaded load "gemma-3n-E4B-it-Q4_K_M" --gpu-layers 33

Check system GPU status: 

bgo system gpu