Translate a Plain-English ICP Brief into a Clay Search Query via the CLI

Convert a free-text audience description into a valid clay search query-mode query string with a deterministic, rule-based shell script, then run it via the CLI.

What you will build

A bash script that pattern-matches known phrasings (tenure, seniority, role, company size/industry) into a Clay query string, then submits it via clay search query-mode create.

plain-English brief
    ↓
rule-based bash/grep translation (not an LLM call)
    ↓
clay search query-mode create --query '<translated query>'
    ↓
clay search query-mode run <searchId>

AI Prompt

Using the clay CLI, translate a plain-English ICP brief into a Clay
query-mode search string with a deterministic, rule-based script, then run
it.

Requirements:
- Run `clay search query-mode reference` first to ground the query grammar.
- The clay CLI does NOT accept natural language directly -- `clay search
  query-mode create --query` requires an already-structured query string.
  Build the translation with your own rule-based parsing (keyword/regex
  matching over known patterns) -- do not silently call an LLM and call it
  "translation" unless you actually add and disclose that dependency.
- Print the translated query string before submitting it, so the user can
  see exactly what will be sent.
- Run the verification step below before finishing.

Using the clay CLI, translate a plain-English ICP brief into a Clay
query-mode search string with a deterministic, rule-based script, then run
it.

Requirements:
- Run `clay search query-mode reference` first to ground the query grammar.
- The clay CLI does NOT accept natural language directly -- `clay search
  query-mode create --query` requires an already-structured query string.
  Build the translation with your own rule-based parsing (keyword/regex
  matching over known patterns) -- do not silently call an LLM and call it
  "translation" unless you actually add and disclose that dependency.
- Print the translated query string before submitting it, so the user can
  see exactly what will be sent.
- Run the verification step below before finishing.

Prerequisites

The clay CLI on PATH, authenticated
bash (the translator below uses only POSIX-ish shell + grep, no external LLM)

1. Confirm the query grammar

clay search query-mode reference

clay search query-mode reference

This reference document is explicitly described as being for converting natural-language audience descriptions into Clay queries — but the CLI itself still only accepts an already-built query string.

2. Write the rule-based translator

#!/bin/bash
# translate_brief.sh -- deterministic, rule-based translation. Not an LLM call.
BRIEF="$1"
LOWER=$(echo "$BRIEF" | tr '[:upper:]' '[:lower:]')

CLAUSES=()

if echo "$LOWER" | grep -qE "current(ly)?"; then
  CLAUSES+=("is_current = true")
elif echo "$LOWER" | grep -qE "former|used to work"; then
  CLAUSES+=("is_current = false")
fi

for LEVEL in VP Director "C-Level" Manager Senior Head; do
  if echo "$LOWER" | grep -qi "${LEVEL,,}"; then
    SENIORITY="${SENIORITY:+$SENIORITY, }\"$LEVEL\""
  fi
done
[ -n "$SENIORITY" ] && CLAUSES+=("seniority in ($SENIORITY)")

for ROLE in sales engineering marketing product finance; do
  if echo "$LOWER" | grep -qi "$ROLE"; then
    CLAUSES+=("job_title_is_similar_to (\"$ROLE\")")
    break
  fi
done

if echo "$LOWER" | grep -qi "software compan"; then
  CLAUSES+=('company.industry = "Software Development"')
fi

if [[ "$LOWER" =~ ([0-9]+)\ *(or\ more|\+)?
  CLAUSES+=("company.estimated_employee_count >= ${BASH_REMATCH[1]}")
fi

IFS=" and "
QUERY="select from people where experiences.any(${CLAUSES[*]})"
echo "TRANSLATED QUERY: $QUERY"

clay search query-mode create --query "$QUERY"

#!/bin/bash
# translate_brief.sh -- deterministic, rule-based translation. Not an LLM call.
BRIEF="$1"
LOWER=$(echo "$BRIEF" | tr '[:upper:]' '[:lower:]')

CLAUSES=()

if echo "$LOWER" | grep -qE "current(ly)?"; then
  CLAUSES+=("is_current = true")
elif echo "$LOWER" | grep -qE "former|used to work"; then
  CLAUSES+=("is_current = false")
fi

for LEVEL in VP Director "C-Level" Manager Senior Head; do
  if echo "$LOWER" | grep -qi "${LEVEL,,}"; then
    SENIORITY="${SENIORITY:+$SENIORITY, }\"$LEVEL\""
  fi
done
[ -n "$SENIORITY" ] && CLAUSES+=("seniority in ($SENIORITY)")

for ROLE in sales engineering marketing product finance; do
  if echo "$LOWER" | grep -qi "$ROLE"; then
    CLAUSES+=("job_title_is_similar_to (\"$ROLE\")")
    break
  fi
done

if echo "$LOWER" | grep -qi "software compan"; then
  CLAUSES+=('company.industry = "Software Development"')
fi

if [[ "$LOWER" =~ ([0-9]+)\ *(or\ more|\+)?\ *employees ]]; then
  CLAUSES+=("company.estimated_employee_count >= ${BASH_REMATCH[1]}")
fi

IFS=" and "
QUERY="select from people where experiences.any(${CLAUSES[*]})"
echo "TRANSLATED QUERY: $QUERY"

clay search query-mode create --query "$QUERY"

3. Run it

bash translate_brief.sh "Find people with VP or Director level sales titles currently working at software companies with 200 or more employees"

bash translate_brief.sh "Find people with VP or Director level sales titles currently working at software companies with 200 or more employees"

4. Verify the result

This example was tested live with the query it produces (the translator logic above matches the same rule set validated in an earlier session).

clay search query-mode create --query 'select from people where experiences.any(is_current = true and job_title is_similar_to ("sales") and seniority in ("VP", "Director") and company.industry = "Software Development" and company.estimated_employee_count >= 200)'

clay search query-mode create --query 'select from people where experiences.any(is_current = true and job_title is_similar_to ("sales") and seniority in ("VP", "Director") and company.industry = "Software Development" and company.estimated_employee_count >= 200)'

{ "searchId": "search_0tjznb9iKuyQyyqH8Bu", "sourceType": "people" }

{ "searchId": "search_0tjznb9iKuyQyyqH8Bu", "sourceType": "people" }

clay search query-mode run search_0tjznb9iKuyQyyqH8Bu --limit 25

clay search query-mode run search_0tjznb9iKuyQyyqH8Bu --limit 25

Real output: 25 real people matched, hasMore: true. This confirms the translated query string is syntactically valid and returns real matches against the live API.

How it works

The translator is deterministic pattern-matching over known phrasings — it is not a call to an LLM. This keeps the translation auditable: printing the translated query before submission lets you see exactly which rule fired and what will be sent to Clay.

Common issues

Brief produces an empty or overly broad query

Cause: the brief uses phrasing the rule-based parser doesn't recognize.

Fix: extend the keyword lists (SENIORITY, role keywords, industry mapping) with the phrasing you need.

Assuming this calls an LLM

Not a bug, but a scope note: this implementation is intentionally rule-based for auditability and zero added cost. If your use case needs genuinely open-ended natural-language understanding beyond fixed patterns, add an LLM call explicitly and disclose that dependency — this example does not include one.

Next steps

Find companies hiring for a role directly — see the Clay companies-hiring-for-role CLI example
Filter by growth momentum — see the Clay growth-momentum TAM CLI example
Enrich the resulting people — see the Clay contact-waterfall-enrichment CLI example

Verification

verification:
  status: verified
  tested_at: "2026-08-18"
  cli_version: "0.7.0"
  auth_method: "clay login --device"
  command: "clay search query-mode create --query 'select from people where experiences.any(is_current = true and job_title is_similar_to (\"sales\") and seniority in (\"VP\", \"Director\") and company.industry = \"Software Development\" and company.estimated_employee_count >= 200)' && clay search query-mode run search_0tjznb9iKuyQyyqH8Bu --limit 25"
  expected_result: "sourceType=people, 25 real matches returned, hasMore=true"

verification:
  status: verified
  tested_at: "2026-08-18"
  cli_version: "0.7.0"
  auth_method: "clay login --device"
  command: "clay search query-mode create --query 'select from people where experiences.any(is_current = true and job_title is_similar_to (\"sales\") and seniority in (\"VP\", \"Director\") and company.industry = \"Software Development\" and company.estimated_employee_count >= 200)' && clay search query-mode run search_0tjznb9iKuyQyyqH8Bu --limit 25"
  expected_result: "sourceType=people, 25 real matches returned, hasMore=true"