🧀 Parm 🧀

Install any program from your terminal.

Table of Contents:

1. Introduction
   • What is Parm?
   • Disclaimers
2. Quick Start
3. Pre-requisites
4. Installation
5. GitHub Personal Access Token
6. Usage/Documentation
7. Contributing
8. Adding Packages to Parm
9. Acknowledgements

Parm is a cross-platform binary installer with a package manager-esque workflow. It allows you to install any program off of GitHub via their REST API. Parm directly downloads binaries provided by GitHub repository releases and includes niceties such as symlinking binaries to PATH and checking for updates.

This means that Parm

• has zero root access & zero required dependencies
• requires no additional package maintainers
• receives new versions upstream instantly.
• is incredibly lightweight

To install Parm on Linux/macOS: run the following command:

curl -fsSL https://raw.githubusercontent.com/alxrw/parm/master/scripts/install.sh | sh

Windows is currently not fully supported, but will be coming soon. You can install the binaries manually in the releases tab.

To use parm:

parm install <owner>/<repo> # installs a package

parm remove <owner>/<repo> # uninstalls a package

parm update <owner>/<repo> # to update a package

For more detailed install instructions, see Installation. For more detailed documentation, go to Usage or the docs

1. (optional) Must have objdump on Linux or otool on macOS installed and added to PATH
   • Parm may use these tools to search for potential dependencies on installed programs.
     • Parm will not try to search for dependencies on Windows at the moment.
     • On Linux, ldd is not used since some implementations of it may execute the program to find dependencies. This is more accurate than using objdump or readelf, but poses a bigger security risk given the scope and design of this project.
   • objdump and otool should already be installed and added to PATH on your machine. You can check this by running

   which objdump

   or

   which otool

2. (optional) Must have a free GitHub personal access token with access to PUBLIC repositories. Go here to find out how to add an access token.

To install Parm on Linux/macOS: run the following command:

curl -fsSL https://raw.githubusercontent.com/alxrw/parm/master/scripts/install.sh | sh

You can also set the GITHUB_TOKEN option to use your GitHub API Key to bypass rate limits:

GITHUB_TOKEN=YOUR_TOKEN curl -fsSL https://raw.githubusercontent.com/alxrw/parm/master/scripts/install.sh | sh

In addition, you can also specify that the GITHUB_TOKEN you pass in will the same token you want to use for Parm by setting WRITE_TOKEN=1

GITHUB_TOKEN=YOUR_TOKEN WRITE_TOKEN=1 curl -fsSL https://raw.githubusercontent.com/alxrw/parm/master/scripts/install.sh | sh

Windows is currently not fully supported, but will be coming soon. You can install the binaries manually in the releases tab.

To update parm, just run the install script again. I recommend not setting the GITHUB_TOKEN or the WRITE_TOKEN options if updated.

1. Add a personal access token (classic) by following this guide.
   • You can use a fine-grained personal access token if you want, but this is not tested properly. Check out the guide for that here.
2. Add the API key to your shell environment:

echo 'export GH_TOKEN=<your_token_here> >> ~/.bashrc'

• You can substitute GH_TOKEN with GITHUB_TOKEN or PARM_GITHUB_TOKEN
• You can also substitute ~/.bashrc with your shell environment of choice (e.g. ~/.zshrc)

3. Parm will automatically use your token from your shell's environment variable.
4. If Parm does not detect your token from your shell, you can set a fallback in the github_api_token_fallback in your config, which will be in $XDG_CONFIG_HOME/parm/config.toml

To use the github_api_token_fallback instead, run the following command (with parm installed):

parm config set github_api_token_fallback=<token>

5. If no token is found, it will default to non-authenticated GitHub REST API usage, which defaults to 60 requests/hr.

For more detailed documentation, see the docs.

Parm is in a very early state, so any and all PRs are welcome. If you want to contribute to a new feature not already on the roadmap, please create an issue first, or check if an issue has already been created for it.

Before making a contribution, read over the contributing guidelines as well as the code of conduct.

If you want to make your Github Repo to be installable via Parm, ensure the following:

• Your repository is PUBLIC.
• Your repository has at least ONE release with an associated release tag.
• Your repository release tag names follow semver (semantic versioning).
• Your repository is meant to be run on Windows, macOS, or Linux.
• Your repository release assets actually contain binaries
  • This is important, since some GitHub repositories don't actually do this (e.g. tmux/tmux only provides source code in their releases).

That's it! Your program is now compatible with Parm. To ensure maximized compatibility, I strongly recommend the following:

• Asset names must follow the convention: <program-name>-<OS-name>-<arch-name>.<file-extension>
  • For example, "parm-linux-amd64.tar.gz" follows this convention.
• Ensure that your program has no external dependencies, or requires no dependencies that aren't usually pre-installed on most users' machines.
  • This is because Parm's dependency resolution is very weak right now, due to how the program was designed, and how it's quite difficult to find dependencies programmatically without being given them explicitly (like how other package managers do this).
  • As a rule of thumb, if your program is statically linked, you should be good to go.

Parm tries its best to adhere to current conventions of open-source software when parsing repositories. If there's something I'm missing, please create an issue.

Parm was created using the Go programming language and the cobra CLI framework.

While not the direct inspirations for Parm, here are some projects that helped shape Parm's development:

• homebrew
• asdf
• lazy.nvim.

Similar projects:

• ubi
• eget