openwebui-cli/README.md

OpenWebUI CLI

A command-line interface for OpenWebUI.

Note: This is a community project proposing what an official CLI could look like. Not currently affiliated with or endorsed by the OpenWebUI team. See docs/RFC.md for the full proposal.

Status: Alpha (v0.1.0) — tested, linted, ~90% coverage. Known limitations: OAuth/provider login and API key management are not implemented yet; models pull/delete depend on server support.

Features

• Authentication & token management (keyring + env + --token)
• Profiles for multiple OpenWebUI instances
• Chat with streaming/non-streaming modes, history, RAG context
• RAG files/collections (list, upload, delete, search)
• Model info/list (pull/delete supported when server supports it)
• Admin stats/users/config (admin role required)
• JSON/YAML/text output with Rich formatting

Installation

pip install openwebui-cli
# or from source
git clone https://github.com/dannystocker/openwebui-cli.git
cd openwebui-cli
pip install -e .

Requirements

• Python 3.11+
• OpenWebUI server reachable at your chosen --uri

Quick start

# 1) Init config (creates ~/.config/openwebui/config.yaml)
openwebui config init

# 2) Login (stores token in keyring, or use --token/OPENWEBUI_TOKEN)
openwebui auth login

# 3) Chat (streaming by default)
openwebui chat send -m llama3.2:latest -p "Hello from the CLI"

# 4) RAG search
openwebui rag search --query "deployment steps" --collection my-coll

Commands overview

Area	Examples	Notes
Auth	openwebui auth login, logout, whoami, token, refresh	Tokens via keyring/env/--token
Chat	openwebui chat send --prompt "Hello"	Streaming/non-streaming, RAG context
Models	openwebui models list, info MODEL_ID	Pull/delete currently placeholders
RAG	openwebui rag files list, collections list, search	Upload/search files & collections
Config	openwebui config init, show, set, get	Profiles, defaults, output options
Admin	openwebui admin stats, users, config	Admin-only endpoints (role required)

See docs/commands/README.md for a compact reference.

Global options (all commands)

Option	Description
-v, --version	Show version and exit
-P, --profile	Profile name to use
-U, --uri	Override server URI
--token	Bearer token (overrides env/keyring)
-f, --format	Output format: text, json, yaml
-q, --quiet	Suppress non-essential output
--verbose	Enable debug logging
-t, --timeout	Request timeout in seconds

Configuration

Config precedence: CLI flags → environment variables → config file → defaults.

• Config file: ~/.config/openwebui/config.yaml (Linux/macOS) or %APPDATA%\openwebui\config.yaml (Windows).
• Env vars: OPENWEBUI_PROFILE, OPENWEBUI_URI, OPENWEBUI_TOKEN.
• Tokens: stored in keyring (openwebui-cli service, key <profile>:<uri>). If no keyring backend, use --token or OPENWEBUI_TOKEN; in headless/CI, install keyrings.alt or rely on env.
• Example config:

version: 1
default_profile: default
profiles:
  default:
    uri: http://localhost:8080
defaults:
  model: llama3.2:latest
  format: text
  stream: true
  timeout: 30
output:
  colors: true
  progress_bars: true
  timestamps: false

More details: docs/guides/configuration.md.

Usage examples

• Set a default model (so you don’t pass -m each time):

  openwebui config set defaults.model llama3.2:latest
  openwebui chat send -p "Hello"  # uses the default model
  

• Non-streaming chat with JSON output:

  openwebui chat send -m my-model -p "Summarize" --no-stream --json
  

• Continue a conversation:

  openwebui chat send --chat-id CHAT123 -p "Tell me more"
  

• Shell completions:

  openwebui --install-completion bash
  openwebui --install-completion zsh
  openwebui --install-completion fish
  

• RAG file upload + search:

  openwebui rag files upload ./docs/*.pdf
  openwebui rag search --query "auth flow" --collection my-coll
  

• Use a different profile and token:

  openwebui --profile prod --token "$PROD_TOKEN" chat send -p "Ping prod"
  

Troubleshooting

• No keyring backend available: pass --token or set OPENWEBUI_TOKEN; or install keyrings.alt.
• 401/Forbidden: re-login openwebui auth login or refresh token; verify --uri and profile.
• Connection issues: check server is reachable; override with --uri; increase --timeout.
• Invalid history file: ensure JSON array or { "messages": [...] }.

Exit codes

Code	Meaning
0	Success
1	General error
2	Usage/argument error
3	Authentication error
4	Network error
5	Server error (5xx)

Development

python -m venv .venv
. .venv/bin/activate
pip install -e ".[dev]"
ruff check openwebui_cli
mypy openwebui_cli --ignore-missing-imports
pytest tests/ --cov=openwebui_cli

Contributing and community

• Contribution guide: CONTRIBUTING.md
• Code of Conduct: CODE_OF_CONDUCT.md
• Security policy: SECURITY.md
• RFC: docs/RFC.md

License

MIT License - see LICENSE.

Note on license: OpenWebUI itself uses a modified BSD-3-Clause license with branding requirements. This CLI uses MIT for simplicity as a community tool. If the OpenWebUI team were interested in official adoption, we'd happily relicense to match their terms.

Credits

Created and maintained by Danny Stocker at if.