A template tag that safely runs commands for you
spawn-tag allows you to safely run terminal commands while including user
input. Instead of using escaping techniques, it uses Node.js’s spawn API to
pass arguments directly to the target command without using a shell to handle
parsing.
Although the method used in this module should be secure, please email me
(address is in my profile) or contact me via Keybase (I’m j_f) if you find a
security issue. Please do not open an issue as this would reveal the
security issue before I can release a fix.
npm install spawn-tag
# or:
yarn add spawn-tagImport the library:
import spawn from 'spawn-tag'
// or:
import { spawn } from 'spawn-tag'
// or, if you’re using CommonJS still:
const { spawn } = require('spawn-tag')const message = 'Hello, world!'
await spawn`echo ${message}`
// => { stdout: 'Hello, world!\n', stderr: '', code: 0, signal: null }If you don’t need to keep the output, use .silently to avoid capturing it and
save memory.
await spawn.silently`rm -r node_modules`
// => { stdout: null, stderr: null, code: 0, signal: null }If you want to customize encodings or other options passed to spawn, pass an
object:
await spawn({
env: { ...process.env, MESSAGE: message },
})`node -e 'console.log(process.env.MESSAGE)'`
// => { stdout: 'Hello, world!\n', stderr: '', code: 0, signal: null }Important: Since
spawn-tagdoes not use a shell, things like$VARor~won’t resolve themselves.
spawn can also give you buffers for stdout/stderr:
await spawn({ capture: { stdout: true } })`echo ${message}`
// => { stdout: <Buffer 48 65 6c 6c 6f 2c 20 77 6f 72 6c 64 21 0a>, stderr: null, code: 0, signal: null }The Promise-like object returned from spawn has a childProcess property
that contains the actual ChildProcess object if you need to interact with it.
// Either of these will work:
import spawn, { spawn } from 'spawn-tag'
// Same with these:
import { spawnSilently, silently } from 'spawn-tag'
const { silently } = spawn
// if you use TypeScript
import { Options } from 'spawn-tag'interface Result {
// string by default or if you pass an encoding
// Buffer if you pass `true`
// null if you pass `false` or use `.silently`
stdout: string | Buffer | null
stderr: string | Buffer | null
code: number
signal: string | null
}
interface PromiseLike extends Promise<Result> {
childProcess: ChildProcess
}
declare const silently:
| TemplateTag<PromiseLike>
| ((options: Options) => TemplateTag<PromiseLike>)
declare const spawn: { silently: typeof silently } & (
| TemplateTag<PromiseLike>
| ((options: Options) => TemplateTag<PromiseLike>))PRs accepted.
Small note: If editing the README, please conform to the standard-readme specification.
MIT © 2018 Jed Fox