# @rulemetric/cli

The RuleMetric CLI. Manages instructions, sessions, evals, and (as of the
user-management release) organizations.

## Auth

```bash
rulemetric auth login            # interactive — writes ~/.config/rulemetric/env
rulemetric auth create-key       # generate a long-lived API key
rulemetric auth status           # show the current auth state (email / API key)
```

Credentials are read from (first match wins):
1. `RULEMETRIC_API_URL` + `RULEMETRIC_API_KEY` (or `RULEMETRIC_ACCESS_TOKEN`)
2. `~/.config/rulemetric/env`
3. `~/.config/rulemetric/auth.json` (JSON fallback, requires `jq`)
4. `.env.local` in the project root (development)

## Local mode (all data on your machine)

By default the CLI talks to the hosted service at `rulemetric.com`. `local up`
runs the whole product on your own machine instead — API, dashboard, and
database — with no cloud contact at all.

```bash
rulemetric local up                       # start (downloads the local runtime on first run)
rulemetric local up --foreground          # run in this terminal instead of as a service
rulemetric local up --port 3210           # non-default port
rulemetric local up --email you@example.com --password '<pw>'   # provision the first user
rulemetric local down                     # stop; data is preserved
rulemetric local down --delete-data       # stop and wipe the local database (irreversible)
```

**Requires Docker** (the database runs in it) and the
[Supabase CLI](https://supabase.com/docs/guides/cli) —
`brew install supabase/tap/supabase`. First run downloads `@rulemetric/local`
(~10 MB: bundled API server, dashboard, and migrations) at a version locked to
your CLI; add `--yes` to skip the confirmation. Cloud-only users never download it.

The dashboard is then at `http://localhost:3000` (or your `--port`), and
`rulemetric hooks install` points capture at it like any other API URL.

To guarantee nothing ever reaches the cloud — including implicit fallbacks —
set strict mode, which turns every unconfigured cloud call into a loud failure
instead of a silent upload:

```bash
echo 'RULEMETRIC_STRICT_LOCAL=1' >> ~/.config/rulemetric/env
```

`local down` leaves your data on disk; `local up` picks it back up.

## Org commands

The org commands let you list and switch the "active org" used by every
subsequent CLI invocation. Sessions captured by hooks/proxy/MCP while an
active org is set will stamp `sessions.org_id` to that org.

```bash
rulemetric org list              # list orgs you belong to; star marks the active one
rulemetric org current           # print the active org's slug and id
rulemetric org switch <slug>     # set the active org (cached locally)
rulemetric org switch --clear    # clear the active org (back to personal mode)
```

**Active-org resolution order:**
1. `RULEMETRIC_ORG_ID` environment variable (process-scoped override)
2. Local cache at `~/.config/rulemetric/active-org` (written by
   `rulemetric org switch`)
3. None (sessions captured without an org_id)

A background prefetch refreshes the cache on a TTL so a slug change in the
web UI is picked up by the next CLI run without an explicit `org switch`.

**Creating an org:** Currently web-only — visit `/orgs/new` in the
dashboard. The CLI will adopt the org once you `org switch <slug>` (or set
the active org in the web UI, which the CLI cache picks up).

## Other top-level commands

- `rulemetric instructions ...` — list, get, create, delete, fork, promote, pull, upstream, versions
- `rulemetric skills search|install ...` — install a skill to `.agents/skills/` + `.claude/skills/`
- `rulemetric sessions ...` — list, start, end, import, analyze
- `rulemetric evals ...` — eval target/case/run/optimize commands + `agent` (background worker)
- `rulemetric hooks install|uninstall|run <name>` — manage tool hook scripts
- `rulemetric proxy ...` — start/stop the mitmproxy capture layer
- `rulemetric service install|status|uninstall` — background services (`--worker-only` installs just the worker)

Session insights are enriched automatically (hooks + the background worker) —
there is no manual `insights` command.

## Tests

```bash
pnpm --filter @rulemetric/cli test:unit   # unit tests (no creds needed)
pnpm --filter @rulemetric/cli test:e2e    # e2e (needs Supabase creds)
```

E2E tests start a real Hono API on port 3001 and create a temp Supabase
user; see `apps/cli/e2e/global-setup.ts`.