The Scarf CLI

The Scarf CLI is a set of tools aimed at empowering users and maintainers of open source software, leveraging the Scarf ecosystem, and built on top of Nomia.

Nomia integration

Each of the Scarf commands uses the general abstractions provided by Nomia to identify their resources. For example, when adding a package to an environment with the Environment Manager, you would specify the package to add and the environment to add it to by name, using the common Nomia conventions for string representations of names. This provides a unified interface to specified disparate areas of software distribution and development. Now they can be seamlessly combined and efficiently realized, while also enabling integration with any other system that offers Nomia resources.

Environment Manager

The Scarf Environment Manager is used to manage the environments for user sessions, development workflows, and automated systems. It is similar to a package manager, except in that it treats environments as first-class resources to be manipulated, combined, transferred, etc.

Get started

Before you begin

To install and use the Scarf CLI, you must have Nix and Git installed.

Install

1. Clone this repository and switch to it. Run git clone https://github.com/scarf-sh/scarf.git && cd scarf.
2. Run ./install.

Try it

You can test that Scarf works by creating and installing a package in a Scarf environment. Try this:

1. Install the Hello World package into your default user environment. Run scarf env add hello.
2. Compare your system with the Scarf environment. Run these commands:

   $ which hello  // shows path to system hello, if any
   $ scarf env enter which hello  // shows path to Nix-provided hello
       

3. Remove the Hello World package from your environment. Run scarf env remove hello.

Usage

scarf has one subcommand, env. All scarf env subcommands accept an --environment flag, to operate on/within a specified environment. The default is the user’s global environment.

scarf env enter CMD [ARGS ...]

Run CMD ARGS... inside the environment

scarf env add PKG

Add PKG to the environment, if it’s not already there

scarf env remove PKG

Remove PKG from the environment

Packages

Packages are units of software ready to use as files or directories in the filesystem, together with any other system resources needed for the software to function. Currently packages are implemented on top of Nix, though eventually they will be implemented on top of native Nomia package namespaces.

scarf-pkgset package namespace

The scarf-pkgset namespace is the default namespace for adding and removing packages. Names within the namespace are simply package names, e.g. scarf-pkgset:vim is the Vim editor.

Eventually this will be a curated package set, offering access to software from maintainers we work with, along with the relationships and other features that we plan to provide. In the current prototype, the package set is built on top of nixpkgs.

nixpkgs package namespace

The nixpkgs namespace is a namespace of packages, pulled from the nixpkgs package set. The namespace takes an optional revision parameter specifying a git revision to pull; when omitted, nixpkgs is found in your NIX_PATH. Names within the namespace correspond to top-level package attributes in nixpkgs.

As use cases evolve, we may expose names for more complex Nix-derived constructions and manipluations, possibly up to arbitrary Nix expressions.

Environments

An environment is the background context within which some process or other computational unit runs.

Currently, environments include a set of packages, which are made available to processes running inside of them.

Currently, only one environment is available to each user: Their global mutable environment. We plan to add other environment names and types soon.

Potential future tools

At present, we plan to develop two additional tools in the near term. Contributions and expressions of interest especially welcome!

Developer Tool

The Scarf Developer Tool will enable developers to build their software in a more streamlined fashion. As currently envisioned, it will support drop-in replacements for existing build tools (e.g. cabal or gcc) that are automatically integrated in with packages managed by Nomia and enable incremental caching and distribution of builds on top of Nomia.

It may also provide a generic development interface to enable the same development lifecycle commands and UX to work across projects and languages. For example, we might have the following commands work for a wide array of projects:

• scarf dev build to build the project
• scarf dev airplane-mode to download any dependencies to the local machine to work offline
• scarf dev test to run the project’s testsuite

Service Manager

The Scarf Service Manager will enable management of services in a way that integrates with packages managed by Nomia, and uses Nomia to manage the service interrelations. As currently envisioned, the initial version will support isolated local services for development and testing.

Supporting maintainers

Our goal is that the default package resolution underlying the Scarf tools will source package definitions, tarballs, and binaries through Scarf’s Gateway registry. When fully implemented, this will enable us to empower maintainers with aggregate anonymized download statistics without compromising end-user privacy or sending any unexpected information from the end user’s machine.

End-users will always retain the ability to configure their own namespaces and upstream registries. Scarf does not store personally identifiable information.

Community

Join us in the Scarf-Community workspace on Slack. We’ll keep an eye out for your questions and concerns. And, if you’re interested in learning more about the Nomia project and meeting the Nomia community, we’ve got a Discord server for that.