0
# Command Line Interface
1
2
Command-line tools for running WSGI applications directly from the shell, with extensive configuration options and comprehensive help documentation.
3
4
## Capabilities
5
6
### Main Command-Line Entry Point
7
8
The primary function for running waitress from the command line, processing arguments and serving applications.
9
10
```python { .api }
11
def run(argv=None, _serve=serve):
12
"""
13
Command-line entry point for waitress-serve.
14
15
Parameters:
16
- argv (list): Command-line arguments (default: sys.argv)
17
- _serve (callable): Serve function to use (default: waitress.serve)
18
19
Returns:
20
int: Exit code (0 for success, non-zero for error)
21
22
Raises:
23
SystemExit: On argument parsing errors or application import failures
24
"""
25
```
26
27
### Help Documentation
28
29
Functions for displaying comprehensive help information and error details.
30
31
```python { .api }
32
def show_help(stream, name, error=None):
33
"""
34
Display complete help text with all available options.
35
36
Parameters:
37
- stream: Output stream (sys.stdout, sys.stderr, etc.)
38
- name (str): Program name for help display
39
- error (str): Optional error message to display first
40
41
Returns:
42
None
43
"""
44
45
def show_exception(stream):
46
"""
47
Display import exception details for troubleshooting.
48
49
Parameters:
50
- stream: Output stream for error display
51
52
Returns:
53
None
54
"""
55
```
56
57
### Console Script Usage
58
59
The `waitress-serve` console script is installed with the package and provides full command-line access.
60
61
```bash
62
# Basic usage
63
waitress-serve myapp:application
64
65
# With configuration options
66
waitress-serve --host=127.0.0.1 --port=8080 --threads=6 myapp:app
67
68
# Unix socket (Linux/macOS)
69
waitress-serve --unix-socket=/tmp/app.sock myapp:app
70
71
# Call factory function
72
waitress-serve --call myapp:create_app
73
74
# Display help
75
waitress-serve --help
76
```
77
78
### Available Command-Line Options
79
80
Complete list of supported command-line parameters for server configuration.
81
82
```python { .api }
83
# Standard options:
84
--help # Show help information
85
--call # Call the given object to get WSGI app
86
87
# Network configuration:
88
--host=ADDR # Hostname/IP to bind (default: 0.0.0.0)
89
--port=PORT # TCP port to bind (default: 8080)
90
--listen=ip:port # Listen on specific ip:port (can be repeated)
91
--[no-]ipv4 # Toggle IPv4 support
92
--[no-]ipv6 # Toggle IPv6 support
93
--unix-socket=PATH # Unix domain socket path
94
--unix-socket-perms=PERMS # Unix socket permissions (octal, default: 600)
95
96
# Performance tuning:
97
--threads=INT # Number of worker threads (default: 4)
98
--backlog=INT # Socket listen backlog (default: 1024)
99
--recv-bytes=INT # Socket receive buffer size (default: 8192)
100
--send-bytes=INT # Socket send buffer size (default: 18000)
101
--connection-limit=INT # Max concurrent connections (default: 100)
102
103
# Request limits:
104
--max-request-header-size=INT # Max request header size (default: 262144)
105
--max-request-body-size=INT # Max request body size (default: 1073741824)
106
107
# Timeouts:
108
--channel-timeout=INT # Idle connection timeout (default: 120)
109
--cleanup-interval=INT # Connection cleanup interval (default: 30)
110
111
# Proxy configuration:
112
--trusted-proxy=IP # Trusted proxy IP address
113
--trusted-proxy-count=INT # Number of trusted proxies
114
--trusted-proxy-headers=LIST # Trusted proxy headers (space-separated)
115
116
# URL handling:
117
--url-scheme=STR # Default URL scheme (default: http)
118
--url-prefix=STR # SCRIPT_NAME prefix
119
120
# Debugging and logging:
121
--expose-tracebacks # Show Python tracebacks to clients
122
--ident=STR # Server identification string (default: waitress)
123
124
# Buffer configuration:
125
--inbuf-overflow=INT # Input buffer overflow size (default: 512000)
126
--outbuf-overflow=INT # Output buffer overflow size (default: 1048576)
127
```
128
129
### Usage Examples
130
131
Common command-line usage patterns for different deployment scenarios.
132
133
#### Basic Application Serving
134
135
```bash
136
# Serve a Flask app
137
waitress-serve --host=127.0.0.1 --port=5000 myflaskapp:app
138
139
# Serve a Django app (requires DJANGO_SETTINGS_MODULE)
140
export DJANGO_SETTINGS_MODULE=myproject.settings
141
waitress-serve --port=8000 myproject.wsgi:application
142
143
# Serve with app factory
144
waitress-serve --call --host=0.0.0.0 --port=8080 myapp:create_app
145
```
146
147
#### Performance Configuration
148
149
```bash
150
# High-performance setup
151
waitress-serve \
152
--threads=8 \
153
--connection-limit=1000 \
154
--recv-bytes=16384 \
155
--backlog=2048 \
156
myapp:application
157
158
# Development setup with debugging
159
waitress-serve \
160
--host=127.0.0.1 \
161
--port=5000 \
162
--threads=1 \
163
--expose-tracebacks \
164
myapp:app
165
```
166
167
#### Proxy and Load Balancer Setup
168
169
```bash
170
# Behind nginx reverse proxy
171
waitress-serve \
172
--host=127.0.0.1 \
173
--port=8080 \
174
--trusted-proxy=127.0.0.1 \
175
--trusted-proxy-headers="x-forwarded-for x-forwarded-proto" \
176
--url-scheme=https \
177
myapp:app
178
179
# Multiple proxy layers (e.g., Cloudflare + nginx)
180
waitress-serve \
181
--trusted-proxy-count=2 \
182
--trusted-proxy-headers="x-forwarded-for x-forwarded-proto x-real-ip" \
183
myapp:app
184
```
185
186
#### Unix Socket Configuration
187
188
```bash
189
# Unix socket with custom permissions (Linux/macOS)
190
waitress-serve \
191
--unix-socket=/var/run/myapp.sock \
192
--unix-socket-perms=666 \
193
myapp:app
194
195
# Socket with nginx configuration
196
waitress-serve \
197
--unix-socket=/tmp/myapp.sock \
198
--unix-socket-perms=660 \
199
myapp:app
200
```
201
202
#### Security-Focused Configuration
203
204
```bash
205
# Restricted for security
206
waitress-serve \
207
--host=127.0.0.1 \
208
--max-request-header-size=65536 \
209
--max-request-body-size=10485760 \
210
--channel-timeout=60 \
211
--connection-limit=50 \
212
myapp:app
213
```
214
215
### Module and Application Specification
216
217
The command-line interface supports flexible module and application specification.
218
219
```bash
220
# Module:attribute format
221
waitress-serve mypackage.mymodule:myapp
222
223
# Package with __main__ module
224
waitress-serve mypackage
225
226
# Nested attribute access
227
waitress-serve mypackage.submodule:factory().wsgi_app
228
229
# With --call flag for factory functions
230
waitress-serve --call mypackage:create_application
231
232
# Django integration
233
waitress-serve django_project.wsgi:application
234
```
235
236
### Error Handling
237
238
The command-line interface provides helpful error messages for common issues.
239
240
```bash
241
# Import errors show detailed traceback
242
waitress-serve nonexistent:app
243
# Shows import error with suggestions
244
245
# Invalid arguments show help
246
waitress-serve --invalid-option
247
# Shows error and displays help
248
249
# Module not found
250
waitress-serve badmodule:app
251
# Shows import error with troubleshooting info
252
```
253
254
### Integration with Process Managers
255
256
Waitress command-line interface works well with process managers and deployment tools.
257
258
```ini
259
# Supervisor configuration
260
[program:myapp]
261
command=waitress-serve --host=127.0.0.1 --port=8080 myapp:app
262
directory=/path/to/app
263
user=www-data
264
autostart=true
265
autorestart=true
266
267
# systemd service file
268
[Unit]
269
Description=My WSGI App
270
After=network.target
271
272
[Service]
273
Type=exec
274
User=www-data
275
WorkingDirectory=/path/to/app
276
ExecStart=/usr/local/bin/waitress-serve --host=127.0.0.1 --port=8080 myapp:app
277
Restart=always
278
279
[Install]
280
WantedBy=multi-user.target
281
```