0
# Command Line Interface
1

2
Complete command-line interface for managing Procfile-based applications with commands for starting, running, checking, and exporting processes. The CLI provides a user-friendly interface to all of Honcho's capabilities.
3

4
## Capabilities
5

6
### Main Entry Point
7

8
The main function serves as the entry point for the honcho command-line tool.
9

10
```python { .api }
11
def main(argv=None):
12
    """
13
    Main entry point for the honcho command-line interface.
14
    
15
    Parameters:
16
    - argv: list, optional command-line arguments (defaults to sys.argv)
17
    
18
    Raises:
19
    SystemExit: exits with appropriate return code
20
    """
21
```
22

23
### Command Functions
24

25
Core command implementations for the CLI interface.
26

27
```python { .api }
28
def command_start(args):
29
    """
30
    Start the application processes from Procfile.
31
    
32
    Parameters:
33
    - args: argparse.Namespace, parsed command-line arguments
34
    
35
    Raises:
36
    CommandError: if Procfile is invalid or processes fail
37
    """
38

39
def command_run(args):
40
    """
41
    Run a single command using the application's environment.
42
    
43
    Parameters:
44
    - args: argparse.Namespace, parsed command-line arguments with argv
45
    
46
    Raises:
47
    SystemExit: exits with the command's return code
48
    """
49

50
def command_export(args):
51
    """
52
    Export Procfile to another process management format.
53
    
54
    Parameters:
55
    - args: argparse.Namespace, parsed arguments including format and location
56
    
57
    Raises:
58
    CommandError: if export fails or format is unsupported
59
    """
60

61
def command_check(args):
62
    """
63
    Validate a Procfile for syntax and format errors.
64
    
65
    Parameters:
66
    - args: argparse.Namespace, parsed command-line arguments
67
    
68
    Raises:
69
    CommandError: if Procfile is invalid
70
    """
71

72
def command_version(args):
73
    """
74
    Display honcho version information.
75
    
76
    Parameters:
77
    - args: argparse.Namespace, parsed command-line arguments
78
    """
79

80
def command_help(args):
81
    """
82
    Display help information for commands.
83
    
84
    Parameters:
85
    - args: argparse.Namespace, parsed arguments with optional task name
86
    """
87
```
88

89
### Exception Handling
90

91
Custom exception for command execution errors.
92

93
```python { .api }
94
class CommandError(Exception):
95
    """
96
    Exception raised for command execution errors.
97
    Used to signal errors that should result in non-zero exit codes.
98
    """
99
    pass
100
```
101

102
### Configuration Management
103

104
Functions for managing configuration from multiple sources.
105

106
```python { .api }
107
def map_from(args):
108
    """
109
    Create configuration mapping from command-line arguments, environment variables,
110
    environment files, and defaults.
111
    
112
    Parameters:
113
    - args: argparse.Namespace, parsed command-line arguments
114
    
115
    Returns:
116
    ChainMap: configuration mapping with precedence order
117
    """
118
```
119

120
### Argument Parser Setup
121

122
The CLI uses argparse for command-line argument parsing with subcommands.
123

124
```python { .api }
125
import argparse
126

127
# Main parser
128
parser = argparse.ArgumentParser(
129
    'honcho',
130
    description='Manage Procfile-based applications'
131
)
132

133
# Common arguments shared across commands
134
def _add_common_args(parser, with_defaults=False):
135
    """
136
    Add common command-line arguments to parser.
137
    
138
    Parameters:
139
    - parser: argparse.ArgumentParser, parser to add arguments to
140
    - with_defaults: bool, whether to include default values
141
    """
142
```
143

144
## Command Reference
145

146
### start
147

148
Start the application processes from Procfile.
149

150
```bash
151
honcho start [options] [process...]
152
```
153

154
**Options:**
155
- `-f, --procfile FILE`: Procfile path (default: Procfile)
156
- `-e, --env FILE`: Environment file (default: .env)
157
- `-d, --app-root DIR`: Application root directory (default: .)
158
- `-p, --port N`: Starting port number (default: 5000)
159
- `-c, --concurrency process=num`: Number of each process type to run
160
- `-q, --quiet process1,process2`: Process names to suppress output for
161
- `--no-colour`: Disable colored output
162
- `--no-prefix`: Disable logging prefix
163

164
**Examples:**
165
```bash
166
# Start all processes
167
honcho start
168

169
# Start specific processes
170
honcho start web worker
171

172
# Start with custom concurrency
173
honcho start -c web=2,worker=3
174

175
# Start with custom port and environment
176
honcho start -p 8000 -e production.env
177

178
# Start quietly suppressing worker output
179
honcho start -q worker
180
```
181

182
### run
183

184
Run a single command using the application's environment.
185

186
```bash
187
honcho run [options] command [args...]
188
```
189

190
**Options:**
191
- `-f, --procfile FILE`: Procfile path
192
- `-e, --env FILE`: Environment file
193
- `-d, --app-root DIR`: Application root directory
194

195
**Examples:**
196
```bash
197
# Run database migration
198
honcho run python manage.py migrate
199

200
# Run with custom environment
201
honcho run -e production.env python manage.py collectstatic
202

203
# Run interactive shell
204
honcho run python manage.py shell
205

206
# Run with double-dash separator
207
honcho run -- python -c "print('hello world')"
208
```
209

210
### export
211

212
Export Procfile to another process management format.
213

214
```bash
215
honcho export [options] format location
216
```
217

218
**Formats:**
219
- `systemd`: systemd service files
220
- `supervisord`: supervisord configuration  
221
- `upstart`: Ubuntu upstart jobs
222
- `runit`: runit service directories
223

224
**Options:**
225
- `-f, --procfile FILE`: Procfile path
226
- `-e, --env FILE`: Environment file
227
- `-d, --app-root DIR`: Application root directory
228
- `-a, --app APP`: Application name (default: directory name)
229
- `-l, --log DIR`: Log directory (default: /var/log/APP)
230
- `-p, --port N`: Starting port number
231
- `-c, --concurrency process=num`: Process concurrency
232
- `-u, --user USER`: User to run as
233
- `-s, --shell SHELL`: Shell to use (default: /bin/sh)
234
- `-t, --template-dir DIR`: Custom template directory
235

236
**Examples:**
237
```bash
238
# Export to systemd
239
honcho export systemd /etc/systemd/system
240

241
# Export with custom app name and user
242
honcho export systemd /tmp/services -a myapp -u myapp
243

244
# Export with concurrency settings
245
honcho export supervisord /etc/supervisor/conf.d -c web=2,worker=3
246

247
# Export to custom location with templates
248
honcho export upstart /etc/init -t /path/to/templates
249
```
250

251
### check
252

253
Validate a Procfile for syntax and format errors.
254

255
```bash
256
honcho check [options]
257
```
258

259
**Options:**
260
- `-f, --procfile FILE`: Procfile path
261
- `-d, --app-root DIR`: Application root directory
262

263
**Examples:**
264
```bash
265
# Check default Procfile
266
honcho check
267

268
# Check specific Procfile
269
honcho check -f Procfile.production
270

271
# Check Procfile in different directory
272
honcho check -d /path/to/app
273
```
274

275
### version
276

277
Display honcho version information.
278

279
```bash
280
honcho version
281
```
282

283
### help
284

285
Display help information for commands.
286

287
```bash
288
honcho help [command]
289
```
290

291
**Examples:**
292
```bash
293
# Show general help
294
honcho help
295

296
# Show help for specific command
297
honcho help start
298
honcho help export
299
```
300

301
## Usage Examples
302

303
### Basic Workflow
304

305
```bash
306
# Create a Procfile
307
cat > Procfile << EOF
308
web: python app.py
309
worker: python worker.py
310
scheduler: python scheduler.py
311
EOF
312

313
# Create environment file
314
cat > .env << EOF
315
DATABASE_URL=postgresql://localhost:5432/myapp
316
DEBUG=true
317
PORT=5000
318
EOF
319

320
# Check Procfile validity
321
honcho check
322

323
# Start all processes
324
honcho start
325

326
# Start with custom configuration
327
honcho start -c web=2,worker=1 -p 8000
328
```
329

330
### Development Environment
331

332
```bash
333
# Development with debug output
334
honcho start --no-colour -e development.env
335

336
# Run database migrations
337
honcho run python manage.py migrate
338

339
# Run tests in app environment
340
honcho run pytest tests/
341

342
# Start specific services only
343
honcho start web redis
344
```
345

346
### Production Deployment
347

348
```bash
349
# Export to systemd for production
350
sudo honcho export systemd /etc/systemd/system \
351
  -a myapp \
352
  -u myapp \
353
  -l /var/log/myapp \
354
  -c web=4,worker=2
355

356
# Enable and start services
357
sudo systemctl enable myapp.target
358
sudo systemctl start myapp.target
359

360
# Check service status
361
sudo systemctl status myapp.target
362
```
363

364
### Configuration Precedence
365

366
Configuration is loaded from multiple sources with the following precedence (first match wins):
367

368
1. Command-line arguments
369
2. Environment file (`.env` or specified with `-e`)
370
3. OS environment variables
371
4. Built-in defaults
372

373
```bash
374
# Environment variable
375
export PORT=3000
376

377
# Environment file
378
echo "PORT=4000" > .env
379

380
# Command line (highest precedence)
381
honcho start -p 5000  # Uses port 5000
382
```
383

384
## Error Handling
385

386
```python { .api }
387
# Common error scenarios and handling
388

389
try:
390
    # Command execution
391
    COMMANDS[args.command](args)
392
except CommandError as e:
393
    # User-facing errors (invalid Procfile, missing files, etc.)
394
    log.error(str(e))
395
    sys.exit(1)
396
except KeyboardInterrupt:
397
    # Graceful shutdown on Ctrl+C
398
    sys.exit(130)
399
except Exception as e:
400
    # Unexpected errors
401
    log.error(f"Unexpected error: {e}")
402
    sys.exit(1)
403
```
404

405
## Configuration Constants
406

407
```python { .api }
408
# Default configuration values
409
DEFAULTS = {
410
    'port': '5000',
411
    'procfile': 'Procfile',
412
}
413

414
# Environment variable mappings
415
ENV_ARGS = {
416
    'port': 'PORT',
417
    'procfile': 'PROCFILE',
418
}
419

420
# Base directory name for app naming
421
BASENAME = os.path.basename(os.getcwd())
422

423
# Command function mappings
424
COMMANDS = {
425
    'start': command_start,
426
    'run': command_run,
427
    'export': command_export,
428
    'check': command_check,
429
    'version': command_version,
430
    'help': command_help,
431
}
432
```