Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


Build status MIT licensed view on npm download count node npm type definitions standard-readme compliant

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.

Table of Contents


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-tag


Import 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-tag does not use a shell, things like $VAR or ~ 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


A template tag that safely runs commands for you







No packages published