Open WebUI Admin

CLI tool for managing Open WebUI instances.

Very much a work in progress, and everyone is welcome to contribute.

Idea around this module is to use the existing API to simplify common tasks, checks etc. So you need to able to use the API and have an API key.

Focus on this tool is verification.

Commands Overview

Command	Description
models list	List all available models (standard + custom)
models list -v	List models with provider/connection info
models custom list	List custom/preset models with base_model_id
models custom list --name <model>	Show full JSON for a specific custom model
models check --name <model>	Check if model is valid
models check --name <model> -v	Check with provider/URL info
models verify --name <model>	Verify single model works
models verify --all	Verify all models
models verify --all -v	Verify all with provider/URL info
models verify --debug	Verify with debug output
models custom verify --all	Verify all custom models
models custom verify --name <model>	Verify a specific custom model
models custom verify -v	Verify custom with provider info
models custom verify --debug	Verify custom with debug output
models config	Get models configuration
connections verify	Verify external connections
config get --name openai|ollama	Get OpenAI or Ollama configuration
config get --json	Output config as JSON
config export	Export all configuration
users get --all	List all users
users get --all --json	List all users in JSON format
users get --include-email <regex>	Include users matching email pattern
users get --exclude-email <regex>	Exclude users matching email pattern
knowledge list	List all knowledge bases
knowledge show <id>	Show knowledge base details
knowledge files <id>	List files in a knowledge base
knowledge create --name <name>	Create a new knowledge base
knowledge delete <id>	Delete a knowledge base
knowledge add-file <id> <file-id>	Add file to knowledge base
knowledge remove-file <id> <file-id>	Remove file from knowledge base
knowledge add-folder <id> <folder>	Upload all files from folder to knowledge base
files list	List all files
files show <id>	Show file details
files upload <path>	Upload a file
files delete <id>	Delete a file
images list	List image models
audio models	List audio models
audio voices	List available voices
banners get	Get banners
banners set --type <type> --content <text>	Set a banner
banners set --dismissible	Set a dismissible banner
banners clear	Clear all banners

Installation

pip install open-webui-admin

Or install from source:

poetry install
poetry build
pip install dist/open_webui_admin-*.whl

Configuration

Set environment variables:

• OPENWEBUI_URL - Base URL of Open WebUI instance (e.g., https://open-webui.example.com)
• OPENWEBUI_TOKEN - Authentication token (from Account settings)

Commands

models

List all available models (standard + custom):

open-webui-admin models list

List with verbose output (shows provider and connection info):

open-webui-admin models list -v
# Output: model_id | provider | connection_type | urlIdx | url
# Example: gpt-5 | openai | external | 1 | https://api.openai.com/v1

List custom/preset models only:

open-webui-admin models custom list
# Output: model_id (base: base_model_id)
# Example: dada (base: gpt-4o)

Show full details for a specific custom model:

open-webui-admin models custom list --name dada
# Output: Full JSON for the model

Check if a model is valid:

open-webui-admin models check --name gpt-4o

Check with provider/URL info:

open-webui-admin models check --name gpt-4o -v

Get models configuration:

open-webui-admin models config
# Output: Full JSON models configuration

Verify a single model works:

open-webui-admin models verify --name gpt-4o
# Output: Model 'gpt-4o' is working
#        Model 'anthropic.claude-opus-4-6' is NOT working: authentication_error

Verify with debug output (shows full API response):

open-webui-admin models verify --name gpt-4o --debug

Verify all available models:

open-webui-admin models verify --all
# Output:
# Verifying 134 models...
# [OK] gpt-5
# [FAIL] anthropic.claude-opus-4-6 | authentication_error
# ...
# 58 models verified

Verify all with provider/URL info:

open-webui-admin models verify --all -v
# Output:
# [OK] gpt-5 | https://api.openai.com/v1
# [FAIL] anthropic.claude-opus-4-6 | https://api.anthropic.com/v1 | authentication_error

Verify all custom models:

open-webui-admin models custom verify --all
# Output:
# Verifying 10 custom models...
# [OK] dada
# [FAIL] test-model | error_message
# ...
# 10 custom models verified

Verify custom with provider info:

open-webui-admin models custom verify --all -v

Verify custom with debug output:

open-webui-admin models custom verify --name dada --debug

Verify a specific custom model:

open-webui-admin models custom verify --name dada
# Output: Model 'dada' is working

connections

Verify external connections (OpenAI, Ollama):

open-webui-admin connections verify

config

Get OpenAI configuration:

open-webui-admin config get --name openai

Get OpenAI configuration as JSON:

open-webui-admin config get --name openai --json

Get Ollama configuration:

open-webui-admin config get --name ollama

Get Ollama configuration as JSON:

open-webui-admin config get --name ollama --json

Export all configuration:

open-webui-admin config export
# Output: Full JSON configuration

users

Get all users:

open-webui-admin users get --all
# Output: user_id | name | email | role

Get all users in JSON format:

open-webui-admin users get --all --json

Include users matching email pattern (can be used multiple times):

open-webui-admin users get --all --include-email "@example.com"
open-webui-admin users get --all --include-email "@admin.com" --include-email "@test.com"

Exclude users matching email pattern (can be used multiple times):

open-webui-admin users get --all --exclude-email "@spam.com"

images

List available image models:

open-webui-admin images list

knowledge

List all knowledge bases:

open-webui-admin knowledge list

Show knowledge base details:

open-webui-admin knowledge show <id>

List files in a knowledge base:

open-webui-admin knowledge files <id>

Create a new knowledge base:

open-webui-admin knowledge create --name "My KB" --description "Optional desc"

Delete a knowledge base:

open-webui-admin knowledge delete <id>

Add a file to a knowledge base:

open-webui-admin knowledge add-file <id> <file-id>

Remove a file from a knowledge base (destroys the file):

open-webui-admin knowledge remove-file <id> <file-id>

Add all files from a local folder to a knowledge base (uploads + adds):

open-webui-admin knowledge add-folder <id> /path/to/folder
# With pattern matching (only PDFs)
open-webui-admin knowledge add-folder <id> /path/to/folder --pattern "*.pdf"
# Recursively upload from subfolders
open-webui-admin knowledge add-folder <id> /path/to/folder --recursive

files

List all files:

open-webui-admin files list

Show file details:

open-webui-admin files show <id>

Upload a file:

open-webui-admin files upload /path/to/file.pdf

Delete a file:

open-webui-admin files delete <id>

audio

List available audio models:

open-webui-admin audio models

List available voices:

open-webui-admin audio voices

banners

Get current banners:

open-webui-admin banners get

Set a banner (required: --type, --content):

open-webui-admin banners set --type Warning --title "System Update" --content "Maintenance scheduled"

Set a non-dismissible banner:

open-webui-admin banners set --type Warning --title "Alert" --content "Critical update" --dismissible

Clear all banners:

open-webui-admin banners clear

Options for --type: Info, Warning, Error, Success

Options for --dismissible: Flag (default: True)

Output Formats

models list -v

model_id | provider | connection_type | urlIdx | url

• provider: Inferred from model name or URL (e.g., openai, anthropic, pipeline, ollama)
• connection_type: external or local
• urlIdx: Index into configured API endpoints (see /openai/config)
• url: The actual API endpoint URL

models verify --all -v

[OK] model_name
[FAIL] model_name | error_message
[ERROR] model_name | status_code

models custom list

model_id (base: base_model_id)
model_id (no base model)

users get --all

user_id | name | email | role

Error Messages

• authentication_error - Invalid API key
• not_found - Model not found (404)
• not_chat_model - Model doesn't support chat completions endpoint
• server_error - Upstream provider error (500)
• timeout - Request timed out

Development

Install for development:

poetry install

Run tests:

poetry run pytest

Run tests with coverage:

poetry run pytest --cov=open_webui_admin --cov-report=term-missing

Run CLI directly:

poetry run open-webui-admin --help

Build package:

poetry build