Configuration

04 / 05

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 (and an optional per-tree API-address override). Per-tree, not global — different trees on the same machine can target different namespaces, or different API hosts.
• Per-install config (optional) — a hand-edited config.json in the config dir holding a machine-wide apiBase / uiBase default. See API base resolution.

Default paths for the first two:

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

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=<your-namespace-id> \
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:

1. The --api-base flag, if a subcommand accepts it.
2. SCIRIX_API_BASE env var.
3. Per-namespace override — apiBase in the .scirix-namespace marker for the tree you're in. Point one tree at dev and another at prod by giving each marker a different apiBase.
4. Per-install default — apiBase in config.json under the config dir (hand-edited). The machine-wide address when no tree pins its own.
5. apiBase field in credentials.json (written at login time).
6. Compiled-in default.

uiBase (used only by the auth consent flow) resolves through the same chain with --ui-base / SCIRIX_UI_BASE / the uiBase fields.

Two config files feed steps 3–4. A per-install default:

// ~/.scirix/config.json  (Windows: %USERPROFILE%\.scirix\config.json)
{ "apiBase": "https://api.dev.scirix.fi", "uiBase": "https://ui.dev.scirix.fi" }

A per-tree override lives in the marker scirix ns init already wrote:

// .scirix-namespace at the tree root
{ "namespaceId": "019cc1ec-…", "apiBase": "https://api.dev.scirix.fi" }

The override redirects only the address, not your token, so the API you point at must be one your saved credential is valid for. scirix auth login resolves its target through the same chain, so set the override before logging in and the token is minted against that realm.

Profiles

A profile is a named credential bundle — its own token, user, and API host. Use profiles to keep several accounts side by side: the same person on dev and prod, or two different users on one host.

scirix auth login --profile work    # mint a token into the "work" profile
scirix --profile work rm search …   # run any command as that profile
scirix auth profiles                # list; * = active, (default) = config default
scirix auth use work                # persist "work" as the default
scirix auth whoami                  # who the active profile is
scirix ns profile                   # show the profile pinned to this tree
scirix ns profile work              # rebind this tree to the "work" account

The default profile is the ordinary credentials.json — nothing changes for a single-account setup. Named profiles add credentials-<name>.json beside it (names: [A-Za-z0-9._-]+). The active profile resolves as --profile flag → SCIRIX_PROFILE → the .scirix-namespace marker's profile field → config.json defaultProfile → default.

Every namespace tree names its account explicitly: scirix ns init stamps the profile into the marker, and a command run in a tree whose marker has no profile backfills it with the current default. A pinned tree therefore ignores scirix auth use <name> — that sets the per-install default, which only reaches trees without a pin. Use scirix ns profile <name> to rebind one. A --profile flag or SCIRIX_PROFILE still wins for a single invocation, and suppresses the backfill so a one-off override is never pinned to the tree.

Each profile remembers the API host it was minted against, so switching profile usually switches host too (it's step 5 of API base resolution). Your token is only valid against that host.

Resetting state

Troubleshooting