folk CLI

Use the folkctl CLI to inspect and update folk.app CRM data without third-party connectors. Covers people, companies, groups, deals, users, notes, reminders, interactions, and webhooks.

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:

bash

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:

bash

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:

bash

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

For local setup:

bash

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

Common tasks

List or search people

bash

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:

bash

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

Then run without --dry-run once confirmed.

Create or update companies

bash

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

bash

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.

bash

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

bash

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\nRRULE: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

bash

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):

bash

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