Skip to main content
This guide will walk you through generating your first VCF contact file from Recurse Center profiles.

​
Steps

1

Set up your API token

The tool requires a Recurse Center personal access token to authenticate with the API.Create a .env file in your project directory:
# Create .env file
echo 'RECURSE_PAT=your_token_here' > .env
Or export it as an environment variable:
export RECURSE_PAT=your_token_here
Replace your_token_here with your actual token from recurse.com/settings/api
The tool uses the dotenv crate to automatically load .env files, so creating a .env file is the recommended approach.
2

Run the generator

Execute the tool to fetch profiles and generate the VCF file:
rc-vcf
You’ll see live progress output as the tool works:
🔄 RC VCF Generator

✓ API client initialized (0s)
✓ Batch 1: fetched 50 profiles (2s)
⠙ Processing 12/50: Alice Johnson (downloading photo...) (8s)
3

Watch the progress

The tool provides detailed feedback during execution:
  • API initialization - Confirms connection to Recurse Center API
  • Batch fetching - Shows progress as profiles are retrieved in batches of 50
  • Profile processing - Displays current profile being processed and photo download status
  • Completion summary - Shows total stats when finished
Example complete output:
🔄 RC VCF Generator

✓ API client initialized (1s)
✓ Batch 1: fetched 50 profiles (3s)
⠋ Processing 50/50: Zoe Williams (downloading photo...) (45s)
✓ Batch 2: fetched 50 profiles (47s)
⠋ Processing 100/100: David Chen (downloading photo...) (1m 32s)
✓ Batch 3: fetched 50 profiles (1m 34s)
⠋ Processing 150/150: Maria Garcia (downloading photo...) (2m 18s)
✓ Batch 4: fetched 50 profiles (2m 20s)
⠋ Processing 200/200: James Lee (downloading photo...) (3m 5s)
✓ Batch 5: fetched 47 profiles (3m 7s)
⠋ Processing 247/247: Sarah Brown (downloading photo...) (3m 52s)
✓ Fetched all 247 profiles in 5 batches (3m 54s)
✓ Wrote 247 contacts to recursers.vcf (3m 55s)

📊 Summary
   ├─ Contacts: 247
   ├─ With photos: 189
   ├─ File size: 12.4 MB
   └─ Time: 3m 55s
4

Find your VCF file

The tool creates a file named recursers.vcf in your current directory.
ls -lh recursers.vcf
Output:
-rw-r--r--  1 user  staff    12M Mar  3 14:23 recursers.vcf
File size varies depending on the number of profiles and how many include photos. Expect 10-15 MB for a typical full download.
5

Import into your contacts app

Now import the VCF file into your preferred contacts application:
# Double-click the file, or:
open recursers.vcf

​
What’s Included in Each Contact?

Each vCard in the generated file contains:
  • Full Name - Structured with first name and last name (FN and N fields)
  • Email - Primary email address
  • Phone Number - Normalized to readable format:
    • US numbers: (718) 769-2654
    • International: +44 20 7946 0958
  • Profile Photo - Base64-encoded image embedded directly in the vCard
  • Social Links - GitHub, Twitter, LinkedIn, and personal website URLs
  • Company Info - Organization name and role (if provided)
  • Batch Affiliation - Recurse batches as categories (e.g., “Recurse W2 ‘23”)
  • RC Profile Link - Direct link to their Recurse Center directory page
  • Pronouns - Listed in the notes field
Example vCard structure from the code: 
BEGIN:VCARD
VERSION:3.0
FN:Jane Smith
N:Smith;Jane;;;
item1.EMAIL;TYPE=INTERNET:jane@example.com
item1.X-ABLabel:
item2.TEL:(555) 123-4567
item2.X-ABLabel:mobile
ORG:Example Corp;Software Engineer
TITLE:Software Engineer
item3.URL:https\://jane.dev
item3.X-ABLabel:website
item4.URL:https\://github.com/janesmith
item4.X-ABLabel:GitHub
item5.URL:https\://www.recurse.com/directory/12345-jane-smith
item5.X-ABLabel:Recurse Center
PHOTO;ENCODING=b;TYPE=JPEG:base64encodeddata...
CATEGORIES:Recurser,Recurse W2 '23
NOTE:Pronouns: she/her
UID:recurser-12345
END:VCARD

​
Understanding the Progress Indicators

​
Spinner Animation

The tool uses an animated spinner (⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏) to show active processing. From src/main.rs:46: 
const SPINNER: &[char] = &['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];

​
Status Messages

Each status message shows:
  • Current action (e.g., “Processing 23/50”)
  • Profile name being processed
  • Current phase (e.g., “downloading photo…”)
  • Elapsed time in seconds or minutes

​
Summary Statistics

After completion, you’ll see:
  • Contacts - Total number of profiles processed
  • With photos - How many contacts include embedded photos
  • File size - Size of the generated VCF file in MB
  • Time - Total execution time
From src/main.rs:409-420: 
eprintln!("\n\x1b[1m📊 Summary\x1b[0m");
eprintln!("   \x1b[90m├─\x1b[0m Contacts: \x1b[1m{}\x1b[0m", total_count);
eprintln!("   \x1b[90m├─\x1b[0m With photos: \x1b[1m{}\x1b[0m", photo_count);
eprintln!(
    "   \x1b[90m├─\x1b[0m File size: \x1b[1m{:.1} MB\x1b[0m",
    all_vcards.len() as f64 / 1_000_000.0
);
eprintln!(
    "   \x1b[90m└─\x1b[0m Time: \x1b[1m{}\x1b[0m",
    progress.elapsed()
);

​
Troubleshooting

​
Error: RECURSE_PAT environment variable not set

Make sure you’ve either:
  1. Created a .env file with RECURSE_PAT=your_token
  2. Exported the variable: export RECURSE_PAT=your_token
From src/main.rs:323-325: 
let auth = rc_api::Authentication::Bearer(
    std::env::var("RECURSE_PAT").expect("RECURSE_PAT environment variable not set"),
);

​
Error: Failed to create API client

This usually means:
  • Your token is invalid or expired
  • Network connectivity issues
  • The Recurse Center API is temporarily unavailable
Try:
  1. Verify your token at recurse.com/settings/api
  2. Check your internet connection
  3. Wait a few minutes and retry

​
Slow Performance

The tool downloads profile photos for each contact, which can take time:
  • Expect ~1-2 seconds per profile
  • 250 profiles typically take 3-5 minutes
  • Progress is shown in real-time
If it seems stuck:
  • Check your internet connection speed
  • The spinner should still be animating if the process is active
  • Wait for the timeout or press Ctrl+C to cancel

​
Error: Failed to write VCF data

This means the tool couldn’t create recursers.vcf in the current directory:
  • Check write permissions: ls -la
  • Ensure you have disk space available: df -h .
  • Try running from a different directory

​
Next Steps

API Reference

Learn about the Recurse Center API and available endpoints

Data Types

Deep dive into the vCard 3.0 specification and field structure

Troubleshooting

Get help with common issues and errors

GitHub Repository

View the source code and report issues

​
Tips & Tricks

​
Re-running the Generator

If you run the tool again, it will overwrite the existing recursers.vcf file. This is useful for:
  • Getting updated profile information
  • Adding new Recursers who joined recently
  • Fixing any import issues
Before re-importing, you may want to delete the previously imported contacts from your contacts app to avoid duplicates.

​
Filtering Profiles

The current version fetches all Recurse profiles. Future versions may support filtering by:
  • Specific batches
  • Location
  • Search queries
  • Custom date ranges
See the API reference for available query parameters in ProfileSearchParams (src/rc_api.rs:318-327).

​
Large Imports

For large contact lists (500+ profiles):
  • Some contacts apps may take several minutes to import
  • iOS sometimes processes imports in the background
  • Google Contacts handles large imports well
  • Consider importing to a specific group/label for organization

Build docs developers (and LLMs) love

Get started for freeTalk to us