0
# Command Execution
1

2
Execute Ansible command-line tools (ansible-playbook, ansible, ansible-inventory, etc.) programmatically with full argument support and output capture. Provides a consistent interface for running any Ansible command with process isolation and event handling capabilities.
3

4
## Capabilities
5

6
### Synchronous Command Execution
7

8
Execute Ansible commands and wait for completion. Returns a Runner instance with command output, return codes, and execution artifacts.
9

10
```python { .api }
11
def run_command(
12
    executable_cmd: str,
13
    cmdline_args: list = None,
14
    private_data_dir: str = None,
15
    input_fd: object = None,
16
    output_fd: object = None,
17
    error_fd: object = None,
18
    quiet: bool = False,
19
    artifact_dir: str = None,
20
    ident: str = None,
21
    rotate_artifacts: int = 0,
22
    timeout: int = None,
23
    runner_mode: str = 'pexpect',
24
    process_isolation: bool = False,
25
    process_isolation_executable: str = None,
26
    process_isolation_path: str = None,
27
    process_isolation_hide_paths: list = None,
28
    process_isolation_show_paths: list = None,
29
    process_isolation_ro_paths: list = None,
30
    container_image: str = None,
31
    container_volume_mounts: list = None,
32
    container_options: list = None,
33
    directory_isolation_base_path: str = None,
34
    envvars: dict = None,
35
    cancel_callback: callable = None,
36
    finished_callback: callable = None,
37
    status_handler: callable = None,
38
    event_handler: callable = None,
39
    artifacts_handler: callable = None,
40
    ignore_logging: bool = True,
41
    debug: bool = None,
42
    logfile: str = None
43
) -> Runner
44
```
45

46
Parameters:
47
- **executable_cmd** (str): Ansible command to execute (e.g., 'ansible-playbook', 'ansible', 'ansible-inventory')
48
- **cmdline_args** (list): Command-line arguments as a list of strings
49
- **private_data_dir** (str): Directory for input files and output artifacts
50
- **timeout** (int): Maximum execution time in seconds
51
- **process_isolation** (bool): Enable container-based execution
52
- **envvars** (dict): Environment variables to set during execution
53

54
Usage examples:
55

56
```python
57
import ansible_runner
58

59
# Run ansible-playbook command
60
result = ansible_runner.run_command(
61
    executable_cmd='ansible-playbook',
62
    cmdline_args=[
63
        'site.yml',
64
        '-i', 'inventory/hosts',
65
        '--extra-vars', 'env=production',
66
        '--check'
67
    ],
68
    private_data_dir='/path/to/private_data'
69
)
70

71
print(f"Command completed with return code: {result.rc}")
72
print(f"Status: {result.status}")
73

74
# Run ansible ad-hoc command
75
result = ansible_runner.run_command(
76
    executable_cmd='ansible',
77
    cmdline_args=[
78
        'all',
79
        '-i', 'inventory/hosts',
80
        '-m', 'setup',
81
        '--tree', '/tmp/facts'
82
    ],
83
    private_data_dir='/path/to/private_data'
84
)
85

86
# Run ansible-inventory command
87
result = ansible_runner.run_command(
88
    executable_cmd='ansible-inventory',
89
    cmdline_args=[
90
        '-i', 'inventory/hosts',
91
        '--list',
92
        '--yaml'
93
    ],
94
    private_data_dir='/path/to/private_data'
95
)
96
```
97

98
### Asynchronous Command Execution
99

100
Execute Ansible commands asynchronously for non-blocking operation with callback-based monitoring.
101

102
```python { .api }
103
def run_command_async(
104
    executable_cmd: str,
105
    cmdline_args: list = None,
106
    private_data_dir: str = None,
107
    input_fd: object = None,
108
    output_fd: object = None,
109
    error_fd: object = None,
110
    quiet: bool = False,
111
    artifact_dir: str = None,
112
    ident: str = None,
113
    rotate_artifacts: int = 0,
114
    timeout: int = None,
115
    runner_mode: str = 'pexpect',
116
    process_isolation: bool = False,
117
    process_isolation_executable: str = None,
118
    process_isolation_path: str = None,
119
    process_isolation_hide_paths: list = None,
120
    process_isolation_show_paths: list = None,
121
    process_isolation_ro_paths: list = None,
122
    container_image: str = None,
123
    container_volume_mounts: list = None,
124
    container_options: list = None,
125
    directory_isolation_base_path: str = None,
126
    envvars: dict = None,
127
    cancel_callback: callable = None,
128
    finished_callback: callable = None,
129
    status_handler: callable = None,
130
    event_handler: callable = None,
131
    artifacts_handler: callable = None,
132
    ignore_logging: bool = True,
133
    debug: bool = None,
134
    logfile: str = None
135
) -> Runner
136
```
137

138
Usage example:
139

140
```python
141
import ansible_runner
142
import time
143

144
def command_status_handler(data, runner_config):
145
    print(f"Command status: {data['status']}")
146

147
# Start async command execution
148
runner = ansible_runner.run_command_async(
149
    executable_cmd='ansible-playbook',
150
    cmdline_args=['long-running-playbook.yml', '-i', 'inventory'],
151
    private_data_dir='/path/to/private_data',
152
    status_handler=command_status_handler
153
)
154

155
# Monitor progress
156
while runner.status in ['pending', 'running']:
157
    print("Command still executing...")
158
    time.sleep(2)
159

160
print(f"Command finished with status: {runner.status}")
161
```
162

163
## Common Use Cases
164

165
### Ansible Playbook Execution
166

167
```python
168
# Basic playbook run
169
result = ansible_runner.run_command(
170
    executable_cmd='ansible-playbook',
171
    cmdline_args=['site.yml', '-i', 'hosts'],
172
    private_data_dir='/project'
173
)
174

175
# Playbook with extra variables and verbosity
176
result = ansible_runner.run_command(
177
    executable_cmd='ansible-playbook',
178
    cmdline_args=[
179
        'deploy.yml',
180
        '-i', 'production',
181
        '--extra-vars', '@vars/production.yml',
182
        '--limit', 'webservers',
183
        '-vvv'
184
    ],
185
    private_data_dir='/project'
186
)
187

188
# Dry run (check mode)
189
result = ansible_runner.run_command(
190
    executable_cmd='ansible-playbook',
191
    cmdline_args=['site.yml', '-i', 'hosts', '--check', '--diff'],
192
    private_data_dir='/project'
193
)
194
```
195

196
### Ad-hoc Commands
197

198
```python
199
# Gather facts from all hosts
200
result = ansible_runner.run_command(
201
    executable_cmd='ansible',
202
    cmdline_args=[
203
        'all',
204
        '-i', 'inventory',
205
        '-m', 'setup'
206
    ],
207
    private_data_dir='/project'
208
)
209

210
# Execute shell command on specific hosts
211
result = ansible_runner.run_command(
212
    executable_cmd='ansible',
213
    cmdline_args=[
214
        'webservers',
215
        '-i', 'inventory',
216
        '-m', 'shell',
217
        '-a', 'uptime'
218
    ],
219
    private_data_dir='/project'
220
)
221

222
# Copy files to remote hosts
223
result = ansible_runner.run_command(
224
    executable_cmd='ansible',
225
    cmdline_args=[
226
        'all',
227
        '-i', 'inventory',
228
        '-m', 'copy',
229
        '-a', 'src=/local/file dest=/remote/file'
230
    ],
231
    private_data_dir='/project'
232
)
233
```
234

235
### Inventory Operations
236

237
```python
238
# List inventory in JSON format
239
result = ansible_runner.run_command(
240
    executable_cmd='ansible-inventory',
241
    cmdline_args=['-i', 'inventory', '--list'],
242
    private_data_dir='/project'
243
)
244

245
# Show inventory for specific host
246
result = ansible_runner.run_command(
247
    executable_cmd='ansible-inventory',
248
    cmdline_args=['-i', 'inventory', '--host', 'web01'],
249
    private_data_dir='/project'
250
)
251

252
# Export inventory graph
253
result = ansible_runner.run_command(
254
    executable_cmd='ansible-inventory',
255
    cmdline_args=['-i', 'inventory', '--graph'],
256
    private_data_dir='/project'
257
)
258
```
259

260
### Ansible Configuration
261

262
```python
263
# View current configuration
264
result = ansible_runner.run_command(
265
    executable_cmd='ansible-config',
266
    cmdline_args=['view'],
267
    private_data_dir='/project'
268
)
269

270
# List all configuration options
271
result = ansible_runner.run_command(
272
    executable_cmd='ansible-config',
273
    cmdline_args=['list'],
274
    private_data_dir='/project'
275
)
276

277
# Dump configuration
278
result = ansible_runner.run_command(
279
    executable_cmd='ansible-config',
280
    cmdline_args=['dump'],
281
    private_data_dir='/project'
282
)
283
```
284

285
## Advanced Usage
286

287
### Process Isolation
288

289
Run commands in isolated containers for security and reproducibility:
290

291
```python
292
result = ansible_runner.run_command(
293
    executable_cmd='ansible-playbook',
294
    cmdline_args=['site.yml', '-i', 'inventory'],
295
    private_data_dir='/project',
296
    process_isolation=True,
297
    process_isolation_executable='podman',
298
    container_image='quay.io/ansible/ansible-runner:latest',
299
    container_volume_mounts=['/host/keys:/runner/keys:Z'],
300
    envvars={'ANSIBLE_HOST_KEY_CHECKING': 'False'}
301
)
302
```
303

304
### Custom Environment Variables
305

306
```python
307
result = ansible_runner.run_command(
308
    executable_cmd='ansible-playbook',
309
    cmdline_args=['site.yml'],
310
    private_data_dir='/project',
311
    envvars={
312
        'ANSIBLE_HOST_KEY_CHECKING': 'False',
313
        'ANSIBLE_TIMEOUT': '30',
314
        'ANSIBLE_GATHERING': 'smart'
315
    }
316
)
317
```
318

319
### Output Handling
320

321
```python
322
import tempfile
323

324
# Capture output to files
325
with tempfile.NamedTemporaryFile(mode='w+') as stdout_file, \
326
     tempfile.NamedTemporaryFile(mode='w+') as stderr_file:
327
    
328
    result = ansible_runner.run_command(
329
        executable_cmd='ansible-playbook',
330
        cmdline_args=['site.yml'],
331
        private_data_dir='/project',
332
        output_fd=stdout_file,
333
        error_fd=stderr_file
334
    )
335
    
336
    # Read captured output
337
    stdout_file.seek(0)
338
    stderr_file.seek(0)
339
    stdout_content = stdout_file.read()
340
    stderr_content = stderr_file.read()
341
```