feat: add --schema and --data options for email and phone provider commands

docs/auth0_email_provider_create.md

@@ -11,6 +11,10 @@ To create interactively, use `auth0 email provider create` with no arguments.
 
 To create non-interactively, supply the provider name and other information through the flags.
 
+Use `--data` to supply the whole payload as JSON (inline, `@file.json`, or piped via stdin). It is sent as-is and validated by the API. Use `--schema` to print the request payload schema and exit.
+
+For a `custom` provider, `--data` must include `"credentials":{}`; the API rejects the request without it.
+
 ## Usage
 ```
 auth0 email provider create [flags]
@@ -34,18 +38,29 @@ auth0 email provider create [flags]
   auth0 email provider create --provider azure_cs --credentials='{ "connection_string":"TheConnectionString" }'
   auth0 email provider create --provider ms365 --credentials='{ "tenantId":"TheTenantId", "clientId":"TheClientID", "clientSecret":"TheClientSecret" }'
   auth0 email provider create --provider custom --enabled=true --default-from-address="admin@example.com"
+
+  # Discover the payload schema
+  auth0 email provider create --schema
+  auth0 email provider create --schema --json
+
+  # JSON input mode (for agents and automation)
+  auth0 email provider create --data '{"name":"sendgrid","credentials":{"api_key":"TheAPIKey"},"enabled":true}'
+  auth0 email provider create --data '{"name":"custom","credentials":{},"enabled":true}'
+  auth0 email provider create --data @provider.json
 ```
 
 
 ## Flags
 
 ```
   -c, --credentials string            Credentials for the email provider, formatted as JSON.
+      --data string                   JSON payload for the operation, as a JSON string or file path (@file.json). Can also be piped via stdin.
   -f, --default-from-address string   Provider default FROM address if none is specified.
   -e, --enabled                       Whether the provided is enabled (true) or disabled (false). (default true)
       --json                          Output in json format.
       --json-compact                  Output in compact json format.
   -p, --provider string               Provider name. Can be 'mandrill', 'ses', 'sendgrid', 'sparkpost', 'mailgun', 'smtp', 'azure_cs', 'ms365', or 'custom'
+      --schema                        Print the request payload schema for this command and exit. Use with --json or --json-compact for machine-readable output.
   -s, --settings string               Settings for the email provider. formatted as JSON.
 ```
 

docs/auth0_email_provider_update.md

@@ -11,6 +11,8 @@ To update interactively, use `auth0 email provider update` with no arguments.
 
 To update non-interactively, supply the provider name and other information through the flags.
 
+Use `--data` to supply the whole payload as JSON (inline, `@file.json`, or piped via stdin). It is sent as-is and validated by the API. Use `--schema` to print the request payload schema and exit.
+
 ## Usage
 ```
 auth0 email provider update [flags]
@@ -38,18 +40,28 @@ auth0 email provider update [flags]
   auth0 email provider update --provider azure_cs --credentials='{ "connection_string":"TheConnectionString" }'
   auth0 email provider update --provider ms365 --credentials='{ "tenantId":"TheTenantId", "clientId":"TheClientID", "clientSecret":"TheClientSecret" }'
   auth0 email provider update --provider custom --enabled=true --default-from-address="admin@example.com"
+
+  # Discover the payload schema
+  auth0 email provider update --schema
+  auth0 email provider update --schema --json
+
+  # JSON input mode (for agents and automation)
+  auth0 email provider update --data '{"credentials":{"api_key":"NewAPIKey"}}'
+  auth0 email provider update --data @provider.json
 ```
 
 
 ## Flags
 
 ```
   -c, --credentials string            Credentials for the email provider, formatted as JSON.
+      --data string                   JSON payload for the operation, as a JSON string or file path (@file.json). Can also be piped via stdin.
   -f, --default-from-address string   Provider default FROM address if none is specified.
   -e, --enabled                       Whether the provided is enabled (true) or disabled (false). (default true)
       --json                          Output in json format.
       --json-compact                  Output in compact json format.
   -p, --provider string               Provider name. Can be 'mandrill', 'ses', 'sendgrid', 'sparkpost', 'mailgun', 'smtp', 'azure_cs', 'ms365', or 'custom'
+      --schema                        Print the request payload schema for this command and exit. Use with --json or --json-compact for machine-readable output.
   -s, --settings string               Settings for the email provider. formatted as JSON.
 ```
 

docs/auth0_phone_provider_create.md

@@ -11,6 +11,8 @@ To create interactively, use `auth0 phone provider create` with no arguments.
 
 To create non-interactively, supply the provider name and other information through the flags.
 
+Use `--data` to supply the whole payload as JSON (inline, `@file.json`, or piped via stdin). It is validated against the OpenAPI schema before it is sent. Use `--schema` to print the request payload schema and exit.
+
 ## Usage
 ```
 auth0 phone provider create [flags]
@@ -24,7 +26,15 @@ auth0 phone provider create [flags]
   auth0 phone provider create --json-compact
   auth0 phone provider create --provider twilio --disabled=false --credentials='{ "auth_token":"TheAuthToken" }' --configuration='{ "default_from": "admin@example.com", "sid": "+1234567890", "delivery_methods": ["text", "voice"] }'
   auth0 phone provider create --provider custom --disabled=true --configuration='{ "delivery_methods": ["text", "voice"] }'
-  auth0 phone provider create -p twilio -d "false" -c '{ "auth_token":"TheAuthToken" }' -s '{ "default_from": "admin@example.com", "sid": "+1234567890", "delivery_methods": ["text"] }'  
+  auth0 phone provider create -p twilio -d "false" -c '{ "auth_token":"TheAuthToken" }' -s '{ "default_from": "admin@example.com", "sid": "+1234567890", "delivery_methods": ["text"] }'
+
+  # Discover the payload schema
+  auth0 phone provider create --schema
+  auth0 phone provider create --schema --json
+
+  # JSON input mode (for agents and automation)
+  auth0 phone provider create --data '{"name":"twilio","credentials":{"auth_token":"TheAuthToken"},"configuration":{"default_from":"+1234567890","delivery_methods":["text"]}}'
+  auth0 phone provider create --data @provider.json
 ```
 
 
@@ -33,10 +43,12 @@ auth0 phone provider create [flags]
 ```
   -s, --configuration string   Configuration for the phone provider. formatted as JSON.
   -c, --credentials string     Credentials for the phone provider, formatted as JSON.
+      --data string            JSON payload for the operation, as a JSON string or file path (@file.json). Can also be piped via stdin.
   -d, --disabled               Whether the provided is disabled (true) or enabled (false).
       --json                   Output in json format.
       --json-compact           Output in compact json format.
   -p, --provider string        Provider name. Can be 'twilio', or 'custom'
+      --schema                 Print the request payload schema for this command and exit. Use with --json or --json-compact for machine-readable output.
 ```
 
 

docs/auth0_phone_provider_list.md

@@ -7,6 +7,9 @@ has_toc: false
 
 List your existing Phone providers. Currently we can create a max of 1 phone Provider, If none are created, you can create one by running `auth0 phone provider create`.
 
+Use '--schema' to see available query parameters.
+Use '--query' to filter results via a JSON object (any API-supported parameter works immediately).
+
 ## Usage
 ```
 auth0 phone provider list [flags]
@@ -16,10 +19,17 @@ auth0 phone provider list [flags]
 
 ```
   auth0 phone provider list
-  auth0 phone provider ls 
+  auth0 phone provider ls
   auth0 phone provider ls --json
   auth0 phone provider ls --json-compact
   auth0 phone provider ls --csv
+
+  # Discover the query schema
+  auth0 phone provider list --schema
+  auth0 phone provider list --schema --json
+
+  # JSON query (for agents and automation)
+  auth0 phone provider list --query '{"disabled":false}'
 ```
 
 
@@ -29,6 +39,8 @@ auth0 phone provider list [flags]
       --csv            Output in csv format.
       --json           Output in json format.
       --json-compact   Output in compact json format.
+  -q, --query string   Filter results with a JSON object of query parameters. Any API-supported parameter works immediately. Run '--schema' to see documented parameters. On offset-paginated endpoints, add "include_totals":true to receive total counts and a pagination hint (without it the API returns a bare array and no hint can be given).
+      --schema         Print the request payload schema for this command and exit. Use with --json or --json-compact for machine-readable output.
 ```
 
 

docs/auth0_phone_provider_update.md

@@ -11,6 +11,8 @@ To update interactively, use `auth0 phone provider update` with no arguments.
 
 To update non-interactively, supply the provider name and other information through the flags.
 
+Use `--data` to supply the whole payload as JSON (inline, `@file.json`, or piped via stdin). It is validated against the OpenAPI schema before it is sent. Use `--schema` to print the request payload schema and exit.
+
 ## Usage
 ```
 auth0 phone provider update [flags]
@@ -28,6 +30,14 @@ auth0 phone provider update [flags]
   auth0 phone provider update --configuration='{ "default_from": admin@example.com }'
   auth0 phone provider update --provider twilio --disabled=false --credentials='{ "auth_token":"NewAuthToken" }' --configuration='{ "sid": "+1234567890", "default_from": "admin@example.com", "delivery_methods": ["voice", "text"] }'
   auth0 phone provider update --provider custom --disabled=false --configuration='{ "delivery_methods": ["voice", "text"] }'
+
+  # Discover the payload schema
+  auth0 phone provider update --schema
+  auth0 phone provider update --schema --json
+
+  # JSON input mode (for agents and automation)
+  auth0 phone provider update <id> --data '{"credentials":{"auth_token":"NewAuthToken"}}'
+  auth0 phone provider update <id> --data @provider.json
 ```
 
 
@@ -36,10 +46,12 @@ auth0 phone provider update [flags]
 ```
   -s, --configuration string   Configuration for the phone provider. formatted as JSON.
   -c, --credentials string     Credentials for the phone provider, formatted as JSON.
+      --data string            JSON payload for the operation, as a JSON string or file path (@file.json). Can also be piped via stdin.
   -d, --disabled               Whether the provided is disabled (true) or enabled (false).
       --json                   Output in json format.
       --json-compact           Output in compact json format.
   -p, --provider string        Provider name. Can be 'twilio', or 'custom'
+      --schema                 Print the request payload schema for this command and exit. Use with --json or --json-compact for machine-readable output.
 ```
 
 

internal/cli/data_json.go

@@ -2,6 +2,7 @@ package cli
 
 import (
 	"encoding/json"
+	"errors"
 	"fmt"
 	"os"
 	"strings"
@@ -116,6 +117,23 @@ func readAndValidateJSON(cli *cli, inputStr, method, path string) (json.RawMessa
 	return handler.ReadAndValidate(inputStr, method, path)
 }
 
+// readJSONObject reads a --data payload and checks only that it is a JSON object.
+func readJSONObject(input string) (json.RawMessage, error) {
+	data, err := readJSONInput(input)
+	if err != nil {
+		return nil, validationError{err: fmt.Errorf("failed to read JSON input: %w", err)}
+	}
+
+	var obj map[string]json.RawMessage
+	if err := json.Unmarshal(data, &obj); err != nil {
+		return nil, validationError{err: fmt.Errorf("invalid JSON: the payload must be a JSON object: %w", err), reason: "malformed_json"}
+	}
+	if obj == nil {
+		return nil, validationError{err: errors.New("the payload must be a JSON object"), reason: "malformed_json"}
+	}
+	return data, nil
+}
+
 // readJSONInput reads JSON from various input sources.
 func readJSONInput(input string) ([]byte, error) {
 	if input == "" {
@@ -220,6 +238,10 @@ type jsonWriteSpec struct {
 	URI        string // Fully-qualified request URL.
 	Data       string // Raw --data value (inline JSON, @file, or piped payload).
 	SchemaCmd  string // Command to suggest in the "--schema" hint, e.g. "auth0 actions create".
+
+	// SkipValidation sends the payload after checking only that it is a JSON object,
+	// leaving validation to the API, for operations whose published schema is unreliable.
+	SkipValidation bool
 }
 
 // runJSONWrite validates a --data payload against the OpenAPI schema, sends it to
@@ -228,7 +250,16 @@ type jsonWriteSpec struct {
 // supplying their spec and the management type; the API's own semantics (e.g. PATCH
 // preserving unspecified fields) apply to the exact bytes sent.
 func runJSONWrite[T any](cli *cli, cmd *cobra.Command, spec jsonWriteSpec) (*T, error) {
-	payload, validated, err := readAndValidateJSON(cli, spec.Data, spec.Method, spec.SchemaPath)
+	var (
+		payload   json.RawMessage
+		validated = true
+		err       error
+	)
+	if spec.SkipValidation {
+		payload, err = readJSONObject(spec.Data)
+	} else {
+		payload, validated, err = readAndValidateJSON(cli, spec.Data, spec.Method, spec.SchemaPath)
+	}
 	if err != nil {
 		cli.renderer.Infof("Run '%s --schema' to see the expected schema.", spec.SchemaCmd)
 		return nil, err
@@ -251,7 +282,7 @@ func runJSONWrite[T any](cli *cli, cmd *cobra.Command, spec jsonWriteSpec) (*T,
 		// validation via the 400 status and the schema stays discoverable through
 		// --schema. Keep the API's own error clean for machines and enrich it with
 		// the schema hint only for humans.
-		if cli.wantsJSONError() {
+		if cli.wantsJSONError() || spec.SkipValidation {
 			return nil, err
 		}
 		return nil, enhanceAPIError(err, spec.Method, spec.SchemaPath)

internal/cli/data_json_test.go

@@ -57,6 +57,28 @@ func withPipedStdin(t *testing.T, content string, fn func()) {
 	require.NoError(t, r.Close())
 }
 
+func TestReadJSONObject(t *testing.T) {
+	for name, tc := range map[string]struct{ data, wantErr string }{
+		"object":                           {`{"name":"x"}`, ""},
+		"empty object":                     {`{}`, ""},
+		"truncated keeps the parse detail": {`{"name":"x",`, "unexpected end of JSON input"},
+		"empty input":                      {``, "no input provided"},
+		"array":                            {`["x"]`, "must be a JSON object"},
+		"string":                           {`"x"`, "must be a JSON object"},
+		"null":                             {`null`, "must be a JSON object"},
+		"number":                           {`5`, "must be a JSON object"},
+	} {
+		t.Run(name, func(t *testing.T) {
+			_, err := readJSONObject(tc.data)
+			if tc.wantErr == "" {
+				require.NoError(t, err)
+				return
+			}
+			assert.ErrorContains(t, err, tc.wantErr)
+		})
+	}
+}
+
 func TestReadJSONInput(t *testing.T) {
 	t.Run("inline JSON is returned verbatim", func(t *testing.T) {
 		data, err := readJSONInput(`{"name":"x"}`)