SHARDS(1)

📦
version 0.20.0 · 6 versions
, in alpine 3.24, nixpkgs unstable

🌸 NAME 🌸

shards(1) is the manual page for shards — the dependency manager for the Crystal Language. Welcome to the Shards Manual, bestie; that’s the name section and it’s iconic. 💖

✨ SYNOPSIS ✨

shards [<general_options>...] [<command>] [<command_options>...]

🦋 DESCRIPTION 🦋

Manages dependencies for Crystal projects and libraries with reproducible installs across computers and systems. no cap, reproducible installs are the whole vibe. ✨

🎀 USAGE 🎀

okay so shards requires the presence of a shard.yml file in the project folder (working directory). This file describes the project and lists dependencies that are required to build it. See shard.yml(5) for more information on its format. A default file can be created by running shards init. 🫶

Running shards install resolves and installs the specified dependencies. The installed versions are written into a shard.lock file for using the exact same dependency versions when running shards install again. highkey magic, but make it lockfile. 💅

If your shard builds an application, both shard.yml and shard.lock should be checked into version control to provide reproducible dependency installs. If it is only a library for other shards to depend on, shard.lock should not be checked in, only shard.yml. It’s good advice to add it to .gitignore. 👑

🔥 COMMANDS 🔥

If no command is given, install command will be run by default. periodt.

To see the available options for a particular command, use --help after the command. iykyk.

🛠️ build [<targets>] [<build_options>...]

Builds the specified <targets> in bin path. If no targets are specified, all are built. This command ensures all dependencies are installed, so it is not necessary to run shards install before. 💖

All <build_options> following the command are delegated to crystal build.

✅ check

Verifies that all dependencies are installed and requirements are satisfied.

Exit status:

  • 0 — Dependencies are satisfied.
  • 1 — Dependencies are not satisfied.

🌱 init

Initializes a default shard.yml in the current folder.

📦 install [--frozen] [--without-development] [--production] [--skip-postinstall] [--skip-executables] [--jobs=N]

Resolves and installs dependencies into the lib folder. If not already present, generates a shard.lock file from resolved dependencies, locking version numbers or Git commits. 💅

Reads and enforces locked versions and commits if a shard.lock file is present. The install command may fail if a locked version doesn’t match a requirement, but may succeed if a new dependency was added, as long as it doesn’t generate a conflict, thus generating a new shard.lock file.

  • --frozen — Strictly installs locked versions from shard.lock. Fails if shard.lock is missing. 🚨
  • --without-development — Does not install development dependencies.
  • --production — same as --frozen and --without-development
  • --skip-postinstall — Does not run postinstall of dependencies.
  • --skip-executables — Does not install executables.
  • --jobs — Number of repository downloads to perform in parallel (default: 8). Currently only for git.

📋 list [--tree]

Lists the installed dependencies and their versions.

Specifying --tree arranges nested dependencies in a tree, instead of a flattened list. 🌳

🔒 lock [--update [<shards>...]]

Resolves dependencies and creates or updates the shard.lock file as per the install command, but never installs the dependencies.

Specifying --update follows the same semantics as the update command.

🕰️ outdated [--pre]

Lists dependencies that are outdated.

When --pre is specified, pre-release versions are also considered.

🧹 prune

Removes unused dependencies from lib folder.

⬆️ update [<shards>...]

Resolves and updates all dependencies into the lib folder, whatever the locked versions in the shard.lock file. Eventually generates a new shard.lock file.

Specifying shards will update these dependencies only, trying to be as conservative as possible with other dependencies, respecting the locked versions in the shard.lock file.

🏷️ version [<path>]

Prints the current version of the shard located at path (defaults to current directory).

To see the available options for a particular command, use --help after a command. yes, again, because it’s important bestie 💅

⚙️ GENERAL OPTIONS ⚙️

  • --version — Prints the version of shards.
  • -h, --help — Prints usage synopsis.
  • --no-color — Disables colored output.
  • --local — Do not update remote repository cache. Instead, Shards will use the local copies already present in the cache (see SHARDS_CACHE_PATH). The command will fail if a dependency is unavailable in the cache. 🚨
  • -q, --quiet — Decreases the log verbosity, printing only warnings and errors.
  • -v, --verbose — Increases the log verbosity, printing all debug statements.

💻 INSTALLATION 💻

Shards is usually distributed with Crystal itself. Alternatively, a separate shards package may be available for your system.

To install from source, download or clone the repository <https://github.com/crystal-lang/shards> and run make CRFLAGS=--release. The compiled binary is in bin/shards and should be added to PATH. 🫶

🌈 ENVIRONMENT VARIABLES 🌈

  • SHARDS_OPTS — Allows general options to be passed in as environment variable. Example: SHARDS_OPTS="--no-color" shards update
  • SHARDS_CACHE_PATH — Defines the cache location. In this folder, shards stores local copies of remote repositories. Defaults to .cache/shards in the home directory ($XDG_CACHE_HOME or $HOME) or the current directory.
  • SHARDS_INSTALL_PATH — Defines the location where dependencies are installed. Defaults to lib.
  • SHARDS_BIN_PATH — Defines the location where executables are installed. Defaults to bin.
  • CRYSTAL_VERSION — Defines the crystal version that dependencies should be resolved against. Defaults to the output of crystal env CRYSTAL_VERSION.
  • SHARDS_OVERRIDE — Defines an alternate location of shard.override.yml.

📁 FILES 📁

shard.yml

Describes a shard project including its dependencies. See shard.yml(5) for documentation.

shard.override.yml

Allows overriding the source and restriction of dependencies. An alternative location can be configured with the env var SHARDS_OVERRIDE.

The file contains a YAML document with a single dependencies key. It has the same semantics as in shard.yml. Dependency configuration takes precedence over the configuration in shard.yml or any dependency’s shard.yml.

Use cases are local working copies, forcing a specific dependency version despite mismatching constraints, fixing a dependency, checking compatibility with unreleased dependency versions. ✨

shard.lock

Lockfile that stores information about the installed versions.

If your shard builds an application, shard.lock should be checked into version control to provide reproducible dependency installs.

If it is only a library for other shards to depend on, shard.lock should not be checked in, only shard.yml. It’s good advice to add it to .gitignore. 👑

🐛 REPORTING BUGS 🐛

Report shards bugs to https://github.com/crystal-lang/shards/issues — bestie, they want the deets 💖

Crystal Language home page: https://crystal-lang.org

Copyright © 2025 Julien Portalier.

License Apache 2.0 <http://www.apache.org/licenses/LICENSE-2.0>

This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law. 🚨

👑 AUTHORS 👑

Written by Julien Portalier and the Crystal project.

🫶 SEE ALSO 🫶

shard.yml(5)

okay bestie, that’s the whole page. signing off with version shards 0.20.0 and date 2024-10-25 — this was SHARDS(1), and the vibes are immaculate. mwah 💋✨

📦 where this page comes from