@peernova/cuneiform-sf

Know what your Salesforce data is actually doing — before you deploy Agentforce, plan a migration, or prioritize data quality.

@peernova/cuneiform-sf is the Salesforce CLI plugin for Cuneiform For Salesforce. It profiles objects, fields, and value usage patterns directly from your org and gives you evidence for decisions that previously required weeks of manual analysis or specialist data-management expertise.

What is Cuneiform

Cuneiform is built around a single discipline: Know Your Customer's Data (KYCD). You can't deploy AI, migrate an org, or prioritize remediation if you don't know what's in there. The CLI surfaces that knowledge in three phases:

| Phase | Question it answers | Commands | | ------------ | -------------------------------- | -------------------------------------------------------------------------------- | | Discover | What's in this org? | cuneiform org details, cuneiform object list, cuneiform object describe | | Profile | What does the data look like? | cuneiform definition create, cuneiform profile | | Operate | How do we manage this over time? | cuneiform definition export/import, cuneiform summary, cuneiform mcp serve |

It's built for Salesforce Admins, Analysts, Architects, and SI consultants who need evidence — population rates, value distributions, usage patterns — not assumptions.

Install

The plugin runs on top of the Salesforce CLI (sf). Install both, plus the SFDMU peer dependency:

# 1. Install the Salesforce CLI (if you don't have it)
npm install -g @salesforce/cli

# 2. Install the Cuneiform plugin
sf plugins install @peernova/cuneiform-sf

# 3. Install SFDMU (required peer dependency for definition import/export)
sf plugins install sfdmu

Verify:

sf cuneiform --help
sf sfdmu --help

SFDMU (sfdmu.com) powers the data-move operations used by definition export and definition import. It is a required peer dependency.

Compatibility

Each CLI release expects a minimum version of the Cuneiform For Salesforce managed package installed in your target org. This package is identified by the Salesforce namespace pnova — if you see pnova__ prefixed objects or fields in your org, Cuneiform is installed. The required version is published in this package's package.json under cuneiform.requiredAppVersion:

{
  "name": "@peernova/cuneiform-sf",
  "cuneiform": {
    "requiredAppVersion": "4.12.0.17"
  }
}

Check what this CLI build expects (no auth, no API calls):

sf cuneiform compatibility check

Verify a specific org meets the minimum:

sf cuneiform compatibility check --target-org my-org

The command exits non-zero when the installed version is older than required or the managed package is not installed — suitable for CI gates that run profiling after a fresh package install.

| State | Exit | Meaning | | --------------------------- | :--: | ------------------------------------------------------------------------------------------------------------------------ | | installed-match | 0 | Installed version equals required (Major.Minor.Patch.Build padded) | | installed-newer | 0 | Installed version is newer than required | | installed-version-unknown | 0 | Cuneiform detected (via pnova namespace) but version not exposed (common in source-pushed scratch orgs) — can't verify | | installed-older | 1 | Installed version is older than required — upgrade the org | | not-installed | 1 | Cuneiform managed package not installed in the org |

Quickstart

A first profile in five commands:

# 1. Authenticate to your target org
sf org login web --alias my-org

# 2. Confirm the user has the permissions Cuneiform needs (configures them if not)
sf cuneiform user details --target-org my-org

# 3. See what's in the org
sf cuneiform org details --target-org my-org
sf cuneiform object list --target-org my-org

# 4. Create a profiling definition for an object you care about (e.g. Account)
sf cuneiform definition create --target-org my-org --sobject Account

# 5. Run the profile and review results
sf cuneiform profile --target-org my-org --definition-key <key-from-step-4>
sf cuneiform summary reprofile --help

Append --help to any command for the full flag reference. All commands support --json for structured output in CI pipelines and scripts.

Commands

All commands are namespaced under the cuneiform topic.

| Command | What it does | | ------------------------------------- | --------------------------------------------------------------------------- | | sf cuneiform compatibility check | Verify CLI ↔ managed-package version compatibility | | sf cuneiform definition create | Create profiling definition(s) | | sf cuneiform definition get | Retrieve profiling definition(s) by key | | sf cuneiform definition list | List all profiling definitions with status | | sf cuneiform definition update | Update definition metadata (name, category, description, …) | | sf cuneiform definition purge | Delete unused definitions | | sf cuneiform definition export | Export definitions to a VCS-friendly format | | sf cuneiform definition import | Import definitions from an exported bundle | | sf cuneiform object list | List objects with record counts, type distribution, and namespace filtering | | sf cuneiform object describe | Retrieve comprehensive object metadata (fields, record types, dependencies) | | sf cuneiform org details | Show org configuration, installation status, namespaces, and limits | | sf cuneiform profile | Execute profiling for one or more definitions | | sf cuneiform profile request list | List profiling requests with status and progress | | sf cuneiform profile request cancel | Cancel in-progress profiling requests | | sf cuneiform profile request delete | Delete terminal profiling requests | | sf cuneiform summary purge | Delete profiling summary records (with dry-run preview) | | sf cuneiform summary stop | Stop in-progress profiling summaries | | sf cuneiform summary reprofile | Re-execute profiling for existing summaries | | sf cuneiform user details | Show user readiness; configure required permissions |

Discovery

Before profiling, deploying Agentforce, or planning a migration, start by understanding what's actually in an object. object describe is the entry point — it answers "what fields exist, how many are custom, and what's the shape of this object today?" — in seconds, with no SOQL and no Setup clicks.

sf cuneiform object describe --target-org my-org --object Case --with-fields

You'll see the total field count, a custom-vs-standard breakdown, and per-field metadata (type, required, unique, referenced object for lookups). It's the natural first stop for an Agentforce readiness check, a data-quality assessment, or scoping a migration.

Narrow the view with follow-up flags as the question gets sharper:

# Just the lookup fields, sorted by referenced object
sf cuneiform object describe --target-org my-org --object Case --with-fields --field-type lookup

# Just the custom Agentforce-tagged fields
sf cuneiform object describe --target-org my-org --object Case --with-fields --field-pattern '__c$'

Issues

Report bugs and request features at https://github.com/PeerNova-Solutions/salesforce-cli/issues.

Contributing

This is a PeerNova-published package. PeerNova engineers — see the in-repo CONTRIBUTING.md and CLAUDE.md for development conventions, branch model, and PR workflow. External contributors should open an issue before starting work so we can coordinate.

License

Proprietary — see LICENSE. Copyright © PeerNova, Inc.