Debug a Command with the –dev-debug Flag

When a Salesforce CLI command fails with an unhelpful error, run it again with the global --dev-debug flag to print detailed trace logs and full stack traces.

--dev-debug is a global flag, so you can add it to any sf command. It’s most useful when you want to:

See a full stack trace instead of a single-line error message.
Diagnose plugin loading or version conflicts. The output lists every installed plugin and where it’s resolved from.
Gather detailed logs to attach to a GitHub issue or provide to Salesforce Customer Support.

Add --dev-debug to the command you’re debugging. This example debugs a config command:

The flag prints verbose TRACE and DEBUG logs to the console. Under the hood, it sets these environment variables for the single command run:

Environment Variable	Value
`DEBUG`	`*` (all namespaces)
`SF_DEBUG`	`1`
`SF_ENV`	`development`
`SF_LOG_LEVEL`	`trace`, unless you already set it

Because --dev-debug sets SF_LOG_LEVEL only when it’s not already set, you can raise the threshold to reduce noise. This example logs at the debug level and above rather than trace:

--dev-debug output is verbose. To show only the log namespaces you care about, add the --debug-filter flag and a pattern. Each log line shows its namespace in parentheses, such as sf:oclif:config.

You must use --debug-filter together with --dev-debug. On its own, --debug-filter returns a Nonexistent flag error.

This example shows only the sf:oclif:config namespace and its children:

The pattern supports standard debug-namespace syntax. Quote the pattern so your shell doesn’t expand the * character.

Pattern	Result
`"sf:oclif:*"`	Every namespace under `sf:oclif`.
`"sf:oclif:config,sf-startup"`	Two namespaces, separated by a comma.
`"sf:,-sf:oclif:"`	Every `sf:` namespace except `sf:oclif`. Prefix a namespace with `-` to exclude it.

Salesforce CLI always writes these logs to a rotating file in the ~/.sf directory, such as ~/.sf/sf-2026-09-25.log, whether or not you use --dev-debug. Use the flag when you want the logs in the console in real time.
By default, --dev-debug logs go to stdout. To send them to stderr instead, and keep stdout clean for --json output, set the SF_LOG_STDERR environment variable to true.
--dev-debug changes only what the command logs, not what it does.