Setting up O2ID CLI

o2idctl is O2ID's standalone management CLI — it invokes a running O2ID server's HTTP API to manage its resources

Install the latest o2idctl binary for your platform (Linux and macOS, amd64 and arm64) with:

curl -fsSL https://o2identity.pages.dev/install.sh | sh -s o2idctl

This downloads the latest release and installs it onto your PATH (/usr/local/bin by default)

note

To install to a different path, set O2IDCTL_INSTALL_DIR:

export O2IDCTL_INSTALL_DIR="{dir_path}"
curl -fsSL https://o2identity.pages.dev/install.sh | sh -s o2idctl

Quick start

Once the CLI is installed, run the following command to go through connecting to your first O2ID instance in one guided flow.

o2idctl init

it prompts for an API base URL and a profile name, saves the config profile and activates that profile for the current terminal session, then offers to log you in via the browser right away.

Profiles

o2idctl can talk to multiple O2ID deployments, each saved as a named profile. init already set up your first one — add any others with:

o2idctl config add

which prompts for an API base URL and a profile name (defaulting to http://localhost:8080 and local — press enter to accept either), and saves it. Manage saved profiles with:

o2idctl config list             # list saved profiles, and where they're stored
o2idctl config get <profile>    # show one profile's details
o2idctl config update <profile> # change a profile's API base URL
o2idctl config delete <profile> # remove a profile

Select which profile the current terminal session uses with:

o2idctl config use <profile>

Profiles (including the tokens login stores, below) are saved as plaintext JSON, owner-only readable (mode 0600), under $O2IDCTL_CONFIG_DIR, or o2id in your OS's user config directory by default. Run o2idctl config list to see the exact resolved path for your machine — it's printed above the profile list.

Authentication

The O2ID management API is an OAuth2-protected resource; therefore before running any commands, the user should be authenticated. Select the config profile you want to use and run o2idctl login.

o2idctl config add
o2idctl config use <config name>
o2idctl login

o2idctl login prints (and tries to open) a URL; log in through the browser as usual, and o2idctl will save the authentication status. you don't need to run o2idctl login again unless the refresh token itself is revoked or expires.