Clay

Search, manage, and organize your contact network via the Clay CLI.

Security Scan

The skill is coherent with its stated purpose (wrapping the Clay CLI) but has small metadata inconsistencies you should be aware of before installing or trusting its CLI and config file.

Purpose & Capability

The name/description match the runtime instructions: the SKILL.md only instructs using the clay CLI to manage contacts. Requiring the 'clay' binary is appropriate. Minor inconsistency: the registry metadata reported no install spec, but the SKILL.md metadata includes an npm install recommendation (@clayhq/clay-cli). This is plausible but inconsistent between registry fields and the embedded SKILL.md metadata.

Instruction Scope

Instructions are narrowly scoped to running clay CLI commands (search, create, update, list). They instruct interactive OAuth login (clay login) and normal CLI operations. The SKILL.md notes credentials are stored at ~/.config/clay.json — the skill will therefore read/write a per-user config file, which is expected for an OAuth-based CLI.

Install Mechanism

There is no install spec in the registry entry, but the SKILL.md contains an install entry pointing to the npm package @clayhq/clay-cli which would install the 'clay' binary. Installing via a well-known public npm package is a typical mechanism and reasonable, but the mismatch between the registry (no install) and SKILL.md (npm) is worth verifying.

Credentials

The skill declares no required environment variables or primary credential. That aligns with the SKILL.md, which uses OAuth via browser and stores tokens locally. There are no requests for unrelated secrets or system-wide credentials.

Persistence & Privilege

The skill does not request always:true and uses normal autonomous invocation defaults. The only persistent artifact noted is the CLI's credential file (~/.config/clay.json), which is expected for a login-capable CLI and is limited to the user's home config.

Assessment

This skill is essentially documentation for the official Clay CLI. Before installing or using it: (1) confirm you trust the @clayhq/clay-cli npm package (check the package page, publisher, and downloads) if you plan to install it; (2) be aware clay login opens a browser OAuth flow and stores tokens in ~/.config/clay.json — inspect that file and its permissions if you care about token storage; (3) the registry metadata omitted the install spec while SKILL.md includes it — verify which install method your agent will actually run; (4) review the OAuth scopes presented during login so you understand what account data the CLI can access. If you only want to read contact data, consider whether you need to grant full access before proceeding.

Use clay to search, create, update, and manage your personal contact network from the command line.

Requirements

• A Clay account (clay.earth)
• Authenticate before using any commands: clay login

Authentication

Log in (opens browser for OAuth):

clay login

Check authentication status:

clay status

Log out:

clay logout

Credentials are stored in ~/.config/clay.json.

Output Formats

All data commands support --format to control output:

• json (default) — Pretty-printed JSON
• csv — Comma-separated values
• tsv — Tab-separated values

clay contacts:search --name "Alice" --format csv
clay emails:recent --format tsv

Contacts

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 "[e-mail]"
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 "[e-mail]" --phone "[phone]"

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

Notes

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].

Groups

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

Events

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

Emails

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

Reminders

List recent reminders:

clay reminders:recent
clay reminders:recent --limit 5

List upcoming reminders:

clay reminders:upcoming
clay reminders:upcoming --limit 20 --page 2

Search Options Reference

The contacts:search command supports filters for:

• Name: --name
• Work: --work-history-company, --work-history-position, --work-history-active
• Education: --education-history-school, --education-history-degree, --education-history-active
• Location: --location-latitude, --location-longitude, --location-distance
• Age: --age-gte, --age-lte
• Birthday: --upcoming-birthday-gte/lte, --previous-birthday-gte/lte
• Contact info: --information-type (filter by type of info available)
• Interaction dates: --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
• Interaction counts: --email-count-gte/lte, --event-count-gte/lte, --text-message-count-gte/lte
• Notes: --note-content, --note-date-gte/lte
• Groups: --group-ids (group ID or "starred")
• Integration: --integration
• Sorting: --sort-field, --sort-direction
• Pagination: --limit, --exclude-contact-ids
• Fields: --include-fields (select which fields to return)