https://github.com/sderosiaux/segment-cli
Read-only CLI for Segment.com — inspect sources, destinations, tracking plans, transformations, delivery, audit trail. LLM-actionable.
https://github.com/sderosiaux/segment-cli
analytics bun cli data-governance governance observability segment segment-analytics tracking-plan typescript
Last synced: 5 days ago
JSON representation
Read-only CLI for Segment.com — inspect sources, destinations, tracking plans, transformations, delivery, audit trail. LLM-actionable.
- Host: GitHub
- URL: https://github.com/sderosiaux/segment-cli
- Owner: sderosiaux
- License: mit
- Created: 2026-03-19T18:56:09.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-03-20T02:11:14.000Z (3 months ago)
- Last Synced: 2026-03-20T10:43:11.581Z (3 months ago)
- Topics: analytics, bun, cli, data-governance, governance, observability, segment, segment-analytics, tracking-plan, typescript
- Language: TypeScript
- Size: 148 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# segment-cli
Read-only CLI for [Segment](https://segment.com) Public API. Inspect sources, destinations, tracking plans, transformations, delivery, audit trail, and **tap into live events** from your terminal.
Built for governance, observability, and LLM-actionable output.
## Install
### As a Claude Code skill (recommended)
```bash
npx skills add sderosiaux/segment-cli
```
This gives your AI agent full knowledge of the CLI: commands, flags, workflows, and token-saving patterns.
### CLI binary
Requires [Bun](https://bun.sh).
```bash
git clone https://github.com/sderosiaux/segment-cli.git ~/.local/share/segment-cli
cd ~/.local/share/segment-cli && bun install && bun link
```
Optional: [cloudflared](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/) for `sources tap` (live event stream).
```bash
brew install cloudflared
```
## Setup
Create `~/.config/segment-cli/config` with your Segment Public API token:
```bash
mkdir -p ~/.config/segment-cli
cat > ~/.config/segment-cli/config << 'EOF'
SEGMENT_TOKEN=sgp_...
SEGMENT_REGION=eu
EOF
```
`SEGMENT_REGION` is optional (defaults to `eu`). Use `us` for US workspaces.
Alternatively, use `~/.segmentrc` or export `SEGMENT_TOKEN` as an env var.
Generate a token at [app.segment.com](https://app.segment.com) > Settings > Access Management > Tokens.
## Usage
```
segment overview Workspace health summary
segment sources List all sources
segment sources --all Deep dive (volume, destinations, transforms)
segment sources debug Diagnostic snapshot (events/min, top events)
segment sources tap Live event stream (requires cloudflared)
segment destinations List all destinations
segment destinations --all Deep dive (filters, subscriptions)
segment tracking-plans List tracking plans
segment tracking-plans rules Event schemas (governance)
segment transformations List transformations
segment reverse-etl Reverse ETL models (SQL queries)
segment violations Schema violations summary
segment coverage Tracking plan coverage map
segment volume Event volume (last 7 days)
segment delivery egress --source Delivery metrics
segment audit Audit trail
segment users Workspace users
segment regulations GDPR/deletion requests
segment usage API call counts
segment usage mtu Monthly tracked users
```
Every command supports `--json` for structured output:
```bash
segment tracking-plans rules --json | jq '.[].key'
segment audit --json | jq '[.[] | select(.type == "Violations Detected")]'
segment volume --group-by source --json
```
## Global Flags
| Flag | Purpose |
|---|---|
| `--json` | Structured JSON output for LLM/script consumption |
| `--compact` | Minimal JSON fields (id, name, enabled). Reduces 534KB to 5KB. |
| `--limit N` | Cap results to N items |
| `--resolve` | Enrich IDs with human-readable names |
## Examples
### Live Event Stream (tap)
Stream real events flowing through a source. Creates a temporary webhook destination, tunnels events through cloudflared to your machine, and cleans up on exit.
```
$ segment sources tap
Tapping My App [Prod] ()
Events will appear below. Ctrl+C to stop and cleanup.
4:04:11 PM page app.dashboard.Viewed [1b52f875]
path=/dashboard title=My App url=https://app.example.com/dashboard
4:04:14 PM identify user@example.com [f9957...]
email=user@example.com company={"id":1,"name":"Acme","plan":"enterprise"}
4:04:14 PM track app.feature.Used [f9957...]
feature=export format=csv
4:04:32 PM track app.cluster.Connected [1a1e1...]
provider=aws region=us-east-1
^C
Cleaning up...
Webhook destination deleted.
Total events received: 23
```
How it works:
1. Starts a local HTTP server on port 9876
2. Opens a [cloudflared](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/) tunnel to expose it publicly
3. Creates a temporary Webhooks (Actions) destination on Segment pointing to the tunnel
4. Displays events as they arrive (color-coded by type: track, page, identify)
5. On Ctrl+C: deletes the webhook destination, stops the tunnel
**Crash recovery:** If the CLI dies unexpectedly, a breadcrumb file (`/tmp/segment-cli-tap.json`) records the destination ID. On next run of any command, it auto-cleans the stale destination. You can also run `segment sources tap-cleanup` manually.
### Source Debug (diagnostic snapshot)
```
$ segment sources debug
Debug: My App [Prod]
Period: last 60min (2:51 PM - 3:51 PM)
Total: 6,909 events (~115/min)
By Type:
page 4,474
track 1,890
identify 579
Top Events (15):
1,890 ██████████████████████████████ app.dashboard.Viewed
906 ██████████████░░░░░░░░░░░░░░░░ app.feature.Used
703 ███████████░░░░░░░░░░░░░░░░░░░ app.user.LoggedIn
677 ███████████░░░░░░░░░░░░░░░░░░░ app.cluster.Connected
...
```
### Source Deep Dive
```
$ segment sources --all
Name: My App [Prod]
ID:
Enabled: yes
Type: Javascript
Labels: environment:prod
Volume (7d): 1,523,857 events
Connected Destinations (4):
OFF Mixpanel
ON Google Tag Manager
OFF SatisMeter
Transformations (2):
ON Filter Internal Traffic DROP
ON Don't Send Demo Events to Intercom DROP
```
### Reverse ETL
```
$ segment reverse-etl
Reverse ETL Models (2):
ON MAU per Organization (30d) [organization]
ON Last Active + Cluster Count [email]
$ segment reverse-etl
Name: MAU per Organization (30d)
ID:
Enabled: yes
Source: BigQuery
Identifier: organization
Query:
SELECT organization, COUNT(DISTINCT(user_id)) as MAU
FROM identifies WHERE ...
GROUP BY organization
$ segment reverse-etl subscriptions
Subscriptions for "MAU per Organization (30d)" (1):
ON Upsert Company [upsertCompany]
→ HubSpot Prod
```
### Governance: Violations & Coverage
```
$ segment violations
Violations (43):
By Source:
30 API Backend [Prod]
13 My App [Prod]
Timeline:
Mar 16 at 12:00 PM My App [Prod]
Mar 14 at 12:00 PM API Backend [Prod]
Mar 10 at 12:00 PM My App [Prod]
...
$ segment coverage
Tracking Plan Coverage
Sources: 7 active / 21 total
Covered: 12 sources across 11 plans
My App Tracking Plan (1 sources)
● My App [Prod]
API Events Tracking Plan (2 sources)
● API Backend [Prod]
● API Backend [Dev]
Uncovered Active Sources (1):
○ BigQuery
```
### Workspace Overview
```
$ segment overview
Workspace Overview
Sources: 7 active / 21 total
Destinations: 3 active / 29 total
Tracking Plans: 11
Transformations: 14 active (14 dropping)
Violations: 43 recent on: My App [Prod], API Backend [Prod]
Volume (7d): 3,055,482 events
```
## Commands Reference
| Command | Description |
|---------|-------------|
| `overview` | Workspace health summary |
| `sources [id]` | List or detail (`--all`, `--volume`, `--destinations`, `--transformations`, `--schema`, `--enabled`) |
| `sources debug ` | Diagnostic snapshot: events/min, top events, violations (`--period `) |
| `sources tap ` | Live event stream via temporary webhook (requires `cloudflared`) |
| `sources tap-cleanup` | Manual cleanup of stale tap destination |
| `sources destinations ` | Connected destinations |
| `sources schema-settings ` | Schema validation config |
| `destinations [id]` | List or detail (`--all`, `--filters`, `--subscriptions`, `--enabled`) |
| `destinations filters ` | Destination filters |
| `destinations subscriptions ` | Destination subscriptions |
| `tracking-plans [id]` | List tracking plans or detail |
| `tracking-plans rules ` | Event schemas / governance rules (`--type TRACK`) |
| `tracking-plans sources ` | Connected sources |
| `transformations [id]` | List transformations (`--source `, `--resolve`) |
| `reverse-etl [id]` | List Reverse ETL models or detail (includes SQL query) |
| `reverse-etl subscriptions ` | Destination mappings linked to a Reverse ETL model |
| `violations` | Schema violations summary by source (`--source`, `--limit`) |
| `coverage` | Tracking plan coverage: which sources are covered, which are not |
| `delivery ` | Delivery metrics (egress, filtered-source, etc.) |
| `volume` | Event volume (`--group-by eventName`, `--source `) |
| `audit` | Audit trail (`--type`, `--resource`, `--start`, `--end`) |
| `regulations` | GDPR deletion/suppression requests |
| `suppressions` | Suppressed users |
| `users [id]` | Workspace users |
| `usage` | API call counts per source |
| `usage mtu` | Monthly tracked users |
## Design
- **Read-only** -- no write operations (tap creates/deletes a temporary webhook, self-cleaning)
- **LLM-actionable** -- `--json` on every command for structured output
- **Auto-pagination** -- fetches all pages automatically
- **Retry with backoff** -- handles 429 rate limits and server errors
- **EU + US regions** -- configurable via `SEGMENT_REGION`
## Stack
Bun, TypeScript, Commander.js, Chalk, cloudflared.
## License
MIT