0
# Command Line Interface
1

2
Comprehensive CLI for batch notebook execution, parameter passing, and automation workflows with support for YAML configuration files and various parameter input formats. The papermill command provides a powerful interface for integrating notebooks into data pipelines and automation systems.
3

4
## Capabilities
5

6
### Main Command
7

8
Primary CLI entry point for executing notebooks with parameters.
9

10
```bash { .api }
11
papermill [OPTIONS] NOTEBOOK_PATH [OUTPUT_PATH]
12

13
Options:
14
  --help-notebook           Display parameters information for the given notebook path
15
  -p, --parameters TEXT     Parameters to pass to the parameters cell (key value pairs)
16
  -r, --parameters_raw TEXT Parameters to be read as raw string (key value pairs)
17
  -f, --parameters_file TEXT Path to YAML file containing parameters
18
  -y, --parameters_yaml TEXT YAML string to be used as parameters
19
  -b, --parameters_base64 TEXT Base64 encoded YAML string as parameters
20
  --inject-input-path       Insert the path of the input notebook as PAPERMILL_INPUT_PATH as a notebook parameter
21
  --inject-output-path      Insert the path of the output notebook as PAPERMILL_OUTPUT_PATH as a notebook parameter
22
  --inject-paths            Insert the paths of input/output notebooks as PAPERMILL_INPUT_PATH/PAPERMILL_OUTPUT_PATH as notebook parameters
23
  --engine TEXT             The execution engine name to use in evaluating the notebook
24
  --request-save-on-cell-execute / --no-request-save-on-cell-execute Request save notebook after each cell execution
25
  --autosave-cell-every INTEGER How often in seconds to autosave the notebook during long cell executions (0 to disable)
26
  --prepare-only / --prepare-execute Flag for outputting the notebook without execution, but with parameters applied
27
  --kernel, -k TEXT         Name of kernel to run. Ignores kernel name in the notebook document metadata
28
  --language, -l TEXT       Language for notebook execution. Ignores language in the notebook document metadata
29
  --cwd TEXT                Working directory to run notebook in
30
  --progress-bar / --no-progress-bar Flag for turning on the progress bar
31
  --log-output / --no-log-output Flag for writing notebook output to the configured logger
32
  --stdout-file FILE        File to write notebook stdout output to
33
  --stderr-file FILE        File to write notebook stderr output to
34
  --log-level [NOTSET|DEBUG|INFO|WARNING|ERROR|CRITICAL] Set log level
35
  --start-timeout INTEGER   Time in seconds to wait for kernel to start
36
  --execution-timeout INTEGER Time in seconds to wait for each cell before failing execution (default: forever)
37
  --report-mode / --no-report-mode Flag for hiding input
38
  --version                 Show version and exit
39
  -h, --help                Show this message and exit
40
```
41

42
### CLI Function Interface
43

44
Python interface to the CLI command.
45

46
```python { .api }
47
def papermill(
48
    ctx: click.Context,
49
    notebook_path: str,
50
    output_path: str = "",
51
    help_notebook: bool = False,
52
    parameters: tuple = (),
53
    parameters_raw: tuple = (),
54
    parameters_file: tuple = (),
55
    parameters_yaml: tuple = (),
56
    parameters_base64: tuple = (),
57
    inject_input_path: bool = False,
58
    inject_output_path: bool = False,
59
    inject_paths: bool = False,
60
    engine: str = None,
61
    prepare_only: bool = False,
62
    kernel: str = None,
63
    language: str = None,
64
    log_output: bool = False,
65
    stdout_file = None,
66
    stderr_file = None,
67
    no_progress_bar: bool = False,
68
    autosave_cell_every: int = None,
69
    start_timeout: int = 60,
70
    execution_timeout: int = None,
71
    report_mode: bool = False,
72
    cwd: str = None,
73
    version: bool = False
74
) -> None:
75
    """
76
    Main CLI interface for papermill notebook execution.
77
    
78
    This is the Click command function that handles all CLI operations
79
    including parameter parsing, validation, and execution coordination.
80
    """
81
```
82

83
## Usage Examples
84

85
### Basic Execution
86

87
```bash
88
# Execute notebook with output
89
papermill input.ipynb output.ipynb
90

91
# Execute without saving output
92
papermill input.ipynb
93
```
94

95
### Parameter Passing
96

97
```bash
98
# Single parameters
99
papermill analysis.ipynb results.ipynb -p alpha 0.6 -p iterations 100
100

101
# Raw string parameters (no type conversion)
102
papermill notebook.ipynb output.ipynb -r config_file "/path/with spaces/config.json"
103

104
# Multiple parameter methods
105
papermill notebook.ipynb output.ipynb \
106
  -p threshold 0.8 \
107
  -r data_path "/complex path/data.csv" \
108
  -f config.yaml
109
```
110

111
### Parameter Files
112

113
```bash
114
# YAML parameter file
115
papermill experiment.ipynb result.ipynb -f parameters.yaml
116

117
# Inline YAML parameters
118
papermill notebook.ipynb output.ipynb -y "alpha: 0.6, beta: 0.1"
119

120
# Base64 encoded YAML (for complex parameters)
121
papermill notebook.ipynb output.ipynb -b "YWxwaGE6IDAuNgpiZXRhOiAwLjE="
122
```
123

124
### Path Injection
125

126
```bash
127
# Inject input path as parameter
128
papermill template.ipynb result.ipynb --inject-input-path
129

130
# Inject output path as parameter  
131
papermill template.ipynb result.ipynb --inject-output-path
132

133
# Inject both paths
134
papermill template.ipynb result.ipynb --inject-paths
135
```
136

137
### Execution Options
138

139
```bash
140
# Specify kernel
141
papermill notebook.ipynb output.ipynb --kernel python3
142

143
# Use specific engine
144
papermill notebook.ipynb output.ipynb --engine nbclient
145

146
# Set working directory
147
papermill notebook.ipynb output.ipynb --cwd /data/workspace
148

149
# Extended timeout for long-running notebooks
150
papermill analysis.ipynb results.ipynb --start_timeout 300 --execution-timeout 3600
151
```
152

153
### Output Control
154

155
```bash
156
# Hide progress bar
157
papermill notebook.ipynb output.ipynb --no-progress-bar
158

159
# Log output to console
160
papermill notebook.ipynb output.ipynb --log-output
161

162
# Redirect stdout and stderr
163
papermill notebook.ipynb output.ipynb \
164
  --stdout-file execution.log \
165
  --stderr-file errors.log
166

167
# Report mode (hide input cells)
168
papermill analysis.ipynb clean_report.ipynb --report-mode
169
```
170

171
### Validation and Preparation
172

173
```bash
174
# Prepare notebook without executing (validation)
175
papermill template.ipynb prepared.ipynb --prepare-only -p param1 value1
176

177
# Get help about notebook parameters
178
papermill analysis.ipynb --help-notebook
179
```
180

181
### Cloud Storage
182

183
```bash
184
# Execute with S3 paths
185
papermill s3://bucket/input.ipynb s3://bucket/output.ipynb -p dataset "s3://bucket/data.csv"
186

187
# Mixed local and cloud
188
papermill local_template.ipynb s3://bucket/results/output.ipynb
189

190
# Azure Blob Storage
191
papermill abs://account.blob.core.windows.net/container/input.ipynb output.ipynb
192

193
# Google Cloud Storage
194
papermill gs://bucket/notebook.ipynb gs://bucket/result.ipynb
195
```
196

197
## Advanced CLI Usage
198

199
### Automation Scripts
200

201
```bash
202
#!/bin/bash
203
# Batch processing script
204

205
# Define parameters
206
NOTEBOOKS=(
207
  "daily_report.ipynb"
208
  "weekly_analysis.ipynb" 
209
  "monthly_summary.ipynb"
210
)
211

212
DATE=$(date +%Y-%m-%d)
213
OUTPUT_DIR="s3://reports-bucket/${DATE}"
214

215
# Process each notebook
216
for notebook in "${NOTEBOOKS[@]}"; do
217
  echo "Processing ${notebook}..."
218
  
219
  papermill "templates/${notebook}" "${OUTPUT_DIR}/${notebook}" \
220
    -p execution_date "${DATE}" \
221
    -p output_bucket "reports-bucket" \
222
    --log-output \
223
    --report-mode
224
    
225
  if [ $? -eq 0 ]; then
226
    echo "✓ ${notebook} completed successfully"
227
  else
228
    echo "✗ ${notebook} failed"
229
    exit 1
230
  fi
231
done
232

233
echo "All notebooks processed successfully!"
234
```
235

236
### Parameter File Examples
237

238
**parameters.yaml:**
239
```yaml
240
# Data configuration
241
data_source: "s3://data-bucket/sales_2024.csv"
242
output_path: "s3://results-bucket/analysis"
243

244
# Analysis parameters
245
confidence_level: 0.95
246
sample_size: 1000
247
remove_outliers: true
248

249
# Visualization settings
250
plot_style: "seaborn"
251
figure_size: [12, 8]
252
color_palette: "viridis"
253

254
# Complex nested parameters
255
model_config:
256
  algorithm: "random_forest"
257
  hyperparameters:
258
    n_estimators: 100
259
    max_depth: 10
260
    random_state: 42
261
```
262

263
**Using parameter file:**
264
```bash
265
papermill analysis.ipynb results.ipynb -f parameters.yaml
266
```
267

268
### CI/CD Integration
269

270
```bash
271
# GitLab CI example
272
script:
273
  - pip install papermill[all]
274
  - papermill notebooks/test_suite.ipynb results/test_results.ipynb
275
    -p test_environment "ci"
276
    -p commit_sha "${CI_COMMIT_SHA}"
277
    --log-output
278
  - papermill notebooks/performance_test.ipynb results/perf_results.ipynb
279
    --execution-timeout 1800
280
    --no-progress-bar
281

282
# GitHub Actions example
283
- name: Execute notebooks
284
  run: |
285
    papermill experiments/model_training.ipynb artifacts/training_results.ipynb \
286
      -p model_version "${GITHUB_SHA:0:8}" \
287
      -p dataset_version "v2.1" \
288
      --log-output
289
```
290

291
### Error Handling in Scripts
292

293
```bash
294
#!/bin/bash
295
set -e  # Exit on any error
296

297
# Function to handle errors
298
handle_error() {
299
  echo "ERROR: Notebook execution failed at line $1"
300
  echo "Command: $2"
301
  exit 1
302
}
303

304
trap 'handle_error $LINENO "$BASH_COMMAND"' ERR
305

306
# Execute with error handling
307
echo "Starting notebook execution..."
308

309
papermill input.ipynb output.ipynb \
310
  -p environment "production" \
311
  -p debug false \
312
  --log-output \
313
  --stdout-file execution.log \
314
  --stderr-file errors.log
315

316
echo "Notebook execution completed successfully!"
317
```
318

319
## Utility Functions
320

321
Internal CLI utility functions for parameter processing.
322

323
```python { .api }
324
def _resolve_type(value: str):
325
    """
326
    Resolves string values to appropriate Python types.
327
    
328
    Parameters:
329
    - value: String value to resolve
330
    
331
    Returns:
332
    Appropriately typed value (int, float, bool, str)
333
    """
334

335
def _is_int(value: str) -> bool:
336
    """
337
    Checks if string represents an integer.
338
    
339
    Parameters:
340
    - value: String to check
341
    
342
    Returns:
343
    bool: True if string is an integer
344
    """
345

346
def _is_float(value: str) -> bool:
347
    """
348
    Checks if string represents a float.
349
    
350
    Parameters:
351
    - value: String to check
352
    
353
    Returns:
354
    bool: True if string is a float
355
    """
356

357
def print_papermill_version(
358
    ctx: click.Context,
359
    param: click.Parameter,
360
    value: bool
361
) -> None:
362
    """
363
    Prints papermill version information and exits.
364
    
365
    Parameters:
366
    - ctx: Click context
367
    - param: Click parameter
368
    - value: Whether to print version
369
    """
370
```