0
# CLI Commands
1

2
Molecule provides a comprehensive command-line interface for managing the complete lifecycle of Ansible role testing, from initialization through destruction of test environments.
3

4
## Capabilities
5

6
### Main CLI Entry Point
7

8
The primary entry point for all Molecule operations, providing global options and command routing.
9

10
```python { .api }
11
def main(ctx, debug, verbose, base_config, env_file):
12
    """
13
    Molecule aids in the development and testing of Ansible roles.
14
    
15
    Args:
16
        ctx (click.Context): Click context object
17
        debug (bool): Enable or disable debug mode. Default is disabled
18
        verbose (int): Increase Ansible verbosity level. Default is 0
19
        base_config (list[str]): Path to base config files (can be multiple)
20
        env_file (str): File to read variables from when rendering molecule.yml (.env.yml)
21
    """
22
```
23

24
### Lifecycle Commands
25

26
Core commands for managing the test instance lifecycle.
27

28
```python { .api }
29
def create():
30
    """Create test instances using the configured driver."""
31

32
def prepare():
33
    """Run the prepare playbook to set up test instances."""
34

35
def converge():
36
    """Run the converge playbook to apply the role being tested."""
37

38
def verify():
39
    """Run verification tests using the configured verifier."""
40

41
def destroy():
42
    """Destroy test instances and clean up resources."""
43

44
def cleanup():
45
    """Run cleanup tasks and remove temporary files."""
46
```
47

48
### Test Commands
49

50
Commands for running various types of tests and validations.
51

52
```python { .api }
53
def test():
54
    """
55
    Run the full test sequence.
56
    
57
    Executes: dependency → create → prepare → converge → 
58
             idempotence → side_effect → verify → cleanup → destroy
59
    """
60

61
def check():
62
    """Run the check playbook to validate syntax and configuration."""
63

64
def syntax():
65
    """Validate Ansible playbook syntax using ansible-playbook --syntax-check."""
66

67
def idempotence():
68
    """
69
    Test role idempotence by running converge twice.
70
    
71
    Verifies that the role doesn't make changes on subsequent runs.
72
    """
73

74
def side_effect():
75
    """Run the side effect playbook for additional testing scenarios."""
76
```
77

78
### Management Commands
79

80
Commands for managing scenarios, dependencies, and getting information.
81

82
```python { .api }
83
def init():
84
    """Initialize new Molecule scenarios or roles with default templates."""
85

86
def list_():
87
    """List available scenarios and their current status."""
88

89
def matrix():
90
    """Display the test matrix showing which scenarios run which steps."""
91

92
def dependency():
93
    """Install role dependencies using the configured dependency manager."""
94

95
def drivers():
96
    """List available drivers and their capabilities."""
97

98
def reset():
99
    """Reset Molecule state by clearing cached data and configurations."""
100
```
101

102
### Interactive Commands
103

104
Commands for interactive debugging and exploration.
105

106
```python { .api }
107
def login():
108
    """
109
    Login to a test instance for interactive debugging.
110
    
111
    Args:
112
        host (str): Hostname of the instance to login to
113
        
114
    Provides an interactive shell session on the specified test instance.
115
    """
116
```
117

118
## Usage Examples
119

120
### Basic Command Usage
121

122
```bash
123
# Initialize a new role with molecule
124
molecule init role my-role --driver-name default
125

126
# Run the complete test suite
127
molecule test
128

129
# Run individual lifecycle steps
130
molecule create
131
molecule converge  
132
molecule verify
133
molecule destroy
134

135
# Debug mode with increased verbosity
136
molecule --debug -vvv test
137

138
# Use custom configuration
139
molecule -c custom-config.yml test
140

141
# Test specific scenario
142
molecule test -s integration-tests
143

144
# Login to a test instance for debugging
145
molecule login --host instance-1
146
```
147

148
### Multi-Scenario Testing
149

150
```bash
151
# List all scenarios
152
molecule list
153

154
# Show test matrix
155
molecule matrix
156

157
# Test all scenarios
158
molecule test --all
159

160
# Test with parallel execution
161
molecule test --parallel
162
```
163

164
### Custom Configuration
165

166
```bash
167
# Use custom environment file
168
molecule -e custom.env.yml test
169

170
# Use multiple base configs
171
molecule -c base.yml -c override.yml test
172

173
# Test with custom destroy strategy
174
molecule test --destroy never
175
```
176

177
## Command Options
178

179
### Global Options
180

181
- `--debug/--no-debug`: Enable debug mode for detailed logging
182
- `-v, --verbose`: Increase Ansible verbosity (can be repeated: -vvv)  
183
- `-c, --base-config`: Path to base configuration files (multiple allowed)
184
- `-e, --env-file`: Environment file for variable substitution
185
- `--version`: Show version information and exit
186

187
### Common Command Options
188

189
- `-s, --scenario-name`: Target specific scenario
190
- `--driver-name`: Override driver for the operation  
191
- `--platform-name`: Target specific platform
192
- `--force`: Force execution even with warnings
193
- `--parallel`: Enable parallel execution where supported
194

195
### Test Command Options
196

197
- `--destroy`: Destroy strategy ("always" or "never")
198
- `--all`: Test all scenarios
199
- `--scenario-name`: Test specific scenario only
200

201
## Integration Notes
202

203
- Commands use Click framework for argument parsing and validation
204
- Global options are passed through context to individual commands
205
- Verbosity settings affect both Molecule and Ansible output levels
206
- Configuration files support YAML format with environment variable substitution
207
- Command execution follows dependency chains and validates prerequisites