# @peernova/cuneiform-sf

[![NPM Version](https://img.shields.io/npm/v/@peernova/cuneiform-sf.svg?label=@peernova/cuneiform-sf)](https://www.npmjs.com/package/@peernova/cuneiform-sf)
[![Downloads/week](https://img.shields.io/npm/dw/@peernova/cuneiform-sf.svg)](https://www.npmjs.com/package/@peernova/cuneiform-sf)
[![License](https://img.shields.io/badge/License-Proprietary-blue.svg)](https://github.com/PeerNova-Solutions/salesforce-cli/blob/development-ai/LICENSE)

> **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](https://peernova.com). 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:

```bash
# 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:

```bash
sf cuneiform --help
sf sfdmu --help
```

> **SFDMU** ([sfdmu.com](https://help.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`:

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

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

```bash
sf cuneiform compatibility check
```

Verify a specific org meets the minimum:

```bash
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:

```bash
# 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.

```bash
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:

```bash
# 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](./LICENSE). Copyright © PeerNova, Inc.