Indexes#

Sysand defaults to using the Sysand Index at sysand.com but it is possible to specify additional indexes or override this default index. For task-oriented steps, see Configure a different default index.

URLs for additional indexes can be specified with the command line argument --index. Multiple indexes can be given by invoking the argument multiple times, or by passing a comma separated list of URLs. The corresponding environment variable is SYSAND_INDEX, which also accepts comma separated lists of URLs.

Indexes specified with command line arguments or environment variables are prioritized when resolving dependencies but do not override indexes defined in configuration files.

The command line argument --default-index (and environment variable SYSAND_DEFAULT_INDEX) functions the same as --index but will override the default index https://sysand.com and any default indexes defined in configuration files.

The command line argument --no-index disables index use entirely: no index is consulted when resolving projects or their dependencies.

Defining an index in a configuration file#

To add an index with the URL https://index.example.org simply add the following entry to your sysand.toml:

[[index]]
url = "https://index.example.org"

To override the default index add default = true. An index marked default = true replaces https://sysand.com rather than being added alongside it:

[[index]]
url = "https://index.example.org"
default = true

URL templates#

Normally sysand fetches index files by appending their relative path to the index URL: an index at https://index.example.org serves https://index.example.org/<publisher>/<name>/versions.json and so on. Some hosts cannot serve files that way because the file path sits in the middle of the URL, or a query string must follow it. For these, an index URL may instead be a URL template containing exactly one placeholder:

  • {path}: replaced by the relative file path percent-encoded (special characters written as %XX escapes) as a single unit, with / encoded as %2F (so sensmetry/detect/versions.json becomes sensmetry%2Fdetect%2Fversions.json). This is the form the GitLab repository files API expects.

  • {path_raw}: replaced by the relative file path with / kept literal (each path segment percent-encoded individually). For hosts that accept ordinary path segments but need a suffix or query string after the path, such as Gitea’s raw-file API.

If your host’s API documentation shows the file path as a single encoded parameter in the URL, use {path}; if it shows the path with ordinary slashes, use {path_raw}.

Templates work anywhere an index URL is accepted: --index, --default-index, the corresponding environment variables, and [[index]] entries in sysand.toml.

For example, to read an index stored on the index branch of a GitLab project with numeric ID 12345 through GitLab’s repository files API (quote the URL: the ? and {} are otherwise interpreted by your shell):

$ sysand add pkg:sysand/<publisher>/<name> \
    --index "https://gitlab.com/api/v4/projects/12345/repository/files/{path}/raw?ref=index"

or permanently in sysand.toml:

[[index]]
url = "https://gitlab.com/api/v4/projects/12345/repository/files/{path}/raw?ref=index"

Replace 12345 with your project’s numeric ID (shown on the project’s overview page) or its URL-encoded path (group%2Fproject); a literal :id copied from the GitLab API documentation will not work. If the project is private, configure a token as described in Authenticate to an index. The credential URL pattern is matched against the fully expanded URLs, so anchor it at a prefix of the template before the placeholder and end it with **, for example https://gitlab.com/api/v4/projects/12345/**.

Two further notes on templates:

  • An index reached through a URL template is read-only unless the index operator’s discovery file (sysand-index-config.json, which may itself contain a templated index_root) sets api_root: without it, sysand publish to that index fails with an error saying the index does not advertise a publish endpoint.

  • URLs containing commas cannot be passed through the comma-delimited --index/SYSAND_INDEX list; configure such an index in sysand.toml instead.

Index order#

Indexes are tried in the order they are listed: indexes from --index or SYSAND_INDEX first, then indexes from configuration files in the order they appear, and default indexes last. A default index therefore has the lowest priority.