# auth.md - VibeRaven

How a coding agent opens a VibeRaven account for the person it works for. The person approves it in their own browser; the agent never signs in, approves or pays for them.

## What needs no account

- The repository check: `npx -y viberaven check` in the project root. Free, local, no login, no API key.
- `npx -y viberaven changes`, `fix`, `prompt --gap <id>`, `init`, and the local Studio (`npx -y viberaven`).
- The hosted MCP at `https://viberaven.dev/mcp` (migration SQL checks, provider playbooks, guide search).

Ask for an account only when the person wants something that needs one: full checks from the Studio, app changes from viberaven.dev, or a read-only live provider check.

## Agent signup: device code, approved by the person

1. Run `npx -y viberaven login --json` in the background. It writes one JSON line to stderr:
   `{"state":"requires_approval","actionUrl":"https://viberaven.dev/...","expiresAt":"..."}`
2. Show `actionUrl` to the person and say what it does: it opens a free VibeRaven account for them, approved with their Google sign-in. The link expires at `expiresAt` (about 10 minutes).
3. The person signs in and approves in their browser. The command then exits with `{"state":"authenticated"}` and keeps the session in a private local credential store. Nothing is printed that holds a token.
4. If it returns `expired` or `denied`, nothing was created or charged. Run it again only if the person asks.

Without a terminal, give the person https://viberaven.dev/go/agent/try_it instead.

## After signup

- `npx -y viberaven account --json` reads the plan and the remaining allowance.
- Free account: 2 full checks and 2 app changes. Pro: $20 a month, 50 full checks and 300 app changes ([pricing](https://viberaven.dev/pricing.md)).
- A step that needs payment returns a checkout URL. Show it to the person; never pay or enter payment details for them.

## Rules for agents

- Offer the account; do not start it without the person's yes.
- Never type the person's password, codes or card details, and never approve the device code yourself.
- Local checks stay free whether or not the person signs up.