{"id":18718103,"url":"https://github.com/pkgxdev/mash","last_synced_at":"2025-04-10T01:07:14.927Z","repository":{"id":205449878,"uuid":"714262045","full_name":"pkgxdev/mash","owner":"pkgxdev","description":"mash up millions of open source packages into monstrously powerful scripts","archived":false,"fork":false,"pushed_at":"2025-03-18T15:14:05.000Z","size":46,"stargazers_count":60,"open_issues_count":1,"forks_count":21,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-04-10T01:07:09.866Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://mash.pkgx.sh","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pkgxdev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-11-04T11:51:19.000Z","updated_at":"2025-04-02T04:36:26.000Z","dependencies_parsed_at":null,"dependency_job_id":"e8225acf-b3d0-4a2a-92fc-cd13054a613e","html_url":"https://github.com/pkgxdev/mash","commit_stats":null,"previous_names":["pkgxdev/scripthub","pkgxdev/mash"],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pkgxdev%2Fmash","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pkgxdev%2Fmash/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pkgxdev%2Fmash/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pkgxdev%2Fmash/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pkgxdev","download_url":"https://codeload.github.com/pkgxdev/mash/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248137887,"owners_count":21053775,"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-11-07T13:19:31.298Z","updated_at":"2025-04-10T01:07:14.902Z","avatar_url":"https://github.com/pkgxdev.png","language":"TypeScript","funding_links":[],"categories":["Shell"],"sub_categories":[],"readme":"# `mash`\n\nmash up millions of open source packages into monstrously powerful scripts.\n\n\u003e [!CAUTION]\n\u003e\n\u003e We have not vetted any of the scripts `mash` can run and (currently) they\n\u003e can do anything they want to your computer.\n\u003e\n\u003e We fully intend to add sandboxing and user reporting, but you have found\n\u003e `mash` super early in its life so you must practice caution in your usage.\n\u003e\n\u003e All scripts can be read in advance via [mash.pkgx.sh]\n\n\u0026nbsp;\n\n## Quick Start\n\n```sh\nbrew install pkgxdev/made/mash || curl https://mash.pkgx.sh | sh\n```\n\n\u003e [!NOTE]\n\u003e `mash` is a plain POSIX script. All it needs is `bash`, `curl`, and `pkgx`.\n\u003e So if you like you can just download it by itself.\n\n## Getting Started\n\n```sh\n$ mash  # or https://mash.pkgx.sh\n# ^^ lists all script categories\n```\n\nYou can browse script listings with the TUI or at [mash.pkgx.sh]:\n\n```sh\n$ mash ai  # or https://mash.pkgx.sh/ai/\n# ^^ lists all ai scripts\n```\n\n\u003e [!NOTE]\n\u003e The above lists all user submitted scripts in the `ai` category.\n\nOnce you’ve found a script you want to run:\n\n```sh\n$ mash ai chat --help  # or https://mash.pkgx.sh/ai/chat/\n```\n\n\u0026nbsp;\n\n\n## Contributing Scripts\n\n### Writing Scripts\n\nUse any shell or scripting language you like. You specify it with the shebang:\n\n```sh\n#!/usr/bin/env -S pkgx ruby\n```\n\nGenerally it is sensible to specify constrained versions:\n\n```sh\n#!/usr/bin/env -S pkgx python@3.11\n```\n\n### Naming Scripts\n\n`mash` operates with a “categorization by default is good” philosophy. Your\nscripts must be categorized or namespaced with your user.\n\nThus if you add a script named `foo` it can only be used via\n`mash username/foo`. But if you add a script called `foo-bar` if will be\nlisted if a user types `mash foo`:\n\n```sh\n$ mash foo\n\n    mash foo bar           # your description about `foo bar` is shown here\n    mash foo other-script  # …\n```\n\n\u003e [!TIP]\n\u003e Extensions (eg. `.sh`, `.ts`) are *recommended* for GitHub readability.\n\u003e They will be stripped from the mash execution name, eg. `foo-bar.ts` is\n\u003e invoked via `mash foo bar` and not `mash foo bar.ts`\n\n### Installing Language Dependencies\n\nMany languages or interpreters nowadays provide clear methods for importing\nlanguage dependencies inside scripts, eg. `deno`, or `bun`. For other\nlanguages, read on.\n\n#### Ruby\n\nUse [Bundler](https://bundler.io):\n\n```ruby\n#!/usr/bin/env -S pkgx ruby@3\n\nrequire 'bundler/inline'\n\ngemfile do\n  source 'https://rubygems.org'\n  gem 'ruby-macho', '~\u003e 3'\nend\n```\n\n#### Python, Go, Rust, Node, etc.\n\nTypically for everything else, use [`scriptisto`], eg for Python:\n\n```python\n#!/usr/bin/env -S pkgx +python@3.12 +virtualenv scriptisto\n\n# snip… type `scriptisto new python-pip` for the rest.\n```\n\nUse `scriptisto new` for a full listing of platforms Scriptisto makes\navailable.\n\n\n### Making your scripts available to `mash`\n\n1. Fork [pkgxdev/mash]\n2. Add scripts to `./scripts/`\n3. Optionally edit the README adding a description\n4. Push to your fork\n5. Wait an hour and then check [mash.pkgx.sh]\n\n\u003e [!NOTE]\n\u003e Do not create a pull request for your scripts against this repo!\n\u003e *We index the fork graph*.\n\n\u003e [!IMPORTANT]\n\u003e Step 3 (edit the README) is not optional if you want your script to appear\n\u003e on the [mash frontpage][mash.pkgx.sh]!\n\n### Running Your Scripts\n\nAssuming a script named `foo-bar`, while debugging just:\n\n```sh\n$ chmod +x scripts/foo-bar\n$ ./scripts/foo-bar\n```\n\nAfter pushing we will index your script within 60 minutes.\nOnce indexed your script can be run with:\n\n1. `mash foo bar`; or\n2. `mash your-username/foo-bar`\n\n\u003e [!IMPORTANT]\n\u003e `mash` will not be able to run your script until it is indexed.\n\u003e If you can visit https://mash.pkgx.sh/USERNAME/SCRIPT-NAME then you’re\n\u003e script has been indexed.\n\n\u003e [!NOTE]\n\u003e * Categorized scripts occur on a first come first served basis. If you\n\u003e   create a script called `foo-bar` and someone already did that then you are\n\u003e   too late and users can only call your script with `mash youruser/foo-bar`.\n\u003e * Updates are fetched automatically, there is no versioning at this time.\n\u003e * Single letter categorizations are ignored, eg `./scripts/f-u` will not be\n\u003e   indexed or made available to mash. If you have a particularly good single\n\u003e   letter category that you want an exception made, open a discussion and\n\u003e   let’s chat!\n\n\u003e [!NOTE]\n\u003e ### Naming Guidelines: A Call for Consideration\n\u003e Think for a little about the names you are picking. We reserve the right\n\u003e to rename egregious abuse of names and/or namespaces. If you feel a script\n\u003e is misnamed open a ticket for discussion.\n\n\u0026nbsp;\n\n\n## Anatomy of Scripts\n\nThanks to [`pkgx`], `mash` scripts can be written in any scripting language\nusing any packages in the entire open source ecosystem.\n\n### The Shebang\n\nThe shebang is where you instruct `pkgx` on what scripting language you want.\nFor example, if you want to write your script in `fish`:\n\n```sh\n#!/usr/bin/env -S pkgx fish\n```\n\nYou can also use pkgx `+pkg` syntax to add additional packages to the script’s\nrunning environment:\n\n```sh\n#!/usr/bin/env -S pkgx +gh +git +gum +bpb bash\n```\n\npkgx knows what packages to cache (it doesn’t pollute the user system with\ninstalls) based on the commands you want to run. There’s no figuring out\npkg names, just type what you would type to run the command.\n\n\u003e https://docs.pkgx.sh/scripts\n\n### Documenting Your Script\n\nRewrite the README in your fork so there is a `## mash category scriptname`\nsection. If your script is not globally categorized then you would do\n`## mash username/scriptname` instead.\n\n* The paragraph after the `##` will be the [mash.pkgx.sh] description\n  * Keep it short or it’ll get truncated when we display it\n* If you add a `### Usage` section we’ll list it on the web\n\n\u003e [!IMPORTANT]\n\u003e If you don’t provide a description your script won’t be listed on the\n\u003e [mash frontpage][mash.pkgx.sh] (but the scripts can still be run by `mash`).\n\n### Example Fork\n\nhttps://github.com/mxcl/mash\n\n\u0026nbsp;\n\n\n## Appendix\n\n`mash` has no secret sauce; users can just cURL your scripts and run them\ndirectly via `pkgx`:\n\n```sh\n$ curl -O https://raw.githubusercontent.com/mxcl/mash/main/scripts/gh-stargazer\n$ pkgx ./gh-stargazer\n```\n\nEven `pkgx` isn’t required, they can source the dependencies themselves and\nrun the script manually:\n\n```sh\n$ bash ./stargazer\n# ^^ they will need to read the script to determine deps and interpreter\n```\n\nHackers can use your script without installing `pkgx` or `mash` first via our\ncURL one-liner. This executes the script but doesn’t install anything:\n\n```sh\nsh \u003c(curl https://mash.pkgx.sh) \u003ccategory\u003e \u003cscriptname\u003e\n```\n\n\n[mash.pkgx.sh]: https://mash.pkgx.sh\n[pkgxdev/mash]: https://github.com/pkgxdev/mash\n[`pkgx` shebang]: https://docs.pkgx.sh/scripts\n[`pkgx`]: https://pkgx.sh\n[`scriptisto`]: https://github.com/igor-petruk/scriptisto\n[actions]: https://github.com/pkgxdev/mash/actions\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpkgxdev%2Fmash","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpkgxdev%2Fmash","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpkgxdev%2Fmash/lists"}