0
# Command-Line Tools
1

2
cx_Freeze provides two primary command-line tools for freezing Python applications and generating setup configurations. These tools offer complete functionality without requiring Python programming knowledge.
3

4
## Capabilities
5

6
### cxfreeze Command
7

8
The main command-line interface for freezing Python scripts into standalone executables with comprehensive configuration options.
9

10
```python { .api }
11
def main() -> None:
12
    """Entry point for cxfreeze command line tool."""
13

14
def prepare_parser() -> argparse.ArgumentParser:
15
    """Create and configure argument parser."""
16
```
17

18
#### Core Parameters
19

20
Essential parameters for defining the script to freeze and basic executable configuration.
21

22
```bash
23
# Script and target configuration
24
--script NAME              # Python file to freeze (required)
25
--target-name NAME          # Executable filename  
26
--target-dir DIR           # Build directory for output
27
--base NAME                # Base type: console, gui, service
28
--init-script NAME         # Startup initialization script
29
```
30

31
#### Visual and Metadata Options
32

33
Options for customizing executable appearance and embedded metadata.
34

35
```bash
36
# Visual customization
37
--icon NAME                # Icon file path (auto-detects extension)
38
--manifest NAME            # XML manifest file (Windows)
39

40
# Windows metadata
41
--copyright TEXT           # Copyright string
42
--trademarks TEXT          # Trademarks string
43
--uac-admin               # Request elevation privileges
44
--uac-uiaccess            # Bypass UI control restrictions
45

46
# MSI installer options  
47
--shortcut-name NAME       # Shortcut name for MSI packages
48
--shortcut-dir DIR         # Shortcut directory for MSI packages
49
```
50

51
#### Command Execution
52

53
The cxfreeze tool supports direct freezing or execution of setup.py commands.
54

55
```bash
56
# Direct script freezing
57
cxfreeze --script main.py --target-dir dist
58

59
# Command-based execution
60
cxfreeze build_exe --includes tkinter --excludes unittest
61
cxfreeze bdist_msi --target-name MyApp
62

63
# Available commands
64
cxfreeze build          # Build executables (implies build_exe)
65
cxfreeze build_exe      # Build executables explicitly
66
cxfreeze bdist_msi      # Create MSI installer (Windows)
67
cxfreeze bdist_dmg      # Create DMG image (macOS)
68
cxfreeze bdist_mac      # Create app bundle (macOS)
69
cxfreeze bdist_rpm      # Create RPM package (Linux)
70
cxfreeze bdist_deb      # Create DEB package (Linux)
71
cxfreeze bdist_appimage # Create AppImage (Linux)
72
```
73

74
#### Advanced Options
75

76
Configuration options for development, debugging, and special requirements.
77

78
```bash
79
# Development options
80
--debug                    # Enable debug information
81
--verbose, -v             # Verbose output
82
--help                    # Show help information
83
--version                 # Show version information
84

85
# Integration options
86
# Options from pyproject.toml are automatically loaded
87
# Additional command-specific options passed to underlying commands
88
```
89

90
### Usage Examples
91

92
```bash
93
# Basic console application
94
cxfreeze --script main.py --target-dir dist
95

96
# GUI application with icon
97
cxfreeze --script gui_app.py --base gui --icon app --target-dir build
98

99
# Windows service with metadata
100
cxfreeze --script service.py --base service --copyright "© 2024 Company" --uac-admin
101

102
# Custom initialization and naming
103
cxfreeze --script main.py --init-script custom_init --target-name MyApp
104

105
# Direct MSI creation
106
cxfreeze bdist_msi --target-name MyApp-1.0 --shortcut-name "My Application"
107

108
# Build with additional options
109
cxfreeze build_exe --includes requests,numpy --excludes unittest,test --target-dir dist
110
```
111

112
#### Deprecated Options Handling
113

114
The cxfreeze command automatically handles deprecated options for backward compatibility.
115

116
```bash
117
# Deprecated → Modern equivalent
118
--install-dir DIR       → --build-exe DIR
119
--exclude-modules LIST  → --excludes LIST  
120
--include-modules LIST  → --includes LIST
121
-c, --compress         → (removed, use setup.py options)
122
-O, -OO               → --optimize=1, --optimize=2
123
-z                    → --zip-includes
124
--default-path        → --path
125
-s, --silent          → --silent
126
```
127

128
### cxfreeze-quickstart Command
129

130
Interactive tool for generating setup.py files without programming knowledge.
131

132
```python { .api }
133
def main() -> None:
134
    """Entry point for cxfreeze-quickstart command line tool."""
135

136
class SetupWriter:
137
    """Interactive setup script generator."""
138
    
139
    def populate_from_command_line(self) -> None:
140
        """Interactive configuration through prompts."""
141
    
142
    def write(self) -> None:
143
        """Generate setup.py file from configuration."""
144
    
145
    def get_value(
146
        self, 
147
        label: str, 
148
        default: str = "", 
149
        separator: str = ": "
150
    ) -> str:
151
        """Get user input with default value."""
152
    
153
    def get_boolean_value(
154
        self, 
155
        label: str, 
156
        default: bool = False
157
    ) -> bool:
158
        """Get yes/no input from user."""
159
```
160

161
#### Interactive Configuration
162

163
The quickstart tool guides users through configuration with intelligent defaults and validation.
164

165
```python { .api }
166
# Configuration properties
167
class SetupWriter:
168
    bases: ClassVar[dict[str, str]] = {
169
        "C": "console",
170
        "G": "gui", 
171
        "S": "service",
172
    }
173
    
174
    # User configuration
175
    name: str                    # Project name
176
    description: str             # Project description  
177
    script: str                  # Main Python script
178
    version: str                 # Project version
179
    executable_name: str         # Target executable name
180
    setup_file_name: str         # Output setup.py filename
181
    base_code: str              # Base type code (C/G/S)
182
    
183
    @property
184
    def base(self) -> str:
185
        """Get base name from code."""
186
    
187
    @property  
188
    def default_executable_name(self) -> str:
189
        """Generate default executable name from script."""
190
```
191

192
#### Quickstart Workflow
193

194
```bash
195
# Run interactive configuration
196
cxfreeze-quickstart
197

198
# Example interaction:
199
# Project name: MyApp
200
# Version [1.0]: 1.0.0  
201
# Description: My Python Application
202
# Python file to make executable from: main.py
203
# Executable file name [main]: MyApp
204
# (C) console application, (G) GUI application, or (S) service [C]: G
205
# Save setup script to [setup.py]: setup.py
206
# Run this now [n]: y
207
```
208

209
#### Generated Setup Files
210

211
The quickstart tool creates complete setup.py files with best practices and platform compatibility.
212

213
```python
214
# Example generated setup.py
215
from cx_Freeze import setup, Executable
216

217
# Dependencies are automatically detected, but it might need
218
# fine tuning.
219
build_options = {'packages': [], 'excludes': []}
220

221
base = 'gui'
222

223
executables = [
224
    Executable('main.py', base=base, target_name='MyApp')
225
]
226

227
setup(name='MyApp',
228
      version='1.0.0',
229
      description='My Python Application',
230
      options={'build_exe': build_options},
231
      executables=executables)
232
```
233

234
### Integration with pyproject.toml
235

236
The cxfreeze command automatically reads configuration from pyproject.toml files following modern Python packaging standards.
237

238
```python { .api }
239
# Configuration loading from pyproject.toml
240
def get_pyproject_tool_data() -> dict:
241
    """Load cx_Freeze configuration from pyproject.toml."""
242
```
243

244
Example pyproject.toml configuration:
245

246
```toml
247
[tool.cxfreeze]
248
executables = [
249
    {script = "main.py", base = "gui", target_name = "MyApp"}
250
]
251

252
[tool.cxfreeze.build_exe]
253
packages = ["tkinter", "requests"]
254
excludes = ["unittest", "test"]
255
include_files = [
256
    {source = "data/", dest = "data/"},
257
    "config.ini"
258
]
259
```
260

261
### Environment Integration
262

263
Command-line tools integrate with development environments and CI/CD pipelines.
264

265
```bash
266
# Environment variable support
267
export DISTUTILS_DEBUG=1           # Enable debug mode
268
export CXFREEZE_SILENCE_WARNINGS=1 # Suppress warnings
269

270
# CI/CD integration
271
cxfreeze --script main.py --target-dir dist --silent
272
cxfreeze bdist_msi --target-name MyApp-$VERSION
273

274
# Shell completion and help
275
cxfreeze --help                     # General help
276
cxfreeze build_exe --help          # Command-specific help
277
cxfreeze --version                  # Version information
278
```
279

280
### Error Handling and Debugging
281

282
Command-line tools provide comprehensive error reporting and debugging capabilities.
283

284
```python { .api }
285
# Common CLI errors and handling
286
class OptionError(Exception):
287
    """Invalid command-line option configuration."""
288

289
class SetupError(Exception):  
290
    """Setup script or configuration errors."""
291

292
# Debug output control
293
--debug                            # Enable debug mode
294
--verbose                          # Verbose output
295
DISTUTILS_DEBUG=1                  # Environment debug flag
296
```
297

298
### Platform-Specific Behavior
299

300
Command-line tools adapt behavior based on the target platform with appropriate defaults and validation.
301

302
**Windows:**
303
- Automatic .exe extension handling
304
- UAC and manifest option validation
305
- Windows-specific base types (gui, service)
306
- MSI-specific options available
307

308
**macOS:**
309
- App bundle naming conventions
310
- .icns icon preference
311
- macOS-specific distribution commands
312
- Framework path handling
313

314
**Linux:**
315
- Executable permission handling
316
- .desktop file generation hints
317
- Linux distribution command availability
318
- Shared library dependency warnings