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 placeholders 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

Supported Entity Types

The data import command supports the following entity types:

Entity Type	Description
CustomerDto	Customer organizations
SubscriptionDto	Subscriptions within a customer
TenantDto	Tenants within a subscription
ClaimRuleDto	Claim transformation and filter rules
ClientAppDto	OAuth/OIDC client applications
ClientAppResourceDto	API resources for client apps
ClientAppScopeDto	OAuth scopes for client apps
ClientAppRedirectUriDto	Redirect URIs for client apps
ClientAppRoleDto	Roles assigned to client applications
CertStoreDto	Certificate store entries
IPAddressRangeDto	IP address range restrictions
IdpInstanceDto	Identity provider instances
TwoFactorInstanceDto	Two-factor authentication instances
ProAuthUserRoleDto	Roles assigned to ProAuth users
ProAuthGroupRoleDto	Roles assigned to ProAuth groups
ProAuthGroupDto	ProAuth groups with member users and nested groups
CustomViewFileImport	Custom view templates
CustomAssetFileImport	Custom assets (images, files)

ProAuth Group Import Example

ProAuth groups can be imported with their hierarchical relationships (parent/member groups) and member users:

---
!ProAuthGroupDto
id: "{{guid:group_admins}}"
name: "Administrators"
subscriptionId: "{{guid:subscription_001}}"
idpInstanceId: "{{guid:userstore_001}}"
parentGroups:
memberGroups:
memberUsers:
---
!ProAuthGroupDto
id: "{{guid:group_developers}}"
name: "Developers"
subscriptionId: "{{guid:subscription_001}}"
idpInstanceId: "{{guid:userstore_001}}"
parentGroups:
  - id: "{{guid:group_admins}}"
memberGroups:
memberUsers:
  - id: "{{proauthuserfromuserstore}}:{{guid:userstore_001}}.{{guid:user_001}}"

TIP

When importing groups with relationships, ensure that referenced parent groups and member users are defined earlier in the YAML file or already exist in the system.

Import Behavior for Missing References

When importing configurations with many-to-many relationships (such as tenants referencing client apps, or IDP instances referencing tenants), the CLI handles missing references gracefully:

• If a referenced entity is not found in the import file, the CLI prints a warning message and skips that reference
• The import continues processing the remaining entities and relationships
• This allows partial imports to succeed even when some referenced entities are missing

Example warning output:

Warning: ClientAppDto '62a9112e-2cf1-44a4-8e7f-76b47ed5bb2e' referenced in TenantDto '147c4e19-34f8-490e-ab6d-68bffae00570' not found in import file, skipping.

WARNING

While the import continues on missing references, you should review warning messages to ensure all intended relationships are properly established. Missing references may indicate:

• The referenced entity needs to be added to the import file
• The entity already exists in the system (which is fine)
• A typo in the GUID reference

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