Introducing the sevk CLI

The dashboard and the SDKs cover most of what you do with sevk. The sevk CLI is for the cases where neither fits: sending a one-off email, checking why a domain is not verified, wiring a send into a CI job, or letting an AI agent call sevk as a subprocess.

Why a CLI?

APIs and SDKs are great for building applications, but they require you to write code for every interaction. Sometimes you just want to quickly send a test email, check your domain status, or debug a delivery issue. Opening a browser, navigating to a dashboard, and clicking through forms feels slow when you already have a terminal open.

The CLI bridges that gap. It gives you full access to the sevk platform with a single command. And because it outputs structured JSON when piped, it becomes a building block for automation.

Installation

The CLI ships through a few channels so you can install it the way your machine is set up:

# npm
npm install -g sevk-cli

# bun
bun install -g sevk-cli

# Homebrew
brew install sevk-io/tap/sevk

# Shell script (macOS / Linux)
curl -fsSL https://sevk.io/install.sh | bash

# PowerShell (Windows)
irm https://sevk.io/install.ps1 | iex

After installation, the sevk command is available globally. Run sevk doctor to verify everything is set up correctly.

Authentication

The CLI supports multiple ways to authenticate, designed for both interactive use and automation:

# Interactive login - saves your API key to a local config file
sevk login

# Environment variable - perfect for CI/CD
export SEVK_API_KEY=sevk_xxxxxxxxxxxxx

# Inline flag - one-off commands
sevk --api-key sevk_xxx emails send ...

The resolution order is: flag → environment variable → config file. This means CI/CD pipelines can set SEVK_API_KEY as a secret and never need an interactive login step. You can also manage multiple profiles with --profile for switching between staging and production.

Sending Emails

The core use case. Send transactional emails directly from your terminal:

sevk emails send \
  --from "you@yourdomain.com" \
  --to "hello@example.com" \
  --subject "Hello from sevk" \
  --text "Sent from my terminal."

# Or send HTML
sevk emails send \
  --from "you@yourdomain.com" \
  --to "hello@example.com" \
  --subject "Welcome" \
  --html "<h1>Welcome!</h1><p>Thanks for signing up.</p>"

# Or render sevk Markup and send in one go
sevk emails send \
  --from "you@yourdomain.com" \
  --to "hello@example.com" \
  --subject "Welcome" \
  --markup-file template.sevk

Managing Resources

The CLI mirrors the full sevk API. Anything you can do in the dashboard, you can do from the terminal:

# Domains
sevk domains list
sevk domains create --name yourdomain.com --email you@yourdomain.com
sevk domains verify <domain-id>

# Contacts
sevk contacts list
sevk contacts create --email "user@example.com" --audience-id aud_xxx

# Audiences
sevk audiences list
sevk audiences create --name "Newsletter Subscribers"

# Templates
sevk templates list
sevk templates create --title "Welcome" --content-file welcome.sevk

# Broadcasts
sevk broadcasts list
sevk broadcasts create \
  --name "Monthly Update" \
  --subject "Monthly Update" \
  --audience-id aud_xxx \
  --sender-name "Your Team" \
  --domain-id <domain-id> \
  --body-file newsletter.sevk

sevk Markup in the Terminal

You can render sevk Markup to HTML directly from the CLI. This is useful for previewing templates, generating static HTML files, or piping into other tools:

# Render to stdout
sevk markup render template.sevk

# Render to file
sevk markup render template.sevk -o output.html

# Pipe from stdin
cat template.sevk | sevk markup render

Built for CI/CD

The CLI auto-detects non-interactive environments (piped output, no TTY) and switches to structured JSON output. No flags needed. This makes it trivial to integrate into any CI/CD pipeline:

name: Send deploy notification

on:
  push:
    branches: [main]

jobs:
  notify:
    runs-on: ubuntu-latest
    steps:
      - run: npm install -g sevk-cli

      - run: |
          sevk emails send \
            --from "deploy@yourdomain.com" \
            --to "team@yourdomain.com" \
            --subject "Deploy complete" \
            --text "Commit ${{ github.sha }} deployed."
        env:
          SEVK_API_KEY: ${{ secrets.SEVK_API_KEY }}

Built for AI Agents

The same JSON output mode that makes the CLI great for CI/CD also makes it perfect for AI agents. Any LLM-based agent (Claude, GPT, Cursor, etc.) can call the CLI as a subprocess and parse the structured response:

# Agent sends an email - JSON output is automatic
sevk emails send \
  --from "agent@yourdomain.com" \
  --to "user@example.com" \
  --subject "Your report is ready" \
  --html "<h1>Report</h1><p>Your report is ready.</p>"

# Agent lists contacts and pipes to jq
sevk contacts list | jq '.items[].email'

# Agent checks domain status
sevk domains list | jq '.[] | select(.verified == true) | .domain'

No interactive prompts, no ambiguous output. Just flags in, JSON out. This makes the CLI a reliable tool in any agent's toolbox.

Diagnostics with sevk doctor

Not sure if everything is set up correctly? sevk doctorruns a series of checks and tells you exactly what's working and what's not:

$ sevk doctor

  🩺 sevk Doctor

  ✔ CLI Version: v1.0.0
  ✔ Runtime: Node.js v20.11.0 (linux-x64)
  ✔ API Key: sevk_xxx...xxx (source: environment)
  ✔ API Connection: Connected to https://api.sevk.io
  ✔ Config: /home/user/.config/sevk/config.json

It checks your CLI version, runtime environment, API key configuration, connectivity to the sevk API, and config file status. If anything is wrong, it tells you exactly how to fix it. In JSON mode, it returns a structured object with an ok boolean and a checks array.

Global Options

Every command supports a set of global flags that let you customize behavior on the fly:

• --api-key: Override the API key for a single command
• --profile: Switch between saved profiles (staging, production, etc.)
• --base-url: Point to a custom API endpoint
• --json: Force JSON output even in interactive mode
• --quiet: Suppress all interactive output (implies --json)

What's Next

The CLI is installable now. New commands land alongside new API features, so the terminal stays in sync with the rest of the platform. Bug reports and missing-command requests go in the repo issues or our Discord.

kubilay

just a tech