runme

Runme.js

A JavaScript module to use Runme in Node.js.

Runme.js contains the Runme CLI and allows to access its functionality through a simple JavaScript interface. The CLI binary is downloaded and cached when the interface is first being used.

Install

Node.js

Install the module through NPM:

$ npm install runme
# or Yarn
$ yarn add runme

You can also install the package globally and it as a CLI, e.g.:

npm i -g runme
runme list

By default this package downloads the Runme CLI when the interface is used for the first time. You can download it after running npm install by setting the RUNME_DOWNLOAD_ON_INSTALL environment flag. You can also modify the Runme version that is being installed by setting RUNME_VERSION, e.g.:

RUNME_DOWNLOAD_ON_INSTALL=1 RUNME_VERSION=1.0.0 npm install runme
npx runme --version # prints "runme version 1.0.0 (adae05c5b75351e9fe82acd595ac8086b6abf19b) on 2023-03-28T20:56:21Z"

Usage

The module exposes the following methods:

run

Run code cells from markdown files:

import { run } from "runme";

const result = await run(["helloWorld"]);
console.log(result); // outputs: { exitCode: 0, stdout: 'Hello World\r\n', stderr: '' }

Runme can run multiple commands in a single shell session that allows you to keep environment variables around.

import { run } from "runme";

// execute `echo "exported FOO=$FOO"` from markdown code cell with id "print"
const result = await run(["export", "print"]);
console.log(result);
// outputs:
// {
//   exitCode: 0,
//   stdout: ' ►  Running task export...\n' +
//     ' ►  ✓ Task export exited with code 0\n' +
//     ' ►  Running task print...\n' +
//     'exported FOO=bar\r\n' +
//     ' ►  ✓ Task print exited with code 0\n',
//   stderr: ''
// }

Contributing

See CONTRIBUTING.md for more information or just click on:

Copyright 2025 © Stateful – Apache 2.0 License