folk CLI skill

Use this skill when the user wants to work with folk.app CRM data through the first-party folk API and does not want a third-party connector.

Tooling

The CLI command is folkctl. It is designed for OpenClaw-style agent use:

• --json for machine-readable output
• --dry-run before mutations when you need to preview requests
• --all to follow pagination
• --no-input to fail instead of prompting
• --yes or --force only when the user has explicitly confirmed deletion

Never print, log, or include FOLK_API_KEY in responses. Prefer environment variables over stored config in automated environments.

First checks

Run these before doing unfamiliar work:

folkctl --version
folkctl api ls
folkctl api docs people.list
folkctl people --help

When a command is missing or the schema is unclear, use the generic escape hatch:

folkctl api request GET /v1/users/me --json
folkctl api request POST /v1/people --data '{"firstName":"Ada"}' --dry-run --json

Authentication

For OpenClaw, expect FOLK_API_KEY to be set in the environment:

export FOLK_API_KEY="fk_live_..."
folkctl auth status

For local setup:

printf '%s' "$FOLK_API_KEY" | folkctl auth login --token-stdin

Common tasks

List or search people

folkctl people list --limit 20 --json
folkctl people search "Ada Lovelace" --json
folkctl people list --filter fullName:like:Ada --json

Create a person

Preview first:

folkctl people create \
  --first-name Ada \
  --last-name Lovelace \
  --email [email protected] \
  --group-id grp_123 \
  --dry-run --json

Then run without --dry-run once confirmed.

Create or update companies

folkctl companies create --name "Acme Inc" --url https://acme.example --group-id grp_123 --dry-run --json
folkctl companies update com_123 --name "Acme Corporation" --dry-run --json

Discover groups and custom fields

folkctl groups list --json
folkctl groups fields grp_123 person --json
folkctl groups fields grp_123 company --json
folkctl groups fields grp_123 Deals --json

Deals

folk deals are addressed under a group and an object type, usually the name of the deal object field, for example Deals.

folkctl deals list --group-id grp_123 --object-type Deals --json
folkctl deals create --group-id grp_123 --object-type Deals --name "Project Alpha" --company-id com_123 --person-id per_123 --custom Status=Active --dry-run --json

Notes, reminders, and interactions

folkctl notes create --entity-id per_123 --content "Met at SaaStr. Follow up next week." --visibility private --dry-run --json
folkctl reminders create --entity-id per_123 --name "Follow up" --visibility private --recurrence-rule "DTSTART;TZID=Europe/Paris:20250717T090000\
RRULE:FREQ=WEEKLY;INTERVAL=1" --dry-run --json
folkctl interactions create --entity-id per_123 --date-time 2025-07-17T09:00:00.000Z --title "Coffee" --content "Discussed the new project." --type ☕️ --dry-run --json

Webhooks

folkctl webhooks list --json
folkctl webhooks create --name "My app" --target-url https://example.com/webhook --event person.created --dry-run --json

Safety rules

Before create/update/delete commands, prefer --dry-run --json and summarize the exact resource, method, path, and body for the user.

For deletes, do not pass --yes or --force unless the user explicitly asks to delete the exact record. If the user has not confirmed, run a dry-run or ask for confirmation.

If the API returns 401/403, tell the user to verify or rotate FOLK_API_KEY. Do not ask them to paste secrets into chat.

Installation hint

If folkctl is missing, install it from npm (or from GitHub as a fallback):

npm install -g folkctl
# or: npm install -g github:j-edel/folkctl