Salesforce DX projects — sfdx-project.json, source vs metadata format, folders and suffixes, .forceignore, manifests, API version precedence, project templates including agent
How a Salesforce DX project is laid out and how the CLI decides what to deploy — the sfdx-project.json the CLI generates (packageDirectories, namespace, sfdcLoginUrl, sourceApiVersion), source format vs metadata (MDAPI) format and converting between them, how folders and file suffixes map to metadata types, .forceignore, generating package.xml, which API version a deploy uses, and the standard and agent project templates.
markdownreferencev13BCQ-VCP5stage: buildtrust: officialservice: dxinterface: clisfdx-project.jsonpackageDirectoriessourceApiVersionsfdcLoginUrlnamespacesource formatmetadata formatMDAPI formatsf project convert sourcesf project convert mdapiforce-app/main/default-meta.xmlmetadata registry folders suffixesdecomposed Bot BotVersionbundle types.forceignorepackage.xml manifestsf project generate manifest--from-orgsf project generate --template agentsf project generate --template standardAPI version precedence--api-version deploysourceApiVersion 67.0 CLI defaultsource-deploy-retrieve
Salesforce DX projects
The project file
sf project generate --name demo --template standard writes this sfdx-project.json (CLI 2.155.7):
{
"packageDirectories": [{ "path": "force-app", "default": true }],
"name": "demo",
"namespace": "",
"sfdcLoginUrl": "https://login.salesforce.com",
"sourceApiVersion": "67.0"
}packageDirectories: where source lives. More than one is allowed; Coral Cloud splits its app intocc-base-app,cc-employee-appandcc-service-app. Exactly one isdefault.sourceApiVersion: the metadata shape your files are written in. The CLI generated 67.0 even though Salesforce's docs list Winter '27 as 68.0: set it deliberately (reference/orgs/orgs-and-editions.md).--template agentcreates an Agentforce DX starter project (guides/agentforce/build-agent-with-agentforce-dx.md). It includes an Agent Script authoring bundle, Apex and flow actions, a prompt template, permission sets and permission set groups, and a scratch definition.
Source format vs metadata format
| Source format (what you commit) | Metadata format (what the Metadata API deploys) | |
|---|---|---|
| Layout | force-app/main/default/<folder>/<Name>.<suffix>-meta.xml, large types split up | One file per component plus package.xml |
| Example | bots/Agent/Agent.bot-meta.xml plus bots/Agent/v1.botVersion-meta.xml | bots/Agent.bot holding every version |
| Convert | sf project convert source --source-dir force-app --output-dir mdapi-out | sf project convert mdapi --root-dir mdapi-out --output-dir force-app |
The CLI maps folders and suffixes to types through Salesforce's metadata registry. Three strategies matter for agents:
| Strategy | Meaning | Examples |
|---|---|---|
| Plain | One <Name>.<suffix>-meta.xml file | genAiPlugins/X.genAiPlugin-meta.xml, genAiPromptTemplates/X.genAiPromptTemplate-meta.xml, flows/X.flow-meta.xml |
| Decomposed | One parent file plus child files in a folder | Bot → bots/<Agent>/<Agent>.bot-meta.xml + v1.botVersion-meta.xml |
| Bundle | A folder that deploys as one component | aiAuthoringBundles/<Agent>/ (<Agent>.agent + <Agent>.bundle-meta.xml); genAiFunctions/<Action>/ (meta file + input/schema.json + output/schema.json); genAiPlannerBundles/<Agent>/ |
| Matching content | Code plus a meta file | classes/X.cls + X.cls-meta.xml |
The full list of Agentforce types: reference/dx/agentforce-metadata-types.md.
Ignoring and listing
.forceignorekeeps files out of deploys and retrieves, with the same syntax as.gitignore. The generated one ignorespackage.xml, LWC config files,**/__tests__/**andnode_modules/.sf project generate manifest --source-dir force-app --name packagewrites apackage.xmlfrom your source.--from-org <alias>lists everything in an org instead.
Which API version a deploy uses
sf project deploy start --api-version <v> overrides the default, which per the CLI's help is "the latest version supported by the CLI". sourceApiVersion says which shape the files are in. The hub's reading: keep sourceApiVersion at or below the target org's maximum, and pass --api-version when an org is a release behind, as sandboxes are during preview windows.