WARNING: Be careful with your access tokens.

cargo-sideload is a toolkit for working with alternative Cargo registries. Its primary function is downloading crates from authenticated download endpoints, a feature that Cargo does not currently support. It is meant to be a temporary workaround until this feature is added to Cargo.

Cargo's documentation has lots of useful information about working with alternative registries.

Installation

cargo install cargo-sideload

Usage

1. Add your alternate registry to ~/.cargo/config.toml.

   [registries]
   test_registry = { index = "https://github.com/picklenerd/test_registry" }
   

2. Add registry = "[registry-name]" to any dependencies that use the registry.

   my_lib = { version = "1.0", registry = "test_registry" }
   

3. Run cargo sideload fetch --registry=[registry-name] in your crate's root.

   • Use the --headers argument if your download endpoint requires authentication or other headers.
     Header format: [Header-Name]: [Header Value].

4. Your crates are now in the local Cargo cache. Running Cargo commands will work as usual.

5. If you add or update dependencies from your private registry you'll have to run cargo sideload fetch again.

More Info

cargo sideload --help

Headers

HTTP headers for the download request performed by cargo sideload fetch can be set a few ways.

Command-line arguments

The most straightforward way to set headers is to use the --headers argument followed by a comma-separated list of headers in the format [Header-Name]: [Header Value].

Example: cargo run -- fetch --headers "FIRST-HEADER: 1", "SECOND-HEADER: 2".

Environment Variables

A single header can be set with the environment variable CARGO_SIDELOAD_HEADER. If you have a .env file in your current working directory, cargo-sideload will use it. The environment variable header will be overriden by any headers passed to the --headers argument.

Example: CARGO_SIDELOAD_HEADER="MY-HEADER: 12345"

Config file

Default headers can be set in the cargo-sideload config file. These headers will only be used if there are no other headers available from the --headers argument or the CARGO_SIDELOAD_HEADER environment variable. See the section below on how to create a config file.

Config file

A config file can be used to set a default registry and to associate headers with specific registries. This allows you to run commands like cargo sideload fetch without providing --registry and --headers arguments.

To use a config, create the file ~/.config/cargo-sideload/config.toml. All of the available config options are listed in the example below. Default options are only used when command line arguments and environment variables are not set.

default_registry = "test_registry"
  
[registries.test_registry]
default_headers = [ "Authorization: Blah abcd1234" ] 

[registries.other_registry]
default_headers = [ 
        "PRIVATE-KEY: abcdef",
        "Some-Other-Header: And its value",
]

Extra Tools

cargo-sideload comes with a few extra tools for working with private registries. These extra subcommands are provided because existing tools don't always work with private registries or authenticated download endpoints.

cargo sideload list [crate-name] will list some information about each available version of the specified crate. Yanked versions are not included in the result. Using --latest will print the info for the latest version of the crate, while --latest-version will only return the latest version number.

cargo sideload outdated --registry=[registry-name] will list all dependencies with newer versions available in the specified registry. --registry is optional if you have a default registry set. A list of crates to check can be specified with --packages.

Troubleshooting

cargo-sideload uses the pretty_env_logger crate to print debug info. Use RUST_LOG=debug cargo sideload fetch to see the details of the HTTP request and response for your file downloads. You will also see logs from Cargo and any other dependencies based on the value of RUST_LOG. See the env_logger documentation for more details.

If you type your authentication header wrong, you might end up in a situation where your downloaded .crate file is actually the HTML for a login page, or some similar situation. cargo-sideload will tell Cargo to unpack your .crate files after downloading them. If unpacking fails, you'll get an error and the downloaded file will be deleted.

If you find yourself in a situation where you want to force a new download, you can use the --force option. This will delete the existing file and download a new copy.

If you try to run a normal Cargo command with a corrupt or otherwise invalid crate, you'll get an error message something like the one below. If that happens, you most likely need to troubleshoot the download endpoint in your registry index or the headers in your request. Enabling logs and using the --force option can make this troubleshooting process much easier.

error: failed to download `my_lib v0.1.0 (registry `https://github.com/picklenerd/test_registry`)`

Caused by:
  unable to get packages from source

Caused by:
  failed to unpack package `my_lib v0.1.0 (registry `https://github.com/picklenerd/test_registry`)`

Caused by:
  failed to iterate over archive

Caused by:
  failed to fill whole buffer