Design Guidelines

This document outlines the high-level design principles and guidelines for Salesforce CLI. The goal is to help you create a consistent, approachable, opinionated, and human-readable CLI in keeping with our Salesforce Developer Tools Principles.

Interactions with our CLI commands “just make sense.” In time, your understanding of each design pattern will allow you to code new commands without visiting this documentation, and because of the consistent patterns, you'll code with confidence.

We recommend that all plugins follow our core plugin style guidelines. If you want to bundle your plugin with the core Salesforce CLI, then you're required to follow our guidelines. The reason is so our users don't need to learn a new naming system each time they use the commands in a new plugin. This document provides guidance about command and flag names, command structure best practices, and more.

Command Structure

The standard grammatical structure for an sf command is:

<topic> <action> <resource | sub-action> [flags]

Each of these taxonomic elements has its own rules, but in all cases, the most important rule is that the command structure feels consistent. If necessary, break other rules to achieve the goal of consistency.

Examples:

• sf org login web --set-default-dev-hub
• sf apex generate class --name MyClass --output-dir force-app/main/default/classes
• sf project deploy start --metadata ApexClass

General Guidelines

Core Salesforce CLI commands follow these general guidelines; specific naming guidelines for topics, commands, and flags are discussed later.

Be Consistent

• Use the common language around Salesforce software development that we've developed. Using these consistent terms helps lower the bar to software development.
• Use industry-standard terms and concepts, which unify developers everywhere.

Use predictable, human-understandable, and memorable names

• The user shouldn't have to search Reddit to understand what an action or resource is.

Prefer the human

• Commands should be humanly comprehensible. The general user should understand what will happen by reading the command.
• Although it's important to consider the many scripts that use CLI commands, we've chosen to prefer the developer and their work flows first.
• Consider all users and their roles: Salesforce admins or developers, ISV partners, subscribers, or even general DevOps users with no Salesforce experience.

Be descriptive

• Command and flag names should provide insight into their functionality or intent.
• Names should be expressive and identifying, but also concise.
• Avoid names that are non-industry standard, unique, terse, slang, clever, or “cute”.
• Abbreviate only when necessary (unless already industry-standard).