Embrasure CLI

Terminal tools for Embrasure investigation, lineage, context, governance, monitoring, and migration workflows.

Install

Public npm distribution:

npm install -g @embrasure/cli

Dogfood fallback from this repo:

pnpm --filter @embrasure/cli build
node apps/cli/dist/index.js --help

Release

Publish the runtime dependency first, then the CLI:

pnpm --filter @embrasure/api-client publish --access public
pnpm --filter @embrasure/cli publish --access public

The published packages only include built dist files and package metadata, not the TypeScript sources, tests, or monorepo.

First Run

Give your agent the setup instructions at https://embrasure.ai/setup/agent.md, or run:

npx @embrasure/cli@latest setup --json

Setup reuses your saved sign-in, workspace, and server-side setup progress. Approve source access in the browser; setup connects all supported tables by default. As soon as a requested source has verified query access, the result supplies the next command for a useful answer with evidence. Readiness is not itself a business finding.

Use --no-install when MCP is already available or when continuing through CLI commands. Use --no-wait for an immediate status result after sign-in. Re-run setup to resume, or pass --run <id> to resume the exact run. --no-open prints browser handoffs to stderr without opening them. --quiet suppresses those handoffs, so avoid combining it with unattended browser sign-in.

With --json, stdout contains one final document. Progress goes to stderr. Exit 30 means approval or additional setup is needed, 40 means the wait expired with progress saved, and 10 means setup failed. Inspect status, nextAction, and resumeCommand; do not treat these exits as completed setup. A completed setup with verified query access says ready_for_analysis. A synchronized setup without a verified read marker (including CDC and Flow) says setup_complete_query_verification_required: exit 0 confirms setup only, queryReady remains false, and nextAction.kind is verify_and_analyze. Run its read-only query verification and answer command with the original question before claiming first value. When a requested source becomes query-ready sooner, ready_for_first_answer allows the agent to answer with explicit coverage while the remaining setup continues (setupComplete: false). Coverage separates ready, partially ready, pending, and verification-required sources, and includes the exact blocked tables for this setup. All setup results leave first value unfinished until a verified answer is returned. Returned commands use npx, so a global install is not required.

For account checks:

embrasure auth
embrasure doctor

If you are already signed in, embrasure auth shows the saved account, API, workspace, token fingerprint, and logout command. If you need a manual token path:

embrasure auth token set <token>
embrasure workspaces use <workspace_id>

CLI config is stored in ~/.embrasure/config.json with file mode 0600. The CLI masks token values in normal output. On macOS and Linux with libsecret, the CLI stores browser-session credentials in the system credential store and keeps only non-secret session metadata in the config file. Browser-session access and refresh tokens must both be stored in the system credential store. Manually supplied static tokens may still fall back to the local config file when no supported credential store is available. When a browser-backed session is saved, it is used before EMBRASURE_API_TOKEN; the environment token is a fallback for standalone/debug use, while --token remains the explicit per-command override. Use embrasure auth logout to remove the saved local token.

Maintenance

embrasure doctor
embrasure update
embrasure config list
embrasure completion install zsh

doctor checks for a newer npm release and prints the update command when one exists. Update checks are skipped in CI and when EMBRASURE_SKIP_UPDATE_CHECK=1 or NO_UPDATE_NOTIFIER=1 is set.

Agent-native data workflows

embrasure ask "Why did weekly conversion change?"
embrasure investigate table analytics.orders
embrasure investigate lineage analytics.orders --direction upstream
embrasure lineage impact analytics.orders --connector <connector_id>
embrasure lineage impact analytics.orders --connector <connector_id> --column amount
embrasure lineage export --connector <connector_id>
embrasure lineage export --out lineage.ndjson
embrasure insights brief
embrasure monitor scouts list --relation analytics.orders
embrasure monitor tables checks <monitor_id>
embrasure monitor tables owner <monitor_id> --user <owner_user_id>
embrasure schema changes impact <change_id>
embrasure dashboard preview <dashboard_id>
embrasure notebook export <notebook_id> --format ipynb
embrasure context search "What is an activated customer?"
embrasure governance trust <query_request_id>
embrasure access findings

Table ownership

Ownership claims answer "who owns this table". A claim recorded with --user is confirmed immediately, because a workspace member id is an assertion someone can be held to. A claim recorded with --label or --email stays unconfirmed: it is a proposal (usually a pull-request author matched by email) and is never used to route alerts until a human confirms it.

embrasure governance owners list --status unconfirmed
embrasure governance owners set analytics.orders --user <owner_user_id>
embrasure governance owners set analytics.orders --label "Data Platform"
embrasure governance owners confirm <claim_id> --user <owner_user_id>
embrasure governance owners dismiss <claim_id>

All reads support the global --json and --quiet flags. Mutations require an interactive confirmation or --yes; JSON/YAML payloads use --input '{"...":"..."}' or --input @request.yaml. Connector credentials remain browser/env-file workflows and are never command arguments.

Install the compact MCP surface by default, or opt into specialist tools:

embrasure setup --surface core
embrasure setup --surface full --replace-client-config

Metabase Migration

Audit an extracted Metabase serialization export before importing anything:

embrasure metabase audit --path ./metabase-export --report metabase-migration-report.json

Import supported artifacts into the current Embrasure workspace. Imports are dry-run by default; pass --yes to create dashboards, verified queries, and context seeds.

embrasure metabase import \
  --path ./metabase-export \
  --connector <connector_id> \
  --semantic-model <semantic_model_id> \
  --report metabase-migration-report.json \
  --yes

For Metabase instances without a local serialization export, use REST extraction:

METABASE_API_KEY=... embrasure metabase audit --metabase-url https://metabase.example.com

The migration tool preserves native SQL cards, maps common SQL-backed dashboard cards to Embrasure dashboard specs, writes Metabase models/metrics/glossary/table metadata as context seeds, and reports MBQL/query-builder cards or unsupported visualizations with manual follow-up reasons.