---
name: gives-cli
description: Use this skill to operate the Mere Gives CLI for authenticated giving, campaign, donor, receipt, team, and workspace setup workflows.
---

# Gives CLI

Use this skill for requests that operate the `mere-gives` CLI, inspect its auth/session flow, or map tenant, team, and workspace-provisioning commands to the gives app routes.

## Scope

- CLI entrypoints in `gives/cli/*`, especially `zerodonate.ts`, `auth.ts`, and `session.ts`.
- Shared product browser auth routes in `gives/src/routes/api/cli/v1/auth/*`.
- Session-backed admin routes used by tenant, team, donation, campaign, donor, receipt, event, and Stripe commands.
- Internal ZeroSMB bridge provisioning route used by `workspace provision`.

## Base commands and environment

1. Set the base URL:
   - `--base-url` flag or `MERE_GIVES_BASE_URL`
2. Human session override:
   - `--token` flag or `MERE_GIVES_TOKEN`
3. Preferred workspace for browser login:
   - `--workspace` flag or `MERE_GIVES_WORKSPACE_ID`
4. ZeroSMB provisioning token:
   - `ZERODONATE_INTERNAL_TOKEN`
5. Prefer `--json` when the result will be consumed by another tool.
6. Use `completion [bash|zsh|fish]` for shell setup.
7. Use `--yes --confirm <exact-id>` for deletes, team removal, and workspace disconnect.

## Immediate runbook

1. Build the CLI:
   - `cd /Users/nerd/mere/gives && pnpm build`
2. Authenticate:
   - `pnpm exec mere-gives -- auth login`
   - `pnpm exec mere-gives -- auth whoami`
3. Inspect tenant state:
   - `pnpm exec mere-gives -- tenant show --tenant ten_123 --json`
4. Inspect team state:
   - `pnpm exec mere-gives -- team list --tenant ten_123 --json`
5. Inspect donation operations:
   - `pnpm exec mere-gives -- donations list --tenant ten_123 --json`
   - `pnpm exec mere-gives -- donations show don_123 --tenant ten_123 --json`
   - `pnpm exec mere-gives -- donations refund don_123 --tenant ten_123 --full --yes --confirm don_123 --json`
   - `pnpm exec mere-gives -- campaigns list --tenant ten_123 --json`
6. Provision from ZeroSMB automation when needed:
   - `pnpm exec mere-gives -- workspace provision --workspace-id ws_123 --slug demo --name "Demo"`

## References

- [command-reference.md](references/command-reference.md): canonical command surface and required inputs.
- [route-map.md](references/route-map.md): auth routes, admin endpoints, and internal provisioning anchor.
- `/Users/nerd/mere/gives/cli/README.md`: repo-local CLI overview and examples.

## Auth workflow

1. `auth login` uses the shared product CLI contract and writes an XDG-backed local session.
2. Session app name is `mere-gives`, with legacy compatibility for `zerodonate`.
3. Typical fallback session path:
   - `~/.local/state/mere-gives/session.json`
4. The local session contains refresh token state, access token, user, default workspace, workspace list, and expiry metadata.
5. There is no explicit `refresh` subcommand; refresh is handled through the shared session helpers.

## Command families

### Human admin commands

- `auth login|whoami|logout`
- `workspace list|current|use`
- `tenant show|update`
- `campaigns list|show|create|update|delete`
- `donations list|export|show|refund`
- `donors list|show|update`
- `receipts list|show|download|year-end`
- `widget snippet`
- `settings get|update`
- `events list|show|create|update|delete`
- `stripe status`
- `team list|add|remove`

### ZeroSMB automation path

- `workspace provision`

## Validation notes

- `tenant` and `team` commands require either a saved session or `MERE_GIVES_TOKEN`.
- `workspace provision` uses the internal ZeroSMB token path instead of the human session flow.
- `team add` expects `--tenant` and `--user`, with optional `--role owner|admin`.
- `team remove` expects `--tenant` and `--membership`.
- `tenant update` only sends fields that were explicitly provided.
- `campaigns` and `events` mutations accept `--data` or `--data-file`; deletes require `--yes --confirm <id>`.
- `donations refund` requires `--yes --confirm <donation-id>` and either `--full` or `--amount-cents`.
- `receipts download` writes the existing receipt HTML/PDF route response to `--output`.

## Safe edits

For CLI behavior:
- `gives/cli/zerodonate.ts`
- `gives/cli/auth.ts`
- `gives/cli/session.ts`

For auth/session route behavior:
- `gives/src/routes/api/cli/v1/auth/*`
- `gives/src/lib/server/cli-auth.ts`

For admin and provisioning behavior:
- `gives/src/routes/api/admin/settings/tenant/+server.ts`
- `gives/src/routes/api/admin/settings/team/+server.ts`
- `gives/src/routes/api/admin/donations/[id]/+server.ts`
- `gives/src/routes/api/admin/donations/[id]/refund/+server.ts`
- `gives/src/routes/api/admin/receipts/[id]/+server.ts`
- `gives/src/routes/api/internal/zerosmb/workspaces/[workspaceId]/provision/+server.ts`
- `gives/src/lib/server/admin-auth.ts`
- `gives/src/lib/server/product-access.ts`