@littlefriend/cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ZVN DEV
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,566 @@
+# @littlefriend/cli
+
+Set up Little Friend from the terminal: create a project, print the install snippet for your framework, write secret keys straight into an env file, and check that events arrive. Every command takes `--json`, so a coding agent can do the whole setup and read the results.
+
+No dependencies. Node 22 or later.
+
+## Install
+
+```sh
+npx @littlefriend/cli login
+```
+
+Or install it once and use `littlefriend`:
+
+```sh
+npm install -g @littlefriend/cli
+littlefriend login
+```
+
+## Set up a site
+
+```sh
+littlefriend login
+littlefriend projects create --name "Acme" --domain acme.com --mode journey
+littlefriend snippet --framework next
+littlefriend keys create --kind server --env-file .env.local
+littlefriend verify
+```
+
+`snippet` detects the framework in the current directory when you leave out `--framework`, and falls back to the plain script tag. `verify` waits up to 60 seconds for the first event, then shows what arrived and anything the collector refused, with the reason.
+
+`littlefriend guide` prints the full setup guide for coding agents.
+
+## Signing in
+
+`littlefriend login` opens your browser to approve the CLI. It listens on `127.0.0.1` on a random port for the answer, checks it, and stores the sign-in in `~/.littlefriend/credentials.json`, readable only by you (mode 0600). Pass `--no-browser` to open the printed link yourself. The CLI waits 5 minutes for the approval.
+
+The sign-in acts as you, with your role in each workspace: it can create and change projects, goals, funnels, keys and settings, and only read where you are a viewer. It never reaches billing, your password or invites.
+
+The access token renews on its own. `littlefriend logout` revokes the sign-in and deletes it from the machine. You can also revoke it in the dashboard under Account, Connected apps.
+
+For CI, set `LITTLEFRIEND_TOKEN` to an access token. It is used as is, never stored or renewed.
+
+## Choosing a project
+
+Commands that act on a project take `--project`, which accepts a project id (`prj_...`), a site key (`lf_...`), a name or a domain. Leave it out when you can see a single project. `--workspace` (id, slug or name) narrows the search when you belong to several workspaces.
+
+Set `LITTLEFRIEND_PROJECT` and `LITTLEFRIEND_WORKSPACE` to skip the flags.
+
+## Output
+
+Human output goes to stdout. Progress notes and warnings go to stderr.
+
+With `--json`, stdout carries one JSON document. On an error it is:
+
+```json
+{ "error": { "code": "NOT_SIGNED_IN", "message": "Not signed in to https://api.littlefriend.io. Run: littlefriend login" } }
+```
+
+and stderr repeats the message. Messages from the API are repeated word for word.
+
+| Exit code | Meaning |
+|---|---|
+| 0 | Done |
+| 1 | Failed, or `verify` saw no events |
+| 2 | Wrong flags or arguments, or a confirmation (`--yes`) is missing |
+| 3 | Sign in needed: not signed in, the sign-in expired, or the token was refused |
+
+## Environment
+
+| Variable | |
+|---|---|
+| `LITTLEFRIEND_API` | API origin. Default `https://api.littlefriend.io`. Same as `--api`. |
+| `LITTLEFRIEND_WORKSPACE` | Default workspace. Same as `--workspace`. |
+| `LITTLEFRIEND_PROJECT` | Default project. Same as `--project`. |
+| `LITTLEFRIEND_TOKEN` | Access token to use instead of the stored sign-in. |
+| `LITTLEFRIEND_HOME` | Directory for `credentials.json`. Default `~/.littlefriend`. |
+
+## Commands
+
+The JSON shapes below list the top-level keys. Where a command returns an API response unchanged, the type is named from `@littlefriend/contract`.
+
+A project in JSON is:
+
+```ts
+{
+  id: string; workspaceId: string; name: string; domain: string;
+  publicKey: string;               // the site key, lf_...
+  privacyMode: 'aggregate' | 'journey';
+  timezone: string;
+  allowedOrigins: string[];        // empty: every origin
+  campaignAllowTerm: boolean;
+  retentionEventsDays: number; retentionAggregatesDays: number;
+  installVerifiedAt: string | null; createdAt: string;
+}
+```
+
+### Sign in
+
+#### `login`
+
+Signs in with your browser.
+
+```sh
+littlefriend login
+```
+
+```ts
+{ api: string; email: string | null; scope: string | null; expiresAt: string }
+```
+
+#### `logout`
+
+Revokes this machine's sign-in and deletes it. Running it when not signed in does nothing and exits 0.
+
+```sh
+littlefriend logout
+```
+
+```ts
+{ api: string; signedOut: boolean; revoked: boolean }
+```
+
+#### `whoami`
+
+Shows who the CLI is signed in as and your workspaces.
+
+```sh
+littlefriend whoami
+```
+
+```ts
+{
+  api: string; email: string | null;
+  source: 'stored' | 'env';        // env: LITTLEFRIEND_TOKEN
+  expiresAt: string | null;
+  workspaces: { id: string; name: string; slug: string; role: 'owner' | 'editor' | 'viewer' }[];
+}
+```
+
+### Workspaces and projects
+
+#### `workspaces list`
+
+```sh
+littlefriend workspaces list
+```
+
+```ts
+{ workspaces: { id: string; name: string; slug: string; role: string }[] }
+```
+
+#### `projects list`
+
+Lists projects in every workspace you belong to, or in the one `--workspace` names.
+
+```sh
+littlefriend projects list --workspace acme
+```
+
+```ts
+{ projects: Project[] }
+```
+
+#### `projects create`
+
+Creates a project. If a project in the workspace already has the domain, it prints that one instead and exits 0, so running it twice is safe.
+
+Allowed origins default to `https://<domain>` and `https://www.<domain>`, so events from local and preview builds are refused and your numbers stay clean. `--origin` (repeatable) replaces that list. `--any-origin` accepts every origin. Other flags: `--mode aggregate|journey` (default aggregate) and `--timezone` (default this machine's time zone, as in the dashboard).
+
+```sh
+littlefriend projects create --name "Acme" --domain acme.com --mode journey
+```
+
+```ts
+{ created: boolean; project: Project }   // created: false when the domain already had a project
+```
+
+#### `projects get`
+
+```sh
+littlefriend projects get --project acme.com
+```
+
+```ts
+{ project: Project; role: 'owner' | 'editor' | 'viewer' }
+```
+
+#### `projects update`
+
+Changes a project's settings: `--name`, `--domain`, `--mode`, `--timezone`, `--events-days <1-7>`, `--aggregates-days <30-395>`, `--campaign-term` or `--no-campaign-term`. For allowed origins, `--origin` replaces the list, `--add-origin` and `--remove-origin` edit it, and `--any-origin` empties it.
+
+```sh
+littlefriend projects update --add-origin https://staging.acme.com
+```
+
+```ts
+{ project: Project }
+```
+
+#### `projects delete`
+
+Deletes the project. Owners only. Needs `--yes`.
+
+```sh
+littlefriend projects delete --project prj_... --yes
+```
+
+```ts
+{ deleted: true; project: { id: string; name: string } }
+```
+
+#### `projects check`
+
+The project, whether events arrive, and why any were refused. It is `verify` without waiting, and returns the same JSON with the full project.
+
+```sh
+littlefriend projects check --project acme.com
+```
+
+### Install
+
+#### `snippet`
+
+Prints what to add to the site, with the site key filled in: the script tag, or the npm package and the file to put `init` in, plus the Content Security Policy lines. Frameworks: `html`, `next`, `nuxt`, `sveltekit`, `astro`, `remix`, `react`, `vue`, `angular`, `wordpress`, `npm`.
+
+The mode comes from the project unless you pass `--mode`. `--consent required` waits for your consent banner (journey mode). `--replay` adds session replay. `--site-key lf_...` prints a snippet without signing in.
+
+For a staging site, add `data-test` to the tag (or `test: true` to `init`): its events show in `verify` and never in reports.
+
+```sh
+littlefriend snippet --framework next --mode journey --consent required
+```
+
+```ts
+{
+  project?: { id: string; name: string };
+  framework: string; route: 'tag' | 'npm'; siteKey: string;
+  mode: 'aggregate' | 'journey'; consent: 'required' | 'none'; replay: boolean;
+  steps: { title: string; file?: string; language: string; code: string }[];
+  csp: string[];                   // directives to add if the site sets a CSP
+  notes: string[];
+}
+```
+
+#### `keys list`
+
+Lists the project's secret keys by prefix. Secrets are never shown again after creation.
+
+```sh
+littlefriend keys list
+```
+
+```ts
+{ keys: ApiKey[] }
+
+// ApiKey, never the secret
+{ id: string; kind: 'server' | 'edge' | 'read'; label: string | null; prefix: string;
+  createdAt: string; lastUsedAt: string | null; revokedAt: string | null;
+  createdBy: { id: string; name: string | null; email: string } | null }
+```
+
+#### `keys create`
+
+Creates a secret key: `server` for `@littlefriend/node`, `edge` for `@littlefriend/edge` and the agent door, `read` for reading reports.
+
+With `--env-file`, the secret goes straight into the file as `NAME=secret` and is never printed. The name defaults to `LF_SERVER_KEY`, `LF_EDGE_KEY` or `LF_READ_KEY`; change it with `--env-name`. If the file already sets that name, no key is created. The CLI warns when git does not ignore the file.
+
+```sh
+littlefriend keys create --kind server --env-file .env.local
+```
+
+```ts
+// with --env-file
+{ created: true; key: ApiKey; envFile: string; envName: string }
+{ created: false; envFile: string; envName: string; reason: 'already_set' }
+// without --env-file: the secret appears once, here
+{ key: ApiKey; secret: string; notice: string }
+```
+
+#### `keys revoke`
+
+Needs `--yes`. Requests that use the key are refused from then on.
+
+```sh
+littlefriend keys revoke key_... --yes
+```
+
+```ts
+{ key: ApiKey }
+```
+
+#### `verify`
+
+Waits for the first event from the site and says what it was: time, name, route and source. Then it shows the project's health: whether the install is verified, when the last event arrived, which sources send, and requests refused in the last 24 hours with what each reason means. `origin_not_allowed`, for example, means a page on a host missing from the allowed origins sent it.
+
+`--wait <seconds>` (default 60, 0 checks once) and `--since <minutes>` (default 60) set how long to wait and how far back an event counts. Exits 1 when nothing arrived.
+
+```sh
+littlefriend verify --wait 120
+```
+
+```ts
+// an event arrived, exit 0
+{ seen: true; project: { id: string; name: string; publicKey: string };
+  event: LiveEvent; events: number; sinceMinutes: number; health: DataHealth }
+// nothing arrived, exit 1
+{ seen: false; project: { id: string; name: string; publicKey: string };
+  waitedSeconds: number; sinceMinutes: number;
+  rejected: { reason: string; count: number }[];   // refusals seen while waiting
+  health: DataHealth; error: { code: 'NO_EVENTS'; message: string } }
+```
+
+`DataHealth.rejected24h` lists the refusals of the last 24 hours as `{ reason, count }`.
+
+### Measure
+
+#### `goals list`
+
+`--archived` includes archived goals.
+
+```sh
+littlefriend goals list
+```
+
+```ts
+{ goals: GoalDefinition[] }
+```
+
+#### `goals create`
+
+A goal counts a page view (`--route /thanks`) or an event (`--event order.completed`, with `--source browser|server` to count one source only). `--server-confirmed` counts only outcomes confirmed by your server.
+
+```sh
+littlefriend goals create --name "Paid" --event order.completed --source server --server-confirmed
+```
+
+```ts
+{ goal: GoalDefinition }
+```
+
+#### `goals update`
+
+Takes the same flags as `create`, plus `--no-server-confirmed` and `--restore` for an archived goal.
+
+```sh
+littlefriend goals update goal_... --name "Checkout completed"
+```
+
+```ts
+{ goal: GoalDefinition }
+```
+
+#### `goals delete`
+
+Archives the goal, so past completions stay explainable. Needs `--yes`.
+
+```sh
+littlefriend goals delete goal_... --yes
+```
+
+```ts
+{ archived: true; goalId: string }
+```
+
+#### `funnels list`
+
+```sh
+littlefriend funnels list
+```
+
+```ts
+{ funnels: { id: string; projectId: string; name: string; steps: string[];
+             createdAt: string; updatedAt: string }[] }
+```
+
+#### `funnels create`
+
+Steps run in order, up to 8 of them: `route:/path` (a page view), `event:<name>` or `goal:<goalId>`.
+
+```sh
+littlefriend funnels create --name Signup --step route:/pricing --step event:signup.start --step goal:goal_...
+```
+
+```ts
+{ funnel: SavedFunnel }
+```
+
+#### `funnels update`
+
+`--step` replaces all the steps.
+
+```sh
+littlefriend funnels update fnl_... --name "Trial signup"
+```
+
+```ts
+{ funnel: SavedFunnel }
+```
+
+#### `funnels delete`
+
+Needs `--yes`.
+
+```sh
+littlefriend funnels delete fnl_... --yes
+```
+
+```ts
+{ deleted: true; funnelId: string }
+```
+
+#### `funnels report`
+
+Runs a saved funnel, or steps given with `--step`, over `--from` and `--to` (default the last 7 days in the project's time zone). `--within 30m|1h|session` sets how long a session has to finish. Funnels need journey mode.
+
+```sh
+littlefriend funnels report fnl_... --from 2026-09-01 --to 2026-09-28
+```
+
+The JSON is the API's `FunnelReport`: `{ meta, available, unavailableReason?, within, steps, sessionsInScope, completed, conversionRate, coveredFrom, denominator }`.
+
+#### `report`
+
+Quick numbers to check the data looks right: `overview` (the default), `pages`, `sources`, `goals` or `countries`, over `--from` and `--to` (default the last 7 days in the project's time zone).
+
+```sh
+littlefriend report sources --from 2026-09-01 --to 2026-09-28
+```
+
+The JSON is the API's report response, with `meta.range` holding the dates used.
+
+### Session replay, the agent door and log drains
+
+#### `replay get`, `replay enable`, `replay disable`
+
+Replay records sessions with every word masked. It needs journey mode. `enable` takes `--rate <1-100>`, the percent of sessions to record.
+
+```sh
+littlefriend replay enable --rate 25
+```
+
+```ts
+// ReplaySettingsResponse
+{ settings: { enabled: boolean; sampleRate: number; unmaskSelectors: string[]; blockSelectors: string[];
+              excludeRoutes: string[]; minActiveMs: number; version: number; updatedAt: string | null };
+  available: boolean; unavailableReason?: string; installed: boolean }
+```
+
+#### `replay set`
+
+`--unmask`, `--block` and `--exclude` replace a list; `--add-*`, `--remove-*` and `--clear-*` edit it. `--unmask-preset` adds the recommended set: navigation, headers, footers, headings, buttons and labels. Also `--rate` and `--min-active-ms <0-60000>`.
+
+```sh
+littlefriend replay set --unmask-preset --exclude /account --exclude /checkout --block .support-chat
+```
+
+Returns `ReplaySettingsResponse`.
+
+#### `door get`
+
+Shows the agent door policy: dry run or live, and its rules.
+
+```sh
+littlefriend door get
+```
+
+```ts
+// DoorSettingsResponse
+{ policy: DoorPolicy; presets: Record<string, DoorRule[]>; canEdit: boolean;
+  updatedAt: string | null; updatedBy: string | null; installed: boolean }
+```
+
+#### `door set`
+
+Applies a preset (`open`, `no_training`, `verified_only`, `commerce`), switches `--mode dry_run|live`, or both. Replacing custom rules with a preset needs `--yes`.
+
+```sh
+littlefriend door set --preset no_training --mode dry_run
+```
+
+Returns `DoorSettingsResponse`.
+
+#### `door simulate`
+
+With `--ua`, shows what the door decides for one request. The user agent is classified on your machine with the same rules the collector uses. `--path` and `--method` describe the request, `--verified` or `--spoofed` stand in for the address check, and `--preset` tries a preset instead of the saved policy.
+
+Without `--ua`, it tries the policy against the last 7 days of agent traffic.
+
+```sh
+littlefriend door simulate --ua "GPTBot/1.1" --path /blog
+```
+
+```ts
+// with --ua
+{ classification: object; facts: DoorFacts;
+  policy: { source: 'saved' | 'preset'; preset?: string; mode: 'dry_run' | 'live'; version: number };
+  decision: { action: string; ruleId: string | null } }
+// without --ua: DoorSimulation
+{ from: string; to: string; requests: number; rules: object[]; unmatched: number }
+```
+
+#### `drains list`
+
+```sh
+littlefriend drains list
+```
+
+```ts
+{ endpoint: string; drains: DrainInfo[] }   // never the secrets
+```
+
+#### `drains create`
+
+Creates a Vercel log drain and prints its URL, the header to set, the signature secret and the steps to finish in Vercel. The secret is shown once.
+
+```sh
+littlefriend drains create --provider vercel --label "Vercel production"
+```
+
+```ts
+// DrainCredentials
+{ drain: DrainInfo; endpoint: string; headers: Record<string, string>; secret: string; notice: string }
+```
+
+#### `drains rotate`
+
+Replaces the drain's key and secret and prints the new ones once. The old ones keep working for `--grace-hours` (default 24, up to 168), or stop at once with `--expire-now`.
+
+```sh
+littlefriend drains rotate drn_...
+```
+
+Returns `DrainCredentials`.
+
+#### `drains delete`
+
+Needs `--yes`.
+
+```sh
+littlefriend drains delete drn_... --yes
+```
+
+```ts
+{ drain: DrainInfo }
+```
+
+### Help
+
+#### `guide`
+
+Prints the agent setup guide that ships with this version of the CLI.
+
+```sh
+littlefriend guide
+```
+
+```ts
+{ guide: string; bundled: boolean }
+```
+
+`littlefriend help <command>` or `--help` on any command shows its flags and an example.
+
+## License
+
+MIT