Configuration

04 / 04

The CLI follows the platform conventions for OS config storage and exposes a small set of environment-variable overrides for non-interactive use (CI runs, automation, ephemeral containers).

State on disk

After first login + scirix ns init, scirix has three pieces of persistent state plus (when available) one OS keyring entry:

Access token — stored in the OS keyring (macOS Keychain, Windows Credential Manager, Linux Secret Service) under service scirix, account credentials. If no keyring is reachable, the token is written to the credentials manifest below as a permission-restricted fallback.
Credentials manifest — credentials.json (everything except the token: API base, user, scopes, etc.).
Namespace marker — a .scirix-namespace file at the root of a directory tree, holding the namespace GUID. Per-tree, not global — different trees on the same machine can target different namespaces.

Default paths for the first two:

OS	Config dir (agent skill, update state)	State dir (`credentials.json`)
Linux	`~/.scirix/`	`${XDG_STATE_HOME:-~/.local/state}/scirix/`
macOS	`~/.scirix/`	`~/Library/Application Support/scirix/`
Windows	`%USERPROFILE%\.scirix\`	`%LOCALAPPDATA%\scirix\`

The .scirix-namespace marker lives wherever you ran scirix ns init — it's the root of your namespace folder tree, not under the dirs above.

Override the config + state dirs with SCIRIX_AUTH_CONFIG_DIR:

SCIRIX_AUTH_CONFIG_DIR=/tmp/scirix-ephemeral scirix login

The marker walk is unaffected — it's keyed off your working directory by design.

Environment variables

Variable	Default	What it does
`SCIRIX_API_BASE`	`https://api.scirix.fi`	API base URL. After `scirix auth login`, the credential file becomes authoritative.
`SCIRIX_UI_BASE`	`https://ui.scirix.fi`	UI base URL. Drives the consent page URL.
`SCIRIX_TOKEN`	(none)	Explicit bearer token. Skips the keyring + manifest entirely.
`SCIRIX_NS_ID`	(none)	Explicit namespace id. Skips the `.scirix-namespace` marker walk.
`SCIRIX_AUTH_CONFIG_DIR`	(OS default above)	Override the config directory.

Non-interactive auth

When the CLI runs somewhere a browser can't be opened (CI, batch jobs, remote build agents), skip the login flow and pass a pre-issued token directly:

SCIRIX_TOKEN=$(cat /run/secrets/scirix-token) \
SCIRIX_NS_ID=019cc1ec-9345-73a2-9571-53c133ed2f19 \
scirix rm search "auth flow"

Tokens for automation should be issued from the Scirix UI's Tokens page with a clear label (e.g. ci-runner / ingest-pipeline) and the minimum scope set the job needs.

API base resolution

The CLI resolves the API base in this order, first hit wins:

The --api-base flag, if a subcommand accepts it.
SCIRIX_API_BASE env var.
apiBase field in credentials.json (written at login time).
Compiled-in default (https://api.scirix.fi).

Resetting state

Goal	Command
Revoke and forget the current token	`scirix auth logout`
Switch a tree to a different namespace	Delete `.scirix-namespace` at the tree root and run `scirix ns init` again
Reset everything	Delete the config + state directories and `scirix login` again

Troubleshooting

Symptom	Likely cause
`HTTP 401 — run \`scirix auth login``	No token resolved, or the token was revoked.
`flow expired`	Consent page wasn't approved within ten minutes. Rerun `scirix login`.
`no entry for <os>_<arch> in checksums.txt`	Mid-publish state on the install host. Retry in a minute.
Namespace prompt loops on a TTY	Your token has zero accessible namespaces — check with `scirix namespaces`.