Why HagiCode Chose execa for CLI Command Execution

Using child_process directly in Node.js projects to execute external commands comes with pain points like significant platform differences and inconsistent error handling. This article shares the practical experience of introducing execa in the HagiCode project, including core design decisions and real code examples.

Background

In Node.js projects, directly using the child_process module to execute external commands is common practice, but it comes with quite a few issues:

• Significant platform differences: Windows .cmd/.bat files require special handling, and paths containing spaces need to be wrapped in quotes
• Inconsistent error handling: execFile, spawn, and execFileSync produce error information in varying formats, making unified handling difficult
• Tedious stream processing: Manual collection and buffering of stdout/stderr streams is required
• Complex timeout and signal handling: Extra code is needed to implement command timeout cancellation and process signal handling

The Hagiscript and Desktop applications within the HagiCode project both need to execute a large number of external CLI commands (npm, node, PowerShell, etc.). Directly using child_process led to code duplication and high maintenance costs.

To address these pain points, we made a decision: introduce execa as a unified command execution solution. The impact of this decision turned out to be greater than you might imagine — I'll explain the specifics shortly.

About HagiCode

The approach shared in this article comes from our practical experience in the HagiCode project. HagiCode is an AI coding assistant project that needs to execute a large number of external commands across multiple sub-projects (the Hagiscript scripting engine and the Desktop application). The complexity of supporting multiple languages and platforms is perhaps the direct reason we chose to introduce execa.

If you find the approach shared in this article valuable, it speaks to our engineering capabilities — and HagiCode itself is worth checking out.

Why execa?

execa is a mature process execution library that addresses the core problems of child_process:

1. Cross-platform consistency: Automatically handles Windows command shims without manually detecting .cmd files
2. Unified error handling: Standardized error objects containing exitCode, signal, timedOut, stdout, and stderr
3. Better API design: Supports Promise API, AbortSignal cancellation, and stream processing
4. Security: Maintains argument boundaries, avoiding command injection risks

These are exactly the features we needed during HagiCode development. Hagiscript needs to execute npm commands across different platforms, and Desktop needs to call PowerShell and various development tools. execa's cross-platform consistency significantly reduced our platform-specific code. After all, who wants to write special handling code for every platform?

Core Design Decisions

Both projects' implementations use an internal wrapper layer rather than calling execa directly:

// Hagiscript's unified executor
export const runCommand: CommandRunner = async (command, args, options) => {
  const result = await execa(command, args, { /* normalized options */ });
  return { /* normalized result */ };
};

Reasons:

• Maintain domain-specific error types (e.g., NpmCommandError)
• Enable injecting mock executors during testing
• Unify error handling and logging
• Make it easy to replace the underlying implementation in the future

Argument Boundary Protection

Both implementations emphasize argument arrays over shell strings:

// Correct: clear argument boundaries
await runCommand('npm', ['install', '@scope/package@1.0.0']);

// Wrong: prone to injection risks
await execa(`npm install @scope/package@1.0.0`, { shell: true });

This avoids security issues related to argument quoting, escaping, and injection. In HagiCode, we frequently handle user-supplied inputs like package names and script names as parameters. Using argument arrays effectively prevents command injection. When it comes to security, once something goes wrong, it's a big problem.

Hagiscript's Solution

HagiCode's Hagiscript sub-project created a runtime/command-launch.ts module that provides:

1. Unified executor: The runCommand function wraps execa
2. Standardized result: CommandResult interface
3. Standardized error: CommandExecutionError class
4. Compatibility helpers: normalizeCommandPath, requiresShellLaunch

export interface CommandResult {
  command: string;
  args: string[];
  stdout: string;
  stderr: string;
  exitCode?: number;
  signal?: string;
  timedOut?: boolean;
}

export class CommandExecutionError extends Error {
  readonly context: CommandFailureContext;
}

This abstraction allows Hagiscript to handle all external commands uniformly, whether installing npm dependencies or executing scripts with node. With a unified interface, the code really does flow much more smoothly.

Desktop's Solution

HagiCode's Desktop sub-project created a utils/cli-executor.ts module that provides:

1. Execution options: CliExecutorOptions supports timeout, cancellation, and environment variables
2. Result classification: CliExecutionResult includes success/failure status
3. Stream processing: executeCliStreaming supports real-time output callbacks
4. Error classification: CliFailureKind distinguishes between exit, timeout, cancellation, and other failure types

export async function executeCli(options: CliExecutorOptions): Promise<CliExecutionResult>
export async function executeCliStreaming(options: CliExecutorOptions): Promise<CliExecutionResult>

The Desktop application needs to display command execution progress in the UI, which is where the streaming feature comes in handy. Users can see the output of npm install in real time rather than waiting until the command finishes. Once you've experienced it, there's no going back.

Usage Examples

Executing Commands in Hagiscript

import { runCommand } from '../runtime/command-launch.js';

// Simple execution
const result = await runCommand('node', ['--version']);
console.log(result.stdout); // 'v20.0.0'

// Execution with options
const installResult = await runCommand('npm', ['install', 'express'], {
  cwd: '/project/path',
  env: { NODE_ENV: 'development' },
  timeoutMs: 30000
});

Executing Commands in Desktop

import { executeCli, executeCliStreaming } from './utils/cli-executor.js';

// Buffered execution
const result = await executeCli({
  command: 'npm',
  args: ['list', '--json'],
  cwd: projectPath,
  timeoutMs: 5000,
});

if (result.success) {
  console.log(result.stdout);
} else {
  console.error(result.error?.message);
}

// Streaming execution
await executeCliStreaming({
  command: 'npm',
  args: ['install'],
  onOutput: (type, data) => {
    console.log(`[${type}]`, data);
  }
});

Error Handling

try {
  await runCommand('npm', ['install', 'invalid-package']);
} catch (error) {
  if (error instanceof CommandExecutionError) {
    console.error('Command failed:', error.context.command);
    console.error('Exit code:', error.context.exitCode);
    console.error('Stderr:', error.context.stderr);
  }
}

Unified error handling allows us to provide a better user experience in HagiCode. For example, when an npm installation fails, we can extract the specific error message and display it to the user instead of showing a generic "command execution failed" message. Seeing the specific error at least tells the user where the problem lies.

Testing Strategy

Both projects support dependency injection for easier testing:

// Production code
async function installPackage(pkg: string, runCommand = defaultRunCommand) {
  return runCommand('npm', ['install', pkg]);
}

// Test code
it('installs package', async () => {
  const mockRunCommand = vi.fn().mockResolvedValue({
    stdout: 'installed',
    stderr: '',
    exitCode: 0
  });
  await installPackage('test-pkg', mockRunCommand);
  expect(mockRunCommand).toHaveBeenCalledWith('npm', ['install', 'test-pkg']);
});

This design makes HagiCode's tests more reliable and faster. We don't need to actually execute npm commands in tests — we only need to mock the executor to return expected results. Faster tests naturally lead to a better development experience.

Best Practices

Based on HagiCode's practice, we've summarized the following best practices:

1. Keep arguments separated: Always pass the command and arguments as separate array elements
2. Use shell mode sparingly: Only use shell: true when necessary, such as when piping or redirection is needed
3. Handle timeouts: Set timeoutMs for commands that may hang
4. Buffer size: Consider setting maxBuffer for commands with large output
5. Windows paths: execa automatically handles .cmd shims — no manual detection needed
6. Cancellation: Use AbortSignal instead of manual kill()
7. Error classification: Distinguish between process startup failure, execution failure, timeout, cancellation, and other scenarios

These are all pitfalls we've encountered during actual development. Hopefully they can save you some detours.

Common Pitfalls

// Wrong: string concatenation may allow injection
await execa(`npm install ${userInput}`, { shell: true });

// Correct: argument array
await execa('npm', ['install', userInput]);

// Wrong: ignoring timeout
await execa('npm', ['install', 'heavy-package']);

// Correct: set timeout
await execa('npm', ['install', 'heavy-package'], { timeout: 60000 });

// Wrong: assuming exit code is 0
const result = await execa('npm', ['install']);

// Correct: check for failure
try {
  await execa('npm', ['install']);
} catch (error) {
  // Handle failure
}

These pitfalls are hard-won lessons. After all, who hasn't stepped on a few landmines in production?

Summary

After introducing execa, the HagiCode project saw significant improvements in both code quality and maintainability for command execution:

• Cross-platform consistency: No more writing special handling code for Windows
• Unified error handling: Structured error messages make display and analysis easier
• Better testability: Command execution can be easily mocked through dependency injection
• More secure argument handling: Using argument arrays avoids injection risks

If you also need to execute external commands in a Node.js project, we highly recommend giving execa a try. The approach shared in this article was refined through real-world pitfalls and optimizations during HagiCode development. We hope you find it helpful.

Good tools deserve wider recognition.

References

• execa Official Documentation
• Node.js child_process Documentation
• HagiCode GitHub Repository
• HagiCode Official Website

If this article was helpful:

• Give us a Star on GitHub: github.com/HagiCode-org/site
• Visit our website to learn more: hagicode.com
• Watch a 30-minute hands-on demo: www.bilibili.com/video/BV1pirZBuEzq/
• Quick install with one click: docs.hagicode.com/installation/docker-compose
• Desktop app quick install: hagicode.com/desktop/

Original Article & License

Thanks for reading. If this article helped, consider liking, bookmarking, or sharing it.
This article was created with AI assistance and reviewed by the author before publication.

• Author: newbe36524
• Original URL: https://docs.hagicode.com/go?platform=devto&target=%2Fblog%2F2026-04-28-why-hagicode-chose-execa-for-cli-execution%2F
• License: Unless otherwise stated, this article is licensed under CC BY-NC-SA. Please retain attribution when sharing.