DOCSEARCHbyAlgolia
Submit Docs

Salesforce CLI

repository·main·Indexed 41 days ago

https://github.com/salesforcecli/cli

The primary command-line interface for interacting with Salesforce platforms, providing tools for managing orgs, deploying code, and automating development workflows. Version 2.152.10 introduces the `sf` executable and specialized commands for Agentforce, including agent activation, Agentforce Data Library (ADL) management, and the generation of agent specs and authoring bundles.

Tokens
92.7K
Snippets
279
Records
303
Agent score
50%

What's inside Salesforce CLI

  1. Configure Apex test levels for deletions

    main

    When deleting components that include Apex, you can specify a --test-level to control how tests are run in the target org.

    Available options for --test-level:

    • NoTestRun: No tests are run. Default for development environments (sandbox, Developer Edition, etc.).
    • RunSpecifiedTests: Runs only the tests specified via the --tests flag. Requires minimum 75% code coverage for each class/trigger in the package.
    • RunLocalTests: Runs all tests in the org except those from installed managed/unlocked packages. Default for production deployments.
    • RunAllTestsInOrg: Runs all tests in the org, including managed packages.
    • RunRelevantTests (Beta): Runs only tests relevant to the files being deployed based on dependency analysis.
    # Example: Running specific tests during a deletion
$ sf project delete source --metadata ApexClass --test-level RunSpecifiedTests --tests TestClass1 TestClass2

  2. How agent specs and authoring bundles relate

    main

    The Salesforce Agent development process follows a hierarchy from high-level intent to low-level implementation:

    1. Agent Spec (YAML): A high-level, human-readable description of what the agent is (role, company, tone). It is used by an LLM to brainstorm a list of topics (capabilities).
    2. Authoring Bundle (Metadata): A technical container that holds the actual logic. It is generated from the Agent Spec.
    3. Agent Script (.agent): The core blueprint inside the Authoring Bundle. It uses the Agent Script language to define exactly how the agent executes tasks. While the Spec provides the 'essence', the Script provides the 'instructions'.

    Note: While you can create an agent directly from a spec using agent create, it is recommended to use the Authoring Bundle workflow because it allows for the use of Agent Scripts, which are more flexible and maintainable.

  3. Handle deployment conflicts and errors

    main

    Control how the CLI handles discrepancies between your local project and the org:

    • --ignore-conflicts (-c): Overwrites changes in the org with local files. Note: This only works in orgs that allow source tracking (e.g., sandboxes). It has no effect on production.
    • --ignore-warnings (-g): Allows the deployment to succeed even if warnings occur (e.g., trying to delete a component that doesn't exist). Useful for CI/CD.
    • --ignore-errors (-r): Skips components with errors and continues with others without rolling back. Warning: Never use this in production as it can leave the org in an inconsistent state.

  4. Manage source tracking in scratch orgs

    main

    The --track-source flag controls whether the scratch org uses source tracking to detect metadata changes between your local project and the org.

    • Enabled (Default): Recommended for most development workflows. It allows the CLI to detect conflicts and track changes automatically.
    • Disabled (--no-track-source): Useful for CI/CD pipelines where you want to deploy metadata or run Apex tests without the performance overhead of polling the SourceMember object or performing file system operations for conflict detection.

  5. Configure session variables in `sf agent preview`

    main

    Use the --context-variables flag to set session variables for an agent preview, mirroring the behavior of the Agentforce Builder UI. You can provide multiple variables using the format Name=Value (comma-separated or multiple flag instances).

    Variable Namespaces:

    1. Linked Context Variables: Use the $Context. prefix (e.g., --context-variables '$Context.MyLinkedVar=foo'). These map to externally-provided fields that the runtime resolves and are accessible via $Context.Name in live actions and topic-routing expressions.
    2. State Variables: Use a bare name (e.g., --context-variables 'MyStateVar=bar'). These seed mutable agent state declared in agentVersion.stateVariables.

    Important Tips:

    • Shell Escaping: Wrap the entire argument in single quotes (e.g., '...') to prevent the shell from attempting to expand the $ character.
    • Verbatim Names: Names are passed to the runtime exactly as provided. A bare name is treated as a state variable; if a live action expects a linked context variable via $Context.Name, a bare name will result in a null value.
    # Example of mixing linked context and state variables
$ sf agent preview --context-variables '$Context.MyLinkedVar=foo,MyStateVar=bar'

  6. How the Salesforce CLI plugin architecture works

    main

    The Salesforce CLI is built on the oclif framework, which uses a plugin-based architecture. This allows the CLI to be extended with specific feature areas without requiring a full CLI rebuild.

    Key Benefits

    • Isolation: Plugin providers (internal teams or external contributors) can maintain their own commands in isolation from other plugins.
    • Extensibility: New features can be added as plugins, which can be either bundled with the CLI installation or installed manually by the user.
    • Previewing: Users can manually install a plugin to preview new features or fixes before they are officially shipped in a standard CLI update.
    • Logic Reuse: Most business logic is encapsulated in standalone NPM libraries. This allows CLI commands to act as lightweight wrappers and enables other tools (like the Salesforce Extension pack for VS Code) to use the same underlying functionality.

  7. Retrieve metadata in Metadata API (ZIP) format

    main

    By default, sf project retrieve start retrieves files in source format. To retrieve them in the Metadata API format (as a ZIP file or a directory of metadata files), use the --target-metadata-dir flag.

    Usage Patterns:

    • Retrieve to a directory: Use --target-metadata-dir <dir> to place the metadata files in a specific folder.
    • Retrieve and unzip: Combine --target-metadata-dir <dir> with --unzip to automatically extract the contents into the target directory.
    • Custom filename: Use --zip-file-name <name> to specify the name of the resulting ZIP file.
    # Retrieve components into a ZIP file in the "output" directory
$ sf project retrieve start --source-dir force-app --target-metadata-dir output

# Retrieve in metadata format and automatically extract into the "output" directory
$ sf project retrieve start --source-dir force-app --target-metadata-dir output --unzip

  8. Manage asynchronous deployment validation

    main

    If you run a validation command with the --async flag, the CLI immediately returns a job ID and gives control of the terminal back to you. This allows you to continue working while the validation runs in the background.

    To manage an asynchronous validation, use the following commands:

    • Check status: sf project deploy report
    • Resume watching output: sf project deploy resume
    # Start an async validation
$ sf project deploy validate --source-dir force-app --async --target-org my-org

# Later, check the status using the job ID
$ sf project deploy report

  9. Deploy specific metadata components

    main

    You can target specific components for deployment using several methods:

    1. By Metadata Type/Name: Use --metadata <type>:<name> or --metadata <type>. Wildcards are supported if quoted.
      • sf project deploy start --metadata ApexClass:MyApexClass
      • sf project deploy start --metadata 'ApexClass:MyApex*'
    2. By Source Directory: Use --source-dir <path> to deploy a file or an entire folder. Note: If using --source-dir, do not use --metadata or --manifest.
      • sf project deploy start --source-dir force-app/main/default/classes
    3. By Manifest: Use --manifest <path> to deploy components listed in a package.xml file.
      • sf project deploy start --manifest path/to/package.xml
    4. By Metadata Directory: Use --metadata-dir <path> for metadata-formatted files (MDAPI format).
      • sf project deploy start --metadata-dir MDAPI
    sf project deploy start --metadata ApexClass:MyApexClass

  12. Develop sf plugins

    main
    To build custom functionality for the Salesforce CLI, refer to the sf Plugin Developer Guide. If you are migrating existing sfdx plugins to the new sf architecture, consult the migration section of the developer guide.