0
# CLI Development Tools
1

2
Command-line interface for managing Brython projects, installing packages, creating distributions, and running development servers. The CLI provides essential tools for Python developers to work with Brython projects efficiently.
3

4
## Capabilities
5

6
### Project Installation
7

8
Install Brython runtime files into a new or existing directory, setting up the basic structure for Brython development.
9

10
```python { .api }
11
def install(install_dir: str = ".", no_demo: bool = False) -> None:
12
    """
13
    Install Brython files to directory.
14
    
15
    Args:
16
        install_dir: Target directory for installation (default: current directory)
17
        no_demo: Skip installation of demo.html file
18
        
19
    Creates:
20
        - brython.js: Core Brython runtime
21
        - brython_stdlib.js: Standard library bundle
22
        - index.html: Basic HTML template
23
        - demo.html: Example usage (unless no_demo=True)
24
    """
25
```
26

27
**Usage:**
28
```bash
29
brython-cli install
30
brython-cli install --install-dir /path/to/project
31
brython-cli install --no-demo
32
```
33

34
### Project Updates
35

36
Update existing Brython installations with the latest runtime files while preserving custom project files.
37

38
```python { .api }
39
def update(update_dir: str = ".") -> None:
40
    """
41
    Update Brython scripts in existing project.
42
    
43
    Args:
44
        update_dir: Directory containing Brython project to update
45
        
46
    Updates:
47
        - brython.js: Core runtime to latest version
48
        - brython_stdlib.js: Standard library to latest version
49
    """
50
```
51

52
**Usage:**
53
```bash
54
brython-cli update
55
brython-cli update --update-dir /path/to/project
56
```
57

58
### Package Management
59

60
Add Python packages from the current environment to Brython projects for browser usage.
61

62
```python { .api }
63
def add_package(package: str, dest_dir: str = None) -> None:
64
    """
65
    Add Python package to Brython project.
66
    
67
    Args:
68
        package: Name of installed Python package to add
69
        dest_dir: Destination directory (default: ./Lib/site-packages)
70
        
71
    Copies package files from current Python environment to Brython project,
72
    making them available for import in browser Python scripts.
73
    """
74
```
75

76
**Usage:**
77
```bash  
78
brython-cli add_package requests
79
brython-cli add_package django --dest-dir custom/lib
80
```
81

82
### Package Creation
83

84
Create optimized browser-loadable packages from Python source code.
85

86
```python { .api }
87
def make_package(package_name: str, src_dir: str = ".", exclude_dirs: list[str] = None, output_path: str = None) -> None:
88
    """
89
    Create browser-loadable .brython.js package file.
90
    
91
    Args:
92
        package_name: Name for the package (used in imports)
93
        src_dir: Source directory containing Python files
94
        exclude_dirs: Directories to exclude from package
95
        output_path: Output path for .brython.js file
96
        
97
    Creates optimized JavaScript file containing Python package
98
    that can be loaded in browsers.
99
    """
100
```
101

102
**Usage:**
103
```bash
104
brython-cli make_package mylib
105
brython-cli make_package mylib --src-dir src/ --exclude-dirs tests docs
106
brython-cli make_package mylib -o dist/mylib.brython.js
107
```
108

109
### Module Bundling
110

111
Create optimized module bundles containing only the modules used by the application.
112

113
```python { .api }
114
def make_modules(output_path: str = None, reset: bool = False, modules_paths: str = None) -> None:
115
    """
116
    Create brython_modules.js with application modules.
117
    
118
    Args:
119
        output_path: Output path for modules file
120
        reset: Reset to standard library only
121
        modules_paths: File containing module paths to include
122
        
123
    Analyzes application code and creates optimized bundle
124
    containing only required modules.
125
    """
126
```
127

128
**Usage:**
129
```bash
130
brython-cli make_modules
131
brython-cli make_modules --reset
132
brython-cli make_modules -o custom_modules.js
133
```
134

135
### Distribution Creation
136

137
Create Python distributions for PyPI upload from web applications.
138

139
```python { .api }
140
def make_dist() -> None:
141
    """
142
    Create Python distribution for PyPI upload.
143
    
144
    Analyzes current project and creates setup.py and distribution
145
    files suitable for uploading to PyPI.
146
    """
147
```
148

149
**Usage:**
150
```bash
151
brython-cli make_dist
152
```
153

154
### Virtual File System
155

156
Create JavaScript virtual file systems from directory structures.
157

158
```python { .api }
159
def make_file_system(vfs_name: str, prefix: str = None) -> None:
160
    """
161
    Create JavaScript file system from directory.
162
    
163
    Args:
164
        vfs_name: Name for the virtual file system
165
        prefix: Prefix for file paths in VFS
166
        
167
    Creates JavaScript file containing directory structure
168
    that can be loaded as virtual file system in browsers.
169
    """
170
```
171

172
**Usage:**
173
```bash
174
brython-cli make_file_system assets
175
brython-cli make_file_system templates /templates
176
```
177

178
### Development Server
179

180
Start lightweight development server for testing Brython applications locally.
181

182
```python { .api }
183
def start_server(port: int = 8000, bind: str = "localhost") -> None:
184
    """
185
    Start development server.
186
    
187
    Args:
188
        port: Port number to listen on
189
        bind: Address to bind to
190
        
191
    Starts HTTP server serving static files from current directory
192
    with proper MIME types for Brython development.
193
    """
194
```
195

196
**Usage:**
197
```bash
198
brython-cli start_server
199
brython-cli start_server 3000
200
brython-cli start_server 8080 --bind 0.0.0.0
201
```
202

203
### Version Information
204

205
Display version information for the installed Brython CLI.
206

207
```python { .api }
208
def version() -> str:
209
    """
210
    Get Brython version information.
211
    
212
    Returns:
213
        Version string for current Brython installation
214
    """
215
```
216

217
**Usage:**
218
```bash
219
brython-cli --version
220
```
221

222
## CLI Command Reference
223

224
All commands are accessed through the `brython-cli` console script:
225

226
```bash
227
brython-cli <command> [options]
228
```
229

230
**Available Commands:**
231
- `install` (alias: `init`) - Install Brython to directory
232
- `update` - Update Brython files
233
- `add_package` - Add Python package
234
- `make_package` - Create loadable package
235
- `make_modules` - Bundle application modules  
236
- `make_dist` - Create PyPI distribution
237
- `make_file_system` - Create virtual file system
238
- `start_server` - Start development server
239
- `--version` - Show version
240

241
**Global Options:**
242
- `--help` - Show help information
243
- Command-specific `--help` available for detailed options
244

245
## Installation Workflow
246

247
Typical development setup workflow:
248

249
```bash
250
# Create new project directory
251
mkdir my-web-app
252
cd my-web-app
253

254
# Install Brython files
255
brython-cli install
256

257
# Add required packages
258
brython-cli add_package requests
259
brython-cli add_package beautifulsoup4
260

261
# Start development server  
262
brython-cli start_server 8000
263
```
264

265
This creates a ready-to-use Brython development environment with all necessary files and dependencies.