Metadata-Version: 2.4
Name: open-webui-admin
Version: 0.1.1
Summary: Open WebUI admin CLI tool
License: MIT
License-File: LICENSE
Author: Mikke Schirén
Requires-Python: >=3.11,<4.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: click (>=8.4.1,<9.0.0)
Requires-Dist: httpx (>=0.28.1,<0.29.0)
Description-Content-Type: text/markdown

# Open WebUI Admin

![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13-blue) [![Tests & Coverage](https://github.com/Digitalist-Open-Cloud/Open-WebUI-Admin/actions/workflows/tests.yaml/badge.svg)](https://github.com/Digitalist-Open-Cloud/Open-WebUI-Admin/actions/workflows/tests.yaml) [![Security](https://github.com/Digitalist-Open-Cloud/Open-WebUI-Admin/actions/workflows/security.yaml/badge.svg)](https://github.com/Digitalist-Open-Cloud/Open-WebUI-Admin/actions/workflows/security.yaml)

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, if you want to work with the models etc.
I recommend to use another tool, like [owui-cli](https://github.com/rndmcnlly/owui-cli).

## 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 |
| `tika test` | Test Tika file processing integration |
| `tika test --path <file>` | Test with a specific file |
| `tika test --json` | Output test results as JSON |

## Installation

```bash
pip install open-webui-admin
```

Or install from source:

```bash
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):

```bash
open-webui-admin models list
```

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

```bash
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:

```bash
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:

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

Check if a model is valid:

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

Check with provider/URL info:

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

Get models configuration:

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

Verify a single model works:

```bash
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):

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

Verify all available models:

```bash
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:

```bash
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:

```bash
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:

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

Verify custom with debug output:

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

Verify a specific custom model:

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

### connections

Verify external connections (OpenAI, Ollama):

```bash
open-webui-admin connections verify
```

### config

Get OpenAI configuration:

```bash
open-webui-admin config get --name openai
```

Get OpenAI configuration as JSON:

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

Get Ollama configuration:

```bash
open-webui-admin config get --name ollama
```

Get Ollama configuration as JSON:

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

Export all configuration:

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

### users

Get all users:

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

Get all users in JSON format:

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

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

```bash
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):

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

### images
List available image models:
```bash
open-webui-admin images list
```
### knowledge
List all knowledge bases:
```bash
open-webui-admin knowledge list
```
Show knowledge base details:
```bash
open-webui-admin knowledge show <id>
```
List files in a knowledge base:
```bash
open-webui-admin knowledge files <id>
```
Create a new knowledge base:
```bash
open-webui-admin knowledge create --name "My KB" --description "Optional desc"
```
Delete a knowledge base:
```bash
open-webui-admin knowledge delete <id>
```
Add a file to a knowledge base:
```bash
open-webui-admin knowledge add-file <id> <file-id>
```
Remove a file from a knowledge base (destroys the file):
```bash
open-webui-admin knowledge remove-file <id> <file-id>
```
Add all files from a local folder to a knowledge base (uploads + adds):
```bash
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:
```bash
open-webui-admin files list
```
Show file details:
```bash
open-webui-admin files show <id>
```
Upload a file:
```bash
open-webui-admin files upload /path/to/file.pdf
```
Delete a file:
```bash
open-webui-admin files delete <id>
```
### audio

List available audio models:

```bash
open-webui-admin audio models
```

List available voices:

```bash
open-webui-admin audio voices
```

### banners

Get current banners:

```bash
open-webui-admin banners get
```

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

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

Set a non-dismissible banner:

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

Clear all banners:

```bash
open-webui-admin banners clear
```

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

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

### tika

Test Tika file processing integration by uploading a PDF and verifying the content extraction pipeline works end-to-end. If no file is specified, it looks for `test-artifacts/tika-test.pdf`:

```bash
open-webui-admin tika test
# Output:
# [1/4] Uploaded 'tika-test.pdf' -> id: abc123
# [2/4] Processing complete (attempt 1)
# [3/4] Retrieved content: 4253 chars

# === Tika test: PASSED ===
# File ID: abc123
#   [OK] upload
#   [OK] processing
#   [OK] content
#   [OK] verification
```

Test with a specific file:

```bash
open-webui-admin tika test --path /path/to/test.pdf
```

Output test results as JSON for scripting:

```bash
open-webui-admin tika test --json
# Output:
# {
#   "result": "success",
#   "file_id": "abc123",
#   "steps": { ... }
# }
```

The test performs 4 steps:
1. **Upload** - Uploads the file with processing enabled via `/api/v1/files/`
2. **Process** - Polls `/api/v1/files/{id}/process/status` (up to 10 attempts) waiting for completion
3. **Retrieve** - Fetches extracted content from `/api/v1/files/{id}/data/content`
4. **Verify** - Confirms extracted content is meaningful (>10 chars)

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

```bash
poetry install
```

Run tests:

```bash
poetry run pytest
```

Run tests with coverage:

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

Run CLI directly:

```bash
poetry run open-webui-admin --help
```

Build package:

```bash
poetry build
```

