Using .env File

The easiest way to configure para-files is with a .env file.

Create .env File

In your para-files project directory:

cat > .env << EOF
PARA_FILES_PARA_ROOT=~/Documents/PARA
PARA_FILES_MLX_SCORE_THRESHOLD=0.75
EOF

Then use para-files normally:

uv run para-files classify file.pdf

# Automatically reads .env file

Common .env Entries

Minimal Setup 

PARA_FILES_PARA_ROOT=~/Documents/PARA

Standard Setup 

# Required
PARA_FILES_PARA_ROOT=~/Documents/PARA

# Optional: customize embedding sensitivity
PARA_FILES_MLX_SCORE_THRESHOLD=0.75

# Optional: reference tree location
PARA_FILES_REFERENCE_TREE_PATH=config/personal_file_tree.yaml

Full Setup (With LLM) 

# Core
PARA_FILES_PARA_ROOT=~/Documents/PARA
PARA_FILES_REFERENCE_TREE_PATH=config/personal_file_tree.yaml

# MLX Embedding Model
PARA_FILES_MLX_MODEL_NAME=mlx-community/nomic-embed-text-v1.5
PARA_FILES_MLX_SCORE_THRESHOLD=0.75

# LLM Fallback (Optional)
PARA_FILES_LLM_ENABLED=true
PARA_FILES_LLM_MODEL=ollama/qwen2.5:1.5b
PARA_FILES_LLM_API_BASE=http://localhost:11434
PARA_FILES_LLM_CONFIDENCE_THRESHOLD=0.6

# Other
PARA_FILES_CONTENT_PREVIEW_CHARS=2000

Expanding Paths

Use ~ for home directory:

# These work fine
PARA_FILES_PARA_ROOT=~/Documents/PARA
PARA_FILES_REFERENCE_TREE_PATH=~/config/tree.yaml

Or absolute paths:

# Also fine
PARA_FILES_PARA_ROOT=/Users/you/Documents/PARA
PARA_FILES_REFERENCE_TREE_PATH=/Users/you/Projects/para-files/config/tree.yaml

Verify Settings Loaded 

# Check that your settings are being used
uv run para-files config --show

# Should show your configured values

.gitignore

If you have secrets or personal paths, ignore .env:

# In .gitignore
.env
.env.local

Troubleshooting

Settings not being used?

# Make sure .env is in the right directory
pwd  # Current directory

# Check if settings are loaded
uv run para-files config --show

# Try absolute path in .env
PARA_FILES_PARA_ROOT=/Users/you/Documents/PARA

Special characters in paths?

# Quote paths with spaces or special characters
PARA_FILES_PARA_ROOT="/Users/My User/Documents/My PARA"