Skip to content

j-f1/spawn-tag

master
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?
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
src
 
 
 
 
 
 
 
 
 
 
 
 
 
 

spawn-tag

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

Security

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.

Install

npm install spawn-tag
# or:
yarn add spawn-tag

Usage

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.

API

// 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>))

Maintainers

@j-f1

Contribute

PRs accepted.

Small note: If editing the README, please conform to the standard-readme specification.

License

MIT © 2018 Jed Fox

About

A template tag that safely runs commands for you

Resources

License

Stars

Watchers

Forks

Packages

No packages published