Search, manage, and organize your contact network via the Clay CLI.
Use clay to search, create, update, and manage your personal contact network from the command line.
clay loginLog in (opens browser for OAuth):
clay login
Check authentication status:
clay status
Log out:
clay logout
Credentials are stored in ~/.config/clay.json.
All data commands support --format to control output:
json (default) — Pretty-printed JSONcsv — Comma-separated valuestsv — Tab-separated valuesclay contacts:search --name "Alice" --format csv
clay emails:recent --format tsv
Get a contact by ID:
clay contact --contact-id 12345
Search contacts:
clay contacts:search --name "Jane Smith"
clay contacts:search --work-history-company "Acme" --work-history-active true
clay contacts:search --education-history-school "MIT"
clay contacts:search --location-latitude 37.7749 --location-longitude -122.4194 --location-distance 50
clay contacts:search --last-email-date-gte "2025-01-01" --sort-field "last_email_date" --sort-direction "desc"
clay contacts:search --group-ids "starred" --limit 10
clay contacts:search --keywords "investor" --include-fields "name,email,title"
Create a contact:
clay contacts:create --first-name "Jane" --last-name "Doe" --email "[email protected]"
clay contacts:create --first-name "Bob" --title "CEO" --organization "Acme Inc" --birthday "1990-05-15"
Update a contact:
clay contacts:update --contact-id 12345 --title "CTO" --organization "NewCo"
clay contacts:update --contact-id 12345 --email "[email protected]" --phone "+1234567890"
Archive / restore contacts:
clay contacts:archive --contact-ids 12345
clay contacts:restore --contact-ids 12345
Merge duplicate contacts:
clay contacts:merge --contact-ids 12345 --contact-ids 67890
List notes in a date range:
clay notes --start "2025-01-01" --end "2025-12-31"
clay notes --contact-ids 12345
Create a note on a contact:
clay notes:create --contact-id 12345 --content "Met at the conference, very interested in partnerships."
clay notes:create --contact-id 12345 --content "Follow up next week" --reminder-date "2026-03-01T09:00:00Z"
Notes support contact references in content: [contact:123:John Doe].
List all groups:
clay groups
clay groups --limit 50
Create a group:
clay groups:create --title "Investors"
Update a group (rename, add/remove members):
clay groups:update --group-id 42 --title "Angel Investors"
clay groups:update --group-id 42 --add-contact-ids 12345 --add-contact-ids 67890
clay groups:update --group-id 42 --remove-contact-ids 11111
List events in a date range:
clay events --start "2025-01-01" --end "2025-03-01"
clay events --contact-ids 12345
List upcoming events:
clay events:upcoming
clay events:upcoming --limit 20 --page 2
List emails in a date range:
clay emails --start "2025-01-01" --end "2025-02-01"
clay emails --contact-ids 12345
List recent emails:
clay emails:recent
clay emails:recent --limit 25 --contact-ids 12345
List recent reminders:
clay reminders:recent
clay reminders:recent --limit 5
List upcoming reminders:
clay reminders:upcoming
clay reminders:upcoming --limit 20 --page 2
The contacts:search command supports filters for:
--name--work-history-company, --work-history-position, --work-history-active--education-history-school, --education-history-degree, --education-history-active--location-latitude, --location-longitude, --location-distance--age-gte, --age-lte--upcoming-birthday-gte/lte, --previous-birthday-gte/lte--information-type (filter by type of info available)--first-email-date-gte/lte, --last-email-date-gte/lte, --first-event-date-gte/lte, --last-event-date-gte/lte, --first-text-message-date-gte/lte, --last-text-message-date-gte/lte, --first-interaction-date-gte/lte, --last-interaction-date-gte/lte--email-count-gte/lte, --event-count-gte/lte, --text-message-count-gte/lte--note-content, --note-date-gte/lte--group-ids (group ID or "starred")--integration--sort-field, --sort-direction--limit, --exclude-contact-ids--include-fields (select which fields to return)