0
# Command Line Interface
1

2
Command-line interface for starting and configuring Flower with extensive configuration options, environment variable support, and integration with Celery's command system.
3

4
## Capabilities
5

6
### Main Command Function
7

8
The primary entry point for the Flower command-line interface, integrated with Celery's command system.
9

10
```python { .api }
11
@click.command(cls=CeleryCommand, context_settings={'ignore_unknown_options': True})
12
@click.argument("tornado_argv", nargs=-1, type=click.UNPROCESSED)
13
@click.pass_context
14
def flower(ctx, tornado_argv):
15
    """
16
    Web based tool for monitoring and administrating Celery clusters.
17
    
18
    Args:
19
        ctx: Click context object containing Celery app
20
        tornado_argv: Additional Tornado/Flower specific arguments
21
    """
22
```
23

24
### Configuration Management
25

26
Functions for applying configuration from various sources including environment variables and configuration files.
27

28
```python { .api }
29
def apply_env_options():
30
    """
31
    Apply configuration options from environment variables.
32
    
33
    Processes environment variables with FLOWER_ prefix and applies
34
    them to Tornado's options system. Handles type conversion and
35
    multiple value options.
36
    """
37

38
def apply_options(prog_name, argv):
39
    """
40
    Apply configuration options from command line and config file.
41
    
42
    Args:
43
        prog_name (str): Program name for argument parsing
44
        argv (list): Command line arguments to process
45
        
46
    Parses command line options and loads configuration file if specified.
47
    """
48

49
def setup_logging():
50
    """
51
    Configure logging system based on options.
52
    
53
    Sets up appropriate logging levels and handlers based on
54
    debug and logging configuration options.
55
    """
56

57
def extract_settings():
58
    """
59
    Extract and validate application settings from options.
60
    
61
    Processes authentication, SSL, and other settings, performing
62
    validation and applying defaults where necessary.
63
    """
64
```
65

66
### Environment Variable Support
67

68
Flower supports extensive configuration through environment variables with the `FLOWER_` prefix.
69

70
```python { .api }
71
def is_flower_envvar(name):
72
    """
73
    Check if environment variable is a valid Flower option.
74
    
75
    Args:
76
        name (str): Environment variable name
77
        
78
    Returns:
79
        bool: True if variable name is valid Flower option
80
    """
81

82
# Environment variable prefix
83
ENV_VAR_PREFIX = 'FLOWER_'
84
```
85

86
### Utility Functions
87

88
Helper functions for option validation, banner display, and argument processing.
89

90
```python { .api }
91
def is_flower_option(arg):
92
    """
93
    Check if command line argument is a valid Flower option.
94
    
95
    Args:
96
        arg (str): Command line argument
97
        
98
    Returns:
99
        bool: True if argument is valid Flower option
100
    """
101

102
def print_banner(app, ssl):
103
    """
104
    Display startup banner with connection information.
105
    
106
    Args:
107
        app: Celery application instance
108
        ssl (bool): Whether SSL is enabled
109
        
110
    Prints server URL, broker information, and registered tasks.
111
    """
112

113
def warn_about_celery_args_used_in_flower_command(ctx, flower_args):
114
    """
115
    Warn about incorrectly placed Celery arguments.
116
    
117
    Args:
118
        ctx: Click context
119
        flower_args: Flower command arguments
120
        
121
    Warns users about Celery arguments that should come before flower command.
122
    """
123
```
124

125
## Configuration Options
126

127
### Server Configuration
128

129
Core server settings for network binding and protocol options.
130

131
```bash
132
# Basic server options
133
--port=5555                    # Server port (default: 5555)
134
--address=0.0.0.0             # Server address (default: 0.0.0.0)
135
--unix-socket=/path/socket    # Unix socket path
136
--url-prefix=/flower          # URL prefix for reverse proxy setups
137

138
# SSL/TLS options
139
--certfile=/path/cert.pem     # SSL certificate file
140
--keyfile=/path/key.pem       # SSL private key file
141
--ca-certs=/path/ca.pem       # SSL CA certificates
142
```
143

144
### Authentication Options
145

146
Configure authentication methods and providers.
147

148
```bash
149
# Basic authentication
150
--basic-auth=user:password    # Basic HTTP authentication
151
--auth=user@domain.com        # Email-based authentication pattern
152

153
# OAuth2 providers
154
--auth=google|github|gitlab|okta
155
--oauth2-key=client_id        # OAuth2 client ID
156
--oauth2-secret=client_secret # OAuth2 client secret
157
--oauth2-redirect-uri=uri     # OAuth2 redirect URI
158
```
159

160
### Performance and Storage Options
161

162
Configure memory limits, persistence, and performance settings.
163

164
```bash
165
# Memory management
166
--max-workers=5000            # Maximum workers in memory
167
--max-tasks=100000           # Maximum tasks in memory
168

169
# Persistence and storage
170
--persistent                  # Enable persistent mode
171
--db=/path/flower.db         # Database file path
172
--state-save-interval=60     # State save interval in seconds
173

174
# Inspection settings
175
--inspect-timeout=10000      # Worker inspection timeout (ms)
176
```
177

178
### Monitoring and Integration Options
179

180
Configure event monitoring, broker API access, and external integrations.
181

182
```bash
183
# Event monitoring
184
--enable-events              # Auto-enable events on workers
185
--disable-events             # Disable event monitoring
186

187
# Broker API integration
188
--broker-api=http://guest:guest@localhost:15672/api/  # RabbitMQ API
189

190
# Logging and debugging
191
--debug                      # Enable debug mode
192
--logging=info|debug|warning # Set logging level
193
```
194

195
## Usage Examples
196

197
### Basic Usage
198

199
```bash
200
# Start with default settings
201
celery flower
202

203
# Specify broker and port
204
celery -b redis://localhost:6379 flower --port=5555
205

206
# With authentication
207
celery flower --basic-auth=admin:secret
208

209
# With SSL
210
celery flower --certfile=cert.pem --keyfile=key.pem
211
```
212

213
### Environment Variable Configuration
214

215
```bash
216
# Set options via environment variables
217
export FLOWER_PORT=8888
218
export FLOWER_BASIC_AUTH=admin:password
219
export FLOWER_PERSISTENT=true
220
export FLOWER_MAX_WORKERS=1000
221

222
celery flower
223
```
224

225
### Advanced Configuration
226

227
```bash
228
# Production setup with SSL and OAuth
229
celery -b redis://prod-redis:6379 flower \
230
  --port=443 \
231
  --certfile=/etc/ssl/flower.crt \
232
  --keyfile=/etc/ssl/flower.key \
233
  --auth=google \
234
  --oauth2-key=$GOOGLE_CLIENT_ID \
235
  --oauth2-secret=$GOOGLE_CLIENT_SECRET \
236
  --oauth2-redirect-uri=https://flower.company.com/login \
237
  --persistent \
238
  --max-workers=10000 \
239
  --broker-api=https://guest:guest@rabbitmq.company.com:15672/api/
240
```
241

242
### Configuration File Usage
243

244
Create `flowerconfig.py`:
245

246
```python
247
# Flower configuration file
248
port = 5555
249
address = "0.0.0.0"
250
basic_auth = ["admin:secret", "user:password"]
251
max_workers = 5000
252
persistent = True
253
db = "/var/lib/flower/flower.db"
254
```
255

256
Use with:
257

258
```bash
259
celery flower --conf=flowerconfig.py
260
```
261

262
### Docker Usage
263

264
```bash
265
# Docker environment variables
266
docker run -d \
267
  -e FLOWER_PORT=5555 \
268
  -e FLOWER_BASIC_AUTH=admin:secret \
269
  -e FLOWER_PERSISTENT=true \
270
  -e CELERY_BROKER_URL=redis://redis:6379 \
271
  -p 5555:5555 \
272
  myapp-flower
273
```
274

275
## Integration with Celery Commands
276

277
### Standard Celery Integration
278

279
Flower integrates as a Celery command, allowing use of all Celery options:
280

281
```bash
282
# Use Celery app and broker settings
283
celery -A myapp worker &         # Start worker
284
celery -A myapp flower           # Start Flower monitoring
285

286
# With broker specification
287
celery -b redis://localhost:6379 flower
288

289
# With result backend
290
celery -b redis://localhost:6379 --result-backend=redis://localhost:6379 flower
291
```
292

293
### Programmatic Integration
294

295
```python
296
from celery.bin.celery import main, celery
297
from flower.command import flower
298

299
# Add flower command to Celery
300
celery.add_command(flower)
301

302
# Can now use: celery flower
303
if __name__ == "__main__":
304
    main()
305
```
306

307
## Error Handling
308

309
The command-line interface includes comprehensive error handling:
310

311
- Configuration file validation with helpful error messages
312
- SSL certificate validation and path checking
313
- Authentication option validation
314
- Port and address binding error reporting
315
- Environment variable type conversion error handling
316

317
## Default Configuration
318

319
Flower includes sensible defaults for all options:
320

321
```python
322
# Default configuration file name
323
DEFAULT_CONFIG_FILE = 'flowerconfig.py'
324

325
# Core defaults
326
default_options = {
327
    'port': 5555,
328
    'address': '0.0.0.0',
329
    'debug': False,
330
    'max_workers': 5000,
331
    'max_tasks': 100000,
332
    'inspect_timeout': 10000,
333
    'persistent': False,
334
    'enable_events': True,
335
    # ... additional defaults
336
}
337
```