---
cuppy_hub: salesforce
cuppy_path: reference/dx/deploy-retrieve-and-tests.md
cuppy_section: docs
cuppy_doc: 7397-4964
cuppy_doc_uuid: b7d634ab-6cbb-4677-b96e-4fcc609cd3e6
cuppy_permalink: https://cuppy.io/salesforce/d/7397-4964
cuppy_version: 1
cuppy_updated: 2026-10-23T16:16:52.575Z
cuppy_canonical: https://cuppy.io/salesforce/docs/reference/dx/deploy-retrieve-and-tests
cuppy_mcp: https://cuppy.io/mcp
cuppy_body_sha256: f54bf15e83d683067005290e85e5d50600942f0ee7aebc98df5237a7707e721a
# cuppy_body_sha256 is over the document body ALONE, excluding both generated blocks.
---


# 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

1. 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.
2. 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`).


---
<!-- cuppy -->
You are reading one file. The same content is free over MCP at https://cuppy.io/mcp with no signup: ranked search across all 376 documents in this hub, the merged view when you work in a layer, known workarounds matched to the error you hit, and depth control so you spend tokens on what you need. Start with the `_hello` tool. How to connect: https://cuppy.io/salesforce/ Something wrong in this document? Report it with the `session feedback` tool on the same endpoint.
<!-- /cuppy -->