# summary

Build profiling definitions that translate scoping decisions — object selection, filtering, and profiling methodology — into executable configuration records across one or dozens of objects in a single command.

# description

Profiling definitions are the blueprint that tells Cuneiform what to analyze. Each definition specifies an object, a profiling method, and a time scope. This command translates your intent — expressed through flags for method selection, object filtering, and time windowing — into structured definition records in the target org.

The command executes in two phases. Phase 1 discovers and validates objects, builds a preview table showing each object with its record count, profiling type, category, time category, and segment category, then prompts for confirmation. Phase 2 creates definitions sequentially, reporting progress via spinner updates. Output includes separate Created and Skipped tables, a summary box (Objects/Created/Skipped/Failed), and optional post-creation actions: trigger immediate profiling, open the first definition in Salesforce Lightning, or write session data to a local log directory.

PREREQUISITES: Run `sf cuneiform user details --configure` to verify permissions. Objects must exist in the target org.

CHOOSING A PROFILING METHOD (--method):

- metadata — Catalogs field structure and configuration. No record scanning. Fast. No time dimension.
- historical — Full record-level data profiling with year-based time windows. Captures how field population changes over time.
- comparative — Year-over-year comparison: compares current-period records (SetA) against prior-period records (SetB). Requires --year or --date-literal.
- recordtype — Per-record-type analysis across 6 time windows. Segments data by business process stage (e.g., New Business vs Renewal).
- outcome — Boolean outcome comparison: Won vs Lost for Opportunity, Closed vs Open for Case, Converted vs Unconverted for Lead. Surfaces data quality gaps between business outcomes.
- full — All five methods combined. Comprehensive first-time profiling of a new org. Default.

SCOPING OBJECTS:

- --objects Account,Contact — Profile specific named objects (comma-separated or repeated)
- --filter custom — All custom objects; --filter standard — All standard objects
- --with-records — Only objects that have at least one record (recommended for historical/comparative)
- --min-records 100 — Only objects with 100+ records
- --namespace SBQQ — Only objects from a specific managed package (e.g., SBQQ for CPQ, FinServ for FSC)
- --pattern Account\* — Objects matching a wildcard pattern

ROLLING TIME WINDOWS (use with --method comparative, historical, recordtype, or full):

- --date-literal THIS_YEAR — Profile the current year's records
- --date-literal THIS_QUARTER — Profile the current quarter
- --date-literal THIS_MONTH — Profile the current month
- --depth 3 — With a date literal, creates 3 cascading periods: this period, last period, and two periods ago
- --depth 2 --date-literal THIS_QUARTER — Creates definitions for this quarter AND last quarter
- --year 2026 — Use a specific year instead of a date literal; --depth controls how many prior years to include
- --date-field LastModifiedDate — Use LastModifiedDate instead of CreatedDate for time filtering

NATURAL LANGUAGE → FLAG MAPPING:

- "compare X from 2025 vs 2026" → --method comparative --year 2026
- "rolling quarterly analysis" → --method comparative --date-literal THIS_QUARTER --depth N
- "year-over-year trends" → --method comparative
- "by business stage / record type" → --method recordtype
- "won vs lost / closed vs open" → --method outcome
- "field-level stats only" → --method metadata
- "objects with data" → --with-records
- "FSC objects" → --namespace FinServ
- "CPQ objects" → --namespace SBQQ
- "last N months" → --date-literal LAST_MONTH --depth N

COMMAND SEQUENCE: `user details --configure` (verify permissions) → `object describe` (understand structure) → `definition create` (build definitions) → `profile` (execute profiling)

SAFETY: Deduplication is by generated name (object + method + time-segment + prefix/suffix) — same object with a different --name-prefix creates a new definition, not a skip. A confirmation prompt appears before creation. Use --dry-run to preview without creating.

# flags.target-org.summary

Salesforce org where definitions will be created. The command validates Cuneiform installation and permission sets before any API calls.

# flags.objects.summary

Salesforce object API names to create definitions for (e.g., --objects Account --objects Contact). Repeat the flag for multiple objects. When you know exactly which objects to profile, this is the most direct selection mode. Cannot be combined with --filter when targeting specific objects.

# flags.pattern.summary

Filter objects by API name pattern using wildcard matching (e.g., Account\_ matches Account and AccountTeamMember). Use plain text for substring matching (e.g., Account matches any object containing "Account"). Targets families of related objects by naming convention.

# flags.filter.summary

Filter objects by Salesforce object type: custom (objects with \_\_c suffix), standard (built-in objects like Account, Contact, Opportunity), or all (both). Defaults to all.

# flags.namespace.summary

Filter objects by managed package namespace prefix to scope profiling to a specific product installation (e.g., --namespace SBQQ for CPQ, --namespace FinServ for Financial Services Cloud, --namespace HealthCloudGA for Health Cloud). Pass an empty string ("") to target only unpackaged custom objects. Combines with --filter custom to isolate custom objects from a specific package.

# flags.classification.summary

Filter by object classification: customer (business-facing objects), internal (system objects), or all. Defaults to all.

# flags.with-records.summary

Include only objects that have at least one record. Avoids creating definitions for empty staging or archive objects. Recommended for historical and comparative profiling where empty objects produce no analytical value. Cannot be combined with --without-records.

# flags.without-records.summary

Include only objects that have zero records. Targets empty objects for data completeness analysis or unused schema identification. Cannot be combined with --with-records.

# flags.with-record-types.summary

Include only objects that have at least one active record type defined. Use with --method recordtype to ensure targeted objects have record types to segment by.

# flags.category.summary

Label assigned to every definition created in this run (e.g., --category "Phase 1" or --category "Sales Cloud"). Groups definitions by engagement phase or functional area for later filtering and management. Freeform text.

# flags.min-records.summary

Minimum record count an object must have to be included (e.g., --min-records 100 skips objects with fewer than 100 records). Filters out low-volume objects that would produce statistically insignificant profiling results. Defaults to 0 (include all).

# flags.limit.summary

Maximum number of objects to create definitions for (e.g., --limit 20 for a quick demo setup). Constrains scope in large orgs or matches a statement-of-work object count. Objects are selected in the order returned by the Salesforce DescribeGlobal API. When omitted, processes all matching objects.

# flags.method.summary

Profiling methodology that determines the analytical questions each definition can answer:
metadata — Catalogs field structure and configuration. Fast, no record scanning, no time dimension.
historical — Full record-level analysis with year-based time windows. Captures field population changes over time.
comparative — Compares current-period records (SetA) vs prior-period records (SetB). Requires --year or --date-literal.
recordtype — Per-record-type analysis across 6 time windows. Segments by business process stage (e.g., New Business vs Renewal for Opportunity).
outcome — Boolean outcome comparison: Won vs Lost (Opportunity), Closed vs Open (Case), Converted vs Unconverted (Lead). Surfaces data quality gaps between business outcomes.
full — All five methods combined. Comprehensive first-time profiling of a new org or client engagement. Default.
Defaults to full.

# flags.year.summary

Anchor year for time-based profiling definitions (e.g., --year 2026). Used with --method comparative, historical, recordtype, or full. Accepts comma-separated years (--year 2026,2025,2024). When combined with --depth, sets the starting year and counts backward (e.g., --year 2026 --depth 3 creates definitions for 2026, 2025, and 2024). Defaults to the current year. Cannot be combined with --date-literal.

# flags.depth.summary

Number of cascading time periods to create, counting backward from the anchor year or date literal (e.g., --depth 3 with --year 2026 creates definitions for 2026, 2025, and 2024). Use with --date-literal to span periods (e.g., --date-literal THIS_QUARTER --depth 2 creates definitions for this quarter and last quarter). When no anchor year is specified, defaults to the current year. Defaults to 1 for comparative, 3 for full and recordtype. Maximum 10.

# flags.from.summary

Start year of an explicit range (inclusive). Use with --to for a custom year range (e.g., --from 2020 --to 2026). Produces one profiling definition per year in the inclusive range — `objects × (to − from + 1)` total. Cannot be combined with --depth.

# flags.to.summary

End year of an explicit range (inclusive). Use with --from for a custom year range (e.g., --from 2020 --to 2026). Produces one profiling definition per year in the inclusive range — `objects × (to − from + 1)` total. Defaults to the current year when --from is specified.

# errors.yearRangeInvalid

Invalid year range: %s

# flags.recordtype.summary

Filter to a specific record type name for record-type-specific profiling (e.g., --recordtype "New Business"). Used with --method recordtype or --method full. When omitted, all record types matching --record-type-status are included.

# flags.record-type-status.summary

Filter record types by activity status: active (default), all (active and inactive), or inactive (only inactive). Used with --method recordtype or --method full.

# warnings.yearIgnored

Year-related flags (--year, --depth, --from, --to) have no effect with --method metadata. Metadata profiling analyzes field structure only, with no time dimension. Ignoring.

# flags.no-value-frequency.summary

Skip common value frequency analysis during profiling. Reduces profiling time for objects where frequency distribution data is not needed.

# flags.use-prior.summary

Expand the comparison baseline (SetB) for comparative definitions to include all records created before the anchor year, rather than only the immediately prior year. Shows "current year vs everything before" instead of "current year vs last year" — useful for demonstrating data quality improvements across the full historical record. Cannot be combined with --date-literal.

# flags.lifetime-primary.summary

Lifetime-vs-X comparative variant: SetA is unfiltered (all records), SetB is the supplied secondary filter. Shows "all records ever vs records matching the filter" — useful for highlighting what fraction of the lifetime data falls within a recent window or specific year. Requires --method comparative AND one of (--date-literal, --year, --from/--to). Mutually exclusive with --use-prior, --depth, and non-comparative methods.

# flags.date-literal.summary

Rolling time window for time-scoped profiling — use instead of --year for calendar-relative periods. Combine with --depth to create cascading definitions across multiple periods (e.g., --date-literal THIS_QUARTER --depth 4 creates definitions for the last 4 quarters). Cannot be combined with --year, --from, --to, or --use-prior.

Supported values:
TODAY, YESTERDAY — Single-day windows
THIS_WEEK, LAST_WEEK — Weekly windows
THIS_MONTH, LAST_MONTH — Monthly windows (use with --depth for "last N months")
THIS_QUARTER, LAST_QUARTER — Quarterly windows (use with --depth for "rolling quarters")
THIS_YEAR, LAST_YEAR — Annual windows
N_YEARS_AGO:2, N_YEARS_AGO:3 — Specific years in the past
LAST_N_YEARS:2, LAST_N_YEARS:3 — Last N complete years

# flags.date-field.summary

Date field used to assign records to time windows when using --date-literal. Determines which records fall in "this year" vs "last year." Defaults to CreatedDate. Use LastModifiedDate to analyze records by when they were last updated rather than when they were created (e.g., --date-field LastModifiedDate to profile recently refreshed data).

# errors.dateLiteralMutualExclusion

Cannot combine --date-literal with --year, --from, --to, or --use-prior. Date literals replace year-based time scoping. Use --date-literal with --depth to cascade across multiple periods.

# errors.lifetimePrimaryMethodRequired

--lifetime-primary is only valid with --method comparative.

# errors.lifetimePrimaryUsePriorMutualExclusion

Cannot combine --lifetime-primary with --use-prior. Choose one variant: --lifetime-primary (lifetime vs filtered) or --use-prior (current year vs all prior).

# errors.lifetimePrimaryDepthMutualExclusion

Cannot combine --lifetime-primary with --depth. The lifetime-vs-X variant produces a single definition shape per object — no cascade.

# errors.lifetimePrimaryRequiresSecondaryFilter

--lifetime-primary requires a secondary filter: provide --date-literal, --year, or --from/--to.

# flags.dry-run.summary

Preview which definitions would be created without writing any records to the org. The preview table shows the same columns as the creation output: object name, record count, type, category, and time segment. Use before any scoped run to verify the object selection and methodology match your intent.

# flags.no-prompt.summary

Skip the confirmation prompt and create definitions immediately. Use for scripted execution and CI automation workflows.

# prompt.showDetail

Show detailed preview?

# prompt.confirm

Create %s Profiling Definitions?

# output.cancelled

Definition creation cancelled.

# examples

- Create definitions for a single object using all profiling methods:

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

- Preview what would be created before committing (recommended before batch runs):

  <%= config.bin %> <%= command.id %> --target-org myOrg --filter custom --with-records --dry-run

- Profile all custom objects with at least 100 records, tagged by engagement phase:

  <%= config.bin %> <%= command.id %> --target-org myOrg --filter custom --with-records --min-records 100 --category "Phase 1"

- Isolate Financial Services Cloud objects by namespace:

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

- Rolling quarterly trend analysis across the last 4 quarters:

  <%= config.bin %> <%= command.id %> --target-org myOrg --objects Opportunity --method comparative --date-literal THIS_QUARTER --depth 4

- Lifetime vs last 2 years — show what fraction of all records were created in the recent window:

  <%= config.bin %> <%= command.id %> --target-org myOrg --objects Account,Contact,Opportunity --method comparative --lifetime-primary --date-literal LAST_N_YEARS:2

- Lifetime vs a specific year — compare all records ever against records created in 2024:

  <%= config.bin %> <%= command.id %> --target-org myOrg --objects Opportunity --method comparative --lifetime-primary --year 2024

- Won vs Lost opportunity analysis to surface data quality gaps between business outcomes:

  <%= config.bin %> <%= command.id %> --target-org myOrg --objects Opportunity --objects Case --objects Lead --method outcome

- Bulk run with shared, human-readable category labels across every created definition:

  <%= config.bin %> <%= command.id %> --target-org myOrg --filter custom --with-records --time-category "Q1 2026" --segment-category "Pilot Run"

# flags.profiled.summary

Only create definitions for objects that already have successful metadata profiling results. Builds on prior metadata analysis — run metadata profiling first, review the results, then create historical or comparative definitions for the objects worth deeper analysis. Cannot be combined with --method metadata.

# errors.profiledWithMetadata

Cannot use --profiled with --method metadata. The --profiled flag targets objects that already have metadata profiling results.

# errors.noObjectsFound

No objects found matching the specified filters.

# errors.objectsNotFound

None of the specified objects exist in the org: %s

# errors.allObjectsSkipped

All %d objects already have existing definitions.

# errors.operationFailed

Failed to create definitions: %s

# errors.filterFailed

Failed to filter objects: %s

# flags.profile.summary

Trigger profiling immediately after definitions are created — equivalent to running `sf cuneiform profile` as a follow-up. Useful for quick single-object setup. For batch runs, create definitions first, review them, then profile separately.

# flags.open.summary

Open the created definition in Salesforce Lightning after creation completes. When multiple definitions are created, opens the first one. Useful for verifying the definition record in the Profiling Definition Wizard.

# flags.logs.summary

Write session logs to the .cuneiform/logs/ directory for audit and troubleshooting.

# errors.noProfiledObjects

No objects have been profiled yet. Run profiling with --method metadata first.

# errors.orgUnreachable

Unable to connect to the target org.

The org "%s" could not be reached. This usually means:

1. The org alias or username is incorrect
2. The org has expired or been deleted
3. Your authentication has expired

To resolve:

- Verify the org exists: sf org list
- Re-authenticate: sf org login web --alias <your-org>
- Check org status: sf org display --target-org <your-org>

# errors.noTargetOrg

Could not determine target org username.

# errors.mutuallyExclusiveRecordFlags

Cannot use --with-records and --without-records together.

# errors.minRecordsWithoutRecords

Cannot use --min-records with --without-records. The --min-records flag requires record counts, which --without-records excludes.

# errors.recordtypeMethodRequired

--recordtype flag cannot be used with --method metadata. Use it with --method historical, comparative, recordtype, outcome, or full.

# output.title

Creating Cuneiform Profiling Definitions for %s (%s)

# output.creating

Creating %d Cuneiform Profiling Definitions

# errors.objectsNotFoundDetail

No Salesforce Objects were found matching the specified criteria.

Please check the object name(s) and confirm they exist in your Salesforce org.

# spinner.connecting

Connecting

# spinner.validatingObjects

Validating Salesforce Objects

# warnings.objectNotVerified

We could not verify the Object %s; no Profiling Definitions will be created for this object.

# output.failedSummary

%s definitions failed:

# output.profileDryRun

[DRY RUN] Would start profiling for %s definitions.

# output.profilingStarting

Profiling created definitions...

# output.profilingSuccess

[PROFILING] %s — request %s

# warnings.profilingFailed

Failed to start profiling for %s: %s

# output.openedMultiple

Opened first definition. Use Salesforce to view all %s definitions.

# output.openedSingle

Opened definition in Salesforce.

# output.sessionLog

Session log: %s

# output.creationSummary

Creation Summary

# output.summaryObjects

Objects:

# output.summaryMethod

Method:

# output.summaryToCreate

To create:

# output.summaryExisting

Existing:

# output.summaryPreview

Preview:

# output.summaryCreated

Created:

# output.summarySkipped

Skipped:

# output.summaryFailed

Failed:

# output.summaryHeader

Summary

# output.tablePrefix.preview

Preview

# output.tablePrefix.created

Created

# output.skippedExisting

Skipped %s Existing Definitions

# output.definitionsTitle

Cuneiform Profiling Definitions

# table.header.object

object

# table.header.records

records

# table.header.type

type

# table.header.category

category

# table.header.time

time

# table.header.segment

segment

# spinner.status.created

created

# spinner.status.skipped

skipped

# output.summaryToCreateSuffix

%s definitions

# output.summaryExistingSuffix

%s definitions (skipped)

# flags.name-prefix.summary

Prefix prepended to each definition name (e.g., --name-prefix TC-01). Joined with the bullet separator character.

# flags.name-suffix.summary

Suffix appended to each definition name (e.g., --name-suffix "Run A"). Joined with the bullet separator character.

# flags.time-category.summary

Verbatim time category applied to every definition created in this run (e.g., --time-category "Q1 2026" or --time-category "Pilot Period"). Overrides all computed time category values regardless of method, year, or outcome configuration. Useful for grouping definitions across a bulk run with a single shared, human-readable time label.

# flags.segment-category.summary

Verbatim segment category applied to every definition created in this run (e.g., --segment-category "Pilot Run" or --segment-category "Phase 1 Cohort"). Overrides all computed segment category values regardless of method, record type, or outcome configuration. Useful for grouping definitions across a bulk run with a single shared, human-readable segment label.

# flags.origin.summary

Origin message appended to auto-generated definition descriptions. Defaults to "Created via the Cuneiform for Salesforce CLI." Pass an empty string to suppress the origin tag.

# spinner.status.failed

failed