CLI commands

dia-scripts is an internal yargs CLI wrapping the Salesforce CLI, git, and project tooling. Every command is invoked as node ./scripts/dia-scripts/index.mjs <command…>, almost always through an npm run alias (see npm scripts).

Commands are grouped: apex, ci, deploy, docs, org, plus a set of top-level commands and the internal lint / test dispatchers. A group is itself a command whose subcommands do the work.

deploy / deploy validate and org scratch-create declare their flags for --help and re-parse process.argv in the handler. An unrecognised flag is ignored without warning. deploy rejects an unrecognised positional word with exit code 4.

Top-level commands

Command	Purpose	npm alias
branch-create	Guided branch creation following the naming convention, forked from origin.	branch:create
cherrypick	Cherry-pick ticket commits onto a dedicated deploy branch (never directly onto a protected branch).	git:cherrypick
create-certificate	Generate a self-signed key/cert pair for JWT connected-app auth.	create:certificate
create-new-project [directory]	Clone the DIA template into a new project and run setup.	project:create
delete-flow-versions	Delete all Obsolete Flow versions from the default org.	flows:delete
format	Prettier over Apex/XML/packagejson (--only-changed, --check).	format, format:changed, format:check
install-latest-version	Install the latest package version from sfdx-project.json onto an org (flags below).	install:latest:version
package-version-create	Create a package version and commit the sfdx-project.json bump (flags below).	package:version:create
setup	Verify tool versions, install plugins + deps.	setup
updateMetadataApiVersion	Rewrite metadata <apiVersion> to the project sourceApiVersion.	update:metadata:api:version
update-template-files	Pull the latest template files over the current project.	update:salesforce:template
validate [scripts…]	Run build → format:check → lint → test in series (the CI static gate).	validate
test	Dispatch to test apex and test javascript.	test
lint	Dispatch to lint metadata, lint javascript, lint markdown (lint secrets rules ride along via regex:Recommended).	lint

Packaging command flags

Command	Flags and behaviour
package-version-create	--package-alias / -p (default: PACKAGE_ALIAS, then the packageDirectories entry with "default": true); --package-version / -z (semantic format, e.g. 1.5.5.1; prompts interactively when omitted); --target-dev-hub / -v (default: the configured target-dev-hub); --wait / -w (minutes for sf package version create, default 60).
	Bumps versionName / versionNumber on the matching packageDirectories entry, runs sf package version create (which records the alias under packageAliases), and commits the sfdx-project.json change with a chore: … [skip ci] message. In CI (IS_CI) the commit is also pushed to the current branch over SSH, which needs ci auth-gitbot earlier in the same step; locally the commit stays local.
install-latest-version	--package / -p (required; a packageAliases name); --target-org / -o (default: the configured target-org); --installation-key / -k; --publish-wait / -b (minutes to wait for a just-created version to become installable, default 10). Installs the newest packageAliases entry recorded for the package.
ci tag-version	--package / -p (required; a packageAliases name); --prefix (default v); --dry-run (prints the tag name, creates and pushes nothing). Derives the version from the newest packageAliases entry, creates an annotated tag <prefix><version> at the current commit and pushes it to origin. An existing tag — local or remote — is logged and skipped with exit code 0.

apex group

Command	Purpose	npm alias
apex testsuite convert	Flatten a test suite to a comma-separated class list for mdapi deploys.	apex:testsuite:convert
apex testsuite generate	Build a test suite from @isTest classes under a source dir.	apex:testsuite:generate

ci group

The pipeline's entry points. Each maps to a ci:* npm script.

Command	Purpose
ci audit-node-dependencies	Audit npm dependencies: block on malware advisories only; report CVEs, verify registry signatures, flag lockfile versions younger than 7 days on PRs.
ci auth-devhub	Authenticate to the DevHub from DEVHUB_AUTH_URL (alias devhub, set default).
ci auth-deploy	Authenticate to the stage org from <ENV>_AUTH_URL (env from branch/PR target).
ci auth-gitbot	Configure the Bitbucket bot's SSH identity so CI can push back.
ci dev-start	Run the CI docker image locally for script testing.
ci install-tools	Link the SF CLI plugins found among the devDependencies (--only to narrow).
ci sync	Retrieve selected metadata (e.g. email templates) from an org and commit it.
ci tag-version	Create and push a git tag from the latest package version alias (flags above).
ci teardown	Best-effort delete of the CI scratch org (never fails the build).

ci install-tools links every devDependency whose manifest targets the sf binary; nothing is fetched from the registry. --only takes one plugin name or a comma-separated list and links only those: npm run ci:install:tools -- --only sfdx-git-delta, --only code-analyzer,sfdx-git-delta.

deploy group

deploy is the orchestrator; see delta and quick deploy for what it does.

Command	Purpose	npm alias
deploy	Deploy metadata (quick → delta → full ladder).	deploy
deploy validate	Check-only deploy; publishes the validation id as a build status.	deploy:validate
deploy prepare-destructive-changes	Build destructiveChangesPre/Post.xml from a release folder.	—

deploy / deploy validate flags

Flag	Effect
--target-org / -o	Target org alias or username. Default: the configured default org; with neither, exit code 4.
--test-level, --tests, --test-suite-names	Apex test scope of a full deploy. Defaults: TEST_LEVEL / TESTS / TEST_SUITE_NAMES, then RunLocalTests. --test-level RunSpecifiedTestSuites --test-suite-names <name> is resolved to RunSpecifiedTests with the suite's class list (via apex testsuite convert) before sf is invoked. The delta leg always runs RunRelevantTests.
--source-dir	Source directory(ies) to deploy.
--skip-workarounds	Skips the workaround apply and revert; hook folders and custom steps still run.
--skip-packages-check	Skips remove-installed-packages-from-metadata; installedPackages/* metadata is deployed regardless of the versions already installed.
--skip-hooks	Skips the pre/ and post/ hook-folder deploys and both custom-steps-* modules. Applies to deploy; deploy validate runs none of them in any case.
--forceignore-context	deployment (default) or scratchinit; any other value fails the run. See forceignore contexts.
--no-prompt / -n	No interactive confirmation. Implied in CI and in SFDX_CONTAINER_MODE.
--wait / -w	Minutes to wait for sf (default 30).
--delta	Forces a delta run. Without it, delta is on when a DELTA_DEPLOY_<NAME> variable matches the run.
--delta-from	Base ref of the delta, handed to sfdx-git-delta as a git revision (SHA, tag, or branch name; no shell substitution). Default: the latest release tag on the default branch, else HEAD^. Sets the range only; it does not turn delta on.
--delta-to	Target ref of the delta (default HEAD).
--pre-destructive-changes / --post-destructive-changes / --release-version (-r)	Include the pre/post destructive manifests prepared from deployment-steps/destructive/release-<version>.
--debug / --verbose	Verbose output.

docs group

Command	Purpose	npm alias
docs apex	Generate Apex class docs via the ApexDoc jar.	docs:apex

org group

Scratch orgs and pooling. See scratch org pooling and the pool definition file.

Command	Purpose	npm alias
org scratch-create	Create, reuse, or claim-from-pool a scratch org; apply workarounds; deploy.	create:scratch, org:pool:get
org pool-activate	Deploy the pooling metadata to a DevHub (one-time).	org:pool:activate
org pool-prepare	Top a pool up toward maxAllocation in batches; seed and stamp each org.	org:pool:prepare
org pool-cleanup	Delete pool orgs (by tag, allocated-only, or single id).	org:pool:cleanup
org pool-list	Summarise pools by tag (total/available/allocated/inProgress/expiring).	org:pool:list
org pool-fetch	Claim one available org from the pool.	—
org pool-release	Return a claimed org to the pool.	—

Internal dispatchers

lint and test fan out to children that have no dedicated npm alias (they run via the parent dispatcher, husky hooks, or org scratch-create):

• lint metadata / lint javascript — Salesforce Code Analyzer (sf code-analyzer run).
• lint secrets — Code Analyzer with the regex:Secrets selector only: the credential rules from code-analyzer/code-analyzer.yml. Runs on every staged file in the pre-commit hook (no opt-out key); on a full run it scans the whole workspace. See how to handle a committed secret.
• lint markdown — markdownlint. lint commitmsg — commitlint. lint createbaseline — rebuild the suppression baseline (lint:createbaseline; see how to baseline the code analyzer).
• test apex — sf apex run test. Runs every deployed local test by default; --suite-names / -s <name> runs the named test suite(s) instead. Other flags: --target-org / -o, --wait / -w (default 20), --outputdir / -d (default test-reports/apex), --resultformat / -r (default human), --coverage / -c. A standalone run has no platform-inferred subset (see curated test suites vs RunRelevantTests). test javascript — sfdx-lwc-jest.

Shared library modules

Module	Role
utils/env.mjs	The only module that reads BITBUCKET_* / CI environment variables; exports semantic values (ENVIRONMENT, IS_CI, SF_DEPLOY_TARGET, delta toggles).
utils/log.mjs	Logging helpers (printHeader, info, debug, error detail) and the stream convention: payload to stdout, diagnostics to stderr.
sf-cli.mjs	runSalesforceCommand — the single path for JSON-returning sf calls.
sf-utils.mjs	Higher-level sf helpers (default usernames, manifest generation, auth).
types.mjs / utils.mjs	Small shared primitives and parsing helpers.

Exit behaviour

Situation	Exit code
A group (ci, org, apex, docs) invoked with no matching child	4 (Unknown command: …).
A command throws an error carrying exitCode	That code; otherwise 1. The stack trace is printed only when DEBUG is set.
deploy given an unrecognised positional word	4.

The entry chain (index.mjs → cli/run-script.mjs → command module) is described in the three-layer architecture; the full exit-code table is in the environment variable reference.