`profile hosts` command group¶

Q: Do profile hosts commands require a server connection or login?

No. All profile hosts commands run locally and need no server connection or prior login. They read and write profile files under ${HOME}/.config/alpinepki/hosts/.

Q: Where are host connection profiles stored?

Host connection profiles, including their embedded OIDC logins with PIN-sealed tokens, are stored under ${HOME}/.config/alpinepki/hosts/.

Q: How do I configure mutual TLS for a host profile?

Supply both --client-cert and --client-key, plus --trust-anchors for the server CA bundle. Supplying only one of the client options is rejected, and TLS material cannot be combined with --plaintext.

Q: Are secrets shown when I list or view a profile?

No. list, view, delete, and set-default redact secrets: an inline client-key PEM is shown as and embedded OIDC tokens are shown as . Trust anchors, the client certificate, and file paths are public and shown unchanged.

Q: How do I select a specific host profile for one command?

Use the global -p/--profile option before the command path. It defaults to default-admin. To change the persistent default, run profile hosts set-default.

profile hosts manages the local gRPC host connection profiles that the {{ product_name }} alpine-admin-cli uses to reach a server. Each profile records the endpoint (host, port, TLS material, timeouts) under ${HOME}/.config/alpinepki/hosts/. These commands run entirely locally and need no server connection or prior login.

Why host profiles matter

The alpine-admin-cli is a remote gRPC client. Every server-touching command first needs a host profile created here, and then an authenticated session from profile authn login. Only init and the local profile hosts / profile authn commands run without a prior login.

The global -p/--profile option (default default-admin) selects which host profile a one-shot command uses; place it before the command path. Use profile hosts set-default to change the persistent default.

Commands in this group¶

Command	Purpose	Anchor
`profile hosts create`	Create a new host connection profile	create
`profile hosts update`	Update fields of an existing profile (partial)	update
`profile hosts delete`	Delete a host connection profile	delete
`profile hosts list`	List all host connection profiles	list
`profile hosts view`	View a single host connection profile	view
`profile hosts set-default`	Set the default host connection profile	set-default

Typical workflow¶

Create the connection with profile hosts create.
Confirm the stored values with profile hosts view.
Authenticate against the host with profile authn login.
Mark the most-used profile as default with profile hosts set-default.

Group help¶

bin/admin.sh profile hosts --help

Secrets are redacted in output

list, view, delete, and set-default print profiles with secret material removed. An inline mTLS client-key PEM is shown as <redacted-inline-pem> and any embedded OIDC login tokens are shown as <redacted>. File-path references, trust anchors, and the client certificate are public and are shown unchanged.

`profile hosts create`¶

Create a new host connection profile. The endpoint host and port are required; TLS is used by default unless --plaintext is set.

Syntax¶

bin/admin.sh profile hosts create [options]

Required options¶

Option	Description
`-n`, `--name`	Host connection profile name (on-disk key under `${HOME}/.config/alpinepki/hosts/`)
`--host`	Server host (DNS name or IP)
`--port`	Server port (1..65535)

Conditionally required options¶

Condition	Required options
Mutual TLS (one of the client options supplied)	both `--client-cert` and `--client-key`

Optional options¶

Show optional options

Option	Default	Description
`--[no-]plaintext`	TLS (`--no-plaintext`)	Connect without TLS; development/test only
`--reply-timeout-sec`	`30`	Per-call reply timeout in seconds (0..60)
`--termination-timeout-sec`	`5`	Channel shutdown timeout in seconds (0..60)
`--description`	none	Optional human-readable description
`--trust-anchors`	none	Path to the server CA bundle (trust anchors) PEM file
`--client-cert`	none	Path to the mTLS client certificate (PEM)
`--client-key`	none	Path to the mTLS client private key (PEM)
`-f`, `--out-format`	`YAML`	Output format: `JSON` or `YAML`

Validation rules

--host and --port are required on create.
TLS material (--trust-anchors, --client-cert, --client-key) cannot be combined with --plaintext.
Mutual TLS requires both --client-cert and --client-key; supplying only one is rejected.
--reply-timeout-sec and --termination-timeout-sec must be between 0 and 60.
TLS option values are stored as file paths; the private key bytes never land in the profile file.

Example (TLS endpoint with mutual TLS)¶

bin/admin.sh profile hosts create \
  --name default-admin \
  --host pki.example.com \
  --port 8443 \
  --description "Production admin endpoint" \
  --trust-anchors ./server-ca.pem \
  --client-cert ./client.pem \
  --client-key ./client-key.pem \
  --reply-timeout-sec 30 \
  --termination-timeout-sec 5 \
  -f json

Example (plaintext dev endpoint)¶

bin/admin.sh profile hosts create \
  --name local-dev \
  --host 127.0.0.1 \
  --port 9090 \
  --plaintext \
  -f yaml

`profile hosts update`¶

Update an existing host connection profile. The update is partial: only the options you pass are changed, and the embedded OIDC login configuration is preserved. The profile named by -n/--name must already exist.

Syntax¶

bin/admin.sh profile hosts update [options]

Required options¶

Option	Description
`-n`, `--name`	Name of the existing host connection profile to update

Conditionally required options¶

Condition	Required options
Mutual TLS (one of the client options supplied)	both `--client-cert` and `--client-key`

Optional options¶

Show optional options

Option	Default	Description
`--host`	unchanged	Server host (DNS name or IP)
`--port`	unchanged	Server port (1..65535)
`--[no-]plaintext`	unchanged	Connect without TLS; development/test only
`--reply-timeout-sec`	unchanged	Per-call reply timeout in seconds (0..60)
`--termination-timeout-sec`	unchanged	Channel shutdown timeout in seconds (0..60)
`--description`	unchanged	Optional human-readable description
`--trust-anchors`	unchanged	Path to the server CA bundle (trust anchors) PEM file
`--client-cert`	unchanged	Path to the mTLS client certificate (PEM)
`--client-key`	unchanged	Path to the mTLS client private key (PEM)
`-f`, `--out-format`	`YAML`	Output format: `JSON` or `YAML`

Validation rules

The named profile must already exist, otherwise the command fails with a configuration error.
Only options supplied on the command line are applied; stored values for omitted options (including timeouts) are preserved.
TLS material cannot be combined with a plaintext endpoint; if the resulting profile is plaintext, no TLS options may be set.
Mutual TLS requires both --client-cert and --client-key.
--reply-timeout-sec and --termination-timeout-sec must be between 0 and 60.

Example (change port and description only)¶

bin/admin.sh profile hosts update \
  --name default-admin \
  --port 9443 \
  --description "Production admin endpoint (new port)" \
  -f json

Example (rotate mTLS material)¶

bin/admin.sh profile hosts update \
  --name default-admin \
  --client-cert ./client-2026.pem \
  --client-key ./client-2026-key.pem \
  -f yaml

`profile hosts delete`¶

Delete a host connection profile. The removed (redacted) profile is echoed in the output. The named profile must exist.

Syntax¶

bin/admin.sh profile hosts delete [options]

Required options¶

Option	Description
`-n`, `--name`	Name of the host connection profile to delete

Optional options¶

Show optional options

Option	Default	Description
`-f`, `--out-format`	`YAML`	Output format: `JSON` or `YAML`

Validation rules

The named profile must exist, otherwise the command fails with a configuration error.

Example¶

bin/admin.sh profile hosts delete --name local-dev -f json

`profile hosts list`¶

List all host connection profiles. Secret material is redacted in the output. This command takes no profile-name option.

Syntax¶

bin/admin.sh profile hosts list [options]

Required options¶

This command has no command-specific required options.

Optional options¶

Show optional options

Option	Default	Description
`-f`, `--out-format`	`YAML`	Output format: `JSON` or `YAML`

Example¶

bin/admin.sh profile hosts list -f json

`profile hosts view`¶

View a single host connection profile, with secret material redacted.

Syntax¶

bin/admin.sh profile hosts view [options]

Required options¶

Option	Description
`-n`, `--name`	Name of the host connection profile to view

Optional options¶

Show optional options

Option	Default	Description
`-f`, `--out-format`	`YAML`	Output format: `JSON` or `YAML`

Example¶

bin/admin.sh profile hosts view --name default-admin -f yaml

`profile hosts set-default`¶

Mark a host connection profile as the default connection used by server-backed commands when -p/--profile is not supplied. The (redacted) profile is echoed in the output.

Syntax¶

bin/admin.sh profile hosts set-default [options]

Required options¶

Option	Description
`-n`, `--name`	Name of the host connection profile to mark as default

Optional options¶

Show optional options

Option	Default	Description
`-f`, `--out-format`	`YAML`	Output format: `JSON` or `YAML`

Example¶

bin/admin.sh profile hosts set-default --name default-admin -f json

Standard CLI options, including -p/--profile, are documented in Global options.

FAQ¶

Do profile hosts commands require a server connection or login?

No. All profile hosts commands run locally and need no server connection or prior login. They read and write profile files under ${HOME}/.config/alpinepki/hosts/.

Where are host connection profiles stored?

Host connection profiles — including their embedded OIDC logins (with PIN-sealed tokens) — are stored under ${HOME}/.config/alpinepki/hosts/.

How do I configure mutual TLS for a host profile?

Supply both --client-cert and --client-key (plus --trust-anchors for the server CA bundle). Supplying only one of the client options is rejected, and TLS material cannot be combined with --plaintext.

Are secrets shown when I list or view a profile?

No. list, view, delete, and set-default redact secrets: an inline client-key PEM is shown as <redacted-inline-pem> and embedded OIDC tokens are shown as <redacted>. Trust anchors, the client certificate, and file paths are public and shown unchanged.

How do I select a specific host profile for one command?

Use the global -p/--profile option before the command path. It defaults to default-admin. To change the persistent default, run profile hosts set-default.

profile hosts command group¶

Commands in this group¶

Typical workflow¶

Group help¶

profile hosts create¶

Syntax¶

Required options¶

Conditionally required options¶

Optional options¶

Example (TLS endpoint with mutual TLS)¶

Example (plaintext dev endpoint)¶

profile hosts update¶

Syntax¶

Required options¶

Conditionally required options¶

Optional options¶

Example (change port and description only)¶

Example (rotate mTLS material)¶

profile hosts delete¶

Syntax¶

Required options¶

Optional options¶

Example¶

profile hosts list¶

Syntax¶

Required options¶

Optional options¶

Example¶

profile hosts view¶

Syntax¶

Required options¶

Optional options¶

Example¶

profile hosts set-default¶

Syntax¶

Required options¶

Optional options¶

Example¶

FAQ¶

Related¶

`profile hosts` command group¶

`profile hosts create`¶

`profile hosts update`¶

`profile hosts delete`¶

`profile hosts list`¶

`profile hosts view`¶

`profile hosts set-default`¶