Clodo CLI

A small, read-only Clodo client for personal agents. The command-line app talks to a private Cloudflare Worker relay; the relay owns the Clodo key, verifies webhooks, and persists asynchronous jobs in D1.

The package intentionally does not expose Clodo's outreach or email-sending endpoints.

What it supports

• People, Deep, and Agentic Search
• People Search continuation without duplicate pages
• Email, professional URL, professional profile, and phone enrichment
• Webhook delivery with signed-body verification
• Polling fallback when a webhook is delayed or unavailable
• Per-device login, status, logout, and server-side revocation
• Stable JSON output for Hermes and other agents

Requirements

• Node.js 18 or newer
• pnpm 11
• A Cloudflare account with Workers and D1
• A Clodo API key and webhook signing secret

Effect packages are pinned to 4.0.0-rc.109. The CLI uses effect/unstable/cli and the Effect platform services.

Install the CLI

git clone https://github.com/T3-Content/clodo-cli.git
cd clodo-cli
pnpm install --frozen-lockfile
pnpm build
npm install --global .
clodo --version

To create a portable package instead:

pnpm build
npm pack

Copy the resulting .tgz to another machine and install it with npm install --global <package.tgz>.

Build and test

pnpm install
pnpm check
pnpm test
pnpm build

Run the built CLI without installing it:

node dist/cli/main.js --help

Configure the relay locally

Create the local D1 database and apply its migration:

pnpm db:migrate:local
cp .dev.vars.example .dev.vars

Put development-only values in .dev.vars; the file is ignored by Git. Use long random values for ENROLLMENT_TOKEN and TOKEN_PEPPER.

Start the Worker:

pnpm worker:dev

In another terminal, enroll this machine:

node dist/cli/main.js login --relay http://127.0.0.1:8787
node dist/cli/main.js status --json

login prompts for the relay enrollment token without echoing it. The returned device token is stored at ~/.config/clodo/config.json with mode 0600. Environment variables CLODO_RELAY_URL, CLODO_DEVICE_ID, and CLODO_DEVICE_TOKEN override the file.

Deploy the relay

Deployment is deliberately separate from the build. No Cloudflare resources are created automatically.

1. Authenticate Wrangler and create D1:

   pnpm exec wrangler login
   pnpm exec wrangler d1 create clodo-relay

2. Replace replace-after-wrangler-d1-create in wrangler.jsonc with the returned database ID.

3. In Clodo's API Keys tab, mint a webhook signing secret if the account does not already have one. Copy it immediately. Then add the Worker secrets; Wrangler prompts for each value and does not put it in the repository:

   pnpm exec wrangler secret put CLODO_API_KEY
   pnpm exec wrangler secret put CLODO_WEBHOOK_SECRET
   pnpm exec wrangler secret put ENROLLMENT_TOKEN
   pnpm exec wrangler secret put TOKEN_PEPPER

4. Apply the migration and deploy:

   pnpm db:migrate:remote
   pnpm worker:deploy

5. The relay supplies its own public callback URL with every asynchronous request. The Worker receives events at:

   https://<worker-host>/webhooks/clodo
   

   CLODO_WEBHOOK_SECRET must be the exact raw secret minted by Clodo. There is no separate callback URL to configure in Clodo.

The default server-side job cap is 500 credits. Override it with the non-secret Worker variable MAX_JOB_CREDITS if needed. Jobs expire after seven days; a daily cron removes expired rows.

CLI

clodo login --relay https://<worker-host>
clodo status --json
clodo logout --json

clodo search "developer relations leaders at Acme" \
  --mode people --limit 25 --max-credits 25 --json

clodo search "developer tool marketing leaders in the US" \
  --mode deep --depth standard --max-credits 200 --json

clodo search "find evidence-backed DevRel decision makers at these companies" \
  --mode agentic --target 25 --max-credits 300 --json

clodo continue <completed-people-job-id> \
  --limit 25 --max-credits 25 --json

clodo enrich email --first Ada --last Lovelace --domain example.com --json
clodo enrich url --email ada@example.com --json
clodo enrich profile --url https://www.linkedin.com/in/example --json
clodo enrich phone --url https://www.linkedin.com/in/example --max-credits 50 --json

clodo jobs get <job-id> --wait --json
clodo jobs cancel <agentic-job-id> --json

Search and phone commands wait for completion by default. Add --no-wait to submit a background job and keep its local job_... ID.

Credit guardrails are enforced by the relay:

• People Search: 25–100 credits, matching the requested result limit
• Deep Search: exactly 200 for standard or 400 for extended
• Agentic Search: 300–2,000, also constrained by target count
• Phone enrichment: explicit 50-credit cap
• A global server cap, 500 by default

Hermes skill

The portable skill is in skills/clodo. It only calls the CLI with --json; it never reads credentials or calls Clodo directly.

After installing the CLI on another machine, install the skill from a published raw URL:

hermes skills install https://raw.githubusercontent.com/T3-Content/clodo-cli/main/skills/clodo/SKILL.md \
  --category tools --name clodo --yes

For a local trial, copy skills/clodo into the Hermes skills directory or point your Hermes setup at that folder.

Security model

• The Clodo API key and webhook secret exist only as Worker secrets.
• Device bearer tokens are shown once; D1 stores only a SHA-256 hash salted with TOKEN_PEPPER.
• logout revokes the device remotely before deleting its local token.
• Webhooks are verified against the raw body with HMAC-SHA256 and a five-minute replay window before JSON parsing.
• D1, rather than eventually consistent KV, stores authentication and jobs.

The MVP enrollment token is reusable. Rotate it after onboarding machines if that matters for your threat model; one-time enrollment codes can be added later without changing the CLI's device-token contract.