0
# Command Line Interface
1

2
Comprehensive CLI for project setup, VBA integration, Excel add-in management, and deployment operations. The xlwings CLI provides powerful tools for managing xlwings projects, automating Excel workflows, and deploying Python-Excel solutions.
3

4
## Capabilities
5

6
### Project Management Commands
7

8
Commands for creating and managing xlwings projects with proper structure and configuration.
9

10
```bash
11
# Core project commands
12
xlwings quickstart <project_name>        # Create new xlwings project
13
xlwings quickstart <project_name> --standalone  # Create standalone project
14
xlwings quickstart <project_name> --addin       # Create add-in project
15

16
# Project configuration
17
xlwings config create                     # Create configuration file
18
xlwings config show                       # Show current configuration
19
xlwings config set <key> <value>         # Set configuration value
20
```
21

22
### Excel Add-in Management
23

24
Commands for installing, managing, and distributing Excel add-ins.
25

26
```bash
27
# Add-in installation and management
28
xlwings addin install                     # Install xlwings Excel add-in
29
xlwings addin remove                      # Remove xlwings Excel add-in  
30
xlwings addin status                      # Show add-in installation status
31
xlwings addin install --file <path>      # Install custom add-in file
32
xlwings addin update                      # Update existing add-in
33

34
# Add-in development
35
xlwings addin build                       # Build add-in for distribution
36
xlwings addin sign <certificate>          # Sign add-in with certificate
37
```
38

39
### Python-Excel Integration Commands
40

41
Commands for executing Python code from Excel and managing the integration.
42

43
```bash
44
# Python execution from Excel
45
xlwings runpython <script>                # Run Python script from Excel
46
xlwings runpython <script> --book <path> # Run with specific workbook
47
xlwings runpython <script> --show        # Show Excel during execution
48

49
# UDF server management  
50
xlwings udf serve                         # Start UDF COM server (Windows)
51
xlwings udf install                       # Install UDF dependencies
52
xlwings udf update                        # Update UDF registration
53
```
54

55
### REST API Server
56

57
Commands for running xlwings REST API server for web-based Excel automation.
58

59
```bash
60
# REST API server
61
xlwings restapi run                       # Start REST API server
62
xlwings restapi run --host <host>         # Specify server host
63
xlwings restapi run --port <port>         # Specify server port
64
xlwings restapi run --debug               # Run in debug mode
65
xlwings restapi config                    # Show REST API configuration
66
```
67

68
### Authentication and Licensing
69

70
Commands for managing xlwings PRO licenses and authentication.
71

72
```bash
73
# License management
74
xlwings license activate <key>            # Activate PRO license
75
xlwings license deactivate                # Deactivate current license
76
xlwings license status                    # Show license status
77
xlwings license info                      # Show license information
78

79
# Authentication (for xlwings Server)
80
xlwings auth login                        # Login to xlwings Server
81
xlwings auth logout                       # Logout from xlwings Server
82
xlwings auth status                       # Show authentication status
83
xlwings auth token                        # Show current auth token
84
```
85

86
### VBA Code Management
87

88
Commands for embedding, extracting, and managing VBA code within xlwings projects.
89

90
```bash
91
# VBA code operations
92
xlwings code embed <book>                 # Embed Python code in Excel file
93
xlwings code extract <book>               # Extract Python code from Excel
94
xlwings code sync <book>                  # Sync code between Python and Excel
95
xlwings code clean <book>                 # Clean embedded code from Excel
96

97
# VBA development support
98
xlwings vba edit                          # Enable VBA live editing
99
xlwings vba import <module>               # Import VBA module
100
xlwings vba export <module>               # Export VBA module
101
```
102

103
### Build and Release Commands
104

105
Commands for building, packaging, and deploying xlwings projects.
106

107
```bash
108
# Project building
109
xlwings release                           # Build project for release
110
xlwings release --include-excel           # Include Excel files in release
111
xlwings release --standalone              # Create standalone executable
112
xlwings release --target <platform>      # Build for specific platform
113

114
# Distribution
115
xlwings pack                              # Package project for distribution
116
xlwings pack --format zip                # Package as ZIP archive
117
xlwings pack --format installer          # Create Windows installer
118
```
119

120
### Template and Configuration Management
121

122
Commands for copying templates, configurations, and project assets.
123

124
```bash
125
# Template operations
126
xlwings copy template <name>              # Copy built-in template
127
xlwings copy config                       # Copy configuration template
128
xlwings copy vba                          # Copy VBA modules
129
xlwings copy addin                        # Copy add-in files
130

131
# Custom templates
132
xlwings template create <name>            # Create custom template
133
xlwings template list                     # List available templates
134
xlwings template install <path>           # Install custom template
135
```
136

137
### Development and Debugging
138

139
Commands for development workflow, debugging, and troubleshooting.
140

141
```bash
142
# Development support
143
xlwings dev install                       # Install development dependencies
144
xlwings dev test                          # Run project tests
145
xlwings dev lint                          # Lint Python code
146
xlwings dev format                        # Format Python code
147

148
# Debugging and diagnostics
149
xlwings debug info                        # Show system and version info
150
xlwings debug engines                     # List available Excel engines
151
xlwings debug config                      # Validate configuration
152
xlwings debug permissions                 # Check file permissions
153
```
154

155
## Command Reference
156

157
### Quickstart Command
158

159
```bash
160
xlwings quickstart myproject
161
```
162

163
Creates a new xlwings project with this structure:
164

165
```
166
myproject/
167
├── myproject.py          # Main Python module
168
├── myproject.xlsm        # Excel workbook with xlwings setup
169
├── xlwings.conf          # Project configuration
170
└── README.md             # Project documentation
171
```
172

173
Options:
174
- `--standalone`: Creates standalone project without Excel dependency
175
- `--addin`: Creates Excel add-in project structure
176
- `--template <name>`: Use custom project template
177

178
### Configuration Management
179

180
```bash
181
# Create default configuration
182
xlwings config create
183

184
# Set interpreter path
185
xlwings config set interpreter /path/to/python
186

187
# Set PYTHONPATH
188
xlwings config set pythonpath /path/to/modules
189

190
# Show all configuration
191
xlwings config show
192
```
193

194
Configuration file format (xlwings.conf):
195
```ini
196
[xlwings] 
197
INTERPRETER = python
198
INTERPRETER_MAC = python
199
PYTHONPATH = 
200
LOG_FILE = 
201
SHOW_CONSOLE = False
202
LICENSE_KEY = 
203
```
204

205
### REST API Server
206

207
```bash
208
# Start server with default settings
209
xlwings restapi run
210

211
# Custom host and port
212
xlwings restapi run --host 0.0.0.0 --port 8080
213

214
# Debug mode with auto-reload
215
xlwings restapi run --debug --reload
216
```
217

218
REST API endpoints:
219
- `GET /docs` - API documentation
220
- `POST /execute` - Execute Python code
221
- `GET /books` - List open workbooks
222
- `POST /books/{book}/sheets/{sheet}/range` - Range operations
223

224
### VBA Integration
225

226
```bash
227
# Embed Python code in Excel file
228
xlwings code embed myproject.xlsm
229

230
# Extract embedded code for editing
231
xlwings code extract myproject.xlsm
232

233
# Sync changes back to Excel
234
xlwings code sync myproject.xlsm
235
```
236

237
### License Activation
238

239
```bash
240
# Activate PRO license
241
xlwings license activate XXXXX-XXXXX-XXXXX-XXXXX-XXXXX
242

243
# Check license status
244
xlwings license status
245

246
# Deactivate license
247
xlwings license deactivate
248
```
249

250
## Environment Variables
251

252
xlwings CLI respects these environment variables:
253

254
```bash
255
# Core configuration
256
XLWINGS_LICENSE_KEY=<license_key>         # PRO license key
257
XLWINGS_LOG_FILE=<path>                   # Log file location
258
XLWINGS_CONFIG_DIR=<path>                 # Configuration directory
259

260
# Development settings
261
XLWINGS_DEBUG=1                           # Enable debug mode
262
XLWINGS_NO_DEPS=1                         # Skip dependency installation
263
XLWINGS_MOCK=1                            # Use mock Excel for testing
264

265
# Server settings
266
XLWINGS_SERVER_URL=<url>                  # xlwings Server URL
267
XLWINGS_SERVER_TOKEN=<token>              # Server authentication token
268
```
269

270
## Integration Examples
271

272
### CI/CD Pipeline Integration
273

274
```yaml
275
# GitHub Actions example
276
name: xlwings-project
277
on: [push, pull_request]
278

279
jobs:
280
  test:
281
    runs-on: windows-latest
282
    steps:
283
    - uses: actions/checkout@v2
284
    - uses: actions/setup-python@v2
285
      with:
286
        python-version: '3.9'
287
    
288
    - name: Install xlwings
289
      run: pip install xlwings
290
    
291
    - name: Setup xlwings
292
      run: xlwings config create
293
    
294
    - name: Run tests
295
      run: xlwings dev test
296
    
297
    - name: Build release
298
      run: xlwings release
299
      if: github.ref == 'refs/heads/main'
300
```
301

302
### Docker Integration
303

304
```dockerfile
305
# Dockerfile for xlwings REST API
306
FROM python:3.9-slim
307

308
RUN pip install xlwings[all]
309

310
COPY . /app
311
WORKDIR /app
312

313
RUN xlwings config create
314
RUN xlwings license activate $LICENSE_KEY
315

316
EXPOSE 8080
317
CMD ["xlwings", "restapi", "run", "--host", "0.0.0.0", "--port", "8080"]
318
```
319

320
### Project Automation Scripts
321

322
```bash
323
#!/bin/bash
324
# deploy.sh - Automated deployment script
325

326
set -e
327

328
echo "Building xlwings project..."
329
xlwings release --include-excel
330

331
echo "Running tests..."
332
xlwings dev test
333

334
echo "Packaging for distribution..."
335
xlwings pack --format installer
336

337
echo "Deployment complete!"
338
```
339

340
## Types
341

342
```python { .api }
343
# CLI command types (conceptual)
344
CLICommand = str  # Command name
345
CLIOption = str   # Command option
346
CLIArgument = str # Command argument
347

348
# Configuration types
349
ConfigKey = str   # Configuration key
350
ConfigValue = str # Configuration value
351
ConfigDict = dict[str, str]  # Configuration dictionary
352

353
# Project structure types
354
ProjectName = str # Project name
355
ProjectPath = str # Project directory path
356
TemplateName = str # Template identifier
357

358
# Server types
359
ServerHost = str  # Server hostname/IP
360
ServerPort = int  # Server port number
361
APIEndpoint = str # REST API endpoint path
362
```