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 --authority "https://auth.mycompany.com" --clientid "<clientid>" --clientsecret "<client-secret>" --tenantid "<tenant-id>" --resource "ProAuthManagementService" --api "https://auth.mycompany.com"

TIP

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

Automation Commands

The ProAuth CLI is particularly useful for automation tasks in CI/CD pipelines. Two key commands for this purpose are data and label, which allow for configuration as code and localization management.

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"

YAML File Structure

The YAML configuration files use a special format with sections separated by ---. Each section defines a ProAuth entity with its properties:

---
!CustomerDto
id: "{{guid:customer_001}}"
name: ProAuth
---
!SubscriptionDto
id: "{{guid:subscription_001}}"
customerId: "{{guid:customer_001}}"
name: ProAuth
status: active

Placeholder System

The YAML files support a powerful placeholder system using double curly braces {{...}} that allows dynamic value generation and reference resolution. Placeholders are evaluated during import and can reference each other, creating relationships between entities. After the parsing step or after the first import, the files are updated with the replaced placeholders. However, dynamic placeholers are not written back until you choose to do so by setting the corresponding flag.

Data Parse Command

You can use the data parse command to pre-process templates and replace all placeholders with new unique values:

proauthcli data parse "./template-file.yml" -o "./output-folder"

This is useful for:

• Creating new configurations from templates
• Creating multiple variations of the same configuration
• Testing placeholder resolution without affecting the ProAuth server

Available Placeholder Types

Placeholder Type	Format	Description
GUID	{{guid}}	Generates a new random GUID each time
GUID Reference	{{guid:name}}	Generates a GUID on first use and references the same value in subsequent occurrences with the same name
Secret	{{secret:length}}	Generates a cryptographically secure random string of specified length
IDP Type	{{idptype:key}}	References an identity provider type by its key (e.g., userstore, openidconnect)
Two-Factor Type	{{twofactortype:key}}	References a two-factor authentication type by key (e.g., totp, email)
Environment Variables	{{env:VARIABLE_NAME}}	Retrieves a value from server environment variables (useful for secrets)
ProAuth User	{{proauthuserfromuserstore:idpId:userId}}	References a ProAuth user from user store
ProAuth Group	{{proauthgroupfromuserstore:idpId:groupId}}	References a ProAuth group from user store

Placeholder Resolution

Placeholders are resolved in order of appearance in the YAML file. When a placeholder with a name appears multiple times:

• The first occurrence creates the value
• Subsequent occurrences reference the same value
• This ensures consistency and proper relationship mapping between entities

This system allows you to define entire ProAuth configurations with proper relationships between objects, without having to hard-code IDs.

Example with Nested Placeholders

!ClientAppDto
id: "{{guid:clientapp_001}}"
name: "ProAuth CLI App"
subscriptionId: "{{guid:subscription_001}}"
clientAppSecrets:
- id: "{{guid}}"
  name: "Default Secret"
  secret: "{{secret:16}}"
clientAppResources:
- id: "{{guid}}"
  key: "ProAuthManagementService"
  name: "PROAUTH_MANAGEMENT_SERVICE"

In this example:

• {{guid:clientapp_001}} creates a consistent GUID for the app that can be referenced elsewhere
• {{guid:subscription_001}} references a subscription GUID defined earlier in the file
• {{guid}} without a name creates unique GUIDs for each occurrence
• {{secret:16}} generates a secure random string of 16 characters

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.

Import Labels

Import translations from one or more YAML files:

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

Label files should be in YAML format and follow this structure:

- contentPath: /label/userpwresetrequest-mail-reset-url-action-text
  labels:
  - language: en-us
    fallback: true
    content: Reset your password

Multiple labels can be defined in a single file, or you can use separate files for different content paths or languages.

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-US"

# 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 "/admin/login"

This removes all translations for the specified content path.

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 \
  --authority "https://auth.mycompany.com" \
  --clientid "00000000-0000-0000-0000-000000000001" \
  --clientsecret "xxxxx" \
  --tenantid "00000000-0000-0000-0000-000000000001" \
  --resource "ProAuthManagementService" \
  --api "https://auth.mycompany.com" \
  --ignorecertificateerrors

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

# Import custom labels
proauthcli label import "./custom-labels/*.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

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