@actions/exec

What is @actions/exec?

@actions/exec is an npm package designed to facilitate the execution of shell commands within GitHub Actions workflows. It provides a simple and flexible API to run commands, capture their output, and handle errors.

What are @actions/exec's main functionalities?

Basic Command Execution

This feature allows you to execute basic shell commands. In this example, the 'echo' command is used to print 'Hello, world!' to the console.

const exec = require('@actions/exec');

async function run() {
  await exec.exec('echo', ['Hello, world!']);
}

run();

Capture Output

This feature allows you to capture the output and error streams of the executed command. In this example, the 'node -v' command is executed, and its output and error streams are captured and printed to the console.

const exec = require('@actions/exec');

async function run() {
  let myOutput = '';
  let myError = '';

  const options = {};
  options.listeners = {
    stdout: (data) => {
      myOutput += data.toString();
    },
    stderr: (data) => {
      myError += data.toString();
    }
  };

  await exec.exec('node', ['-v'], options);
  console.log('Output:', myOutput);
  console.log('Error:', myError);
}

run();

Command with Options

This feature allows you to execute commands with additional options such as the working directory and environment variables. In this example, the 'ls -la' command is executed in a specified working directory with a custom environment variable.

const exec = require('@actions/exec');

async function run() {
  const options = {
    cwd: '/path/to/working/directory',
    env: { MY_VAR: 'value' }
  };

  await exec.exec('ls', ['-la'], options);
}

run();

Other packages similar to @actions/exec

child_process

The 'child_process' module is a built-in Node.js module that provides the ability to spawn child processes. It offers similar functionalities to @actions/exec, such as executing shell commands and capturing their output. However, it is more low-level and requires more boilerplate code to achieve the same tasks.

shelljs

ShellJS is a popular npm package that provides portable Unix shell commands for Node.js. It offers a higher-level API compared to 'child_process' and includes additional utilities for file system operations. While it is not specifically designed for GitHub Actions, it can be used to achieve similar command execution functionalities.

execa

Execa is a modern npm package for executing shell commands in Node.js. It provides a promise-based API, better error handling, and more features compared to 'child_process'. Execa is a good alternative to @actions/exec for general-purpose command execution in Node.js applications.

README

@actions/exec

Usage

Basic

You can use this package to execute your tools on the command line in a cross platform way:

const exec = require('@actions/exec');

await exec.exec('node index.js');

Args

You can also pass in arg arrays:

const exec = require('@actions/exec');

await exec.exec('node', ['index.js', 'foo=bar']);

Output/options

Capture output or specify other options:

const exec = require('@actions/exec');

const myOutput = '';
const myError = '';

const options = {};
options.listeners = {
  stdout: (data: Buffer) => {
    myOutput += data.toString();
  },
  stderr: (data: Buffer) => {
    myError += data.toString();
  }
};
options.cwd = './lib';

await exec.exec('node', ['index.js', 'foo=bar'], options);

Exec tools not in the PATH

You can use it in conjunction with the which function from @actions/io to execute tools that are not in the PATH:

const exec = require('@actions/exec');
const io = require('@actions/io');

const pythonPath: string = await io.which('python', true)

await exec.exec(`"${pythonPath}"`, ['main.py']);