run_ad_hoc
Execute Ansible ad-hoc commands on specified hosts with a single request, enabling immediate task execution and configuration management without full playbooks.
Instructions
Run an Ansible ad-hoc command against specified hosts
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| args | No | ||
| become | No | ||
| extra_vars | No | ||
| inventory | No | ||
| module | No | shell | |
| pattern | Yes |
Input Schema (JSON Schema)
{
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"args": {
"type": "string"
},
"become": {
"type": "boolean"
},
"extra_vars": {
"additionalProperties": {},
"type": "object"
},
"inventory": {
"type": "string"
},
"module": {
"default": "shell",
"type": "string"
},
"pattern": {
"minLength": 1,
"type": "string"
}
},
"required": [
"pattern"
],
"type": "object"
}
Implementation Reference
- The main handler function that executes the Ansible ad-hoc command. It constructs the ansible CLI command from options and runs it using execAsync.export async function runAdHoc(options: RunAdHocOptions): Promise<string> { const inventoryPath = validateInventoryPath(options.inventory); // Build command let command = `ansible ${options.pattern}`; // Add module command += ` -m ${options.module}`; // Add module args if specified if (options.args) { command += ` -a "${options.args}"`; } // Add inventory if specified if (inventoryPath) { command += ` -i ${inventoryPath}`; } // Add become flag if needed if (options.become) { command += ' --become'; } // Add extra vars if specified if (options.extra_vars && Object.keys(options.extra_vars).length > 0) { const extraVarsJson = JSON.stringify(options.extra_vars); command += ` --extra-vars '${extraVarsJson}'`; } try { // Execute command const { stdout, stderr } = await execAsync(command); return stdout || 'Command executed successfully (no output)'; } catch (error) { // Handle exec error const execError = error as { stderr?: string; message: string }; throw new AnsibleExecutionError( `Error running ad-hoc command: ${execError.message}`, execError.stderr ); } }
- Zod schema defining the input validation for the run_ad_hoc tool parameters.export const RunAdHocSchema = z.object({ pattern: z.string().min(1, 'Host pattern is required'), module: z.string().default('shell'), args: z.string().optional(), inventory: z.string().optional(), become: z.boolean().optional(), extra_vars: z.record(z.any()).optional(), });
- src/sysoperator/index.ts:75-79 (registration)Registration of the 'run_ad_hoc' tool in the toolDefinitions object, specifying its description, input schema, and handler function.run_ad_hoc: { description: 'Run an Ansible ad-hoc command against specified hosts', schema: RunAdHocSchema, handler: adHoc.runAdHoc, },