Artix

A generic artifact utility.

Purpose

The motivation behind this project is to provide an integrated, CLI-based experience for managing general (i.e. file-based) artifacts.

Quickstart

To get started with artix you'll need to create an Artix configuration file within your project. Currently, the filename must be artix.toml. The directory the configuration file is placed in will be considered the root path that artix will act on for that configuration file, thus all artifacts will be downloaded relative to that root.

An example configuration is given below for a project that declares some country code data as an artifact.

[artix.config]
version = 0

[repository.country-codes]
source = "https://raw.githubusercontent.com/datasets/country-codes/${tag}/data/country-codes.csv"

[artifact.country-codes]
destination = "country-codes.csv"
locked = true
repository = "country-codes"

[artifact.country-codes.version]
tag = "master"

This configuration declares one "repository", which declares where to pull the artifact data from, as well as one "artifact" and the associated version information for it. The artifact's destination is where to place the downloaded artifact on the filesystem. The artifact's version information will be populated into the repository's source.

Usage

To get started with the Artix CLI, ask it for help using the --help flag:

artix --help

The primary use case of artix is to sync your remote artifacts to your local filesystem. This can be accomplished with the sync command.

artix sync --help

NOTE: At present Artix doesn't fully "sync" your artifacts in that it won't remove artifacts that were once downloaded but have been removed from the configuration file. We intend to add this feature into a future release of Artix.

Configuration

The simplest way to configure Artix is to create an artix.toml file at the root of your project, or at the root of where you want your artifacts to be downloaded (e.g. a /data directory).

There are two main sections of the Artix TOML configuration file. The first is configuring repositories, and the second is configuring artifacts.

Repositories

A repository is simply a declaration of where to pull the artifact from, and it most commonly a URI. Each repository has a name and a source. A repository definition is a table, with the name being the second key of the table.

For example a repository with the name of country-codes would be declared as [repository.country-codes]. The source of the repository would then be declared with a source key/value pair.

The source key/value pair may contain string replacements that are populated from an artifact's version information. These replacements use the ${key} syntax where key is the name of the key/value pair from the version information.

See the full example definition below:

[repository.country-codes]
source = "https://raw.githubusercontent.com/datasets/country-codes/${tag}/data/country-codes.csv"

Artifacts

An artifact is a declaration of a specific version of a file pulled from a repository. Similar to a repository an artifact is declared as a TOML table, with the name of the artifact being the second key of the table. The only required configuration element is the name of the repository the artifact is pulled from.

[artifact.country-codes]
repository = "country-codes"

Additionally, you may specify a destination key which can be used to determine where to place the downloaded artifact. By default, Artix will simply save it in the Artix project's root directory with the same name as the artifact.

The example configuration below will save the artifact under the data directory located alongside the artix.toml configuration file with the name country-codes.csv.

[artifact.country-codes]
destination = "data/country-codes.csv"
repository = "country-codes"

Additionally there is a locked key/value pair that takes a boolean value. If true, this will instruct Artix to check the downloaded artifact against the Artix lockfile (if one exists) to ensure the checksum matches. By default, this is set to true but can be disabled with a false value, which can be useful if you don't care if the contents of the artifact change.

[artifact.country-codes]
destination = "data/country-codes.csv"
locked = false
repository = "country-codes"

Finally, each artifact can have a version definition. This is done via another TOML table and contains key/value pairs that are replaced into the associated repository's source value. Below is an example where we define the tag value to be master for the country-codes artifact's country-codes repository source string.

[artifact.country-codes.version]
tag = "master"