CLI Usage

The ProAuth CLI provides a set of commands to manage and interact with your ProAuth server. This page covers the basic usage patterns and automation-focused commands for DevOps engineers and administrators.

Command Structure

All ProAuth CLI commands follow this general structure:

proauthcli [options] [command] [subcommand] [arguments] [options]

To get help with any command, use the -h or --help option:

proauthcli --help
proauthcli [command] --help
proauthcli [command] [subcommand] --help

Authentication

Before executing commands that interact with the ProAuth API, you need to configure authentication. For automation tasks, we recommend using the loginservice command with client credentials:

proauthcli loginservice --host "https://auth.mycompany.com" --clientid "<clientid>" --clientsecret "<client-secret>"

TIP

You must first configure a client app in ProAuth with the appropriate permissions.

login and loginservice use the root tenant (00000000-0000-0000-0000-000000000001) and ProAuthManagementService resource by default. Use --tenantid only when you need to authenticate for a dedicated tenant, and use --resource only for non-standard CLI integrations. The legacy --authority and --api options are still accepted for compatibility but should be replaced with --host.

Use --dpop to opt a CLI profile into DPoP sender-constrained tokens:

proauthcli loginservice --host "https://auth.mycompany.com" --clientid "<clientid>" --clientsecret "<client-secret>" --dpop

The CLI generates a private DPoP JWK for the profile and reuses it for login, refresh, client credentials, and Management/User Store API calls. Use --bearer when an older ProAuth environment or customer API only accepts bearer tokens.

Crypto Helpers

The crypto commands generate ProAuth deployment keys and certificates in formats that can be pasted into Helm values, environment variables, or Kubernetes Secret creation scripts. They do not contact a ProAuth server.

Generate a stable private DPoP JWK for the Admin App:

proauthcli crypto dpop-jwk generate --kid proauth-adminapp-dpop --format helm

The Helm output contains appsettings.authentication.dpop__jsonwebkey and sets dpop__generateephemeralkeywhenmissing to "false". Use the same generated JWK for every Admin App pod in one deployment.

Generate the Admin App request-object signing certificate used for JAR:

proauthcli crypto request-object-cert generate --kid proauth-adminapp-jar --format helm

The command outputs the private base64 PFX settings for the Admin App and includes a commented public JWKS value that must be registered on the corresponding ProAuth client app key set with usage RequestObjectSigning.

Generate a certificate for private_key_jwt client assertions:

proauthcli crypto client-assertion-cert generate --kid proauth-client-assertion --format helm

Generate the ProAuth default token-signing certificate for initial Helm deployment:

proauthcli crypto token-signing-cert generate --kid proauth-default-token-signing --format helm

Token-signing certificates can be RSA or EC. RSA is the default; use --algorithm ec --curve P-384 for an EC certificate.

Generate the ProAuth data-protection key encryption certificate:

proauthcli crypto data-protection-cert generate --format helm

Data-protection certificates must use RSA because ASP.NET Core Data Protection certificate encryption requires RSA key material.

All certificate commands accept --subject, --password, --algorithm rsa|ec, --keySize, --curve P-256|P-384|P-521, --validDays, --format json|helm|env|kubectl, --secretName, and --out. If --password is omitted, the CLI generates a random PFX password and prints it with the output. Treat all generated private JWKs, PFX values, and passwords as secrets.

You can also inspect existing JWKs:

proauthcli crypto jwk public --inputPath dpop.jwk.json --format json
proauthcli crypto jwk thumbprint --inputPath dpop.jwk.json

Automation Commands

The ProAuth CLI is particularly useful for automation tasks in CI/CD pipelines. The data, label, and viewdefinition commands allow configuration as code, localization management, and Admin UI resource deployment.

Data Import (Configuration as Code)

The data command allows you to import and manage ProAuth configurations using YAML files. This enables "configuration as code" patterns for consistent deployment across environments.

# Import configuration from a YAML file
proauthcli data import "./proauth-config.yml"

ProAuth 3.x uses API-versioned YAML resources. Legacy YAML documents such as !CustomerDto or !TenantDto must be migrated before they can be imported with ProAuth 3.x.

apiVersion: management.proauth.net/v2
kind: Customer
metadata:
  id: "{{guid:customer_001}}"
spec:
  name: ProAuth

The data import schema supports:

• multi-file and multi-document YAML;
• apiVersion and kind based resource binding;
• metadata.id for entity IDs;
• metadata.userStoreId for User Store resources;
• v2 command fields and owned child configuration under spec;
• explicit relationship reconciliation under relationships;
• the existing placeholder system.

data import resolves placeholders in memory by default and does not modify the input file. Use --outputPath when you want the processed YAML written to a separate folder, or --writeProcessedInput to explicitly write the processed YAML back to the source file.

See YAML Import Schema for the full schema, supported resource kinds, relationship rules, and examples.

Migrating Legacy Data YAML

Convert legacy !TypeDto files before using ProAuth 3.x:

proauthcli data migrate-yaml "./config/*.yml" --outputPath "./config-v3" --overwrite

The migration command writes converted files to the output folder and reports warnings, conflicts, unknown fields, and manual-review items. The default relationship conflict strategy is fail, which is recommended for customer migrations.

After migration, review the generated relationship declarations before importing into production.

Label Management

The label command allows you to import and export custom labels for localization purposes. This is particularly useful for maintaining translations across different environments or configuring ProAuth instances with consistent terminology.

See Label Import And Export for the full label schema, migration guidance, and CI/CD examples.

Import Labels

Import translations from one or more YAML files:

proauthcli label import "./labels/*.yml"

ProAuth 3.x label files use apiVersion: management.proauth.io/v2 and kind: LabelBundle:

apiVersion: management.proauth.io/v2
kind: LabelBundle
metadata:
  name: user-labels
spec:
  entries:
    - contentPath: /authviews/userpwresetrequest-mail-reset-url-action-text
      labels:
        - language: en
          fallback: true
          content: Reset your password

Multiple labels can be defined in a single LabelBundle, or you can use separate files for different content paths or languages. ProAuth 3.x label paths use scoped roots such as /authviews, /accountmgmt, /oidc, /system, and /adminapp.

Convert legacy label YAML files before importing them with ProAuth 3.x:

proauthcli label migrate-yaml "./labels/*.yml" --outputPath "./labels-v3" --overwrite

Export Labels

Export all labels to a directory:

proauthcli label export "./exported-labels"

You can filter by language or content path:

# Export labels for a specific language
proauthcli label export "./exported-labels" -l "en"

# Export labels matching a content path pattern
proauthcli label export "./exported-labels" -c "/<path>"

# Export labels with an exact content path match
proauthcli label export "./exported-labels" -e "/<path>/<path>"

Delete Labels

Remove labels by content path:

proauthcli label delete "/authviews/userlogin-sign-in"

This removes all translations for the specified content path.

View Definition Management

The viewdefinition command imports and exports Admin UI view definitions. Existing ProAuth resources use apiVersion: management.proauth.io/v2 and kind: ViewDefinition. The AdminApp supports canonical reafx.net/v3 documents in YAML or JSON. YAML remains the default export format. Canonical exports use readable keys as relative filenames, preserve GUID identity, and omit schema defaults; --expanded includes defaults for diagnostics.

proauthcli viewdefinition export ./views
proauthcli viewdefinition import ./views
proauthcli viewdefinition export ./views-json --format json --expanded

JSON export requires canonical definitions. The legacy migrate-yaml command below only upgrades the older ProAuth YAML envelope; it does not perform the semantic conversion to reafx.net/v3.

Replacing a complete canonical set

replace-set reads a directory recursively, validates canonical YAML/JSON, and submits the set through Management API v2. It defaults to a dry run. Empty directories and invalid files fail before a request is sent. The server checks ownership, references, permissions and the current revision before applying the set atomically, including obsolete-entry removal. Independently managed definitions are preserved.

proauthcli viewdefinition replace-set ./views --deployment-set proauth.admin
proauthcli viewdefinition replace-set ./views --deployment-set proauth.admin --apply --expected-revision "PREVIOUS_REVISION_FROM_DRY_RUN"

For a manual preview, review the returned changes and use previousRevision from that result for --expected-revision. With --apply and no explicit revision, the CLI performs the dry run and revision-checked application automatically. A concurrent definition change invalidates that revision; obtain and review a new dry run before retrying. Keep the input files unchanged between review and application. Rollback uses the previous complete set with a fresh dry-run revision.

The AdminApp set requires the registered proauth.admin owner, the view metadata database migrations, SystemAdmin access, and the backend's deployment/record permissions. The AdminApp resource corpus uses canonical YAML. Its resource job replaces the registered proauth.admin set atomically.

The resource job's importviewdefinitions and importall commands apply the complete canonical proauth.admin set. By default, the CLI validates the exact in-memory document set in a dry run and then applies that same set using the returned revision. To apply against a previously reviewed revision, supply --view-definition-replacement-revision. A stale revision or failed request fails the job; it does not automatically replay an apply. Independently managed definitions remain outside this deployment set.

proauthcli viewdefinition import "./viewdefinitions/*.yml"

Convert legacy view definition YAML files before importing them with ProAuth 3.x:

proauthcli viewdefinition migrate-yaml "./viewdefinitions/*.yml" --outputPath "./viewdefinitions-v3" --overwrite

Exported view definition files are written in the v3 YAML resource format.

Examples for CI/CD Pipelines

Here's a complete example of authenticating and importing configuration in a CI/CD pipeline:

# Authenticate with ProAuth
proauthcli loginservice \
  --host "https://auth.mycompany.com" \
  --clientid "00000000-0000-0000-0000-000000000001" \
  --clientsecret "xxxxx" \
  --ignorecertificateerrors

# Import configuration 
proauthcli data import "./proauth-config.yml" --ignorecertificateerrors

# Import custom labels
proauthcli label import "./custom-labels/*.yml"

# Import Admin UI view definitions
proauthcli viewdefinition import "./viewdefinitions/*.yml"

Common Options

Several global options are available for all commands:

--ignorecertificateerrors                      # Ignore SSL certificate validation errors
--customTrustedRootCaFilePaths <paths>         # Specify custom root CA certificates
--clienttimeoutinseconds <seconds>             # Override HTTP client timeout (default: 100s)
--configurationlocation <path>                 # Override default CLI config file location
--nativetokenstorelocation <path>              # Override default native token store location

Next Steps

For detailed information about specific commands and advanced usage scenarios, refer to the help system with the -h or --help option:

proauthcli -h
proauthcli [command] -h