Authenticate to an index#

Some Sysand indexes are access-restricted, for example a team’s private index on an internal network or a private forge. Use this guide when you have a token for such an index, or a token for publishing, and want sysand to use it. If you do not have credentials yet, ask whoever runs the index; for the Sysand Index at sysand.com, create one by following Create an API token.

Prerequisites#

sysand 0.2.0 or later is installed. The sysand auth commands were added in that release; on an earlier version, use the SYSAND_CRED_* variables instead.
The index URL and a token for it.

Log in#

Run sysand auth login with the index URL, and paste the token at the hidden prompt:

$ sysand auth login https://index.example.org
  Logging in to index `https://index.example.org/`
Enter token for `https://index.example.org/`:
      Stored credential for `https://index.example.org/` (validated (read, api))
      Covers https://index.example.org/**

That is the whole setup: the token is checked against the index, stored in your operating system’s keyring (never in a plaintext file), and from now on every sysand command in any terminal authenticates to that index automatically whenever you pass --index with its URL. To make the index your default so you can drop the --index option, follow Configure a different default index.

The validated (...) part names what accepted the token, and a mistyped or expired token is refused on the spot. Which surfaces are named depends on the index: one without an API says validated (read), and a fully public index cannot test the token at all, so it says stored, not validated, which is normal. See Login validation for every case.

If the index URL is a URL template (it contains {path} or {path_raw}, for example an index read through GitLab’s repository files API), log in with the same templated URL you pass to --index, quoted so the shell leaves the ? and {} alone:

$ sysand auth login "https://gitlab.com/api/v4/projects/12345/repository/files/{path}/raw?ref=index"
  Logging in to index `https://gitlab.com/api/v4/projects/12345/repository/files/{path}/raw?ref=index`
Enter token for `https://gitlab.com/api/v4/projects/12345/repository/files/{path}/raw?ref=index`:
      Stored credential for `https://gitlab.com/api/v4/projects/12345/repository/files/{path}/raw?ref=index` (validated (read))
      Covers https://gitlab.com/api/v4/projects/12345/repository/files/**

For a private GitLab project read this way, a fine-grained personal access token with only Repository: Read on that one project is enough. Such tokens are available on GitLab.com; on a self-managed instance, check that your release has them.

For a private GitHub repository, the index is served from raw URLs of the shape https://raw.githubusercontent.com/OWNER/REPO/BRANCH/.... These append the file path as ordinary segments, so no URL template is needed: log in with the prefix up to the branch as the index URL.

$ sysand auth login https://raw.githubusercontent.com/OWNER/REPO/BRANCH

A fine-grained personal access token with Contents: read-only permission for that repository is enough.

Verify#

The validated (...) output from sysand auth login already proved the token against the index. Two commands let you re-check later, without changing anything:

sysand auth status lists the stored credential, what it covers, and its expiry. It is entirely local.

sysand auth whoami asks the index API, if the index has one, who the token authenticates as:

$ sysand auth whoami https://index.example.org
    Checking identity on index `https://index.example.org/`
       Using stored credential for `https://index.example.org/`
     Subject user alice
  Token name laptop
Token prefix sysand_u_1a2b3c4d
     Expires 2026-10-01 00:00:00 UTC (expires in 73 days)

For an end-to-end check of a read-restricted index (resolution, naming, and credentials together), ask sysand to describe a project that exists only in this index; this reads from the index and changes nothing locally:

$ sysand info --iri pkg:sysand/<publisher>/<name> --index https://index.example.org
Name: <name>
Publisher: <publisher>
Version: 1.0.0
No usages.

With the credential in place, use the index like any other. For example, add a dependency from it to your project:

$ sysand add pkg:sysand/<publisher>/<name> --index https://index.example.org

CI, hosts without a keyring, and username/password indexes#

sysand auth login needs an OS keyring (macOS Keychain, Windows Credential Manager, or the Secret Service on Linux). Use SYSAND_CRED_* environment variables instead when:

you are in CI, or on a headless host without a keyring (there, sysand auth login refuses to store the token and prints the exact variables to set);
the index uses a username and password (HTTP basic) instead of a token, which stored credentials do not cover.

One variable holds a URL pattern that says where the credential applies, and one or two companion variables hold the credential itself. The TEAMIDX part below is a label of your choice that ties them together, and it is required; the trailing ** makes the credential apply to everything under the index URL, so keep it. Replace https://index.example.org with your index’s URL and <token> with your credential.

If your index URL is a URL template, do not reuse it here. Patterns are matched against the URLs sysand actually requests, which have the placeholder already filled in, so a pattern containing {path} matches nothing and the credential is silently never sent. Use the literal part of the URL before the placeholder instead, for example https://gitlab.com/api/v4/projects/12345/** for the templated GitLab URL above.

In a terminal#

Windows

Run in PowerShell:

PS> $env:SYSAND_CRED_TEAMIDX = "https://index.example.org/**"
PS> $env:SYSAND_CRED_TEAMIDX_BEARER_TOKEN = "<token>"

If the index uses a username and password instead of a token, keep the first line and replace the second:

PS> $env:SYSAND_CRED_TEAMIDX_BASIC_USER = "<username>"
PS> $env:SYSAND_CRED_TEAMIDX_BASIC_PASS = "<password>"

macOS

$ export SYSAND_CRED_TEAMIDX='https://index.example.org/**'
$ export SYSAND_CRED_TEAMIDX_BEARER_TOKEN='<token>'

If the index uses a username and password instead of a token, keep the first line and replace the second:

$ export SYSAND_CRED_TEAMIDX_BASIC_USER='<username>'
$ export SYSAND_CRED_TEAMIDX_BASIC_PASS='<password>'

Linux

$ export SYSAND_CRED_TEAMIDX='https://index.example.org/**'
$ export SYSAND_CRED_TEAMIDX_BEARER_TOKEN='<token>'

If the index uses a username and password instead of a token, keep the first line and replace the second:

$ export SYSAND_CRED_TEAMIDX_BASIC_USER='<username>'
$ export SYSAND_CRED_TEAMIDX_BASIC_PASS='<password>'

The variables last only for the current terminal session, so you will repeat this in each new terminal.

In CI#

Keep the token itself in your CI system’s secret storage, and put only the URL pattern in the pipeline file, so the token never appears in the repository or in job logs.

GitHub Actions

Add the token as an encrypted secret, then reference it from the job:

env:
  SYSAND_CRED_TEAMIDX: https://index.example.org/**
  SYSAND_CRED_TEAMIDX_BEARER_TOKEN: ${{ secrets.SYSAND_INDEX_TOKEN }}

GitLab CI

Add the token as a masked CI/CD variable named SYSAND_CRED_TEAMIDX_BEARER_TOKEN, then set the pattern in the pipeline file:

variables:
  SYSAND_CRED_TEAMIDX: https://index.example.org/**

Environment credentials take precedence over stored credentials for the URLs their pattern matches, so a CI variable can temporarily override a login. The full pattern syntax and precedence rules are in Authentication.

When the job publishes rather than reads, prefer trusted publishing, which needs no stored token at all. To confirm a job picked up the credential you configured, run sysand auth status, which reports what sysand will authenticate with without sending a request.

Troubleshooting#

sysand auth login refuses the token. The refusal names what rejected it. Check the token for a copy-paste error, its expiry, and its scope. If the message says the index uses username/password (HTTP basic) authentication, use the SYSAND_CRED_* variables above; stored credentials are bearer-only. Being offline or the index being temporarily unreachable never causes a refusal: nothing can test the token then, so it is stored as stored, not validated with a warning.

Login worked, but a sysand command still cannot find a project. Some hosts report bad authentication as “not found” rather than “not allowed”. GitLab and GitHub raw URLs are both like this: they answer 404 Not Found (not 401) when a token is missing or lacks scope, so an authentication problem looks identical to a missing project. Since login validation passed, first check the publisher and name spelling against what the index actually serves, and that the --index URL matches the URL you logged in to. Running the command with -v logs each URL sysand requests, which shows exactly which index it is trying and where the lookup stops.

A stored credential seems ignored. Run sysand auth status: a shadowed by: line means a SYSAND_CRED_* variable in this shell takes precedence for those URLs; unset or fix that variable. An (expired) qualifier means it is time to create a new token and log in again.

“more than one default index is configured”. Bare sysand auth commands target the default index, and your configuration defines several. Pass the index URL explicitly.

The keyring is locked or unavailable. sysand says so and suggests unlocking it; on a host where that is not possible (for example over SSH), use the SYSAND_CRED_* variables instead.