> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.privategpt.dev/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.privategpt.dev/_mcp/server.

# CLI

> Manage the server, workers, and connected apps with the private-gpt 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.

```bash
private-gpt serve [flags]
```

| Flag          | Default       | Description                               |
| ------------- | ------------- | ----------------------------------------- |
| `--host`      | `0.0.0.0`     | Bind address                              |
| `--port`      | from settings | HTTP port                                 |
| `--reload`    | off           | Enable auto-reload for development        |
| `--log-level` | `info`        | `debug` \| `info` \| `warn` \| `error`    |
| `--pid-file`  | —             | Write PID to file (for systemd / launchd) |

**Examples:**

#### macOS / Linux

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

#### Windows (PowerShell)

```powershell
# 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 C:\ProgramData\private-gpt\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.

```bash
private-gpt worker
```

`PGPT_WORKER_MODE` is required and selects one registered worker runtime:

| `PGPT_WORKER_MODE` | What starts    |
| ------------------ | -------------- |
| `arq`              | ARQ worker     |
| `celery`           | Celery worker  |
| `flower`           | Flower UI only |

**Examples:**

#### macOS / Linux

```bash
PGPT_WORKER_MODE=celery private-gpt worker

# Custom concurrency and queues
PGPT_CELERY_QUEUES=ingest,chat PGPT_CELERY_CONCURRENCY=4 private-gpt worker
```

#### Windows (PowerShell)

```powershell
$env:PGPT_WORKER_MODE = "celery"
private-gpt worker

# Custom concurrency and queues
$env:PGPT_CELERY_QUEUES = "ingest,chat"
$env:PGPT_CELERY_CONCURRENCY = "4"
private-gpt worker
```

#### Windows (CMD)

```cmd
set PGPT_WORKER_MODE=celery
private-gpt worker

:: Custom concurrency and queues
set PGPT_CELERY_QUEUES=ingest,chat
set 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](/integrations/claude-code) section for app-specific setup guides.

```bash
private-gpt run <app> [flags] [-- <app-args>]
```

| Flag                     | Default             | Description                          |
| ------------------------ | ------------------- | ------------------------------------ |
| `--attach / --no-attach` | auto (TTY detected) | Attach stdin/stdout                  |
| `--detach`               | off                 | Run in background, print run ID      |
| `--session <id>`         | —                   | Resume a previous app session        |
| `--model <id>`           | `llm.default_model` | Model name (forwarded via env)       |
| `--auto-approve`         | off                 | Skip confirmations (CI mode)         |
| `--no-server`            | off                 | Skip server detection and auto-start |

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

```bash
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'?
```