npm package: @kelpi/cli
Description: Kelpi CLI - Command-line interface for Kelpi.ai
Author: Kelpi
Latest version: 0.1.1

# @kelpi/cli

Official command-line interface for [Kelpi.ai](https://kelpi.ai) - Customer engagement automation platform.

## Installation

```bash
# npm
npm install -g @kelpi/cli

# pnpm
pnpm add -g @kelpi/cli

# yarn
yarn global add @kelpi/cli
```

## Quick Start

```bash
# 1. Initialize with your secret API key
kelpi init

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

# 3. Create a contact
kelpi create-contact --email user@example.com --external-id user_123

# 4. Track an event
kelpi track-event user.signed_up --email user@example.com
```

## 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.

```bash
# 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:

```json
{
  "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

```bash
# 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

```bash
# Create a test contact
kelpi create-contact --email test@example.com --properties '{"first_name": "Alex", "company_name": "Acme"}'

# Trigger the flow
kelpi track-event user.signed_up --email test@example.com
```

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

```json
{
  "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:

```bash
kelpi init
```

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

```bash
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.

```bash
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.

```bash
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:**

```bash
# 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.

```bash
kelpi api-key list [options]

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

#### `kelpi api-key revoke`

Revoke an API key.

```bash
kelpi api-key revoke <id> [options]

Options:
  -f, --force    Skip confirmation prompt
```

---

### Domain Management

#### `kelpi add-domain`

Add a new domain for sending emails.

```bash
kelpi add-domain [domain] [options]

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

**Example:**

```bash
kelpi add-domain example.com --from-email noreply@example.com
```

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.

```bash
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:**

```bash
# 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.

```bash
kelpi list-domains [options]

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

---

### Contact Management

#### `kelpi create-contact`

Create a new contact.

```bash
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:**

```bash
# Create contact with email
kelpi create-contact --email user@example.com

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

# Create contact with custom properties
kelpi create-contact --email user@example.com --properties '{"firstName": "John", "plan": "pro"}'
```

---

### Event Tracking

#### `kelpi track-event`

Track an event for a contact.

```bash
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:**

```bash
# Track a sign-up event
kelpi track-event user.signed_up --email user@example.com

# 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 user@example.com --properties '{"orderId": "ord_123", "amount": 99.99}'
```

---

### Email Templates

#### `kelpi create-template`

Create a new email template.

```bash
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:**

```bash
# 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.

```bash
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:**

```bash
# 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.

```bash
kelpi activate-flow <id> [options]

Options:
  --json    Output as JSON
```

---

## Output Formats

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

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

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

**Example JSON output:**

```bash
kelpi create-contact --email user@example.com --json
```

```json
{
  "id": "con_abc123",
  "email": "user@example.com",
  "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: user@domain.com
```

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

```bash
# General help
kelpi --help

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

## License

MIT