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.
Quick start
# install (macOS / Linux)
curl -fsSL https://entidex.com/install.sh | sh
# install (Windows PowerShell)
irm https://entidex.com/install.ps1 | iex
# authenticate via device flow
entidex login
# look up your first entity
entidex lookup spacex
# stream live drift (tier: layer_3_drift)
entidex watch openaiInstallation
The CLI is a single static Go binary. Pick the channel that fits your environment — every channel installs the same binary.
macOS / Linux
curl -fsSL https://entidex.com/install.sh | sh
# pin a version
curl -fsSL https://entidex.com/install.sh | sh -s -- --version v0.1.0Windows (PowerShell)
irm https://entidex.com/install.ps1 | iex
# pin a version
$env:ENTIDEX_VERSION = 'v0.1.0'
irm https://entidex.com/install.ps1 | iexHomebrew
brew install entidex/tap/entidexScoop
scoop bucket add entidex https://github.com/entidex/scoop-bucket
scoop install entidexnpm (global)
npm install -g @entidex/clipip
pip 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 spacexSearch the discovery layer.
Return only the canonical id/slug — machine-friendly form of lookup.
AI Visibility Score breakdown across engines + AI Overviews + SERP.
Sentiment Triangulation Index breakdown by source category.
Narrative Drift Score and trajectory points across the chosen window.
Dump 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.
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, search, resolve, schema, doctor, status | login / keys / config |
| layer_1_profile | Full profile access | + export, track *, refresh | + track / refresh |
| layer_2_insight | Visibility & sentiment | + visibility, sentiment, bulk | + bulk |
| layer_3_drift | Live drift & streaming | + drift, watch (SSE) | — |
| layer_4_cohort | Cohort & comparative | + cohort endpoints (API) | — |
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.