{"id":17993508,"url":"https://github.com/chshersh/tool-sync","last_synced_at":"2025-08-08T14:25:00.608Z","repository":{"id":57948571,"uuid":"525016524","full_name":"chshersh/tool-sync","owner":"chshersh","description":"🧰 Download pre-built binaries of all your favourite tools with a single command","archived":false,"fork":false,"pushed_at":"2024-08-16T02:48:19.000Z","size":409,"stargazers_count":80,"open_issues_count":35,"forks_count":19,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-04-02T08:58:30.079Z","etag":null,"topics":["cli","hacktoberfest","hacktoberfest2022","rust","sync"],"latest_commit_sha":null,"homepage":"https://crates.io/crates/tool-sync","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/chshersh.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-08-15T14:22:15.000Z","updated_at":"2025-03-26T11:25:26.000Z","dependencies_parsed_at":"2024-10-29T20:44:17.605Z","dependency_job_id":null,"html_url":"https://github.com/chshersh/tool-sync","commit_stats":{"total_commits":78,"total_committers":9,"mean_commits":8.666666666666666,"dds":"0.41025641025641024","last_synced_commit":"da2958384c8e3d0fc2539b7d812d3c3084481788"},"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chshersh%2Ftool-sync","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chshersh%2Ftool-sync/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chshersh%2Ftool-sync/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chshersh%2Ftool-sync/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chshersh","download_url":"https://codeload.github.com/chshersh/tool-sync/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248054227,"owners_count":21039952,"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":["cli","hacktoberfest","hacktoberfest2022","rust","sync"],"created_at":"2024-10-29T20:11:45.015Z","updated_at":"2025-04-09T14:06:40.954Z","avatar_url":"https://github.com/chshersh.png","language":"Rust","funding_links":["https://github.com/sponsors/chshersh"],"categories":[],"sub_categories":[],"readme":"# tool-sync\n\n[![GitHub CI](https://github.com/chshersh/tool-sync/workflows/CI/badge.svg)](https://github.com/chshersh/tool-sync/actions)\n[![Latest GitHub release](https://img.shields.io/github/v/release/chshersh/tool-sync)](https://github.com/chshersh/tool-sync/releases/latest)\n[![MPL-2.0 license](https://img.shields.io/badge/license-MPL--2.0-blue.svg)](LICENSE)\n\n`tool-sync` is a CLI tool that solves one problem:\n\n**📥 Download pre-built binaries of all your favourite tools with a single command.**\n\n`tool-sync` embraces the idea that configuring your personal development\nenvironment should be as easy as possible. And the life is pretty easy when all\nthe tools are simple executables.\n\n**So why not simply download all the executables you use and put them in a single place???** 🚀 😱\n\n![tool-sync demo](./images/demo.gif)\n\n\u003e ℹ️ **DISCLAIMER:** `tool-sync` is developed and maintained in free time\n\u003e by volunteers. The development may continue for decades or may stop\n\u003e tomorrow. You can use\n\u003e [GitHub Sponsorship](https://github.com/sponsors/chshersh) to support\n\u003e the development of this project.\n\n## Quick start guide\n\nWith `tool-sync`, you can install all the tools you use by following three\nsimple steps:\n\n1. [Install `tool-sync`](#install).\n2. [Configure](#configure) `tool-sync` by describing all the tools you want.\n3. Run `tool sync`.\n\nThat's all! 🥳\n\nThe `tool sync` command does the following:\n\n1. Fetches the information about tools from GitHub Releases\n2. Automatically guesses the asset name from your OS for common tools\n3. Downloads and unpacks assets\n4. Copies binaries from unpacked assets to the location of your choice\n\n## Features\n\n`tool-sync` has several distinguished features that allows you to manage your\npersonal toolbox easily:\n\n* 🚀 Installs the latest version of tools by default\n* 🧹 Helps you to avoid boilerplate configuration for popular tools\n* 📜 Configures via a simple TOML file\n* ☸️ Cross-platform: works on Linux🐧, macOS🍏 and Windows💠\n* 🪶 No runtime dependencies: doesn't require any other tools to do the job\n\n## Limitations\n\nCurrently, `tool-sync` has a few limitations:\n\n* Supports downloading pre-built binaries only from GitHub Releases\n* Doesn't support other configuration besides downloading the binary\n  (e.g. copying additional assets or setting up auto-completion)\n* Doesn't avoid downloading of the same version\n\n## Project goals\n\n\u003e This project is created in pursue of the following goals. Feature requests not\n\u003e compatible with the following list of goals might be rejected.\n\n1. **Learning Rust.**\n    + I like learning by creating new things. I'm learning a lot while working\n      on `tool-sync` and at the same time I find this tool useful for myself! So,\n      please, don't ask \"Why create another package manager?\". It's not even a\n      package manager 😒\n2. **Single-command batch installation.**\n    + Another `tool-sync` is to be able to configure it once and forget about it\n      (ideally forever) and use with the minimal overhead. Installing lots of\n      tools with a single command helps achieving this goal.\n3. **Informative messages.**\n    + When something doesn't work, it should be clear \"Why?\" and\n      \"How to fix it?\". `tool-sync` strives to provide good error messages (but\n      this is an endless work).\n\n## Install\n\n### From binary releases (recommended)\n\nYou can install `tool-sync` directly from GitHub releases in a few steps:\n\n1. Go to the [latest release](https://github.com/chshersh/tool-sync/releases/latest).\n2. Download an asset for your OS.\n3. Unpack the `tool` executable to a desired location.\n\nGood news, you only need to do this once! `tool-sync` will automatically manage\nfuture installations of itself (if you add it to your config).\n\n\u003e ℹ️ Installing pre-built binaries for `tool-sync` is the recommended option\n\u003e because they are:\n\u003e\n\u003e   + **Statically linked** (so they work out-of-the-box on every system)\n\u003e   + **Stripped** (so their size is reduced)\n\n### From crates\n\nYou can use `cargo` to install the latest published version of `tool-sync` from crates:\n\n```shell\ncargo install tool-sync\n```\n\n### From sources\n\nYou can install the latest version of `tool-sync` from sources (requires `git`\nand `cargo`):\n\n```shell\ngit clone https://github.com/chshersh/tool-sync\ncd tool-sync\ncargo build --release\n./target/release/tool --version\n```\n\n## Configure\n\nBefore using `tool-sync`, you need to configure it by specifying the location\nfor downloading the tools and listing all the tools you want.\n\nBy default `tool-sync` reads the configuration from from the `$HOME/.tool.toml`\npath. But you can specify a custom location via the\n`--config=/path/to/my/config` flag.\n\n### Autocomplete\n\n`tool-sync` can generate it's own autocomplete scripts for some common shell\nemulators. you can run `tool completion --help` to see the supported shells.\n\nIf you decide to rename the `tool` binary a `--rename` flag will help make sure\nthe autocompletion will keep working.\n\n\nThe following example will assume you have renamed the binary to `random-name`\nand you are using bash. You can run the following command to get completion for\nthe current session of your shell.\n\n```shell\nrandom-name completion bash --rename random-name\n```\n\nIf you want to have these autocomplete functions in the next (and the ones after\nthat) as well you can add the following to your `~/.bashrc`:\n\n```shell\neval \"$(random-name completion bash --rename random-name)\"\n```\n\n\n### Quick start\n\n`tool-sync` has a command to generate a default configuration with examples and\nfield description. Simply generate it into a file and edit it:\n\n```shell\ntool default-config \u003e ~/.tool.toml  # generate the default config\nvim ~/.tool.toml                    # open it with an editor of your choice\n```\n\n### Simple example\n\nBelow you can find a simple configuration example:\n\n```toml\n# a directory to store all tools\nstore_directory = \"~/.local/bin\"\n\n# the following tools will be installed in 'store_directory'\n[bat]\n[difftastic]\n[exa]\n[fd]\n[ripgrep]\n```\n\n\u003e ℹ️ `tool-sync` automatically expands the tilde `~` and environment variables\n\u003e (e.g `$HOME`) in the `store_directory` field.\n\nYou can also quickly copy the above configuration to the default path by running\nthe following command (Unix-only):\n\n```shell\ncurl https://raw.githubusercontent.com/chshersh/tool-sync/main/example-tool-sync-config.toml \u003e ~/.tool.toml\n```\n\nThe above example config lists some tools natively supported by `tool-sync` and\ntherefore they don't require extra configuration.\n\n### Advanced configuration\n\nTo specify a tool not supported by `tool-sync`, add a TOML table entry and list\nall the required fields like in the example below:\n\n```toml\n[tokei]\nowner    = \"XAMPPRocky\"  # GitHub username\nrepo     = \"tokei\"       # GitHub repository\nexe_name = \"tokei\"       # Executable name inside the asset\n\n# uncomment to download a specific version or tag\n# tag = \"12.1.1\"\n\n# Asset name to download on linux OSes\nasset_name.linux = \"x86_64-unknown-linux-musl\"\n\n# Uncomment if you want to install on macOS as well\n# asset_name.macos = \"apple-darwin\"\n\n# Uncomment if you want to install on Windows as well\n# asset_name.windows = \"x86_64-pc-windows-msvc\"\n```\n\n\u003e ℹ️ `tool-sync` searches asset name using the _substring search_. That's why\n\u003e you don't need to specify the full asset name in the config, only the minimal\n\u003e part required for identifying the asset. However, `tool-sync` doesn't guarantee\n\u003e you to find the asset you need if multiple assets from the GitHub release match\n\u003e the substring.\n\nAll fields in each tool section are\n\n+ **required for unknown tools,**\n+ _optional for known tools._\n\nThis means that you can override only some of the fields for known tools.\n\nThis can be helpful if e.g. you want to install a custom version of `ripgrep`\nfrom a forked repository. To do this, specify only the repository owner in the\nconfig:\n\n```toml\n[ripgrep]\nowner = \"me\"\n```\n\n## Usage\n\nInstall all the tools specified in `~/.tool.toml`:\n\n```shell\ntool sync\n```\n\nInstall one tool specified in `~/.tool.toml`:\n\n```shell\ntool sync exa\n```\n\nInstall all the tools from config in a different location:\n\n```shell\ntool --config=path/to/my/config.toml sync\n```\n\nInstall a tool that is hardcoded in the known tools list:\n\n```shell\ntool install ripgrep\n```\n\nPrint the default config to stdout:\n\n```shell\ntool default-config\n```\n\nPrint the default config location to stdout:\n\n```shell\ntool default-config --path\n```\n\nRun `tool --help` for more details.\n\n\u003e :octocat: If you hit the limit for downloading assets or want to download\n\u003e assets from private repositories,\n\u003e [create a personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token)\n\u003e and export it as the `GITHUB_TOKEN` environment variable.\n\n## Alternatives\n\nThis section contains `tool-sync` comparison to existing alternatives:\n\n1. **Manual download**: you can download GitHub releases manually without using\n   any extra tools.\n\n   + **Pros**\n     + No extra tools required, only your browser and unpack utility\n   + **Cons**\n     + Tedious manual process\n\n2. **GitHub CLI**: you can download assets from releases using\n   [the GitHub CLI tool `gh`][gh].\n\n   ```shell\n   gh release download --repo chshersh/tool-sync v0.0.0 --pattern='*linux*'\n   tar -xvf tool-x86_64-unknown-linux-gnu.tar.gz\n   ./tool --version\n   ```\n\n   + **Pros**\n     + Using a more common tool (that you probably have)\n   + **Cons**\n     + Can't download multiple tools with a single command\n     + Can't guess the asset name by your OS\n\n3. [**home-manager**][home-manager]: provides a full-featured solution for\n   managing a user environment using the Nix package manager.\n\n   + **Pros**\n     + Supports more than downloading tools from GitHub Releases\n     + Access to the bigger Nix ecosystem\n   + **Cons**\n     + More complicated solution\n     + Requires learning and using Nix\n\n4. [**topgrade**][topgrade]: a CLI tool for automatically upgrading everything\n   you have on your system. Its similar to `tool-sync` in a sense that it uses the\n   latest version but it relies on existing packages managers and doesn't install\n   new tools.\n\n   + **Pros**\n     + Leverages your existing package managers and their configuration\n     + Support plugins, editor configs and much more besides executable tools\n   + **Cons**\n     + Only updates, doesn't install new\n\n5. [**cargo-binstall**][cargo-binstall]:\n\n   + **Pros**\n     + Installs more Rust tools than `tool-sync` without configuration\n     + Builds a tool from sources if it doesn't provide a binary release\n   + **Cons**\n     + Supports only Rust tools\n     + Doesn't install multiple tools with a single command\n\n6. [**dra**][dra]: the closest alternative to `tool-sync`. It's a CLI tool,\n   written in Rust, that allows downloading individual releases easily.\n\n   + **Pros**\n     + Convenient interface for downloading a single release\n   + **Cons**\n     + Can't download multiple tools with a single command\n     + Can't guess the asset name by your OS\n\n7. [**clyde**][clyde]: another alternative to `tool-sync`\n\n   + **Pros**\n     + Package integrity checks\n     + Supports man pages\n     + Doesn't require to select a location for installing tools\n   + **Cons**\n     + Tools can't be installed if not added in a central repository\n     + Can't install multiple tools with a single command\n     + Has runtime dependencies: `git` and `tar`\n\n[gh]: https://github.com/cli/cli\n[home-manager]: https://github.com/nix-community/home-manager\n[topgrade]: https://github.com/r-darwish/topgrade\n[cargo-binstall]: https://github.com/cargo-bins/cargo-binstall/\n[dra]: https://github.com/devmatteini/dra\n[clyde]: https://github.com/agateau/clyde\n\n## Adding a new tool\n\n`tool-sync` contains [a database of common tools][db] and provides easier\nsupport for them. It's possible to add more tools (and you can suggest them!).\nThe following list contains guidelines for including a new tool. They don't\nserve as gatekeeping criteria but more as points system:\n\n* 6 months passed since the tool release\n    + So that the database won't be populated with fresh tools that are never\n      supported\n* At least 3 releases\n    + To ensure stable naming scheme for assets\n* Commonly used tool\n    + `tool-sync` strives to be generic so it might not want to support a DNA\n      analysis CLI tool which is useful only for a specific group\n* The `tool-sync` author find the tool helpful\n    + In the end, there're people behind `tool-sync` who maintain this project\n      while the rest of the world benefits from it for free. At least, `tool-sync`\n      authors decide what they want to use and whether they want to support a tool indefinitely.\n\n[db]: https://github.com/chshersh/tool-sync/blob/main/src/sync/db.rs\n\n## For contributors\n\nCheck [CONTRIBUTING.md](https://github.com/chshersh/tool-sync/blob/main/CONTRIBUTING.md)\nfor contributing guidelines.\n\n## Development\n\n### Build\n\nUse `cargo` to build the project and run all tests:\n\n```shell\ncargo build\ncargo test\n```\n\n### Pre-commit hooks\n\nThere is a predefined `.pre-commit-config.yaml` that you can install using\n[pre-commit](https://pre-commit.com/). This will make sure the linting checks\nare run locally before committing changes.\n\n### Update the default config golden test\n\nWhen changing the format of the default configuration, run the following command\nto quickly update the golden `default-config.toml` test:\n\n```shell\ncargo run -- default-config \u003e tests/default-config.toml\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchshersh%2Ftool-sync","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchshersh%2Ftool-sync","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchshersh%2Ftool-sync/lists"}