Skip to content

Managing {{ product_name }} with alpine-admin-cli

alpine-admin-cli is the operator CLI for day-1 and day-2 administration of deployed {{ product_name }} environments. It is a remote gRPC client: almost every command opens a connection to a running {{ product_name }} server and acts on its configuration.

What this section gives you

  • Prerequisite checks before running admin commands
  • The bootstrap → host profile → login sequence every operator follows once
  • A scalable page structure for command groups, subgroups, and leaf references
  • Fast links to command-specific pages

Quick task routes

Use this table when you already know the task and want the shortest path to the right page.

Task First command to run Page
Bootstrap the global administrator OIDC (one time) init init
Register a server connection profile profile hosts create profile hosts
Log in against a host profile profile authn login profile authn
Create or update a tenant tenant create tenant
Configure a tenant database connection tenant db update tenant db
Configure a tenant OIDC resource server tenant oidc update tenant oidc
Assign a license to a tenant tenant license assign tenant license
Grant an ADMIN role to a subject grants add grants
Edit an ADMIN role's permission set roles edit roles
Discover available ADMIN-scope permissions permissions search permissions
Adjust the global administrator OIDC config oidc update oidc
Adjust trusted time source / NTP policy ntp update ntp
Adjust administrator PKIX validation pkix update pkix
Adjust outbound proxy policy proxy update proxy
Inspect running-server metadata server info server
Search the license-definition catalog license search license

Before you begin

alpine-admin-cli talks to a remote {{ product_name }} server. Complete the steps below in order before running any server-touching command.

1. Confirm Java 25 is installed

Java 25 is the only supported runtime.

java -version

Java version requirement

Use Java 25 only. No other Java version is supported.

2. Complete the one-time init bootstrap

Before any operator can log in, the global administrator OIDC resource-server validation must be registered on the server. The init command performs this one-time bootstrap. It runs pre-OIDC and is gated by the shared HMAC HS256 secret, so it needs neither a host profile nor a login.

bin/admin.sh init [options]

See init for the full option set and examples.

Run init once per environment

init registers the issuer, audience, and endpoint settings the server uses to validate administrator tokens. After it succeeds, all later logins become possible.

3. Create a host profile

A host profile records how to reach a specific {{ product_name }} server (host, port, TLS, and optional mutual TLS). Create one with profile hosts create; this is a local, no-server operation.

bin/admin.sh profile hosts create [options]

Host profiles are stored under:

${HOME}/.config/alpinepki/hosts/

See profile hosts for details.

4. Authenticate with profile authn login

Server-touching commands require an authenticated OIDC session bound to a host profile. Log in with profile authn login; this is also a local operation that drives the OIDC flow.

bin/admin.sh profile authn login [options]

A login is embedded inside its host connection profile rather than stored separately. The login holds the OIDC client config (issuer, client id, flow, scopes) plus access and refresh tokens that are AES-GCM sealed with a PIN. Host connection profiles — including their embedded OIDC logins (with PIN-sealed tokens) — are stored under:

${HOME}/.config/alpinepki/hosts/

See profile authn for details.

What needs a prior login

Every server-touching command needs a host profile and an active login. The only exceptions are init (pre-OIDC, HMAC-signed) and the local profile hosts / profile authn commands, which never reach the server.

Start the CLI

bin/admin.sh <command> [options]

Select a non-default host profile for a single invocation with the global -p/--profile option, placed before the command path (default default-admin):

bin/admin.sh -p prod-admin <command> [options]

bin/admin.sh

Includes completion, autosuggestions, and persistent command history.

Documentation map

Section Purpose Start here
Command hierarchy Discover the full CLI tree quickly Command map
Global options Reused options and placement rules Global options
Bootstrap Register the global administrator OIDC (one time) init
Host profiles Create, update, and select server connection profiles profile hosts
Authentication OIDC login, logout, and token management profile authn
Tenants Create, search, update, and delete tenants tenant
Tenant database Manage a tenant's database connection configuration tenant db
Tenant OIDC Manage a tenant's OIDC resource-server configuration tenant oidc
Tenant license Manage a tenant's license assignments tenant license
Grants Search, add, edit, and delete ADMIN role grants grants
Roles Search, edit, delete, and clone ADMIN roles roles
Permissions Search the read-only ADMIN-scope permission catalog permissions
Global OIDC View and update the administrator OIDC config oidc
NTP Manage trusted time source and NTP validation policy ntp
PKIX Manage administrator certificate-path validation settings pkix
Proxy Manage outbound proxy policy and endpoint settings proxy
Server Query running-server metadata server
License catalog Search the read-only license-definition catalog license
  1. Command map for command discovery.
  2. Global options to avoid option-placement mistakes.
  3. init, profile hosts, and profile authn to complete bootstrap and authentication.
  4. Open the needed command-group page (tenant, grants, roles, permissions, oidc, ntp, pkix, proxy, server, license).
  5. Open the final leaf command page for exact syntax and examples.

Common operator flows

  1. init to register the global administrator OIDC.
  2. profile hosts create to register the server.
  3. profile authn login to authenticate.
  4. server info to confirm connectivity.
  1. tenant create to register the tenant.
  2. tenant db update to configure its database connection.
  3. tenant oidc update to configure its OIDC resource server.
  4. tenant license assign to attach a license.
  1. permissions search to discover available ADMIN-scope permissions.
  2. roles edit to shape a role's permission set.
  3. grants add to bind a subject to a role.
  1. Open oidc, ntp, pkix, or proxy.
  2. Apply changes with the group's update command.
  3. Validate with the group's view command.

External references

FAQ

Is alpine-admin-cli a local tool or a remote client?

It is a remote gRPC client. Almost every command opens a connection to a running {{ product_name }} server. The only commands that never reach the server are init, profile hosts, and profile authn.

What do I need before running a server-touching command?

Complete the one-time init bootstrap, create a host profile with profile hosts create, then authenticate with profile authn login. After that, every server-touching command uses the authenticated profile.

Where do I start for command discovery?

Use the Command map page first, then open the matching command-group page under admin/.

How do I target a non-default server for a single command?

Use the global -p/--profile option (default default-admin) placed before the command path, for example bin/admin.sh -p prod-admin server info.