{"id":16682585,"url":"https://github.com/jchip/xsh","last_synced_at":"2026-03-14T18:38:24.608Z","repository":{"id":57402265,"uuid":"94297866","full_name":"jchip/xsh","owner":"jchip","description":"Some random NodeJS helper functions for shell execution","archived":false,"fork":false,"pushed_at":"2020-07-18T16:36:10.000Z","size":42,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-02T00:32:00.181Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jchip.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-06-14T06:34:57.000Z","updated_at":"2020-07-18T16:36:12.000Z","dependencies_parsed_at":"2022-09-17T06:42:41.394Z","dependency_job_id":null,"html_url":"https://github.com/jchip/xsh","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jchip%2Fxsh","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jchip%2Fxsh/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jchip%2Fxsh/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jchip%2Fxsh/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jchip","download_url":"https://codeload.github.com/jchip/xsh/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243271340,"owners_count":20264440,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-12T14:08:01.084Z","updated_at":"2025-12-24T18:48:28.800Z","avatar_url":"https://github.com/jchip.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![NPM version][npm-image]][npm-url] [![Build Status][travis-image]][travis-url]\n[![Dependency Status][daviddm-image]][daviddm-url] [![devDependency Status][daviddm-dev-image]][daviddm-dev-url]\n\n# xsh\n\nSome random NodeJS helper functions for shell execution\n\n## Install\n\n```bash\nnpm install xsh --save-dev\n```\n\n## Usage\n\n```js\nconst xsh = require(\"xsh\");\n\nxsh.exec(\"echo hello\");\n```\n\n## API\n\n### `Promise`\n\nYou can set a custom `Promise` with:\n\n```js\nxsh.Promise = require(\"bluebird\");\n```\n\nOr set to the native `Promise` with:\n\n```js\nxsh.Promise = null;\n```\n\n### [mkCmd](#mkcmd)\n\n```js\nxsh.mkCmd([\"echo\", \"hello\"]);\nxsh.mkCmd(\"echo\", \"hello\");\n```\n\nBoth return the string `\"echo hello\"`.\n\n### [exec](#exec)\n\n```js\nxsh.exec(shellCommand, [options], [callback] );\n```\n\nUse [shelljs `exec`] to execute `shellCommand` in `async` mode.\n\n#### Arguments\n\n-   `shellCommand` - can be combination of multiple strings and arrays.  Array is joined with `\" \"` into strings.  All final strings are joined with `\" \"`.\n\n-   `options` - optional `options`\n\n    -   If it's either `true` or `false`, it sets `silent` flag for output to console.\n    -   It can also be an object that's passed to [NodeJS exec](https://nodejs.org/api/child_process.html#child_process_child_process_exec_command_options_callback).\n        -   For example, it can be `{silent: true}`\n    -   This can be the first, last, or second to last (if last is the callback) argument.\n\n-   `callback` - optional, if provided, it will be called as follows:\n\n`callback( code !== 0 ? new Error(\"...\") : undefined, { stdout, stderr } )`\n\n`error.output` is set to `{ stdout, stderr}`.\n`error.code` is set to `code`.\n\n#### Returns\n\n-   With callback - The `child` object returned by `exec`\n\n-   Without callback - An object with following:\n\n```js\n{\n  then, catch, promise, child, stdout, stderr\n}\n```\n\nWhere:\n\n-   `then` - a wrapper function for calling the `promise.then`\n-   `catch` - a wrapper function for calling the `promise.catch`\n-   `promise` - rejects with the error or resolves with `{ stdout, stderr }`\n-   `child` - the child from `exec`\n-   `stdout` and `stderr` - alias to `child.stdout` and `child.stderr`\n\n#### exec Examples\n\n-   With Promise:\n\n```js\nxsh.exec(\"echo hello\").then(r =\u003e { console.log(\"result\", r.stdout); });\n```\n\n-   With `options`:\n\n```js\nxsh.exec(\"pwd\", {cwd: \"/tmp\"}).then(r =\u003e { console.log(\"result\", r.stdout)})\n```\n\n-   With callback:\n\n```js\nxsh.exec(\"echo hello\", (r) =\u003e {console.log(\"result\", r.stdout)})\n```\n\n-   `shellCommand` as a combination of strings and array of strings:\n\n```js\nxsh.exec(\"echo\", [\"hello\", \"world\"], {silent: false})\n```\n\nWould run shell command: `echo hello world`\n\n### [envPath.addToFront](#envpathaddtofront)\n\n```js\nxsh.envPath.addToFront(path, [env]);\n```\n\nAdd `path` to the front of `process.env.PATH`.  If it already exists, then it is moved to the front.\n\nIf you don't want to operate on `process.env` you can pass in a second argument that's either an object or a string that's the path to change.\n\n### [envPath.addToEnd](#envpathaddtoend)\n\n```js\nxsh.envPath.addToEnd(path, [env]);\n```\n\nAdd `path` to the end of `process.env.PATH`.  If it already exists, then it is moved to the end.\n\nIf you don't want to operate on `process.env` you can pass in a second argument that's either an object or a string that's the path to change.\n\n### [envPath.add](#envpathadd)\n\n```js\nxsh.envPath.add(path, [env]);\n```\n\nIf `path` doesn't exist in `process.env.PATH` then it's added to the end.\n\nIf you don't want to operate on `process.env` you can pass in a second argument that's either an object or a string that's the path to change.\n\n### [`$`](#)\n\nAn instance of [shelljs].\n\n```js\nconst xsh = require(\"xsh\");\nxsh.$.cd(\"/tmp\");\n```\n\n[shelljs `exec`]: http://documentup.com/shelljs/shelljs#execcommand--options--callback\n\n[shelljs]: https://github.com/shelljs/shelljs\n\n[travis-image]: https://travis-ci.org/jchip/xsh.svg?branch=master\n\n[travis-url]: https://travis-ci.org/jchip/xsh\n\n[npm-image]: https://badge.fury.io/js/xsh.svg\n\n[npm-url]: https://npmjs.org/package/xsh\n\n[daviddm-image]: https://david-dm.org/jchip/xsh/status.svg\n\n[daviddm-url]: https://david-dm.org/jchip/xsh\n\n[daviddm-dev-image]: https://david-dm.org/jchip/xsh/dev-status.svg\n\n[daviddm-dev-url]: https://david-dm.org/jchip/xsh?type=dev\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjchip%2Fxsh","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjchip%2Fxsh","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjchip%2Fxsh/lists"}