Folk cli

Zero-dependency CLI and OpenClaw skill for the folk.app CRM API built by June Coast

Install

npx -y skills add j-edel/folkctl --skill folk-cli

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

3 stars3 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

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.

The file declares its own license as MIT-0. That is the author’s claim about this one file, and it is not the same thing as the license GitHub reports for the repository, which is listed with the other numbers below.

SKILL.md

4.6 KB, as published. Nobody here has run it

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

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