Skip to content

prep for ascii docs #102

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
samir-gandhi wants to merge 8 commits into
base: main
Choose a base branch
from
Open

prep for ascii docs #102

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
45cedec
run v060 and add some ticks
samir-gandhi Apr 30, 2025
7f4f1b9
add friendly name for option type
samir-gandhi Apr 30, 2025
3f00954
duplicate header
samir-gandhi Apr 30, 2025
27af1e4
lint
samir-gandhi Apr 30, 2025
d8b7a05
skip generation in pipeline
samir-gandhi Apr 30, 2025
e4df15b
add in environment variable option
samir-gandhi May 1, 2025
8175a68
add ticks
samir-gandhi May 1, 2025
9fbcc1a
cli help formatting
samir-gandhi Jun 4, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
93 changes: 46 additions & 47 deletions docs/tool-configuration/configuration-key.md
View file
Open in desktop
Copy link
Contributor

@patrickcping patrickcping May 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is it worth retiring this doc and linking to the official doc instead, so we don't have the same content in two places that we need to keep in sync?

Copy link
Contributor

@patrickcping patrickcping May 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In fact, same with most other docs in this repo. The repo docs can then be specific to the code project and not tool usage

Original file line number Diff line number Diff line change
Expand Up @@ -2,52 +2,51 @@

The following parameters can be configured in Ping CLI's static configuration file, usually located at $HOME/.pingcli/config.yaml. The following describes the properties that can be set, and an example can be found at [example-configuration.md](./example-configuration.md)


#### General Properties

| Config File Property | Type | Equivalent Parameter | Purpose |
|---|---|---|---|
| activeProfile | ENUM_STRING | | The name of the stored custom configuration profile to use by default. |
| noColor | ENUM_BOOL | --no-color | Disable text output in color. |
| outputFormat | ENUM_OUTPUT_FORMAT | --output-format / -O | Specify the console output format.<br><br>Options are: json, text.<br><br>Example: `json` |

#### Ping Platform Service Properties

| Config File Property | Type | Equivalent Parameter | Purpose |
|---|---|---|---|
| service.pingFederate.adminAPIPath | ENUM_STRING | --pingfederate-admin-api-path | The PingFederate API URL path used to communicate with PingFederate's admin API.<br><br>Example: `/pf-admin-api/v1` |
| service.pingFederate.authentication.accessTokenAuth.accessToken | ENUM_STRING | --pingfederate-access-token | The PingFederate access token used to authenticate to the PingFederate admin API when using a custom OAuth 2.0 token method. |
| service.pingFederate.authentication.basicAuth.password | ENUM_STRING | --pingfederate-password | The PingFederate password used to authenticate to the PingFederate admin API when using basic authentication. |
| service.pingFederate.authentication.basicAuth.username | ENUM_STRING | --pingfederate-username | The PingFederate username used to authenticate to the PingFederate admin API when using basic authentication. Example: `administrator` |
| service.pingFederate.authentication.clientCredentialsAuth.clientID | ENUM_STRING | --pingfederate-client-id | The PingFederate OAuth client ID used to authenticate to the PingFederate admin API when using the OAuth 2.0 client credentials grant type. |
| service.pingFederate.authentication.clientCredentialsAuth.clientSecret | ENUM_STRING | --pingfederate-client-secret | The PingFederate OAuth client secret used to authenticate to the PingFederate admin API when using the OAuth 2.0 client credentials grant type. |
| service.pingFederate.authentication.clientCredentialsAuth.scopes | ENUM_STRING_SLICE | --pingfederate-scopes | The PingFederate OAuth scopes used to authenticate to the PingFederate admin API when using the OAuth 2.0 client credentials grant type.<br><br>Accepts a comma-separated string to delimit multiple scopes.<br><br>Example: `openid,profile` |
| service.pingFederate.authentication.clientCredentialsAuth.tokenURL | ENUM_STRING | --pingfederate-token-url | The PingFederate OAuth token URL used to authenticate to the PingFederate admin API when using the OAuth 2.0 client credentials grant type. |
| service.pingFederate.authentication.type | ENUM_PINGFEDERATE_AUTH_TYPE | --pingfederate-authentication-type | The authentication type to use when connecting to the PingFederate admin API.<br><br>Options are: accessTokenAuth, basicAuth, clientCredentialsAuth.<br><br>Example: `basicAuth` |
| service.pingFederate.caCertificatePEMFiles | ENUM_STRING_SLICE | --pingfederate-ca-certificate-pem-files | Relative or full paths to PEM-encoded certificate files to be trusted as root CAs when connecting to the PingFederate server over HTTPS.<br><br>Accepts a comma-separated string to delimit multiple PEM files. |
| service.pingFederate.httpsHost | ENUM_STRING | --pingfederate-https-host | The PingFederate HTTPS host used to communicate with PingFederate's admin API.<br><br>Example: `https://pingfederate-admin.bxretail.org` |
| service.pingFederate.insecureTrustAllTLS | ENUM_BOOL | --pingfederate-insecure-trust-all-tls | Trust any certificate when connecting to the PingFederate server admin API.<br><br>This is insecure and shouldn't be enabled outside of testing. |
| service.pingFederate.xBypassExternalValidationHeader | ENUM_BOOL | --pingfederate-x-bypass-external-validation-header | Bypass connection tests when configuring PingFederate (the X-BypassExternalValidation header when using PingFederate's admin API). |
| service.pingOne.authentication.type | ENUM_PINGONE_AUTH_TYPE | --pingone-authentication-type | The authentication type to use to authenticate to the PingOne management API.<br><br>Options are: worker.<br><br>Example: `worker` |
| service.pingOne.authentication.worker.clientID | ENUM_UUID | --pingone-worker-client-id | The worker client ID used to authenticate to the PingOne management API. |
| service.pingOne.authentication.worker.clientSecret | ENUM_STRING | --pingone-worker-client-secret | The worker client secret used to authenticate to the PingOne management API. |
| service.pingOne.authentication.worker.environmentID | ENUM_UUID | --pingone-worker-environment-id | The ID of the PingOne environment that contains the worker client used to authenticate to the PingOne management API. |
| service.pingOne.regionCode | ENUM_PINGONE_REGION_CODE | --pingone-region-code | The region code of the PingOne tenant.<br><br>Options are: AP, AU, CA, EU, NA.<br><br>Example: `NA` |

#### Platform Export Properties

| Config File Property | Type | Equivalent Parameter | Purpose |
|---|---|---|---|
| export.format | ENUM_EXPORT_FORMAT | --format / -f | Specifies the export format.<br><br>Options are: HCL.<br><br>Example: `HCL` |
| export.outputDirectory | ENUM_STRING | --output-directory / -d | Specifies the output directory for export. Example: `$HOME/pingcli-export` |
| export.overwrite | ENUM_BOOL | --overwrite / -o | Overwrites the existing generated exports in output directory. |
| export.pingone.environmentID | ENUM_UUID | --pingone-export-environment-id | The ID of the PingOne environment to export. Must be a valid PingOne UUID. |
| export.serviceGroup | ENUM_EXPORT_SERVICE_GROUP | --service-group / -g | Specifies the service group to export. <br><br>Options are: pingone.<br><br>Example: `pingone` |
| export.services | ENUM_EXPORT_SERVICES | --services / -s | Specifies the service(s) to export. Accepts a comma-separated string to delimit multiple services.<br><br>Options are: pingfederate, pingone-mfa, pingone-platform, pingone-protect, pingone-sso.<br><br>Example: `pingone-sso,pingone-mfa,pingfederate` |

#### Custom Request Properties

| Config File Property | Type | Equivalent Parameter | Purpose |
|---|---|---|---|
| request.fail | ENUM_BOOL | --fail / -f | Return non-zero exit code when HTTP custom request returns a failure status code. |
| request.service | ENUM_REQUEST_SERVICE | --service / -s | The Ping service (configured in the active profile) to send the custom request to.<br><br>Options are: pingone.<br><br>Example: `pingone` |
| Configuration Key | Type | Equivalent Parameter | Environment Variable | Purpose |
|---|---|---|---|---|
| `detailedExitCode` | Boolean | `--detailed-exitcode` / `-D` | `PINGCLI_DETAILED_EXITCODE` | Enable detailed exit code output. (default false)<br><br>0 - pingcli command succeeded with no errors or warnings.<br><br>1 - pingcli command failed with errors.<br><br>2 - pingcli command succeeded with warnings. |
| `noColor` | Boolean | `--no-color` | `PINGCLI_NO_COLOR` | Disable text output in color. (default false) |
| `outputFormat` | String (enum) | `--output-format` / `-O` | `PINGCLI_OUTPUT_FORMAT` | Specify the console output format. (default text)<br><br>Options are: json, text. |

#### Export Properties

| Configuration Key | Type | Equivalent Parameter | Environment Variable | Purpose |
|---|---|---|---|---|
| `export.format` | String (enum) | `--format` / `-f` | `PINGCLI_EXPORT_FORMAT` | Specifies the export format. (default HCL)<br><br>Options are: HCL. |
| `export.outputDirectory` | String | `--output-directory` / `-d` | `PINGCLI_EXPORT_OUTPUT_DIRECTORY` | Specifies the output directory for export. Can be an absolute filepath or a relative filepath of the present working directory. <br><br>Example: '/Users/example/pingcli-export'<br><br>Example: 'pingcli-export' |
| `export.overwrite` | Boolean | `--overwrite` / `-o` | `PINGCLI_EXPORT_OVERWRITE` | Overwrites the existing generated exports in output directory. (default false) |
| `export.pingOne.environmentID` | String (UUID Format) | `--pingone-export-environment-id` | `PINGCLI_PINGONE_EXPORT_ENVIRONMENT_ID` | The ID of the PingOne environment to export. Must be a valid PingOne UUID. |
| `export.serviceGroup` | String (enum) | `--service-group` / `-g` | `PINGCLI_EXPORT_SERVICE_GROUP` | Specifies the service group to export. <br><br>Options are: pingone.<br><br>Example: 'pingone' |
| `export.services` | String Array (enum) | `--services` / `-s` | `PINGCLI_EXPORT_SERVICES` | Specifies the service(s) to export. Accepts a comma-separated string to delimit multiple services. <br><br>Options are: pingfederate, pingone-authorize, pingone-mfa, pingone-platform, pingone-protect, pingone-sso.<br><br>Example: 'pingone-sso,pingone-mfa,pingfederate' |

#### Request Properties

| Configuration Key | Type | Equivalent Parameter | Environment Variable | Purpose |
|---|---|---|---|---|
| `request.fail` | Boolean | `--fail` / `-f` | `` | Return non-zero exit code when HTTP custom request returns a failure status code. |
| `request.service` | String (enum) | `--service` / `-s` | `PINGCLI_REQUEST_SERVICE` | The Ping service (configured in the active profile) to send the custom request to.<br><br>Options are: pingone.<br><br>Example: 'pingone' |

#### Service Properties

| Configuration Key | Type | Equivalent Parameter | Environment Variable | Purpose |
|---|---|---|---|---|
| `service.pingFederate.adminAPIPath` | String | `--pingfederate-admin-api-path` | `PINGCLI_PINGFEDERATE_ADMIN_API_PATH` | The PingFederate API URL path used to communicate with PingFederate's admin API. (default /pf-admin-api/v1) |
| `service.pingFederate.authentication.accessTokenAuth.accessToken` | String | `--pingfederate-access-token` | `PINGCLI_PINGFEDERATE_ACCESS_TOKEN` | The PingFederate access token used to authenticate to the PingFederate admin API when using a custom OAuth 2.0 token method. |
| `service.pingFederate.authentication.basicAuth.password` | String | `--pingfederate-password` | `PINGCLI_PINGFEDERATE_PASSWORD` | The PingFederate password used to authenticate to the PingFederate admin API when using basic authentication. |
| `service.pingFederate.authentication.basicAuth.username` | String | `--pingfederate-username` | `PINGCLI_PINGFEDERATE_USERNAME` | The PingFederate username used to authenticate to the PingFederate admin API when using basic authentication.<br><br>Example: 'administrator' |
| `service.pingFederate.authentication.clientCredentialsAuth.clientID` | String | `--pingfederate-client-id` | `PINGCLI_PINGFEDERATE_CLIENT_ID` | The PingFederate OAuth client ID used to authenticate to the PingFederate admin API when using the OAuth 2.0 client credentials grant type. |
| `service.pingFederate.authentication.clientCredentialsAuth.clientSecret` | String | `--pingfederate-client-secret` | `PINGCLI_PINGFEDERATE_CLIENT_SECRET` | The PingFederate OAuth client secret used to authenticate to the PingFederate admin API when using the OAuth 2.0 client credentials grant type. |
| `service.pingFederate.authentication.clientCredentialsAuth.scopes` | String Array | `--pingfederate-scopes` | `PINGCLI_PINGFEDERATE_SCOPES` | The PingFederate OAuth scopes used to authenticate to the PingFederate admin API when using the OAuth 2.0 client credentials grant type. (default [])<br><br>Accepts a comma-separated string to delimit multiple scopes.<br><br>Example: 'openid,profile' |
| `service.pingFederate.authentication.clientCredentialsAuth.tokenURL` | String | `--pingfederate-token-url` | `PINGCLI_PINGFEDERATE_TOKEN_URL` | The PingFederate OAuth token URL used to authenticate to the PingFederate admin API when using the OAuth 2.0 client credentials grant type. |
| `service.pingFederate.authentication.type` | String (enum) | `--pingfederate-authentication-type` | `PINGCLI_PINGFEDERATE_AUTHENTICATION_TYPE` | The authentication type to use when connecting to the PingFederate admin API.<br><br>Options are: accessTokenAuth, basicAuth, clientCredentialsAuth.<br><br>Example: 'basicAuth' |
| `service.pingFederate.caCertificatePEMFiles` | String Array | `--pingfederate-ca-certificate-pem-files` | `PINGCLI_PINGFEDERATE_CA_CERTIFICATE_PEM_FILES` | Relative or full paths to PEM-encoded certificate files to be trusted as root CAs when connecting to the PingFederate server over HTTPS. (default [])<br><br>Accepts a comma-separated string to delimit multiple PEM files. |
| `service.pingFederate.httpsHost` | String | `--pingfederate-https-host` | `PINGCLI_PINGFEDERATE_HTTPS_HOST` | The PingFederate HTTPS host used to communicate with PingFederate's admin API.<br><br>Example: 'https://pingfederate-admin.bxretail.org' |
| `service.pingFederate.insecureTrustAllTLS` | Boolean | `--pingfederate-insecure-trust-all-tls` | `PINGCLI_PINGFEDERATE_INSECURE_TRUST_ALL_TLS` | Trust any certificate when connecting to the PingFederate server admin API. (default false)<br><br>This is insecure and shouldn't be enabled outside of testing. |
| `service.pingFederate.xBypassExternalValidationHeader` | Boolean | `--pingfederate-x-bypass-external-validation-header` | `PINGCLI_PINGFEDERATE_X_BYPASS_EXTERNAL_VALIDATION_HEADER` | Bypass connection tests when configuring PingFederate (the X-BypassExternalValidation header when using PingFederate's admin API). (default false) |
| `service.pingOne.authentication.type` | String (enum) | `--pingone-authentication-type` | `PINGCLI_PINGONE_AUTHENTICATION_TYPE` | The authentication type to use to authenticate to the PingOne management API. (default worker)<br><br>Options are: worker. |
| `service.pingOne.authentication.worker.clientID` | String (UUID Format) | `--pingone-worker-client-id` | `PINGCLI_PINGONE_WORKER_CLIENT_ID` | The worker client ID used to authenticate to the PingOne management API. |
| `service.pingOne.authentication.worker.clientSecret` | String | `--pingone-worker-client-secret` | `PINGCLI_PINGONE_WORKER_CLIENT_SECRET` | The worker client secret used to authenticate to the PingOne management API. |
| `service.pingOne.authentication.worker.environmentID` | String (UUID Format) | `--pingone-worker-environment-id` | `PINGCLI_PINGONE_WORKER_ENVIRONMENT_ID` | The ID of the PingOne environment that contains the worker client used to authenticate to the PingOne management API. |
| `service.pingOne.regionCode` | String (enum) | `--pingone-region-code` | `PINGCLI_PINGONE_REGION_CODE` | The region code of the PingOne tenant.<br><br>Options are: AP, AU, CA, EU, NA.<br><br>Example: 'NA' |
84 changes: 68 additions & 16 deletions internal/configuration/options/options.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,27 +9,79 @@ import (
"github.com/spf13/pflag"
)

type OptionType string
type OptionType int

// OptionType enums
const (
ENUM_BOOL OptionType = "ENUM_BOOL"
ENUM_EXPORT_FORMAT OptionType = "ENUM_EXPORT_FORMAT"
ENUM_HEADER OptionType = "ENUM_HEADER"
ENUM_INT OptionType = "ENUM_INT"
ENUM_EXPORT_SERVICE_GROUP OptionType = "ENUM_EXPORT_SERVICE_GROUP"
ENUM_EXPORT_SERVICES OptionType = "ENUM_EXPORT_SERVICES"
ENUM_OUTPUT_FORMAT OptionType = "ENUM_OUTPUT_FORMAT"
ENUM_PINGFEDERATE_AUTH_TYPE OptionType = "ENUM_PINGFEDERATE_AUTH_TYPE"
ENUM_PINGONE_AUTH_TYPE OptionType = "ENUM_PINGONE_AUTH_TYPE"
ENUM_PINGONE_REGION_CODE OptionType = "ENUM_PINGONE_REGION_CODE"
ENUM_REQUEST_HTTP_METHOD OptionType = "ENUM_REQUEST_HTTP_METHOD"
ENUM_REQUEST_SERVICE OptionType = "ENUM_REQUEST_SERVICE"
ENUM_STRING OptionType = "ENUM_STRING"
ENUM_STRING_SLICE OptionType = "ENUM_STRING_SLICE"
ENUM_UUID OptionType = "ENUM_UUID"
ENUM_BOOL OptionType = iota
ENUM_EXPORT_FORMAT
ENUM_HEADER
ENUM_INT
ENUM_EXPORT_SERVICE_GROUP
ENUM_EXPORT_SERVICES
ENUM_OUTPUT_FORMAT
ENUM_PINGFEDERATE_AUTH_TYPE
ENUM_PINGONE_AUTH_TYPE
ENUM_PINGONE_REGION_CODE
ENUM_REQUEST_HTTP_METHOD
ENUM_REQUEST_SERVICE
ENUM_STRING
ENUM_STRING_SLICE
ENUM_UUID
)

var optionTypeString = map[OptionType]string{
ENUM_BOOL: "ENUM_BOOL",
ENUM_EXPORT_FORMAT: "ENUM_EXPORT_FORMAT",
ENUM_HEADER: "ENUM_HEADER",
ENUM_INT: "ENUM_INT",
ENUM_EXPORT_SERVICE_GROUP: "ENUM_EXPORT_SERVICE_GROUP",
ENUM_EXPORT_SERVICES: "ENUM_EXPORT_SERVICES",
ENUM_OUTPUT_FORMAT: "ENUM_OUTPUT_FORMAT",
ENUM_PINGFEDERATE_AUTH_TYPE: "ENUM_PINGFEDERATE_AUTH_TYPE",
ENUM_PINGONE_AUTH_TYPE: "ENUM_PINGONE_AUTH_TYPE",
ENUM_PINGONE_REGION_CODE: "ENUM_PINGONE_REGION_CODE",
ENUM_REQUEST_HTTP_METHOD: "ENUM_REQUEST_HTTP_METHOD",
ENUM_REQUEST_SERVICE: "ENUM_REQUEST_SERVICE",
ENUM_STRING: "ENUM_STRING",
ENUM_STRING_SLICE: "ENUM_STRING_SLICE",
ENUM_UUID: "ENUM_UUID",
}

var optionTypeFriendlyString = map[OptionType]string{
ENUM_BOOL: "Boolean",
ENUM_EXPORT_FORMAT: "String (enum)",
ENUM_HEADER: "Boolean",
ENUM_INT: "Number",
ENUM_EXPORT_SERVICE_GROUP: "String (enum)",
ENUM_EXPORT_SERVICES: "String Array (enum)",
ENUM_OUTPUT_FORMAT: "String (enum)",
ENUM_PINGFEDERATE_AUTH_TYPE: "String (enum)",
ENUM_PINGONE_AUTH_TYPE: "String (enum)",
ENUM_PINGONE_REGION_CODE: "String (enum)",
ENUM_REQUEST_HTTP_METHOD: "String (enum)",
ENUM_REQUEST_SERVICE: "String (enum)",
ENUM_STRING: "String",
ENUM_STRING_SLICE: "String Array",
ENUM_UUID: "String (UUID Format)",
}

func (e OptionType) String() string {
if s, ok := optionTypeString[e]; ok {
return s
}

return "ENUM_UNKNOWN"
}

func (e OptionType) FriendlyString() string {
if s, ok := optionTypeFriendlyString[e]; ok {
return s
}

return "Unknown"
}

type Option struct {
CobraParamName string
CobraParamValue pflag.Value
Expand Down
Loading