Entidex CLI
The official command-line interface for Entidex. Resolve any entity, inspect its visibility and sentiment indices, stream live drift events, and feed answer-ready intelligence into your scripts, CI pipelines, and LLM agents — all from your terminal.
Private beta
The Entidex CLI is in private beta — the install methods below show the planned UX, but the packages don't publish until v1. Use the MCP server or REST API today.
Use the API or MCP today
The CLI is in private beta. Every command on this page maps 1:1 to a REST endpoint and an MCP tool — both are live now.
# REST (any shell)
curl -H "Authorization: Bearer $ENTIDEX_API_KEY" \
https://entidex.com/api/v1/entities/resolve?q=spacex
# Hosted MCP server — wire into Claude, ChatGPT, or any MCP client
# https://entidex.com/api/mcp
# Sign up for a free key
# https://entidex.com/developersOr try the keyless preview: /scan — see what AI gets wrong about any brand, no auth needed.
Installation
The Entidex CLI will ship as a single static binary distributed through every channel below. None of the install methods publish until v1 — each card is the planned UX. Use the REST API or hosted MCP server today.
macOS / Linux
Coming soon — private betacurl -fsSL https://entidex.com/install.sh | sh
# pin a version
curl -fsSL https://entidex.com/install.sh | sh -s -- --version v0.1.0Windows (PowerShell)
Coming soon — private betairm https://entidex.com/install.ps1 | iex
# pin a version
$env:ENTIDEX_VERSION = 'v0.1.0'
irm https://entidex.com/install.ps1 | iexHomebrew
Coming soon — private betabrew install entidex/tap/entidexScoop
Coming soon — private betascoop bucket add entidex https://github.com/entidex/scoop-bucket
scoop install entidexnpm (global)
Coming soon — private betanpm install -g @entidex/clipip
Coming soon — private betapip install entidexSupported platforms: macOS (arm64, amd64), Linux (arm64, amd64), Windows (amd64). After install, run entidex doctor to verify everything is wired up.
Authentication
The CLI authenticates with an API key. The recommended way to obtain one is the device flow: it never asks for your password and the key is generated server-side, scoped to your selected tier, and saved with mode 0600.
Device flow
$ entidex login
Open this URL in your browser:
https://entidex.com/cli/auth?code=ABCD-EFGH
Verification code: ABCD-EFGH
Waiting for approval...
✓ Logged in. API key saved to ~/.entidex/config.toml- The CLI requests a device code and prints a short URL plus an 8-character user code.
- Open the URL, sign in to Entidex, confirm the code matches, and pick a tier.
- The CLI polls the token endpoint every 5 seconds. On approval it receives a freshly issued API key and stores it in
~/.entidex/config.toml. - Device codes expire after 15 minutes. The plaintext key is consumed once — subsequent polls return denied.
Environment variable
For CI / containers, set the key at runtime. The env var always wins over the config file.
export ENTIDEX_API_KEY=entx_live_sk_xxxxxxxxxxxxxxxxxxxxxxxx
entidex visibility openaiManage keys
entidex keys list
entidex keys create --name ci --tier layer_2_insight --env live
entidex keys revoke <id> --yesKeys are formatted entx_{live|test}_sk_{24 chars}. The plaintext value is shown exactly once at creation. Rotate by creating a new key and revoking the old one.
Output modes
Output mode resolution, in order of precedence:
--jsonflag — always JSON.ENTIDEX_OUTPUTenv var —auto,pretty, orjson.outputfield in~/.entidex/config.toml.- Auto: pretty when stdout is a TTY, JSON otherwise.
# pretty (interactive shell)
$ entidex lookup spacex
SpaceX (spacex)
type: org
completeness: 92%
visibility: 78.4
# JSON (piped)
$ entidex lookup spacex | jq '.visibility_score'
78.4
# JSON (forced)
$ entidex lookup spacex --jsonErrors always use the stable format [CODE] message — action on stderr, regardless of mode, so scripts and LLM agents can parse them deterministically.
Command reference
Every command supports the global flags --json, --debug, --base-url, --output, --yes, --dry-run, and --idempotency-key. Run entidex <command> --help for the full list.
Read — entities & insights
Resolve an entity (slug, name, or alias) and print its canonical profile.
entidex lookup spacexThe complete, categorized intelligence record in one call — identity, categorization, headline signals, surface coverage, scores, perception, derived insights, drift, lifecycle, relationships, decision survival, and cohort. Free returns a generous taste; higher tiers unlock depth (see meta.withheld).
entidex complete spacexBrowse the categorized entity network — list every category with its entity count, or pass a slug to page through that category’s member entities.
entidex categories technologySearch the discovery layer.
Return only the canonical id/slug — machine-friendly form of lookup.
Creator Resolution: resolve a creator/podcast name — or any one profile link — to the single canonical creator: every cross-verified platform handle with provenance + confidence, headline signals, and the signed-record link. Three-state verdict (confirmed / ambiguous / not_found).
entidex creators-resolve "pbd podcast"AI Visibility Score breakdown across engines + AI Overviews + SERP.
Sentiment (cross-surface) breakdown by surface category.
Narrative Drift and trajectory points across the chosen window.
Time-series snapshots for AI Visibility, Sentiment, Share of Voice, Trust Stack, Narrative Coverage, or Entity Maturity. Default: all dimensions, last 30 days. Powers sparklines and drift narratives.
curl -H "Authorization: Bearer $ENTIDEX_API_KEY" \
"https://entidex.com/api/v1/entities/<entityId>/score-history?dimension=visibility&days=30"Trust Stack composite: confidence-weighted credibility score across all surfaces.
Cross-surface consensus/divergence snapshot. --trends adds the over-time correlation matrix.
Decision Survival Score: how often the entity persists as the AI recommendation across multi-turn conversations.
Lifecycle stage (emergence, breakout, expansion, consolidation, fragmentation, acquisition, rebrand, decline, resurrection) with drivers and predicted next stage.
Unified chronological timeline: score movements, drift events and lifecycle transitions interleaved into one dated stream (most recent first), each with cause attribution.
entidex timeline tesla --days 90Entity Knowledge Statement: verified facts, AI engine corrections, and accuracy score.
Verify specific facts against the Entidex verified record. Returns verified values, sources, and where AI engines diverge.
Grounding Packet: the named, free-tier grounding payload over the verified record — deterministic verified facts with provenance, corrections to common AI claims, and Ed25519-signed provenance. Fetch at the top of any agent or RAG workflow. --format grounding-metadata emits a GroundingMetadata-shaped projection (groundingChunks / groundingSupports).
entidex grounding-packet teslaLLM Knowledge Accuracy: how accurately each AI engine (ChatGPT, Claude, Gemini, Perplexity, Grok) knows the entity vs the verified record — overall accuracy % with a 95% confidence interval, plus a per-engine breakdown and the exact fields each engine gets wrong.
entidex knowledge-accuracy teslaGrounding Check: check a statement about the entity against the signed verified record. Returns coded verdicts — supported | contradicted | unverifiable — with confidence and citations. Granularity differences ("Austin" vs "Austin, Texas") are supported; assertions the record does not cover are unverifiable, never guessed. The guardrail hook for agent pipelines.
entidex grounding-check tesla "Tesla is headquartered in Palo Alto"AI Recommendation Potential: per-prompt-class breakdown of how likely AI engines are to surface and recommend the entity. Shows the strongest and weakest prompt classes with per-engine recommendation rates and 95% Wilson intervals over stored Decision Survival probes.
entidex recommendation-potential teslaGuest Intelligence: per-episode multi-role read for a show or creator — video sentiment, per-cast-member (host / guest / mentioned) sentiment with top praise + top criticism, Claim Truth verdicts tied to each cast entity, low-confidence NER conflation warnings, and a Guest Impact roll-up of which appearances moved AI Visibility. Coded reduction over stored comment / episode / score / claim-truth stores. Zero LLM cost.
entidex guest-intelligence pbd-podcastEpisode → Engine Adoption Lag: for each recent episode a show publishes, how long until each of the five canonical AI engines can name it. Coded text-scan over stored knowledge-probe payloads. Zero LLM cost.
entidex episode-adoption-lag pbd-podcastYouTube Intelligence: channel-authority + audience read for a show/creator — channel stats, a daily sentiment timeline with anomaly flags, per-episode sentiment + comment-intent breakdown, top audience questions, intent distribution, and topic ownership (per-episode + per-guest). Coded read over stored YouTube comment + transcript signal. Zero LLM cost.
entidex youtube-intelligence mr-beastSERP vs AI presence: how the entity performs in traditional search (SEO health, domain rank, organic keywords + traffic, top ranked keywords — from the SEO/GEO audit) compared with how AI engines actually surface it (headline AI Visibility, Share of Voice, per-engine mention breakdown across ChatGPT, Claude, Gemini, Perplexity, Grok, LLM Knowledge Accuracy). Returns a coded gap verdict (aligned | serp_dominant | ai_dominant | both_strong | both_weak) with a plain-English headline and an actionable insight. Zero LLM cost.
entidex serp-vs-ai teslaGoogle AI Answers: what Google AI Overviews and Google AI Mode say about the entity per query class (brand / evaluation / discovery) — the generated-answer text, every citation with source, domain, URL and quoted text, mention + order, sentiment around the mentions, competitor mentions, and whether the entity's own site is cited as a source. Deterministic extraction, zero LLM cost.
entidex google-ai-answers teslaLatest X (social) sentiment: weighted polarity, key voices, praises/complaints, narrative context.
AI Ecosystem read: per-engine fit, grounded mention/recommendation/citation/sentiment, cross-engine coherence, reinforcement patterns, and strategic narrative.
Latest stock-market reading: ticker, exchange, price, % change and provenance — the entity's own listing or that of its public owner/parent. --history returns the stored series.
Entity Core Intelligence Profile: ten authority/readability scores (clarity, authority, trust, topical authority, machine readability, momentum, reputation safety, …) plus topic ownership, entity graph, competitors, perception map, strategic actions, and live-web grounding sources.
entidex core-intelligence spacexDump the full entity profile as JSON.
Live & write
Stream live drift events over Server-Sent Events. Caps at 10 minutes per connection.
entidex watch nvidia | jq .Add an entity to your monitored list.
Show currently tracked entities.
Stop tracking an entity. Confirmation required.
Queue a fresh enrichment run; returns a job id and ETA.
Apply lookup/resolve/refresh/track-add to many entities in parallel.
Submit a correction or quality feedback for an entity. Queued for human review.
Cohort & comparison
List all cohorts you have access to.
Show cohort members and their relative rankings.
Full cohort comparison: AI Visibility, Sentiment, Share of Voice deltas vs median.
Show which cohorts an entity belongs to and its rank in each.
Account & auth
Authenticate via device flow. Prints a short URL + code, polls until you approve in the browser, then writes a fresh API key into your config.
Forget local credentials.
Show current auth state.
Show account profile (email, tier, status).
Show plan, entitlements used vs. limit, and token usage for the current period.
List API keys (id, prefix, tier, env, last-used).
Provision a new API key. The full key is shown once.
Revoke a key. Requires --yes.
Local & meta
Print effective configuration with secrets redacted.
Update base_url, output, telemetry, or api_key.
Read a single config field.
Print the absolute path of the config file.
Show telemetry on/off plus current tier.
Enable anonymous CLI telemetry.
Disable telemetry. Free tier requires telemetry; paid tiers may opt out.
Print the OpenAPI spec for the public API. Useful for seeding LLM agents.
Run self-diagnostics: config path, base URL, API key, reachability.
Quick API reachability + auth check with latency.
Generate shell completion script.
Print version, commit, and build date.
Exit codes
The exit-code contract is stable across versions — scripts and CI pipelines can branch on it directly.
| Code | Name | Meaning |
|---|---|---|
| 0 | OK | Success. |
| 1 | Generic error | Unexpected error — read stderr for the [CODE] line. |
| 2 | Misuse | Bad flags or wrong arguments. Run with --help. |
| 3 | Auth required | No API key, expired key, or insufficient scope. Run entidex login. |
| 4 | Rate-limited | Quota exceeded — slow down or upgrade. |
| 5 | Not resolved | No entity matched the query. |
| 6 | Tier unavailable | Endpoint requires a higher tier — visit https://entidex.com/pricing. |
| 7 | Network error | API unreachable or upstream 5xx. |
| 8 | Config error | Local config file unreadable or invalid. |
Configuration
Configuration lives in ~/.entidex/config.toml (mode 0600). Run entidex config path to print the absolute path on your platform.
# ~/.entidex/config.toml
base_url = "https://entidex.com"
api_key = "entx_live_sk_xxxxxxxxxxxxxxxxxxxxxxxx"
api_key_id = "key_01HXXXXXXXXXXXXXXXXXXXXXXX"
output = "auto" # auto | pretty | json
telemetry = true
machine_id = "f1e2d3c4-...." # opaque, generated once
tier = "layer_2_insight"
email = "you@example.com"Environment overrides
ENTIDEX_API_KEY— overrides the file value.ENTIDEX_BASE_URL— point at staging or self-hosted.ENTIDEX_OUTPUT—auto | pretty | json.ENTIDEX_NO_TELEMETRY=1— disable telemetry for one process (paid tier semantics still apply for persistent disable).ENTIDEX_INSTALL_DIR— installer target directory (install.sh / install.ps1).
LLM agent affordances
The CLI is designed to be driven by autonomous agents as comfortably as by humans. Every output is parseable, every error is structured, and the API surface is self-describing.
entidex schemaemits the full OpenAPI spec — point an agent at this once and it can call every endpoint correctly.--jsonalways works, regardless of whether stdout is a TTY.- Errors use the stable line format
[CODE] message — actionon stderr. The action segment is a short imperative the agent can execute. --idempotency-key <key>on every write — safe to retry on network errors without double-spending quota.--dry-rundescribes the action without executing — useful for planning passes.--yesbypasses confirmation prompts on destructive operations (revoke, remove).- Exit codes 3, 4, 6, 7 are recoverable with specific actions (login, back-off, upgrade, retry). Codes 2, 5, 8 indicate the agent has the wrong inputs.
Telemetry & privacy
Telemetry is anonymous CLI usage data we use to improve the tool — it is required on the free tier (so we can keep the free tier free) and opt-out on every paid tier.
What is sent
A whitelist enforced server-side: command, subcommand, flags, exit_code, latency_ms, entity_type, surfaces, window, output_format, tier, error_code, auth_state, install_source.
What is never sent
Entity values (slugs, names, ids), IP addresses, API keys, file paths, command output, free-text query strings. The only stable identifier is an opaque machine_id generated once on first run, used solely for rate-limiting (60 events/minute).
entidex telemetry status # show current state
entidex telemetry disable # paid tiers only
ENTIDEX_NO_TELEMETRY=1 entidex lookup spacex # one-shot disableTier matrix
Each tier unlocks a set of CLI commands. Tiers are additive — higher tiers include everything below.
| Tier | Intent | Read commands | Write commands |
|---|---|---|---|
| free | Discovery & integration | lookup, complete, categories, search, resolve, schema, doctor, status | login / keys / config |
| layer_1_profile | Full profile access | + export, consensus, lifecycle, knowledge, verify, score-history, track * | + track / refresh / feedback |
| layer_2_insight | Visibility, sentiment & drift | + visibility, sentiment, drift, trust-stack, decision-survival, x-sentiment, bulk | + bulk |
| layer_3_drift | Live streaming | + watch (SSE) | — |
| layer_4_cohort | Cohort & comparative | + cohort list/show/compare/position | — |
When a command requires a higher tier, the CLI exits with code 6 and prints [TIER_REQUIRED] … — upgrade at https://entidex.com/pricing.
Troubleshooting
[AUTH_REQUIRED] on every call
Run entidex doctor. If the api key line shows not set, run entidex login or export ENTIDEX_API_KEY. If the key is set but you still see auth errors, the key may have been revoked — list with entidex keys list and create a new one.
watch disconnects every 10 minutes
By design — server-side cap to keep streaming connections fair. Wrap in a small loop with back-off, or use entidex drift on a cron.
Postinstall failed for npm / pip
The Node and Python packages are thin wrappers around the native binary. If the postinstall download fails (corporate proxy, offline CI), install via install.sh / install.ps1 and the wrapper will detect the binary on PATH.
Pretty output renders as raw escape codes
Your terminal does not advertise itself as a TTY, or stdout is being captured. Force a mode with --output pretty or --json.
Diagnosing any other issue
Add --debug to print the request URL and timing to stderr, then attach the output to a GitHub issue at github.com/entidex/entidex-cli.
entidex --debug visibility openaiSource & releases
The CLI is open-source (MIT) at github.com/entidex/entidex-cli. Releases are signed and built reproducibly via GitHub Actions + GoReleaser. Checksums are published with every release; the universal installer verifies them automatically.