Command-Line Interface

The USDA FDC library includes a command-line interface (CLI) that provides quick access to food data without writing any code.

Installation

The CLI is automatically installed when you install the package:

pip install usda-fdc

Basic Usage

The main command is fdc, followed by a subcommand:

fdc [options] <command> [command-options]

Global Options

The following options apply to all commands:

--api-key KEY       FDC API key (can also be set via FDC_API_KEY environment variable)
--format FORMAT     Output format: json, pretty, or text (default: pretty)
--version           Show version and exit
--help              Show help message and exit

Commands

search

Search for foods using keywords:

fdc search "apple" --page-size 10 --page-number 1

Options:

--data-type TYPE    Filter by data type (can be specified multiple times)
--page-size SIZE    Results per page (default: 10)
--page-number NUM   Page number (default: 1)

food

Get detailed information about a specific food:

fdc food 1750340

nutrients

Get nutrient information for a specific food:

fdc nutrients 1750340

list

List foods with pagination:

fdc list --page-size 10 --page-number 1

Options:

--data-type TYPE    Filter by data type (can be specified multiple times)
--page-size SIZE    Results per page (default: 10)
--page-number NUM   Page number (default: 1)

Examples

Search for foods containing “apple”:

fdc search "apple"

Get detailed information about a specific food:

fdc food 1750340

Get nutrient information in JSON format:

fdc nutrients 1750340 --format json

List only branded foods:

fdc list --data-type "Branded"

Using Environment Variables

You can set the API key using an environment variable:

export FDC_API_KEY=your_api_key_here
fdc search "apple"

Or using a .env file in your current directory:

# .env file
FDC_API_KEY=your_api_key_here

# Then run
fdc search "apple"