package-version

You are managing package versions for a 2GP (Second-Generation Packaging) or unlocked package project. Use this skill when the project is distributed as a package (typical for ISVs, optional for internal SFDX projects).

Read Project Config First

source "${CLAUDE_PLUGIN_ROOT}/hooks/lib/config.sh"
DEV_HUB="$(sf_config_get '.platform.devHubAlias // \"DevHub\"' "$ENV")"
PACKAGE="$(sf_config_get '.platform.packageName // empty' "$ENV")"

The package name comes from sf-project.json platform.packageName (you may need to add it). Or, if sfdx-project.json defines a packageDirectories[*].package entry, use that.

Input

$ARGUMENTS:

• create [--name <pkg>] — build a new package version (a beta / installable)
• promote <subscriberPackageVersionId> — promote a beta to released (production-installable)
• list — list versions of the configured package
• install <subscriberPackageVersionId> [--target-org <alias>] — install a version into an org
• --installation-key <key> — for create / install; protects beta versions
• --code-coverage — verify code coverage during create (recommended)
• --ci — machine output

Steps

create

1. Verify Dev Hub auth:

   sf_cli_alias_exists "$DEV_HUB" || { echo "..." >&2; exit 2; }

2. Build:

   sf package version create \
     --target-dev-hub "$DEV_HUB" \
     --package "$PACKAGE" \
     ${KEY:+--installation-key "$KEY"} \
     ${CODE_COV:+--code-coverage} \
     --wait 30 \
     --json > /tmp/pkg-create.json

3. Capture the new SubscriberPackageVersionId (04t...) and the PackageVersionId (05i...) from the JSON.
4. Append to ${CLAUDE_PLUGIN_DATA}/argo/packages/<project>/versions.jsonl:

   {"createdAt":"...","subscriberId":"04t...","packageId":"05i...","versionNumber":"1.4.0.NEXT","released":false,"codeCoverage":89.2}

5. Optionally tag the git ref: v1.4.0-beta.NEXT (per sfdx-project.json versionNumber bump rules)
6. Emit installation URL the user can share for QA.

promote <id>

sf package version promote --package "$id" --no-prompt --json

This converts a beta to released. Update versions.jsonl row's released: true. Tag the git ref v1.4.0 (sans -beta).

list

sf package version list --packages "$PACKAGE" --target-dev-hub "$DEV_HUB" --json

Format as a Markdown table: version number, subscriber id, released?, created date, code coverage.

install <id> [--target-org <alias>]

sf package install --target-org "$ORG" --package "$id" ${KEY:+--installation-key "$KEY"} --no-prompt --wait 20 --json

Output

Default Markdown for create:

# Package Version Created

Package:           Acme_Sales_Pkg
Version:           1.4.0-beta.7 (build #7)
Subscriber ID:     04t1b00000XYZ
Code coverage:     89.2% (above 75% required)
Created at:        2026-04-28T14:30:00Z

## Install URL
https://login.salesforce.com/packaging/installPackage.apexp?p0=04t1b00000XYZ

## Next steps
- Test install in a sandbox: /argo:package-version install 04t1b00000XYZ --target-org Sandbox
- Promote to released: /argo:package-version promote 04t1b00000XYZ
- (After release tag git: git tag v1.4.0)

Exit codes

• 0 — succeeded
• 1 — failed (coverage too low, build failure, etc.)
• 2 — invocation error

Rules

• Always require --code-coverage on create. Salesforce demands ≥75% on production package versions. Failing fast in beta is cheaper than failing at promote
• Don't promote without a sandbox install test. The skill prints a reminder; humans approve
• Honor the 4-day quick-deploy window for non-package projects. This skill is for package projects; non-package projects use /diff-deploy + /quick-deploy
• Never delete versions. Salesforce doesn't allow it for released versions; betas can be deprecated but not deleted

Consumers

• ISV release pipeline: create → install in QA sandbox → run E2E → promote → install in pilot orgs
• /release-notes reads the latest released version's versionNumber for the release header