Deploying and retrieving metadata

Deploy

Choose components by	Command
Folder or file	`sf project deploy start --source-dir force-app --target-org dev`
Name (wildcards allowed)	`sf project deploy start --metadata ApexClass:OrderActions --metadata "GenAiPlugin:Order_*" --target-org dev`
Manifest	`sf project deploy start --manifest manifest/package.xml --target-org dev`

Use only one of the three per command. Source tracking (scratch orgs and sandboxes that allow it) deploys only what changed:

sf project deploy preview --target-org dev shows what will go, the conflicts, and the ignored files.
--ignore-conflicts overwrites the org's changes. It has no effect on orgs without tracking, such as production.

Other flags:

--ignore-warnings lets a deploy succeed despite warnings. That's useful with destructive changes, where deleting something already gone warns.
--ignore-errors skips failing components instead of rolling back. Never use it on production: the CLI's help warns it can leave the org inconsistent.

Apex tests

`--test-level`	Runs	Default when
`NoTestRun`	Nothing	Dev environments: sandbox, Developer Edition, trial
`RunSpecifiedTests` with `--tests A B`	Only those tests; each class and trigger in the package needs 75% from them	—
`RunLocalTests`	Every test except those from managed and unlocked packages	Production deploys that include Apex
`RunAllTestsInOrg`	Every test, managed packages' too	—
`RunRelevantTests` (beta)	Tests Salesforce picks from the payload and its dependencies, plus classes you annotate to always run; each class and trigger needs 75%	—

Deploying Apex to production needs at least 75% coverage and passing tests. Test classes don't count toward coverage, and comments, blank lines and lone braces aren't counted. Report coverage with --coverage-formatters and --junit, written to --results-dir.

Validate first, then quick deploy

Run the deploy's checks and tests without committing anything: sf project deploy validate --source-dir force-app --test-level RunLocalTests --target-org prod. It returns a job ID; tests are required.
Deploy it: sf project deploy quick --job-id <id> --target-org prod (or --use-most-recent). The job ID is valid for 10 days, and the quick deploy skips the tests already run.

--dry-run on deploy start also validates without saving. Long deploys:

--wait <minutes> returns control and prints the job ID if the deploy is still running;
sf project deploy resume reattaches, and sf project deploy report shows status;
--async returns at once.

Retrieve

sf project retrieve start --source-dir force-app --target-org dev refreshes what you have; --metadata, --manifest and --package-name select more.
Agents: --root-type-with-dependencies Bot (or AiAgentDefinitionVersion) also retrieves everything the agent depends on, such as its planner bundle and topics. Salesforce's help example writes this flag with a single dash, which is a typo.
Agent Script authoring bundles: retrieve with a wildcard (AiAuthoringBundle:My_Agent*) to get every version, not just the draft (guides/agentforce/build-agent-with-agentforce-dx.md).