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. ProAuth 3.x view definition files use apiVersion: management.proauth.io/v2 and kind: ViewDefinition.

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