CLI

The private-gpt CLI covers the full service lifecycle: starting the HTTP server, launching background workers, and running connected apps like Claude Code.

private-gpt <command> [flags]
Commands:
  serve     Start the HTTP server
  worker    Start a background worker process
  run       Launch a connected app (claude-code, openclaw, custom)
  help      Show help for any command

serve

Starts the uvicorn HTTP server.

$
private-gpt serve [flags]

Examples:

$
# Start with defaults
$
private-gpt serve
$
$
# Development mode with auto-reload
$
private-gpt serve --reload --log-level debug
$
$
# Production with PID file for process supervision
$
private-gpt serve --pid-file /var/run/private-gpt.pid

PID file behavior: if --pid-file is given and the file already exists with a live process, the command exits with code 1 and prints the existing PID. On SIGTERM the PID file is removed.

worker

Starts the Celery worker stack. All behaviour is controlled through environment variables — no CLI flags.

$
private-gpt worker

The worker process manages up to three sub-processes depending on PGPT_WORKER_MODE:

Examples:

$
# Default: worker + Flower UI
$
private-gpt worker
$
$
# Worker only, no Flower
$
PGPT_WORKER_MODE=worker private-gpt worker
$
$
# Custom concurrency and queues
$
PGPT_CELERY_QUEUES=ingest,chat PGPT_CELERY_CONCURRENCY=4 private-gpt worker

run

Launches a connected app as a managed child process, automatically injecting the server connection details.

See the Integrations section for app-specific setup guides.

$
private-gpt run <app> [flags] [-- <app-args>]

Server auto-start: before launching the app, private-gpt run checks /health. If the server is not reachable it starts one automatically and waits up to 60 s. Pass --no-server to skip this — useful when the server is managed externally (systemd, Docker).

help

Show help for any command:

$
private-gpt help
$
private-gpt help serve
$
private-gpt serve --help

Unknown commands print a suggestion:

$ private-gpt srve
Unknown command: 'srve'. Did you mean: 'serve'?