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 --provider is 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 AuthService Login procedure (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")

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 — pass --server <url>, set OPSCHAIN_SERVER, or 'opschain context use <name>'
• --token and --username are mutually exclusive
• "local" is the reserved local-mode context name
• no 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.