opschain login
Included from Basic tier
Authenticate against a server, store the credential, and record a named context for the server. Two authentication shapes:
- Token (the default): a pre-minted API token is verified against the
server and stored as-is. The token comes from
--token, or is prompted for (piped stdin works:echo "$TOKEN" | opschain login). - Directory (LDAP) users add
--provider <code>to--username: the credentials are verified against the directory through the provider connection's own login leg, which links the identity on first sign-in. Password login without--provideris LOCAL-only — a directory username answers a named 401 pointing here and at API keys. - Username/password (
--username): the credentials are exchanged for a session token pair via the v2 AuthServiceLoginprocedure (the v1/api/tokens/*bootstrap routes are retired). The short-lived access token is stored like a token login's; the rotating refresh token is kept alongside it, so an expired access token is renewed automatically on the next 401 and the call retries once. The password is prompted without echo (or read from piped stdin) and is never stored. A token login clears any stale refresh token — the two shapes are mutually exclusive.
The target server comes from the usual precedence: --server <url>,
OPSCHAIN_SERVER, or the active context. Login always needs one.
Credentials land in the OS keychain (service opschain, one entry per
server URL), falling back to 0600 files under $OPSCHAIN_HOME/credentials;
--no-keychain forces the file store.
Every login also upserts a context — a named server entry in
$OPSCHAIN_HOME/contexts.json — and makes it the active one, so subsequent
commands target this server with no flags. See opschain docs cli/context.
opschain login --server https://opschain.example.com --username alice
Password:
Logged in to https://opschain.example.com as alice (context "opschain.example.com")
Wrote /opt/opschain/contexts.json (home: from OPSCHAIN_HOME)
The second line names the contexts file the context landed in and how its
home was chosen (from --home, from OPSCHAIN_HOME, the per-OS default): only commands resolving the same home see the new context.
-o json|yaml carries context, server, identity, home and
home_source (flag, OPSCHAIN_HOME or default).
Credential scope across homes. The keychain entry is keyed by the
server URL alone, so it is shared by every home on the machine: a login
from one home is usable from another that targets the same server, and a
logout from any home removes it for all of them. The --no-keychain
file store lives under one home's credentials/ and is seen only from
that home.
Flags
| Flag | Meaning |
|---|---|
--token <token> | API token (prompted for when omitted). Mutually exclusive with --username. |
--username <name> | Authenticate with username and password instead of a token (password prompted, or read from stdin). |
--provider <code> | Identity provider connection code for a directory (LDAP) sign-in: the credentials ride POST /auth/login/<code> (the credentials leg) instead of the local AuthService Login. Requires --username. |
--context <name> | Context name to record for this server. Default: the name the target already resolved to, else one derived from the server host (host-port). local is reserved. |
--no-use | Record the context without making it the active one. |
Named errors
login needs a server, but no server is targeted (…): pass --server <url>, set OPSCHAIN_SERVER, or run 'opschain context use <name>'--token and --username are mutually exclusive"local" is the reserved local-mode context nameno token provided (pass --token or pipe it on stdin)no password provided (pipe it on stdin, or run from a terminal)
All exit 2. A token the server rejects exits 1
(verifying the token against <server>: …), as does a failed password
exchange (logging in to <server>: … (wrong username or password)).
Exit codes
| Code | Meaning |
|---|---|
| 0 | Token verified, stored, context recorded. |
| 1 | The server rejected the credential or was unreachable, or storing failed. |
| 2 | Usage error (see Named errors). |
See also
opschain docs cli/logout— remove the stored credential.opschain docs cli/whoami— verify what the stored token resolves to.opschain docs cli/context— switch between recorded servers.