CLI Reference

The @emit-vision/cli package gives you a terminal interface to your Emit Vision projects. It's designed for both humans and AI coding agents (Claude Code, etc.) — every data command supports --json output for machine-readable consumption.

Installation

npm install -g @emit-vision/cli
# or: pnpm add -g @emit-vision/cli

Authentication

Authenticate with a Personal Access Token (PAT). You can generate one in your account settings.

emit-vision login

You'll be prompted to paste your PAT. Credentials are stored in ~/.emit-vision/config.json.

Non-interactive / CI login — pass the token as a flag or environment variable. No prompt, no TTY required:

emit-vision login --token evp_your_pat_here
# or:
EMIT_VISION_PAT=evp_your_pat_here emit-vision login

emit-vision logout         # clear stored credentials
emit-vision status         # verify auth state and confirm token is valid

For self-hosted instances, pass your API URL:

emit-vision login --api-url https://api.your-instance.com

Project management

emit-vision project list
emit-vision project create <name> [--json]
emit-vision project env create <projectId> <envName> [--type development|staging|custom] [--json]
emit-vision key get <projectId>
emit-vision key rotate <projectId> [--yes] [--json]

The --json flag on write commands returns structured JSON including the rawIngestKey — useful for scripted setup:

# Capture the ingest key in a script without interactive prompts
RESULT=$(emit-vision project create my-app --json)
PROJECT_ID=$(echo "$RESULT" | jq -r '.id')
INGEST_KEY=$(echo "$RESULT" | jq -r '.rawIngestKey')

The --yes flag on key rotate skips the confirmation prompt — required in non-interactive contexts:

emit-vision key rotate <projectId> --yes --json

Querying telemetry

All query commands accept these common flags:

Overview

High-level stats for a project: total events, total errors, unique visitors, and top events.

emit-vision overview <projectId>
emit-vision overview <projectId> --from 2025-06-01T00:00:00Z --environment production
emit-vision overview <projectId> --json

Recent events

emit-vision events recent <projectId>
emit-vision events recent <projectId> --environment production --limit 50
emit-vision events recent <projectId> --from 2025-06-18T00:00:00Z --json

Recent errors

Individual error occurrences in reverse-chronological order.

emit-vision errors recent <projectId>
emit-vision errors recent <projectId> --environment production --limit 25 --json

Grouped errors

Deduplicated error groups with occurrence counts and status. Most useful for triage.

emit-vision errors grouped <projectId>
emit-vision errors grouped <projectId> --environment production --limit 20
emit-vision errors grouped <projectId> --json

Logs

Recent structured log entries (OpenTelemetry logs / sdk-node log capture).

emit-vision logs <projectId>
emit-vision logs <projectId> --severity error --limit 100
emit-vision logs <projectId> --from 2025-06-18T00:00:00Z --json

Supported severity values: trace, debug, info, warn, error, fatal.

Feature flags

emit-vision flags list <projectId>
emit-vision flags list <projectId> --limit 20 --json
 
emit-vision flags evaluate <projectId> --environment production
emit-vision flags evaluate <projectId> --environment production --user-key user_123 --flag new-checkout
 
emit-vision flags enable <projectId> new-checkout
emit-vision flags disable <projectId> new-checkout
 
emit-vision flags rollout <projectId> new-checkout 25
 
emit-vision flags archive <projectId> new-checkout --yes
 
emit-vision flags create <projectId> new-checkout --name "New Checkout"
emit-vision flags create <projectId> new-checkout --name "New Checkout" --enabled --rollout 25
 
emit-vision flags create <projectId> --from-json flag.json
cat flag.json | emit-vision flags create <projectId> --from-json -
 
emit-vision flags update <projectId> new-checkout --name "New Checkout v2" --environments production,staging

flags list shows every flag's key, name, enabled state, rollout percentage, and last-updated date. flags evaluate resolves variants the way your app would see them — pass --user-key to evaluate for a specific user, and repeat --flag <key> to scope the response to particular flags. Omit --flag to evaluate every flag in the project; the CLI authenticates with your PAT, which is trusted to list everything (unlike a public ingest key, which must name the flags it wants).

flags enable/flags disable, flags rollout <percent>, and flags archive all take a flag key (not an internal id) and require an admin-scoped token — a token belonging to a non-admin project member gets a clear permissions error rather than a generic failure. flags archive is irreversible, so it prompts for confirmation unless you pass --yes; non-interactive callers (scripts, agents) must pass --yes explicitly.

flags create has two modes. The shorthand — <key> --name <name> plus optional --description, --enabled, and --rollout <0-100> — synthesizes a standard boolean flag with off/on variants (matching what the dashboard's flag form produces): off is false with weight 0, on is true with weight 100. --enabled sets isEnabled and moves defaultVariant to on; without it the flag is created disabled with defaultVariant: "off". For anything beyond a boolean — multiple variants, non-default weights, custom values — pass --from-json <file> (or - for stdin) with a full flagCreateSchema payload; the CLI validates it locally (variant keys, weights, required fields) and reports the offending field before making a request, so a malformed definition never reaches the API as an opaque 400.

flags update covers the non-variant fields — --name, --description, --environments (comma-separated), and --default-variant — sending only the fields you pass. It requires at least one field and an admin-scoped token, same as the other mutation commands. Changing variants themselves isn't supported via CLI flags; recreate the flag (or edit it in the dashboard) if you need to change the variant set.

Using with Claude Code agents

Every query command returns clean JSON with --json. Agents can pipe this directly into analysis:

# Get the top error groups as JSON and let the agent triage them
emit-vision errors grouped <projectId> --environment production --json
 
# Check recent logs for a deploy
emit-vision logs <projectId> --from 2025-06-18T12:00:00Z --severity error --json
 
# Summarize project health
emit-vision overview <projectId> --json
 
# Check which variant a flag resolves to for a given environment
emit-vision flags evaluate <projectId> --environment production --json

The CLI is fully non-interactive — agents can log in, create projects, and rotate keys without any TTY or prompts:

# Log in from a script or agent
EMIT_VISION_PAT=evp_your_token emit-vision login
 
# Create a project and capture the ingest key in one step
emit-vision project create my-app --json | jq -r '.rawIngestKey'
 
# Rotate a key without confirmation
emit-vision key rotate <projectId> --yes --json

Example: CLAUDE.md setup

Add this to your project's CLAUDE.md so agents automatically know how to pull live telemetry:

## Observability
 
This project is instrumented with Emit Vision. Project ID: `<your-project-id>`.
 
To diagnose errors or check recent events:
\`\`\`bash
emit-vision errors grouped <project-id> --environment production --json
emit-vision logs <project-id> --severity error --json
emit-vision overview <project-id> --json
\`\`\`