j17 - Event sourcing for the rest of us

The CLI uses OAuth device authorization. Your password and browser session never pass through the CLI.

Log in

j17 login

The CLI requests a short-lived code, opens the canonical j17 approval page, and waits for you to approve or deny the request. It prints the URL and code as well, so login still works if the browser cannot be launched.

Use --no-browser on a server, over SSH, or whenever you want to open the approval URL on another device:

j17 login --no-browser

The login attempt waits for up to 15 minutes. After approval, j17 stores a refreshable session for the active profile and confirms the account with /api/me.

j17 whoami
j17 whoami --json

Session refresh

Access tokens are short-lived. Before an authenticated command, the CLI refreshes a token that is expired or close to expiring. Refresh tokens rotate on every use.

Credential refresh is serialized across processes, so two j17 commands launched at the same time do not race and invalidate the session. If the server rejects or revokes the session, the CLI removes the unusable local credentials and asks you to run j17 login again.

Each stored session is bound to the control-plane URL that issued it. If J17_CONTROL_URL or the active profile later selects another server, the CLI refuses to send either token and asks you to select the original profile or log in again. It also fails closed when config.json is malformed instead of silently falling back to the production control plane.

Log out

j17 logout

Logout revokes the stored refresh session and removes its local credential bundle. If the server cannot confirm revocation, the CLI still removes the local credentials and reports the remote error.

Profiles

Profiles keep credentials and the selected instance/environment separate. The profile is chosen with J17_PROFILE; the default profile name is default.

J17_PROFILE=work j17 login
J17_PROFILE=work j17 use billing --env prod
J17_PROFILE=work j17 whoami

export J17_PROFILE=local
export J17_CONTROL_URL=http://localhost:4000
j17 login

J17_PROFILE is evaluated for each process. Set it consistently for every command that should use the same session and saved selection.

Credential files written by CLI versions before issuer binding do not contain enough information to identify their issuing server safely. After upgrading, run j17 login once for each profile you still use; the new login replaces that profile's old bundle.

Environment variables

Variable	Purpose
`J17_PROFILE`	Select a named credentials and configuration profile
`J17_CONTROL_URL`	Override `https://console.j17.dev`, normally for local development or self-hosting
`J17_TOKEN`	Use a bearer token for this process without reading, refreshing, or persisting a login session

J17_TOKEN is intended for ephemeral automation. The CLI never saves or refreshes it. j17 logout revokes only the session stored for the active profile; it does not revoke an externally supplied J17_TOKEN.

Files on disk

The CLI uses the operating system's user configuration directory. Common locations are ~/.config/j17 on Linux, ~/Library/Application Support/j17 on macOS, and %AppData%\j17 on Windows.

File	Contents
`config.json`	Profile metadata and the selected instance/environment
`credentials.json`	Access and refresh tokens, grouped by profile
`credentials.lock`	Advisory lock used to serialize credential changes

Credential writes are atomic. On Unix-like systems, credentials.json and refresh-attempt files are created with mode 0600. Do not commit or copy the credential files into a project.

The browser did not open. Copy the printed URL into any browser and enter the displayed code, or rerun with --no-browser.

The code expired. Run j17 login again. Device codes are deliberately short-lived and single-use.

A command says not logged in. The active profile has no usable session, or its refresh session was revoked. Check J17_PROFILE, then log in again.

A command says the credentials belong to another server. Restore the J17_PROFILE and J17_CONTROL_URL used at login, or run j17 login to replace that profile's credential bundle for the currently selected server. The CLI does not send the old tokens to the new server.

A command says the credentials predate server binding. Run j17 login once for that profile. The CLI deliberately does not guess which server issued an older credential bundle.

A local development login points at production. Export J17_CONTROL_URL for both login and later commands, and use a distinct J17_PROFILE to avoid mixing environments.