🔌

Segment

Segment Public API tooling — a surface-agnostic core and a thin CLI for inspecting sources, managing destinations, and reading the catalog.

Features • Packages • Quick Start • Authentication • CLI Reference • Development

🌟 Features

• 🔍 Source inspection — list every source in a workspace, or drill into one for its write keys and connected type
• 🔌 Destination management — list, get, create, update, and delete destinations, scriptable end to end
• 📚 Catalog browsing — search destination types and read a type's full settings schema before you wire anything up
• 🌐 Region-aware — talks to either the us or eu Segment Public API host, per call or per config
• 🧩 Zero-dependency core — @kud/segment ships no runtime dependencies at all, built on the global fetch
• 🖇 Instant workspace linking — the CLI consumes the core straight from source in development, no publish step in the loop
• 🤖 Scriptable output — --json on every command for piping into jq or another tool

📦 Packages

This is an npm workspaces monorepo with two published packages:

Package	What it is
@kud/segment	Surface-agnostic core — SegmentClient, config resolution, types. Zero runtime dependencies.
@kud/segment-cli	Thin CLI over the core. Binary name: segment.

🚀 Quick Start

Install the CLI globally:

npm install -g @kud/segment-cli

Set your token (see Authentication for how to get one):

export SEGMENT_API_TOKEN="<your Public API token>"

List the sources in your workspace:

segment sources list

$ segment sources listID NAME SLUG ENABLED WRITE KEY───────── ────────────── ────────────── ─────── ────────────src_9f2k1a Marketing Site marketing-site yes k3f8s2…9d1asrc_7c4m2b Mobile App mobile-app yes p9x1q7…2m3b

🔑 Authentication

Warning

segment needs a Public API token, not the legacy Config API token. The two are separate credentials in different parts of the dashboard, and a Config API token will fail with a 401 or 403 on every call here.

Create one in the Segment dashboard: Settings → Access Management → Tokens → "+Create Token", then select Public API token.

The token is picked up in this order — first one found wins:

Source	Example
--token flag	segment sources list --token tkn_abc123
SEGMENT_API_TOKEN environment variable	export SEGMENT_API_TOKEN="tkn_abc123"
Local config file	segment config set --token tkn_abc123

The region works the same way, via --region or SEGMENT_API_REGION, and accepts us (default) or eu. EU workspaces are served from eu1.api.segmentapis.com; us uses api.segmentapis.com.

segment config set --token tkn_abc123 --region eu

Config lives at $XDG_CONFIG_HOME/segment-cli/config.json, falling back to ~/.config/segment-cli/config.json. Check what's currently resolved (the token is masked):

segment config show

📖 CLI Reference

Every command accepts --json (raw JSON, no formatting), --timeout <ms>, and the auth flags above.

Sources

Command	Description
segment sources list	List all sources in the workspace
segment sources get <sourceId>	Show details for a single source
segment sources destinations <sourceId>	List destinations connected to a source

Destinations

Command	Description
segment destinations list [--source <sourceId>]	List destinations, optionally filtered to one source
segment destinations get <destinationId>	Show details for a single destination
segment destinations create <sourceId> <metadataId> --settings <json>	Connect a new destination to a source
segment destinations update <destinationId>	Update a destination's name, settings, or enabled state
segment destinations delete <destinationId> --yes	Delete a destination

create also takes --name <name> and --disabled. update takes --settings <json>, --name <name>, and one of --enable / --disable.

Warning

destinations delete refuses to run without --yes. Run it without the flag first — it prints the destination's details so you can confirm you're about to delete the right one.

Catalog

Command	Description
segment catalog destinations [--search <term>]	List catalog destination types, optionally filtered
segment catalog destination <metadataId>	Show a destination type's full settings schema

Config

Command	Description
segment config set [--token <t>] [--region <r>]	Write token and/or region to the local config file
segment config show	Print the currently resolved configuration (token masked)

🎯 Worked example: wiring up Amplitude

The everyday reason to reach for this CLI: check whether a source already has Amplitude connected, and if not, connect it.

Check the source's existing destinations:

segment sources destinations src_9f2k1a

Nothing came back for Amplitude, so look up what its destination type needs before creating one — Amplitude's catalog metadataId is 54521fd525e721e32a72ee91:

segment catalog destination 54521fd525e721e32a72ee91

$ segment catalog destination 54521fd525e721e32a72ee91ID: 54521fd525e721e32a72ee91Name: AmplitudeSlug: amplitudeDescription: Amplitude is a product analytics tool...Website: https://amplitude.comStatus: PUBLICCategories: A/B Testing, AnalyticsSettings schema:NAME TYPE REQUIRED DESCRIPTION──────────────── ─────── ──────── ──────────────────────────────apiKey string yes Your Amplitude API KeysecretKey string no Your Amplitude Secret KeytraitsToIncrement array no Traits to increment as Amplitude user properties

apiKey is the only required setting, so create the destination with just that:

segment destinations create src_9f2k1a 54521fd525e721e32a72ee91 --settings '{"apiKey":"YOUR_AMPLITUDE_API_KEY"}'

$ segment destinations create src_9f2k1a 54521fd525e721e32a72ee91 --settings '{"apiKey":"YOUR_AMPLITUDE_API_KEY"}'ID: dst_4k9p2wName: AmplitudeEnabled: yesSource: src_9f2k1aType: Amplitude (amplitude) — 54521fd525e721e32a72ee91Settings:{ "apiKey": "YOUR_AMPLITUDE_API_KEY"}

📦 Using @kud/segment programmatically

The core has no CLI dependency and no runtime dependencies of its own — it's a thin wrapper around fetch, so any Node 22+ ESM project can consume it directly:

import{SegmentClient}from"@kud/segment"constclient=newSegmentClient(process.env.SEGMENT_API_TOKEN!,{region: "us",})constsources=awaitclient.listSources()constdestinations=awaitclient.listSourceDestinations(sources[0].id)constamplitude=destinations.find((d)=>d.metadata.slug==="amplitude")

resolveConfig() and saveConfig() from the same package handle the token/region/config-file resolution the CLI uses — reach for them directly if you're building another surface (an MCP server, a Raycast extension) on top of the core.

🔧 Development

git clone https://github.com/kud/segment.git

cd segment

npm install

Builds, type-checks, and tests run across every workspace from the root:

npm run build

npm run typecheck

npm test

A change to @kud/segment is picked up by the CLI immediately via npm workspace linking — no publish, no version bump, just re-run npm run build (or npm run dev inside packages/segment-cli for a live tsx run).

Script	Description
npm run build	Build every workspace (tsc -p . per package)
npm run typecheck	Type-check every workspace with no emit
npm test	Run every workspace's test suite
npm run changeset	Record a version bump for the next release
npm run version-packages	Apply pending changesets to package versions
npm run release	Build and publish changed packages (used by CI, not by hand)

Releases are independent per package and publish to npm over GitHub Actions OIDC trusted publishing on every push to main — no NPM_TOKEN involved. Record a change with npm run changeset before merging anything that should ship.

🏗 Tech Stack

Category	Technology
Language	TypeScript 5.9
Runtime	Node.js ≥ 22, ESM only
CLI framework	Commander 14
Terminal styling	chalk 5
HTTP	global fetch — no HTTP dependency
Monorepo tooling	npm workspaces
Versioning & release	Changesets, independent per package
CI/CD	GitHub Actions, npm OIDC trusted publishing

---

MIT © kud — Made with ❤️