Command-line (kd)

Esta página aún no está disponible en tu idioma.

kd is the Kilden command-line client. Sign in once with your browser, then manage your teams, projects, write keys and identity secrets — and stream events live — without leaving the terminal. It’s open source (kildenhq/kilden-cli, MIT).

Authentication uses the OAuth 2.0 Device Authorization Grant (RFC 8628): no passwords, and nothing is stored beyond the tokens the browser hands back.

Install

macOS / Linux

curl -fsSL https://raw.githubusercontent.com/kildenhq/kilden-cli/main/install.sh | bash

The installer detects your OS and CPU, downloads the latest release, verifies its checksum, and installs kd into ~/.local/bin. If that directory isn’t on your PATH, the installer tells you how to add it.

Pin a version or pick a different install directory with env vars:

curl -fsSL https://raw.githubusercontent.com/kildenhq/kilden-cli/main/install.sh \
  | KILDEN_VERSION=v0.1.0 KILDEN_INSTALL_DIR="$HOME/bin" bash

Windows

Download kd_windows_amd64.zip from the latest release, unzip it, and put kd.exe on your PATH.

With Go

go install github.com/kildenhq/kilden-cli@latest

Prefer typing kilden? Add an alias: alias kilden=kd.

kd login

kd prints a short code and opens your browser. Confirm the code matches, approve, and you’re in. The session is stored under your OS config dir (~/.config/kilden/credentials.json, mode 0600) and refreshes itself.

Self-hosting the panel? Point the CLI at it:

kd login --host https://panel.example.com
# or: export KILDEN_HOST=https://panel.example.com

Sign out with kd logout (forgets the stored credentials on this machine).

Team & project

Most commands act on your active team and project. Inspect and switch them:

kd whoami                      # who am I, and which team/project is active

kd team                        # list your teams (the active one is marked *)
kd team use                    # pick the active team (interactive)
kd team use 42                 # …or by id

kd project                     # list the active team's projects
kd project use <project-id>    # switch the active project
kd project create --name "Web" --timezone America/Santiago

Every data command also takes --project <id> to override the active project for that one call.

Write keys

A project has two kinds of write key: a public key (wk_) for the browser, and a secret key (sk_) for your backend.

kd key                                   # list the active project's keys
kd key create --kind public --label web  # public write key (wk_)
kd key create --kind secret --label ci   # server key (sk_), shown once

A secret key’s full value is shown only once, at creation — store it then.

Identity secrets

For identity verification, a project signs trait tokens with a per-project HS256 secret (is_). You can run several at once and rotate without downtime.

kd identity-secret                    # list secrets: id, kid, active/revoked
kd identity-secret create --kid v1    # mint one under a kid; value shown once
kd identity-secret create             # kid auto-generated if you omit it
kd identity-secret disable <id>       # revoke by id (never deleted)

The kid (key id) identifies a secret so you can rotate: create the next kid, move your backend to it, then disable the old one. Like secret keys, the value is shown only once on creation.

Events

List a project’s most recent events, newest first:

kd events                      # recent events
kd events --event signup       # only a given event name

To see the event names and property keys a project has actually received:

kd properties

Kilden properties are schema-less by design — there’s nothing to “create”. kd properties shows what your events actually carry.

Live tail

Stream events as they arrive, in real time:

kd tail                        # stream live events (Ctrl+C to stop)
kd tail --event signup         # only stream a given event
kd tail --json | jq            # raw JSON per event, one per line

kd tail connects to the live-tail websocket with a short-lived ticket and prints each event as HH:MM:SS event distinct_id. It reconnects on its own as tickets refresh; status lines go to stderr, so --json | jq stays clean.

Config-as-code (insights)

Prefer to keep your funnels and trends in version control — or let an AI agent build them — instead of clicking through the panel? Describe saved insights in a YAML (or JSON) file and apply it:

insights:
  - slug: signup-funnel        # stable identity — how apply finds it again
    type: funnel
    name: Signup funnel
    config:
      steps: ["$pageview", "signup_started", "signup_completed"]
      window_days: 14
  - slug: weekly-active
    type: trend
    name: Weekly active users
    config:
      events: ["$pageview"]
      granularity: week
      metric: uniques

kd apply -f insights.yaml       # create or update; - reads stdin
kd insight ls                   # list managed insights (table, -o yaml, -o json)
kd insight get signup-funnel    # one insight as yaml (or -o json)
kd insight export -o yaml       # dump all as an apply-able spec
kd insight rm weekly-active     # delete by slug

apply is idempotent: each insight is matched by its slug, so re-running the same file updates in place and never creates duplicates. export emits the same slug, so export → apply round-trips. Insights you create in the panel are left untouched — only slugged, CLI-managed ones are.

Applying config needs a token with the config:write scope (reading needs config:read); kd login requests both. Today the surface is saved insights (funnels, trends, retention); dashboards, flags and campaigns are on the way.

How authentication works

kd login asks the panel for a device code and opens the approval page.
You approve in the browser; kd polls until it receives an access + refresh token, then stores them locally.
Later commands call the panel’s management API at /api/v1 with the bearer token, refreshing it transparently when it expires.

The CLI ships a public OAuth client id (a CLI can’t keep a secret). What you can do is enforced server-side against your team membership and role — the same permissions as the panel.