Authentication

This page covers proving who you are with NebCLI: signing in through your browser, managing the environment you work against, and checking the health of your session. To install and verify the binary first, see Installation.

Prerequisites

• NebCLI installed and on your PATH. See Installation for the one-line installer and the verified manual recipe.
• A NebCore account that is a member of your tenant. If sign-in is refused, ask your tenant administrator to grant you access.
• A terminal on macOS, Linux, or Windows.

Sign in

NebCLI signs you in through your browser using a device-code flow. NebCLI opens your browser, you log in with your identity provider (Auth0), and NebCLI saves a session on your computer.

nebcli login --tenant <your-tenant>

What happens:

1. NebCLI opens the sign-in page in your browser.
2. You log in and confirm the device code shown in your terminal.
3. On success, NebCLI saves your session locally and sets up only the access you are allowed to have.

note

Signing in proves who you are. It does not by itself grant you everything. The platform still decides what your identity is permitted to do for each action.

When you are done, end the session:

nebcli logout

Show your current authentication state, including which environment is active:

nebcli auth status

Manage environments with contexts

NebCLI uses contexts to track which platform environment you are working against, the same way kubectl uses contexts for clusters. If you work against more than one environment, you switch between them instead of signing in again each time.

nebcli auth contexts            # list every available context
nebcli auth use-context <name>  # switch the active context
nebcli auth rename-context <old> <new>

Run the self-check

doctor runs a sweep of client-side checks against the auth surface and prints a specific fix for every problem it finds. Run it first whenever sign-in or connectivity is not behaving.

nebcli doctor

The checks are grouped into categories so you can see where a problem lies:

Category	What it checks
Config	Your current context and any environment variables that could interfere with sign-in.
Endpoint and discovery	DNS resolution and a TCP connection to the platform and backend hosts.
Login state	Your session token decodes, has not expired, and can be refreshed live.
Membership	That your account carries the access your tenant requires.
Sessions	A live listing of your active sessions, with the current one marked.
Device fingerprint	Whether your session matches the version of NebCLI you are running.
Clock skew	Whether your machine's clock is close enough to the platform's.

Each failing check prints its remediation inline. Add --output json for scripted alerting or evidence collection.

Manage sessions

List the sessions tied to your account and end any one of them. This is how you sign out a session on a laptop you no longer have.

nebcli sessions list
nebcli sessions list --limit 100
nebcli sessions list --limit 100 --cursor <next-cursor>
nebcli sessions revoke <session-id>

One invocation prints one page. The default is 50 sessions and the maximum is 100. When more index work remains, text output prints the opaque next cursor; pass it back unchanged with --cursor. JSON output always includes sessions, next_cursor, and has_more. NebCLI never follows every page in the background. If sessions change between pages, the server asks you to restart the listing so it cannot silently skip or repeat a session. A cursor is bound to your account, authenticated by the server and valid for 15 minutes. Pass it back unchanged. A changed or expired cursor is rejected; a cursor from an older session-list snapshot asks you to restart from the first page.

An account can hold at most 1,024 active CLI sessions. A new sign-in at that limit checks all 1,024 slots and automatically clears entries whose sessions have expired. It is refused only if all 1,024 sessions remain active; list and revoke one first. The service also supports at most 65,536 accounts with active CLI sessions. A new account at that service limit receives cli_session_service_capacity and can retry after the reported five-minute window. Existing active accounts remain serviceable.

One-time session migration

The bounded session index is a forward-only server contract. At activation, every CLI session issued under the earlier contract requires one new sign-in. This prevents an unbounded legacy key scan and establishes a complete bounded maintenance directory.

Before activation, an existing token continues to use the earlier session record. During the brief image-convergence gate, CLI operations can return cli_session_index_upgrading. After activation, the same token returns cli_session_relogin_required instead of running against legacy state.

before: nebcli sessions list -> current unpaged session list
after:  nebcli sessions list -> cli_session_relogin_required
fixed:  nebcli login --tenant <your-tenant>
        nebcli sessions list -> bounded session page

To migrate:

1. Wait for cli_session_index_upgrading to clear.
2. Run nebcli login --tenant <your-tenant> with the current binary.
3. Re-run nebcli sessions list and the command you originally requested.

There is no deprecation overlap or dual-read period. The activation cutoff is immediate because the service is pre-launch with no external customers or user data. Unreachable legacy bodies expire automatically within seven days.

Keep your license current

NebCLI fetches your tenant's signed license and writes it locally, where NebGuard reads it to know which features are allowed. NebCLI refreshes the license on its own, including at sign-in, but you can force a refresh:

nebcli license refresh

Next steps

• Commands: every public command, grouped by task, plus exit codes.
• Examples: get temporary AWS access, validate a chart, refresh a credential.
• Credential brokering: how short-lived access works under the hood.