codemap_macro_run

Execute a shell macro.

macroshellrunexecute

Parameters

Name	Type	Required	Description
`name`	`string`	✅ Required	Macro name to execute

Usage Examples

MCP Usage (for AI Agents like Claude)

json

{
  "name": "codemap_macro_run",
  "arguments": {
    "name": "build"
  }
}

Example Output

JSON Response

json

{
  "success": true,
  "data": {
    "macro": "build",
    "exitCode": 0,
    "stdout": "> webpack --mode production\n\nBuilt successfully in 3.2s\nOutput: dist/bundle.js (245 KB)\n",
    "stderr": ""
  }
}

ℹ️When to Use This Tool

codemap_macro_run

Build automation - Run build, test, lint commands with single macro call
Development workflows - Execute common development tasks quickly
CI/CD pipelines - Run deployment and release macros in automated workflows
Testing - Execute test suites with configured environment variables
Team standardization - Ensure everyone runs commands the same way
Complex operations - Run multi-step commands with proper configuration
Environment-specific tasks - Execute commands with bundled environment variables

💡Common Patterns

Check Exit Code

const result = await codemap.macros.run('test');

if (result.exitCode === 0) {
  console.log('Success');
} else {
  console.error('Failed with code', result.exitCode);
  process.exit(result.exitCode);
}

Sequential Execution with Bail-Out

const tasks = ['lint', 'test', 'build'];

for (const task of tasks) {
  const result = await codemap.macros.run(task);
  
  if (result.exitCode !== 0) {
    console.error(${task} failed, stopping pipeline);
    process.exit(1);
  }
}

Capture and Parse Output

const result = await codemap.macros.run('test');

// Parse test output
const testLines = result.stdout.split('\n');
const passed = testLines.filter(l => l.includes('PASS')).length;
const failed = testLines.filter(l => l.includes('FAIL')).length;

console.log(Tests: ${passed} passed, ${failed} failed);

Conditional Execution

// Only deploy if tests pass
const testResult = await codemap.macros.run('test');

if (testResult.exitCode === 0) {
  await codemap.macros.run('deploy');
}

💡Pro Tips

Always check exit codes - Don't assume success. Always check exitCode === 0 before proceeding.

Capture both stdout and stderr - Errors might be in either stream depending on the command.

Use try-catch for macro not found - Wrap runs in try-catch to handle non-existent macros gracefully.

Stream output for long tasks - For builds or deployments, stream stdout/stderr so users see progress.

Set appropriate timeouts - Ensure macros have realistic timeouts configured (default is 30s).

Validate before running - Use macro_list first to verify the macro exists.

✅Best Practices

Run in order of importance - Run critical tasks (lint, test) before expensive tasks (build, deploy).

Fail fast - Exit immediately on first failure rather than running all macros.

Log macro execution - Always log which macro is running for debugging.

Handle timeouts - Be prepared for macros to timeout on slow operations.

Parse output intelligently - Extract meaningful info from stdout (test counts, build times, etc.).

Don't ignore stderr - Even successful commands (exitCode 0) may have warnings in stderr.

⚠️Common Mistakes

❌ Mistake: Not checking exit code

const result = await codemap.macros.run('test');
console.log('Tests complete'); // Might have failed!

✅ Instead: Always check exit code

const result = await codemap.macros.run('test');
if (result.exitCode === 0) {
  console.log('Tests passed');
} else {
  console.error('Tests failed');
  process.exit(1);
}

---

❌ Mistake: Running non-existent macro

await codemap.macros.run('biuld'); // Typo!
// Error: Macro "biuld" not found

✅ Instead: Validate first

const macros = await codemap.macros.list();
if (macros.some(m => m.name === 'build')) {
  await codemap.macros.run('build');
} else {
  console.error('Build macro not configured');
}

---

❌ Mistake: Ignoring stderr

const result = await codemap.macros.run('build');
console.log(result.stdout); // Misses warnings!

✅ Instead: Check both streams

const result = await codemap.macros.run('build');
if (result.stdout) console.log(result.stdout);
if (result.stderr) console.warn(result.stderr);

---

❌ Mistake: Not handling failures in parallel execution

await Promise.all([
  codemap.macros.run('lint'),
  codemap.macros.run('test'),
  codemap.macros.run('build')
]);
// One failure crashes all

✅ Instead: Use Promise.allSettled

const results = await Promise.allSettled([
  codemap.macros.run('lint'),
  codemap.macros.run('test'),
  codemap.macros.run('build')
]);

results.forEach((result, i) => {
  if (result.status === 'rejected') {
    console.error(Task ${i} failed:, result.reason);
  }
});

---

❌ Mistake: Continuing after critical failure

await codemap.macros.run('test');
await codemap.macros.run('deploy'); // Deploys even if tests failed!

✅ Instead: Check success before proceeding

const testResult = await codemap.macros.run('test');
if (testResult.exitCode === 0) {
  await codemap.macros.run('deploy');
} else {
  console.error('Tests failed, skipping deploy');
  process.exit(1);
}

---

❌ Mistake: Not providing feedback during long operations

// User sees nothing for minutes
const result = await codemap.macros.run('build');
console.log('Build complete');

✅ Instead: Stream output

console.log('Building...');
const result = await codemap.macros.run('build');
console.log(result.stdout); // Shows progress
console.log('Build complete');

---

❌ Mistake: Running macros with stale configuration

// Macro still has old command
await codemap.macros.run('deploy');

✅ Instead: Verify configuration first

const macros = await codemap.macros.list();
const deploy = macros.find(m => m.name === 'deploy');

console.log(Running deploy: ${deploy.cmd});
await codemap.macros.run('deploy');