Export Salesforce Picklists with Dependencies

The Challenge with Dependent Picklists

Picklists are everywhere in Salesforce, and dependent picklists—where the available values in one field depend on the value selected in another—are incredibly useful for maintaining data quality. But when you need to document these relationships, migrate configurations, or audit your picklist setup, you’re stuck clicking through Setup screens and manually recording values.

Try documenting a complex dependent picklist by hand, and you’ll quickly realize there’s got to be a better way. One object might have dozens of picklists, some with hundreds of values, and dependent relationships that need to be mapped precisely.

Why You Need This Tool

I built a Python script that exports all picklist values from any Salesforce object, including the complete dependent picklist mappings. It uses the Salesforce REST API to retrieve field metadata and outputs everything in either JSON or CSV format, ready for documentation, analysis, or migration planning.

Here’s when this tool becomes invaluable:

Configuration Documentation: Create comprehensive documentation of all picklist values and their dependencies for compliance or training purposes.

Sandbox Setup: When configuring a new sandbox, you need to replicate picklist values to match production. Export from prod, review, and use as a reference.

Data Migration Planning: Before migrating data, understand all possible values and dependencies to ensure your data mapping is complete.

Configuration Audits: Quickly identify inactive values, missing dependencies, or picklist configurations that have drifted across environments.

Development Planning: Understand existing picklist structures before proposing changes or building integrations that depend on specific values.

Cross-Org Comparison: Export picklists from multiple orgs to compare configurations and identify discrepancies.

How It Works

The script leverages two powerful tools:

The Salesforce CLI (sf) for authentication—no need to manage OAuth flows or session tokens
The REST API’s describe endpoint to get complete field metadata, including the validFor property that maps dependent picklist relationships

The result is a complete export of picklist configurations without writing a single line of SOQL or clicking through Setup pages.

Installation and Setup

Prerequisites

You need two things installed on your machine:

Python 3.10 or higher: Check with python3 --version
Salesforce CLI (sf): Install from Salesforce CLI Setup Guide

Authentication

Make sure you’re authenticated to the org you want to query:

sf org login web --alias my-org

Or set a default org:

sf config set target-org my-org

The script will use your authenticated session automatically—no need to manage credentials or tokens.

Getting the Script

Download the script from GitHub:

git clone https://github.com/nhelterbrand/sf-picklist-retrieve-with-dependencies.git
cd sf-picklist-retrieve-with-dependencies

No installation step required—just run it with Python.

Usage Examples

Basic Usage: All Picklists on an Object

Export all picklist fields from the Account object:

python3 sf_picklists.py -o Account --pretty

This outputs formatted JSON to your console showing every picklist field, its values, and any dependent relationships.

Single Field Export

Sometimes you just need one field’s configuration:

python3 sf_picklists.py -o Opportunity -f StageName --pretty

Perfect for quickly documenting a specific picklist or verifying its values.

CSV Output for Spreadsheets

Export to CSV for easy sharing with non-technical stakeholders:

python3 sf_picklists.py -o Lead --csv > lead-picklists.csv

Open it in Excel, share it with your team, or use it in data migration documentation.

Include Inactive Values

By default, only active values are exported. To include inactive values (useful for data cleanup projects):

python3 sf_picklists.py -o Case --include-inactive --pretty

Use a Specific Org

If you have multiple authenticated orgs, specify which one to use:

python3 sf_picklists.py -o Account --org my-sandbox --pretty

Save to a File

Write CSV output directly to a file:

python3 sf_picklists.py -o Contact --csv-file /tmp/contact-picklists.csv

Understanding the Output

JSON Format

The JSON output provides a complete programmatic view:

{
  "object": "Opportunity",
  "fieldCount": 3,
  "picklists": [
    {
      "field": "StageName",
      "label": "Stage",
      "type": "picklist",
      "values": ["Prospecting", "Qualification", "Proposal", "Closed Won"],
      "dependentPicklist": false
    },
    {
      "field": "Type",
      "label": "Type",
      "type": "picklist",
      "values": ["New Customer", "Existing Customer"],
      "dependentPicklist": true,
      "controllerField": "StageName",
      "dependencies": {
        "Prospecting": ["New Customer"],
        "Qualification": ["New Customer", "Existing Customer"],
        "Closed Won": ["Existing Customer"]
      }
    }
  ]
}

Each field includes:

Field API name and label
Field type (picklist or multipicklist)
All available values
Whether it’s dependent on another field
Complete dependency mappings

CSV Format

CSV output flattens the data for spreadsheet consumption:

object,field,field_label,field_type,dependent_picklist,controller_field,controller_value,picklist_value,active
Opportunity,StageName,Stage,picklist,False,,,Prospecting,True
Opportunity,StageName,Stage,picklist,False,,,Qualification,True
Opportunity,Type,Type,picklist,True,StageName,Prospecting,New Customer,True
Opportunity,Type,Type,picklist,True,StageName,Qualification,New Customer,True
Opportunity,Type,Type,picklist,True,StageName,Qualification,Existing Customer,True

Each row represents one picklist value, with dependent relationships expanded into separate rows showing the controller value.

Real-World Use Cases

Documentation Before Major Changes

Before restructuring your picklists, export the current state:

python3 sf_picklists.py -o Account --pretty --csv-file account-picklists-before.csv

Make your changes in a sandbox, export again, and compare to ensure nothing was missed.

Training Materials

Export to CSV and format in Excel for training documentation:

python3 sf_picklists.py -o Case --csv-file case-picklists.csv

Share with new team members or include in process documentation.

Integration Development

Before building an integration, understand all possible picklist values:

python3 sf_picklists.py -o Lead -f Status --pretty

Use the output to build proper value mapping in your integration code.

Data Migration Validation

Export picklists from both source and target orgs:

python3 sf_picklists.py -o Account --org source-org --csv-file source-picklists.csv
python3 sf_picklists.py -o Account --org target-org --csv-file target-picklists.csv

Compare the files to identify values that exist in source but not in target, ensuring your migration mapping is complete.

Configuration Drift Detection

Export the same object from production and sandbox:

python3 sf_picklists.py -o Opportunity --org production --csv-file prod-picklists.csv
python3 sf_picklists.py -o Opportunity --org sandbox --csv-file sandbox-picklists.csv

Use diff tools to spot configuration drift before deployment.

Tips for Daily Use

Create Aliases: Add a bash alias for quick access:

alias sf-picklist='python3 ~/path/to/sf_picklists.py'

Standard Naming: Use consistent file naming for exports to make them easy to find later:

python3 sf_picklists.py -o Account --csv-file "Account-picklists-$(date +%Y%m%d).csv"

Version Control: Store picklist exports in version control alongside your Salesforce metadata for historical tracking.

Automate Audits: Schedule regular exports to track when picklist values change over time.

Compare with Git: Store exports in a git repo and use git diff to see what changed between exports.

Documentation Pipeline: Integrate this into your documentation workflow—export, format, and automatically update your wiki or internal docs.

Common Patterns

Full Org Audit:

for obj in Account Contact Lead Opportunity Case; do
  python3 sf_picklists.py -o $obj --csv-file "${obj}-picklists.csv"
done

Quick Validation:

# Check if a value exists
python3 sf_picklists.py -o Lead -f Status --pretty | grep "Qualified"

Dependent Picklist Focus:

# Export and filter for only dependent picklists
python3 sf_picklists.py -o Account --pretty | jq '.picklists[] | select(.dependentPicklist == true)'

Limitations and Notes

API Version: Defaults to v60.0. Use --api-version if you need a different version.

Authentication: You must be authenticated via the SF CLI before running the script. The script will fail with a clear error if you’re not logged in.

ValidFor Data: Some older dependent picklists might not have validFor data exposed in the API. In these cases, the dependency mapping will be empty.

Large Objects: Objects with many picklist fields (think highly customized objects) might take a few seconds to process. This is normal.

Conclusion

Picklist configuration should be visible, documented, and version-controlled—not hidden away in Setup screens. Whether you’re documenting for compliance, planning a migration, or just trying to understand what values are actually being used, having a programmatic way to extract this information is essential.

The script is available on GitHub and works with any Salesforce org you’re authenticated to via the SF CLI. Give it a try the next time you need to document or audit picklist configurations—you’ll wonder how you managed without it.

This post was partially written with assistance from Claude AI to provide additional context and usage examples.