# summary

Execute profiling definitions against a Salesforce org to generate field-level, value-level, and KPI-level evidence about data population and usage patterns.

# description

Profiling is the moment where KYCD moves from planning to evidence. Before profiling, definitions are plans — field lists, filters, and scoping decisions. After profiling, they have results: field population rates, value distributions, null percentages, default detection, and usage patterns across every profiled object.

The command operates as a fire-and-forget execution engine — it creates profiling requests in the processing queue and returns immediately. Results appear in the org as summaries complete, typically within minutes depending on object size and field count. Definitions are managed with the `definition` commands; results are reviewed through summaries.

TWO MODES:

**Single mode** — Profile one definition:

- `--keys PD-0001` — profile by definition key
- `--id a0Bxx000000001AAAA` — profile by Salesforce record ID

Single mode displays definition key, object name, status, request ID, duration, and error details.

**Bulk mode** — Profile multiple definitions with parallel execution:

- `--method metadata` — profile all definitions of a method type (metadata, historical, or comparative)
- Add filters: --status, --namespace, --category, --time-category, --segment-category, --limit
- Control concurrency: --parallel (1-10 threads, default: 5)

Bulk mode displays a configuration summary, a results table, a profiling summary (Successful/Failed/Skipped/Total), and resolution guidance for failures.

Objects with zero records are automatically skipped (--skip-empty defaults to true), preventing wasted API calls. Failed definitions are reported with resolution guidance that provides actionable next steps.

PREREQUISITE: Definitions must exist before profiling. Create them with `sf cuneiform definition create`.

WHEN TO USE:

- After creating definitions — turn scoping work into analytical evidence
- To refresh profiling results — re-run profiling on existing definitions for updated data
- For bulk assessment — sweep all metadata definitions in a single parallel command
- To re-profile after errors — fix the underlying issue, then re-run the failed definitions

NATURAL LANGUAGE → FLAG MAPPING:
"profile the Account definition" → --keys PD-0001
"profile all metadata definitions" → --method metadata
"profile everything that hasn't been profiled" → --method metadata --status "NOT PROFILED"
"profile only FSC objects" → --method metadata --namespace FinServ
"profile with less concurrency" → --method metadata --parallel 1

COMMAND SEQUENCE:
`definition create` or `definition update` → **`profile`** → `profile request list` → `definition get` (view results)

# flags.target-org.summary

Authenticate and execute profiling against this Salesforce org. Specify the org alias or username when you have multiple authenticated orgs.

# flags.keys.summary

Profile one or more definitions by key (e.g., --keys PD-0001). Find keys with `definition list`. Mutually exclusive with --id and --method.

# flags.id.summary

Profile a single definition by its Salesforce record ID (e.g., --id a0Bxx000000001AAAA). Use when you have the record ID from the Salesforce UI or API. Mutually exclusive with --keys and --method.

# flags.method.summary

Profile all definitions matching a method type: metadata (field-level analysis), historical (time-series trends), or comparative (segment comparison). Activates bulk mode with parallel execution. Mutually exclusive with --keys and --id.

# flags.status.summary

Filter definitions by profiling status before executing (e.g., --status "NOT PROFILED" for first-time profiling, --status "ERROR" to retry failures). Applies only in bulk mode with --method.

# flags.namespace.summary

Filter definitions by the namespace prefix of their target object (e.g., "FinServ" for Financial Services Cloud, "SBQQ" for CPQ). Profiles only definitions targeting objects from a specific managed package.

# flags.category.summary

Filter definitions by category label (e.g., "Baseline", "Phase 1"). Combine with --time-category and --segment-category to target definitions across all three category dimensions.

# flags.time-category.summary

Filter definitions by time category (e.g., "Lifetime", "2026 vs 2025", "This Year"). Combine with --category and --segment-category to target time-scoped definitions.

# flags.segment-category.summary

Filter definitions by segment category (e.g., "Historical", "Comparative", "Enterprise Sales", "Won vs Lost"). Combine with --category and --time-category to target specific comparison segments.

# flags.limit.summary

Cap the number of definitions processed in bulk mode (e.g., --limit 10 to profile a small batch for testing). Controls the maximum definitions per run.

# flags.skip-empty.summary

Automatically skip definitions targeting objects with zero records (default: true). Optimizes API usage by focusing execution on populated objects. Use --no-skip-empty to include all definitions regardless of record count.

# flags.parallel.summary

Set the number of parallel concurrent operations for bulk mode (1-10, default: 5). Lower values reduce API consumption; higher values increase throughput when the org has API capacity.

# flags.format.summary

Control the output format: table (default, human-readable with progress and summary boxes) or json (machine-readable for scripting and automation).

# examples

- Profile a single definition by key:

  <%= config.bin %> <%= command.id %> --target-org myOrg --keys PD-0001

- Profile a single definition by Salesforce record ID:

  <%= config.bin %> <%= command.id %> --target-org myOrg --id a0Bxx000000001AAAA

- Sweep all metadata definitions with parallel execution:

  <%= config.bin %> <%= command.id %> --target-org myOrg --method metadata

- Profile only definitions that have never been profiled:

  <%= config.bin %> <%= command.id %> --target-org myOrg --method historical --status "NOT PROFILED"

- Profile only Financial Services Cloud objects:

  <%= config.bin %> <%= command.id %> --target-org myOrg --method metadata --namespace FinServ

- Maximize throughput with full parallelism:

  <%= config.bin %> <%= command.id %> --target-org myOrg --method comparative --parallel 10

- Profile a small batch for testing:

  <%= config.bin %> <%= command.id %> --target-org myOrg --method metadata --limit 5

- Minimize API impact with single-threaded execution:

  <%= config.bin %> <%= command.id %> --target-org myOrg --method metadata --parallel 1

# display.definition

Definition: %s (%s)

# display.status

Status: %s

# display.requestId

Request ID: %s

# display.error

Error: %s

# display.resolution

Resolution: %s

# display.skipReason

Skip reason: %s

# display.processed

Processed %s definition(s):

# display.resolutionGuidance

Resolution guidance for failures:

# display.resolutionItem

%s: %s

# display.summaryTitle

Summary

# display.summarySuccessful

Successful

# display.summaryFailedLabel

Failed

# display.summarySkippedLabel

Skipped

# display.summaryTotalLabel

Total

# display.nextSteps

Track profiling progress:

sf cuneiform profile request list --target-org %s

# spinner.connecting

Connecting

# errors.noSelection

No selection provided. Specify --keys, --id, or --method flag.

# errors.invalidSelection

Invalid flag combination. Only one of --keys, --id, or --method allowed.

# errors.invalidId

Invalid Salesforce ID format: %s. Must be 15 or 18 alphanumeric characters.

# errors.definitionNotFound

Definition not found: %s

# errors.invalidParallel

Invalid --parallel value. Must be between 1 and 10.

# errors.queryFailed

Failed to query definitions: %s

# errors.noDefinitionsFound

No definitions found matching filters.

# errors.executionFailed

Profiling execution failed: %s