gokyn

v3.0.0

Published

9 days ago

CLI and library for the Kyndlo platform via MCP

0High
0Medium
0Low

pirumpi

kyndlo mcp cli events

gokyn-cli

A Node.js CLI and library for the Kyndlo platform that wraps MCP server tools. Designed for AI agents and shell-based workflows. Installable via npm, usable as both a CLI and a library.

Installation

# Global install
npm install -g gokyn

# Or run directly with npx (zero-install)
npx gokyn --help

Library Usage

import { MCPClient, listEvents, createEvent, getNextTask } from 'gokyn';

const client = new MCPClient({
  baseURL: 'https://api.kyndlo.com',
  token: process.env.KYNDLO_API_TOKEN!,
});

// List events
const events = await listEvents(client, { limit: 5 });

// Get next task
const task = await getNextTask(client, {
  campaign: 'colorado-2027',
  assign: true,
  assigneeName: 'my-agent',
});

Configuration

| Flag | Env Variable | Description | Default | |------|-------------|-------------|---------| | --token | KYNDLO_API_TOKEN | API token (required) | — | | --base-url | KYNDLO_API_URL | API base URL | https://api.kyndlo.com | | --timeout | — | HTTP timeout in ms | 30000 | | --json | — | Output raw JSON (also disables color) | false | | --no-color | NO_COLOR | Disable ANSI colors | false | | --verbose | — | Verbose output | false | | --version | — | Print version and exit | — |

Quick Start

export KYNDLO_API_TOKEN=kyndlo_...

gokyn whoami
gokyn activity list --limit 5
gokyn event list --json
gokyn task campaigns
gokyn task context --campaign "colorado-2027"

Commands

whoami

Show token info and permissions.

gokyn whoami
gokyn whoami --json

activity list

List activities with pagination and filters.

| Flag | Type | Default | Description | |------|------|---------|-------------| | --page | int | 1 | Page number | | --limit | int | 20 | Items per page | | --search | string | — | Search by title or description | | --category | string | — | Filter by category key | | --difficulty-level | string | — | Filter by difficulty: low, medium, high |

gokyn activity list
gokyn activity list --search "yoga" --category "wellness" --limit 5
gokyn activity list --difficulty-level medium --json

activity get <id>

Get activity details by ID.

gokyn activity get 507f1f77bcf86cd799439011

activity categories

List all activity categories.

gokyn activity categories

event list

List events with pagination and filters.

| Flag | Type | Default | Description | |------|------|---------|-------------| | --page | int | 1 | Page number | | --limit | int | 20 | Items per page | | --search | string | — | Search by title or description | | --is-active | bool | — | Filter by active status | | --is-public | bool | — | Filter by public visibility | | --location-type | string | — | Filter by physical or virtual |

gokyn event list
gokyn event list --search "yoga" --is-active --location-type virtual
gokyn event list --page 2 --limit 10 --json

event get <id>

Get event details by ID.

gokyn event get 507f1f77bcf86cd799439011

event create

Create a new event. Activities, location, and recurrence can be specified via individual flags (recommended) or JSON strings.

Required flags

| Flag | Description | |------|-------------| | --title | Event title | | --description | Event description | | --start-date-time | Start time (ISO 8601) | | --end-date-time | End time (ISO 8601) | | --timezone | IANA timezone, e.g. America/New_York |

Activities (one required)

| Flag | Description | |------|-------------| | --activity ID:ORDER | Repeatable flag, e.g. --activity abc123:1 --activity def456:2 | | --activities JSON | JSON array: [{"activityId":"...","order":0}] |

Location (one required)

| Flag | Description | |------|-------------| | --location-type | physical or virtual | | --location-place | Place name (physical, required) | | --location-address | Street address (physical, required) | | --location-lat | Latitude (physical, required) | | --location-lng | Longitude (physical, required) | | --location-join-url | Join URL (virtual, required) | | --location-provider | zoom, google_meet, teams, custom (virtual, optional) | | --location-access-code | Access code (virtual, optional) | | --location-instructions | Instructions (virtual, optional) | | --location JSON | Full location JSON object (alternative to individual flags) |

Recurrence (optional)

| Flag | Description | |------|-------------| | --recurring | Enable recurrence | | --recurrence-frequency | daily, weekly, monthly (required if recurring) | | --recurrence-interval | Interval between occurrences (default 1) | | --recurrence-days | Comma-separated 0-6 for weekly (0=Sun), e.g. 1,3,5 | | --recurrence-end-date | End date (ISO 8601) | | --recurrence JSON | Full recurrence JSON object (alternative to individual flags) |

Optional flags

| Flag | Type | Default | Description | |------|------|---------|-------------| | --capacity | int | — | Max attendees | | --is-public | bool | true | Publicly visible | | --is-premium-only | bool | false | Premium-only | | --is-active | bool | true | Active status | | --price | float | — | Event price | | --price-currency | string | — | Currency code, e.g. USD | | --booking-url | string | — | External booking URL | | --images | JSON | — | Images JSON array |

Examples

Physical event with individual flags (recommended):

gokyn event create \
  --title "Hollis Garden Visit" \
  --description "Explore the botanical garden" \
  --activity 697b8d609f234bc9e551611d:1 \
  --activity 697b8c719f234bc9e551611b:2 \
  --start-date-time "2026-04-01T15:00:00Z" \
  --end-date-time "2027-04-01T23:00:00Z" \
  --timezone "America/New_York" \
  --location-type physical \
  --location-place "Hollis Garden" \
  --location-address "702 East Orange Street, Lakeland, FL 33801" \
  --location-lat 28.042307 \
  --location-lng -81.950636 \
  --recurring \
  --recurrence-frequency weekly \
  --recurrence-interval 1 \
  --is-public=false \
  --is-premium-only \
  --is-active \
  --booking-url "https://example.com/book"

Virtual event:

gokyn event create \
  --title "Morning Yoga" \
  --description "Start your day with yoga" \
  --activity 507f1f77bcf86cd799439011:0 \
  --start-date-time "2026-04-01T09:00:00Z" \
  --end-date-time "2026-04-01T10:00:00Z" \
  --timezone "America/New_York" \
  --location-type virtual \
  --location-join-url "https://zoom.us/j/123" \
  --location-provider zoom

event update <id>

Update event fields. Supports the same individual flags as create for activities, location, and recurrence. Only provided fields are updated.

gokyn event update 507f1f77bcf86cd799439011 --title "Updated Title"
gokyn event update 507f1f77bcf86cd799439011 --is-active=false

event delete <id>

Soft-delete an event.

gokyn event delete 507f1f77bcf86cd799439011

image upload

Upload an image from a file or base64 data.

| Flag | Type | Default | Description | |------|------|---------|-------------| | --file | string | — | Path to image file (mutually exclusive with --base64) | | --base64 | string | — | Base64-encoded image data (mutually exclusive with --file) | | --mime-type | string | image/png | Image MIME type (auto-detected from file extension) | | --event-id | string | — | Attach to this event ID | | --folder | string | events/images | R2 storage folder |

gokyn image upload --file ./photo.jpg --event-id 507f1f77bcf86cd799439011
gokyn image upload --base64 "iVBORw0KGgo..." --mime-type image/png

image generate

Generate an AI image using the configured provider (set in Kyndlo dashboard AI Settings) and upload to R2.

| Flag | Type | Default | Description | |------|------|---------|-------------| | --prompt | string | — | Image generation prompt (required) | | --event-id | string | — | Attach generated image to this event | | --width | int | 1024 | Image width in pixels | | --height | int | 1024 | Image height in pixels |

gokyn image generate --prompt "A cozy arcade bar with retro games and neon lighting" --event-id 507f1f77bcf86cd799439011
gokyn image generate --prompt "A serene botanical garden with winding paths" --json

task campaigns

List all event creation campaigns with progress stats.

gokyn task campaigns
gokyn task campaigns --json

task context

Get campaign context: current progress, next county to work on, and next task.

| Flag | Type | Required | Description | |------|------|----------|-------------| | --campaign | string | yes | Campaign ID | | --city | string | no | Filter by city |

gokyn task context --campaign "colorado-2027"
gokyn task context --campaign "florida-2027" --json

task summary

Show task progress summary for a campaign, optionally filtered by county or city.

| Flag | Type | Required | Description | |------|------|----------|-------------| | --campaign | string | yes | Campaign ID | | --county | string | no | Filter by county | | --city | string | no | Filter by city |

gokyn task summary --campaign "colorado-2027"
gokyn task summary --campaign "colorado-2027" --county "Denver"

task next

Get next pending task(s). Use --assign to atomically claim the task.

| Flag | Type | Required | Default | Description | |------|------|----------|---------|-------------| | --campaign | string | yes | — | Campaign ID | | --state | string | no | — | Filter by state | | --county | string | no | — | Filter by county | | --city | string | no | — | Filter by city | | --cluster | string | no | — | Filter by cluster | | --priority | string | no | — | Filter by priority: high, medium, low | | --limit | int | no | 1 | Number of tasks to return | | --assign | bool | no | false | Assign the task to yourself | | --name | string | no | — | Name of agent/person claiming the task |

gokyn task next --campaign "colorado-2027"
gokyn task next --campaign "colorado-2027" --priority high --assign --name "my-agent"

task complete <task-id>

Mark a task as completed with the created event ID.

gokyn task complete 69afabcbb9dcf3066a2d519a --event-id 507f1f77bcf86cd799439011

task skip <task-id>

Skip a task with a reason.

gokyn task skip 69afabcbb9dcf3066a2d519a --reason "No suitable venues found"

task release <task-id>

Release an in-progress task back to pending.

gokyn task release 69afabcbb9dcf3066a2d519a

task release-stale

Release all in-progress tasks that have been assigned for longer than N minutes back to pending. Useful for reclaiming tasks from agents that crashed or disconnected.

| Flag | Type | Default | Description | |------|------|---------|-------------| | --minutes | int | 60 | Release tasks assigned more than N minutes ago |

gokyn task release-stale
gokyn task release-stale --minutes 120

task seed

Seed a campaign with tasks for specific counties and clusters.

gokyn task seed --campaign "newyork-2027" --state "New York" \
  --counties "New York,Kings,Queens" \
  --clusters-json '{"intellectual":["History Museums"],"visionary":["Escape Rooms"]}'

task rules

Show event creation rules (markdown format).

gokyn task rules

task states

List US states with registered county data.

gokyn task states

task counties

List counties for a registered state.

gokyn task counties --state "Colorado"

task cities

List cities and their constituent counties for a state.

gokyn task cities --state "Colorado"

task register-state

gokyn task register-state --state "New York" \
  --counties "New York,Kings,Queens,Bronx,Richmond"

validation summary

Show event validation summary stats.

gokyn validation summary
gokyn validation summary --state "Colorado" --county "Denver"

validation next

Get next event validations due for review.

gokyn validation next
gokyn validation next --limit 5 --assign

validation submit <validation-id>

Submit a validation result.

gokyn validation submit 507f1f77bcf86cd799439011 --status valid
gokyn validation submit 507f1f77bcf86cd799439011 --status invalid \
  --issues-json '[{"field":"price","severity":"high","description":"Price changed"}]'

Tips for Agents

Use --json for all commands when parsing output programmatically.
Prefer individual flags over JSON strings for --activity, --location-*, and --recurring/--recurrence-*.
All IDs are MongoDB ObjectId strings (24 hex chars).
Dates use ISO 8601 format (e.g. 2026-04-01T09:00:00Z).
Boolean flags: use --is-public to set true, --is-public=false to set false.
Use gokyn --help or gokyn <command> --help for built-in help.

MCP Tools Reference

| CLI Command | MCP Tool | |-------------|----------| | gokyn whoami | whoami | | gokyn activity list | list-activities | | gokyn activity get | get-activity | | gokyn activity categories | list-activity-categories | | gokyn event list | list-events | | gokyn event get | get-event | | gokyn event create | create-event | | gokyn event update | update-event | | gokyn event delete | delete-event | | gokyn image upload | upload-event-image | | gokyn image generate | generate-event-image | | gokyn task campaigns | list-event-campaigns | | gokyn task context | get-event-task-context | | gokyn task summary | event-task-summary | | gokyn task next | get-next-event-task | | gokyn task complete | complete-event-task | | gokyn task skip | skip-event-task | | gokyn task release | release-event-task | | gokyn task release-stale | release-stale-event-tasks | | gokyn task seed | seed-event-campaign | | gokyn task rules | get-event-creation-rules | | gokyn task states | list-us-states | | gokyn task counties | get-us-counties | | gokyn task cities | list-cities | | gokyn task register-state | register-state-counties | | gokyn validation summary | event-validation-summary | | gokyn validation next | get-next-event-validation | | gokyn validation submit | submit-event-validation |

Architecture

The CLI sends JSON-RPC 2.0 tools/call requests to the POST /mcp endpoint on the Kyndlo API. It reuses the same kyndlo_* Bearer tokens, permissions, and server-side logic.

src/
  cli.ts                CLI entry point (commander setup)
  index.ts              Library exports (public API)
  mcp-client.ts         JSON-RPC 2.0 MCP client (fetch-based)
  utils.ts              writeJSON, exitError, Color class
  render.ts             All human-readable output formatters
  commands/             CLI command registrations
    whoami.ts activity.ts event.ts task.ts validation.ts image.ts
  lib/                  Core library functions (async, typed)
    types.ts whoami.ts activity.ts event.ts task.ts validation.ts image.ts

Publishing to ClawHub

The kyndlo-events skill is published to ClawHub so OpenClaw agents can install and use it. After making changes to skill/kyndlo-events/SKILL.md, publish the updated version:

Setup (one-time)

npm i -g clawhub
clawhub login          # Opens browser for authentication
clawhub whoami         # Verify you're logged in

Publish a new version

Update the version field in skill/kyndlo-events/SKILL.md frontmatter (semver).
Run:

clawhub publish ./skill/kyndlo-events \
  --slug kyndlo-events \
  --name "Kyndlo Events" \
  --version <new-version> \
  --changelog "<description of changes>" \
  --tags latest

Example

clawhub publish ./skill/kyndlo-events \
  --slug kyndlo-events \
  --name "Kyndlo Events" \
  --version 3.1.0 \
  --changelog "Add interactive onboarding flow and batch-aware event creation" \
  --tags latest

Verify

clawhub inspect kyndlo-events   # Check published metadata

Development

npm install       # Install dependencies
npm run build     # Build CLI + library
npm run dev       # Watch mode
npm run typecheck # Type checking
npm test          # Run tests