0
# Main API
1

2
Core functionality for generating projects from templates, including the primary `cookiecutter()` function and CLI interface. This module provides both programmatic and command-line access to cookiecutter's project generation capabilities.
3

4
## Capabilities
5

6
### Core Project Generation
7

8
The main `cookiecutter()` function that generates projects from templates with comprehensive configuration options.
9

10
```python { .api }
11
def cookiecutter(
12
    template,
13
    checkout=None,
14
    no_input=False,
15
    extra_context=None,
16
    replay=None,
17
    overwrite_if_exists=False,
18
    output_dir='.',
19
    config_file=None,
20
    default_config=False,
21
    password=None,
22
    directory=None,
23
    skip_if_file_exists=False,
24
    accept_hooks=True,
25
    keep_project_on_failure=False
26
):
27
    """
28
    Run Cookiecutter just as if using it from the command line.
29

30
    Parameters:
31
    - template: str - A directory containing a project template directory, or a URL to a git repository
32
    - checkout: str, optional - The branch, tag or commit ID to checkout after clone
33
    - no_input: bool - Do not prompt for user input. Use default values for template parameters
34
    - extra_context: dict, optional - A dictionary of context that overrides default and user configuration
35
    - replay: bool or str, optional - Do not prompt for input, instead read from saved json
36
    - overwrite_if_exists: bool - Overwrite the contents of the output directory if it exists
37
    - output_dir: str - Where to output the generated project dir into
38
    - config_file: str, optional - User configuration file path
39
    - default_config: bool - Use default values rather than a config file
40
    - password: str, optional - The password to use when extracting the repository
41
    - directory: str, optional - Relative path to a cookiecutter template in a repository
42
    - skip_if_file_exists: bool - Skip the files in the corresponding directories if they already exist
43
    - accept_hooks: bool - Accept pre and post hooks if set to True
44
    - keep_project_on_failure: bool - If True keep generated project directory even when generation fails
45

46
    Returns:
47
    str - Path to the generated project directory
48
    """
49
```
50

51
### Command Line Interface
52

53
Main CLI entry point with comprehensive click options for all cookiecutter functionality.
54

55
```python { .api }
56
def main(
57
    template,
58
    extra_context,
59
    no_input,
60
    checkout,
61
    verbose,
62
    replay,
63
    overwrite_if_exists,
64
    output_dir,
65
    config_file,
66
    default_config,
67
    debug_file,
68
    directory,
69
    skip_if_file_exists,
70
    accept_hooks,
71
    replay_file,
72
    list_installed,
73
    keep_project_on_failure
74
):
75
    """
76
    Create a project from a Cookiecutter project template (TEMPLATE).
77
    
78
    Main CLI function that processes command-line arguments and calls the cookiecutter() function.
79
    """
80
```
81

82
### CLI Utilities
83

84
Helper functions for CLI functionality.
85

86
```python { .api }
87
def version_msg():
88
    """
89
    Return the Cookiecutter version, location and Python powering it.
90
    
91
    Returns:
92
    str - Formatted version information string
93
    """
94

95
def validate_extra_context(ctx, param, value):
96
    """
97
    Validate extra context from command line arguments.
98
    
99
    Parameters:
100
    - ctx: click.Context - Click context object
101
    - param: click.Parameter - Click parameter object  
102
    - value: tuple - Extra context values from command line
103
    
104
    Returns:
105
    dict - Validated extra context dictionary
106
    """
107

108
def list_installed_templates(default_config, passed_config_file):
109
    """
110
    List installed (locally cloned) templates.
111
    
112
    Parameters:
113
    - default_config: bool - Whether to use default config
114
    - passed_config_file: str - Path to config file
115
    """
116
```
117

118
## Usage Examples
119

120
### Basic Project Generation
121

122
```python
123
from cookiecutter.main import cookiecutter
124

125
# Generate from local template
126
result = cookiecutter('./my-template/')
127

128
# Generate from GitHub repository
129
result = cookiecutter('gh:audreyfeldroy/cookiecutter-pypackage')
130

131
# Generate with no user input
132
result = cookiecutter(
133
    'template-path',
134
    no_input=True,
135
    extra_context={'project_name': 'my-project'}
136
)
137
```
138

139
### Advanced Configuration
140

141
```python
142
# Generate with custom output directory and overwrite existing
143
result = cookiecutter(
144
    'gh:user/template-repo',
145
    checkout='v2.0.0',
146
    output_dir='/path/to/projects',
147
    overwrite_if_exists=True,
148
    extra_context={
149
        'project_name': 'advanced-project',
150
        'author_name': 'Jane Developer'
151
    }
152
)
153

154
# Generate from specific directory within repository
155
result = cookiecutter(
156
    'gh:multi-template/repo',
157
    directory='python-package',
158
    no_input=True
159
)
160
```
161

162
### Replay and Configuration
163

164
```python
165
# Use replay functionality
166
result = cookiecutter(
167
    'template-path',
168
    replay=True  # Uses saved answers from previous run
169
)
170

171
# Use custom config file
172
result = cookiecutter(
173
    'template-path',
174
    config_file='/path/to/custom-config.yaml',
175
    accept_hooks=False  # Disable pre/post hooks
176
)
177
```
178

179
### Error Handling
180

181
```python
182
from cookiecutter.main import cookiecutter
183
from cookiecutter.exceptions import (
184
    CookiecutterException,
185
    OutputDirExistsException,
186
    RepositoryNotFound
187
)
188

189
try:
190
    result = cookiecutter('template-path')
191
except OutputDirExistsException:
192
    # Handle existing output directory
193
    result = cookiecutter('template-path', overwrite_if_exists=True)
194
except RepositoryNotFound:
195
    print("Template repository not found")
196
except CookiecutterException as e:
197
    print(f"Cookiecutter error: {e}")
198
```
199

200
### CLI Usage Patterns
201

202
```bash
203
# Basic usage
204
cookiecutter template-path
205

206
# With extra context
207
cookiecutter template-path --no-input project_name='My Project' author='Jane Doe'
208

209
# Advanced options
210
cookiecutter gh:user/template \
211
    --checkout v2.0 \
212
    --output-dir ./projects \
213
    --overwrite-if-exists \
214
    --accept-hooks no
215

216
# List installed templates
217
cookiecutter --list-installed
218

219
# Replay previous session
220
cookiecutter template-path --replay
221
```