@kelpi/cli

Official command-line interface for Kelpi.ai - Customer engagement automation platform.

Installation

# npm
npm install -g @kelpi/cli

# pnpm
pnpm add -g @kelpi/cli

# yarn
yarn global add @kelpi/cli

Quick Start

# 1. Initialize with your secret API key
kelpi init

# 2. Add and verify a sending domain
kelpi add-domain example.com --from-email [email protected]
kelpi verify-domain <domain-id> --wait

# 3. Create a contact
kelpi create-contact --email [email protected] --external-id user_123

# 4. Track an event
kelpi track-event user.signed_up --email [email protected]

Example: Building a Welcome Flow

This example walks through creating a complete welcome email sequence that triggers when users sign up.

Step 1: Create Email Templates

Create your email templates first. Templates are reusable and can be referenced across multiple flows.

# Welcome email (sent immediately)
kelpi create-template \
  --slug welcome-email \
  --name "Welcome Email" \
  --subject "Welcome to {{company_name}}!" \
  --body-html "<h1>Welcome, {{first_name}}!</h1><p>Thanks for signing up. We're excited to have you!</p>"

# Follow-up email (sent after 3 days)
kelpi create-template \
  --slug getting-started \
  --name "Getting Started Guide" \
  --subject "Getting started with {{company_name}}" \
  --body-html "<h1>Let's get you set up</h1><p>Here are some tips to get the most out of your account...</p>"

Step 2: Create the Flow Definition

Create a JSON file (welcome-flow.json) that defines your automation:

{
  "name": "Welcome Flow",
  "trigger_type": "event",
  "trigger_event": "user.signed_up",
  "steps": [
    {
      "step_id": "welcome-email",
      "step_order": 0,
      "action_type": "email",
      "template_id": "welcome-email"
    },
    {
      "step_id": "wait-3-days",
      "step_order": 1,
      "action_type": "delay",
      "delay_seconds": 259200
    },
    {
      "step_id": "getting-started",
      "step_order": 2,
      "action_type": "email",
      "template_id": "getting-started"
    }
  ]
}

Step 3: Create and Activate the Flow

# Create the flow
kelpi create-flow --file welcome-flow.json

# Activate it (flows start in draft status)
kelpi activate-flow <flow-id>

Step 4: Test It

# Create a test contact
kelpi create-contact --email [email protected] --properties '{"first_name": "Alex", "company_name": "Acme"}'

# Trigger the flow
kelpi track-event user.signed_up --email [email protected]

Adding Conditions

You can add condition steps to check if a user has performed an action. For example, skip the follow-up email if they've already activated:

{
  "step_id": "check-activated",
  "step_order": 2,
  "action_type": "condition",
  "condition_filter": {
    "type": "group",
    "logic": "AND",
    "conditions": [
      {
        "type": "event",
        "event_name": "user.activated",
        "operator": "has_done",
        "timeframe": { "since": "flow_start" }
      }
    ]
  }
}

Common Delay Values

| Duration | Seconds | |----------|---------| | 1 hour | 3600 | | 1 day | 86400 | | 3 days | 259200 | | 7 days | 604800 |

Authentication

Before using the CLI, initialize it with your secret API key:

kelpi init

You'll be prompted to enter your API key. Alternatively, provide it directly:

kelpi init --api-key klp_sk_your_secret_key

Note: A secret key (klp_sk_*) is required. Public keys (klp_pk_*) cannot be used with the CLI.

Configuration Location

Configuration is stored at ~/.kelpi/config.json.

Commands

kelpi init

Initialize the CLI with your API credentials.

kelpi init [options]

Options:
  --api-key <key>    API key (secret key required)
  -f, --force        Overwrite existing config without confirmation

API Key Management

kelpi api-key create

Create a new API key.

kelpi api-key create [options]

Options:
  -t, --type <type>        Key type: "public" or "secret" (default: "secret")
  -n, --name <name>        Key name
  -s, --scopes <scopes...> Key scopes
  --expires-at <date>      Expiration date (ISO format)
  --json                   Output as JSON

Examples:

# Create a secret key with a name
kelpi api-key create --name "Production Backend" --type secret

# Create a public key for client-side use
kelpi api-key create --name "Web Client" --type public

# Create a key with expiration
kelpi api-key create --name "Temporary" --expires-at 2025-12-31T23:59:59Z

kelpi api-key list

List all API keys.

kelpi api-key list [options]

Options:
  --include-revoked    Include revoked keys
  --json               Output as JSON

kelpi api-key revoke

Revoke an API key.

kelpi api-key revoke <id> [options]

Options:
  -f, --force    Skip confirmation prompt

Domain Management

kelpi add-domain

Add a new domain for sending emails.

kelpi add-domain [domain] [options]

Options:
  --from-email <email>    Default from email address
  --json                  Output as JSON

Example:

kelpi add-domain example.com --from-email [email protected]

After adding a domain, you'll receive DNS records to configure. Add the provided TXT and CNAME records to your DNS provider.

kelpi verify-domain

Verify domain DNS configuration.

kelpi verify-domain <id> [options]

Options:
  --wait                    Wait for verification to complete
  --poll-interval <ms>      Polling interval in milliseconds (default: 5000)
  --max-attempts <n>        Maximum polling attempts (default: 60)
  --json                    Output as JSON

Example:

# Verify immediately
kelpi verify-domain dom_abc123

# Wait for DNS propagation (polls until verified)
kelpi verify-domain dom_abc123 --wait

kelpi list-domains

List all domains.

kelpi list-domains [options]

Options:
  --include-inactive    Include inactive domains
  --json                Output as JSON

Contact Management

kelpi create-contact

Create a new contact.

kelpi create-contact [options]

Options:
  -e, --email <email>          Contact email address
  --external-id <id>           External identifier for the contact
  -p, --properties <json>      Custom properties as JSON
  --json                       Output as JSON

Examples:

# Create contact with email
kelpi create-contact --email [email protected]

# Create contact with external ID
kelpi create-contact --external-id user_123

# Create contact with custom properties
kelpi create-contact --email [email protected] --properties '{"firstName": "John", "plan": "pro"}'

Event Tracking

kelpi track-event

Track an event for a contact.

kelpi track-event <event> [options]

Options:
  --user-id <id>           User ID (external_id)
  -e, --email <email>      Contact email
  -p, --properties <json>  Event properties as JSON
  --json                   Output as JSON

Examples:

# Track a sign-up event
kelpi track-event user.signed_up --email [email protected]

# Track with properties
kelpi track-event page.viewed --user-id user_123 --properties '{"page": "/pricing", "duration": 5000}'

# Track purchase event
kelpi track-event order.completed --email [email protected] --properties '{"orderId": "ord_123", "amount": 99.99}'

Email Templates

kelpi create-template

Create a new email template.

kelpi create-template [options]

Options:
  -s, --slug <slug>          Template slug (unique identifier) [required]
  -n, --name <name>          Template name [required]
  --subject <subject>        Email subject line [required]
  --body-html <html>         Template body HTML (inline)
  --body-file <path>         Path to HTML template file
  -v, --variables <json>     Template variables as JSON array
  --json                     Output as JSON

Examples:

# Create template with inline HTML
kelpi create-template \
  --slug welcome-email \
  --name "Welcome Email" \
  --subject "Welcome to {{company_name}}!" \
  --body-html "<h1>Welcome, {{first_name}}!</h1>"

# Create template from file
kelpi create-template \
  --slug onboarding-day-1 \
  --name "Onboarding Day 1" \
  --subject "Getting started with Kelpi" \
  --body-file ./templates/onboarding-day-1.html

Automation Flows

kelpi create-flow

Create a new automation flow.

kelpi create-flow [options]

Options:
  -n, --name <name>              Flow name
  --trigger-type <type>          Trigger type (event)
  --trigger-event <event>        Event name to trigger the flow
  -f, --file <path>              Path to flow definition JSON file
  --json                         Output as JSON

Examples:

# Create a simple event-triggered flow
kelpi create-flow --name "Welcome Flow" --trigger-type event --trigger-event user.signed_up

# Create flow from definition file
kelpi create-flow --file ./flows/onboarding.json

kelpi activate-flow

Activate a draft flow.

kelpi activate-flow <id> [options]

Options:
  --json    Output as JSON

Output Formats

All commands support --json flag for machine-readable output:

# Human-readable (default)
kelpi api-key list

# JSON output (for scripting)
kelpi api-key list --json

Example JSON output:

kelpi create-contact --email [email protected] --json

{
  "id": "con_abc123",
  "email": "[email protected]",
  "created_at": "2025-01-09T10:30:00Z"
}

Error Handling

The CLI provides helpful error messages:

Error: Invalid email format
  "not-an-email" is not a valid email address
  Hint: Email should be in the format: [email protected]

Common errors:

• Not authenticated: Run kelpi init first
• Invalid API key: Check your key hasn't been revoked
• Contact already exists: A contact with that email/external_id exists

Environment Variables

| Variable | Description | |----------|-------------| | KELPI_API_KEY | Override the configured API key |

Requirements

• Node.js 18.0.0 or later

Getting Help

# General help
kelpi --help

# Command-specific help
kelpi api-key --help
kelpi create-contact --help

License

MIT