Skip to content

Custom subcommands

Scarb is designed to be extensible with new subcommands without having to modify Scarb itself. This is achieved by translating a Scarb invocation of the form scarb (?<command>[^ ]+) into an invocation of an external tool scarb-${command}. The external tool must be present in (preferably) the bin directory in Scarb's local data directory, or in any other of the user's $PATH directories.

When Scarb invokes a custom subcommand, the first argument to the subcommand will be the filename of the custom subcommand, as usual. The second argument will be the subcommand name itself. For example, the second argument would be ${command} when invoking scarb-${command}. Any additional arguments on the command line after ${command} will be forwarded unchanged.

Environment variables

Additionally, Scarb passes more contextual information via environment variables:

Environment variableDescription
SCARBPath to Scarb executable.
PATHSystem $PATH but augmented with bin directory in Scarb's local data directory.
SCARB_CACHEPath to Scarb's cache directory.
SCARB_CONFIGPath to Scarb's config directory.
SCARB_TARGET_DIRPath to the current target directory.
SCARB_PROFILEName of the current profile.
SCARB_MANIFEST_PATHAbsolute path to current Scarb.toml.
SCARB_UI_VERBOSITYScarb's messages verbosity, possible values: quiet, normal, verbose.
SCARB_LOGScarb's logger directives, follows tracing's EnvFilter syntax.

Implementation recommendations

Custom subcommands may use the SCARB environment variable to call back to Scarb. The scarb metadata command can be used to obtain information about the current project, whereas the --json flag make Scarb output machine-readable messages on standard output. If you are using Rust, the scarb-metadata crate can be used to parse the output.