# MetaLens Skill for Claude Code / OpenClaw

One-line install to give any Claude Code agent (local, Docker, OpenClaw, CI)
programmatic access to your MetaLens instance.

## Quick install

```bash
curl -fsSL https://metalens.valiotti.tech/install/metalens.sh | \
  bash -s -- --token mlns_your_token_here
```

Or interactively (prompts for token):

```bash
curl -fsSL https://metalens.valiotti.tech/install/metalens.sh | bash
```

## What it installs

- `~/.claude/utils/metalens.js` — CLI helper
- `~/.claude/skills/metalens/SKILL.md` — skill definition
- `~/.claude/metalens-config.json` — API token + defaults (permissions 600)

## Requirements

- `bash`, `curl`
- Node.js 18 or newer

## Getting a token

1. Go to https://metalens.valiotti.tech/dashboard/settings
2. Scroll to "API Tokens"
3. Click "+ New Token", name it (e.g. "OpenClaw bot")
4. Copy the `mlns_...` value **immediately** — it's only shown once

## Available commands after install

```bash
node ~/.claude/utils/metalens.js <command> [args] [--json]

connections                        List Metabase connections
xray latest [connection]           Latest X-Ray scan health grade + insights
search "<query>" [connection]      Semantic search across cards + dashboards
chat "<question>" [connection]     Natural-language question → SQL
gaps [connection]                  Latest gap analysis
review "<sql>"                     Review SQL for performance
tree list [connection]             List metric trees
tree get <tree-id>                 Show a tree
tree generate [connection]         Generate a new metric tree (5 credits)
tree share <tree-id>               Create public share link
kb list [connection]               List knowledge base docs
```

See `node ~/.claude/utils/metalens.js help` for all flags.

## Environment variables (alternative to flags)

- `METALENS_TOKEN` — API token
- `METALENS_BASE_URL` — override base URL (default: `https://metalens.valiotti.tech`)
- `METALENS_CONNECTION_ID` — pre-set default connection UUID
- `CLAUDE_DIR` — install target (default: `$HOME/.claude`)

## Using in OpenClaw (Docker)

Find your container name first, then run the installer inside it:

```bash
# Find your container name
docker ps | grep openclaw

# Run the installer
docker exec -it YOUR_OPENCLAW_CONTAINER bash -c "
  curl -fsSL https://metalens.valiotti.tech/install/metalens.sh | \
    bash -s -- --token mlns_your_token_here
"
```

Then tag OpenClaw in Slack/Telegram with natural-language questions:

- "@openclaw find all Metabase questions about churn"
- "@openclaw what is the current X-Ray health grade?"
- "@openclaw generate a metric tree for my Metabase, industry: marketplace"
- "@openclaw show me the latest gap analysis"

Claude will auto-invoke the skill and route through `metalens.js`.

## Updating

Re-run the installer any time — it'll fetch the latest `metalens.js` and `SKILL.md`:

```bash
curl -fsSL https://metalens.valiotti.tech/install/metalens.sh | \
  bash -s -- --token "$(jq -r .apiToken ~/.claude/metalens-config.json)"
```

Existing config is backed up to `metalens-config.json.bak`.

## Security

- Tokens are sha256-hashed on the server — we only ever store the hash
- Tokens can be revoked instantly via the Settings UI
- Bearer tokens carry all the same permissions as your user account, including credits
- Treat them like passwords: don't commit to git, don't paste in chats, rotate on compromise

## Troubleshooting

- **HTTP 401** → token is invalid, expired, or revoked. Create a new one.
- **HTTP 402** → out of credits. Buy a pack in Settings or upgrade plan.
- **HTTP 503 on search** → OpenAI embeddings not configured server-side.
- **"Connection not found"** → run `metalens connections` to see valid IDs, then set `defaultConnectionId` in config.

Need more help? Feedback button in MetaLens or file an issue.