{"id":19930649,"url":"https://github.com/mnasyrov/shellboard","last_synced_at":"2025-06-23T05:09:08.458Z","repository":{"id":57358275,"uuid":"166520206","full_name":"mnasyrov/shellboard","owner":"mnasyrov","description":"Simple web server with REST API to execute shell commands for quick monitor or dev automation.","archived":false,"fork":false,"pushed_at":"2019-01-20T12:24:56.000Z","size":225,"stargazers_count":7,"open_issues_count":0,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-06-12T13:16:28.632Z","etag":null,"topics":["api","bash","cli","http","nodejs","proxy","server","shell"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mnasyrov.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-01-19T07:42:49.000Z","updated_at":"2025-03-18T14:40:38.000Z","dependencies_parsed_at":"2022-09-06T21:40:58.725Z","dependency_job_id":null,"html_url":"https://github.com/mnasyrov/shellboard","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/mnasyrov/shellboard","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mnasyrov%2Fshellboard","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mnasyrov%2Fshellboard/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mnasyrov%2Fshellboard/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mnasyrov%2Fshellboard/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mnasyrov","download_url":"https://codeload.github.com/mnasyrov/shellboard/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mnasyrov%2Fshellboard/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261417595,"owners_count":23155076,"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":["api","bash","cli","http","nodejs","proxy","server","shell"],"created_at":"2024-11-12T23:04:43.747Z","updated_at":"2025-06-23T05:09:03.441Z","avatar_url":"https://github.com/mnasyrov.png","language":"TypeScript","readme":"# ShellBoard\n\n[![npm version](https://badge.fury.io/js/shellboard.svg)](https://www.npmjs.com/shellboard)\n[![build Status](https://travis-ci.org/mnasyrov/shellboard.svg?branch=master)](https://travis-ci.org/mnasyrov/shellboard)\n[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg)](https://conventionalcommits.org)\n\n\n## What is it?\n\nShellBoard is a simple web server with REST API to execute shell commands for quick monitor or dev automation. The commands are configured statically and not editable outside. \n\n\n## Why?\n\nSometimes it is need to have an ad-hoc web server:\n\n* for monitoring a system state by shell commands;\n* for triggering system actions during development or integration testing.\n\nShellBoard covers urgent needs to automate some actions by triggering HTTP API.\n\n\n## Features\n\n* Simple configuration;\n* Simple REST API;\n* Optional Basic Authentication for API requests.\n\n\n## Usage\n\n**Disclaimer:** By default, ShellBoard listen requests only from `localhost`. It is a responsibility of a server administrator to configure the tool properly and use it securely.\n\n### Quick start\n\nCreate `shellboard.json` file in a current directory:\n\n```json\n{\n  \"commands\": [\n    \"echo Hello World!\",\n    \"date\"\n  ]\n}\n```\n\nStart the server:\n\n```bash\nnpx shellboard\n# or: yarn shellboard\n# or: node node_modules/.bin/shellboard\n```\n\nTrigger API endpoints:\n\n```bash\n# List commands\ncurl http://localhost:3000/api/commands\n{\"commands\":[\"echo Hello World!\",\"date\"]}\n\n# Execute a command\ncurl -X POST http://localhost:3000/api/commands/0\n{\"command\":\"echo Hello World!\",\"exitStatus\":0,\"stdout\":\"Hello World!\\n\",\"stderr\":\"\"}\n\ncurl -X POST http://localhost:3000/api/commands/1\n{\"command\":\"date\",\"exitStatus\":0,\"stdout\":\"Sat Jan 19 21:56:30 +07 2019\\n\",\"stderr\":\"\"}\n```\n\n### Installation\n\nShellBoard can be installed as a global tool:\n\n```bash\nnpm install --global shellboard\n```\n\nAs a development dependency of a project:\n\n```bash\nnpm install --save-dev --save-exact shellboard\n# or:  yarn add --dev --exact shellboard\n```\n\nShellBoard can be run without installation using `npx` command of `npm`:\n\n```bash\nnpx shellboard\n```\n\n### Configuration\n\nShellBoard is configured by environment variables and a configuration file.\n\n#### Environment variables\n\nThe tool uses [dotenv](https://www.npmjs.com/package/dotenv) library to optionally load environment variables from `.env` file in a current working directory. See [.env.defaults](.env.defaults) file as an example.\n\nVariables and default values:\n\n* `SHELLBOARD_CONFIG` – A path to a configuration file. Default value: `shellboard.json`.\n* `SERVER_HOST` – Configures HTTP server to listen a specified network interface. Default value: `localhost`.\n  To accept external requests from all network interfaces set it to `0.0.0.0`.\n* `SERVER_PORT` – Configures HTTP server to listen a specified port. Default value: `3000`.\n* `HTTP_LOG_FORMAT` – Defines a log format for HTTP requests. Default value: `common`.\n  Other values: `combined`, `common`, `dev`, `short`, `tiny`. Check documentation of [morgan](https://github.com/expressjs/morgan) library to define custom formats.\n* `BASIC_AUTH` – Enables Basic Authentication for API endpoints if it is specified. Value format: `username:password`.\n\n#### Configuration file\n\nBy default ShellBoard looks for `shellboard.json` file in a current working directory. File path can be changed by `SHELLBOARD_CONFIG` environment variable.\n\nThis file declares an array of shell commands which will be available via API.\n\n```json\n{\n  \"commands\": [\n    \"ls\",\n    \"free -h\",\n    \"df -u .\"\n  ]\n}\n```\n\nSee [shellboard-example.json](shellboard-example.json) as an example.\n\n\n## REST API\n\n### `GET /api/commands`\nReturns a list of available commands.\n\nResponse:\n```json\n{\n  \"commands\": [\n    \"echo Hello World!\",\n    \"date\"\n  ]\n}\n```\n\n### `GET /api/commands/:index` \nReturns details about a command specified by an index of `commands` list.\n\nResponse:\n```json\n{\n  \"command\": \"echo Hello World!\"\n}\n```\n\n### `POST /api/commands/:index` \nExecutes a command specified by an index of `commands` list.\n\nResponse:\n\n```json\n{\n  \"command\": \"echo Hello World!\",\n  \"exitStatus\": 0,\n  \"stdout\": \"Hello World!\\n\", \n  \"stderr\": \"\"\n}\n```\n\n\n## Development\n\n[Yarn](https://yarnpkg.com) is used as package and build manager.\n\nDevelopment scripts:\n* `yarn start` – runs a development server in watching mode.\n* `yarn lint` – checks source code by static analysis tools.\n* `yarn test` – runs unit tests.\n* `yarn check-format` – check formats of source code.\n* `yarn format` – formats source code by [prettier](https://prettier.io/) tool.\n* `yarn check-commit` – runs all necessary checks, tests and builds to ensure the commit will be green.\n\nBuild scripts: \n* `yarn build` – compiles sources.\n* `yarn dist` – makes an app bundle in `/dist` directory.\n\nRelease (for maintainers):\n\n```bash\ngit checkout master; git pull origin master\nyarn check-commit\nyarn dist-build\nyarn check-release\nyarn release\ngit push --follow-tags origin master\nnpm publish\n```\n\n## License\n\n[MIT](LICENSE)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmnasyrov%2Fshellboard","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmnasyrov%2Fshellboard","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmnasyrov%2Fshellboard/lists"}