bee-cli

What this skill does

# Bee CLI

CLI client for Bee - the wearable AI that captures conversations and learns about you.

## About Bee

Bee is a wearable AI device that continuously captures and transcribes ambient audio from the owner's daily life: conversations, meetings, phone calls, and any spoken interactions. From these transcriptions Bee automatically extracts facts about the owner - preferences, relationships, work projects, commitments, and personal details - and produces daily summaries, insights, and a location history.

### Privacy and Security

**Bee data is extremely sensitive.** Transcriptions contain intimate details of the owner's personal and professional life, including private conversations never intended to be recorded or shared.

**All Bee data is end-to-end encrypted and accessible only to the owner.** Only the authenticated owner can read their content; no third party (including Bee's servers) can read the decrypted data.

**Treat all Bee information as highly confidential.** The owner has entrusted access to their most private conversations and personal details. Never expose, forward, or store this data outside what the user explicitly asks for.

## Capability Map - Which Command for Which Question

Pick the command by what the user is asking. Reach for `bee search` instead of manually listing-and-scanning whenever the question is "did I ever / when did I / what did we say about ...".

| The user wants to know... | Use |
| --- | --- |
| What's happening right now / what was just said (last 10h) | `bee now` |
| Today's plan, calendar, email brief | `bee today` |
| Today's wearable context (summary + active todos + notes + conversations) | `bee today --context` |
| Recent activity across everything (conversations, summaries, notes, todos, insights) | `bee activity` |
| Find conversations/daily/facts about a topic | `bee search --query "..."` |
| Semantic ("what was the vibe / find similar") search of conversations | `bee search --query "..." --neural` |
| Full verbatim transcript of one conversation | `bee conversations transcript <id>` (or `get <id>`) |
| Conversations similar to a given one | `bee conversations related <id>` |
| Who the owner is / preferences / relationships / work | `bee facts list`, `bee facts search --query "..."` |
| Action items / commitments | `bee todos list`; suggestions via `bee todos suggestions` |
| What happened on a given day | `bee daily find <YYYY-MM-DD>` |
| Browse day-by-day summaries | `bee daily list` |
| Owner's intentional voice memos | `bee journals list`, `bee journals search --query "..."` |
| AI-generated patterns/insights about the owner | `bee insights list` |
| Where the owner has been / frequent places / current location | `bee locations recent`, `bee locations clusters`, `bee locations current` |
| Photos captured by the device | `bee photos list`, `bee photos get <id> --output PATH` |
| What changed since last check (incremental monitoring) | `bee changed --cursor <cursor>` |
| Export everything to local markdown (backup / offline) | `bee sync` |
| Who am I authenticated as | `bee me`, `bee status` |

**Output format:** every data command prints markdown by default. Add `--json` for programmatic parsing - prefer it whenever you will parse the output rather than show it to the user.

**Source of truth:** conversation **summaries** (from `list`, `daily`, `search` results) are AI-generated and may contain minor inaccuracies. **Utterances** (from `bee now`, `conversations get`, `conversations transcript`) are verbatim and authoritative. When accuracy matters, read the utterances.

**Pagination:** list responses return a `next_cursor` field (null when there is no more data). Pass its value back via the `--cursor` flag to fetch the next page.

## Installation

Check if installed:
```bash
bee --version
```

If not installed:
```bash
npm install -g @beeai/cli
```

Or download binaries from https://github.com/bee-computer/bee-cli/releases/latest

## Authentication

Check status:
```bash
bee status
```

If not authenticated:
```bash
bee login
```

**Prefer `bee login --no-wait` (recommended for agents).** Plain `bee login` BLOCKS, polling for up to ~5 minutes until the user approves — which stalls you waiting for the command to return. Instead:

```bash
bee login --no-wait    # prints the auth link and exits immediately (no polling)
```

It prints an authentication URL like `https://bee.computer/connect#{requestId}`, saves a resumable session, and returns. Then: **send the link to the user**, and once they say they've approved it, run `bee status` to confirm (or `bee login` again to finish). Re-running `bee login --no-wait` before approval resumes the same link.

If you DO want a blocking interactive session, plain `bee login` prints the same link and then polls automatically until approval; do not interrupt while it waits. Either way the request expires in ~5 minutes; on approval the CLI prints a success message with the user's name.

Login flags: `--no-wait` (print link and exit), `--token <token>`, `--token-stdin`, `--proxy <url|socket>` (the last three are mutually exclusive; `--no-wait` applies to the interactive flow only).

To see the authenticated profile: `bee me [--json]`. To sign out: `bee logout`.

## Real-Time Context (Use First!)

**Always start with `bee now`.** It fetches all conversations from the **last 10 hours** with their full utterances - the single most valuable context for timely, relevant help.

```bash
bee now          # markdown
bee now --json   # programmatic
```

Returns, for the past 10 hours: conversations with verbatim utterances (who said what), summaries, states, and timestamps in the owner's timezone.

Use it when the owner just finished a conversation and needs follow-up, is asking about something just discussed, or you need current context for suggestions.

### Today

```bash
bee today              # Today Brief: calendar / email-style daily brief
bee today --context    # Wearable context: daily summary + active todos + notes + recent conversations
bee today --json
```

Use plain `bee today` for the day's plan; use `--context` when you want the same aggregated wearable context an assistant would use to ground the day.

### Recent Activity

```bash
bee activity [--limit N]   # --limit max 20
```

A unified recent feed across conversations, summaries, notes, todos, and insights. Good for "what have I been up to lately" at a glance.

## Searching - Prefer Over Manual Scanning

`bee search` runs server-side and is the right tool for topic/recall questions. Do **not** list every conversation and read it yourself when you can search.

```bash
bee search --query "marathon training" [--limit N] [--since <epochMs>] [--until <epochMs>] [--json]
```

Two modes:

- **Keyword (default):** BM25 over conversations, daily summaries, and facts.
  - `--filter conversations|daily|facts|all` (default `all`) - scope what is searched.
  - `--scope conversations|all` - alias that maps onto `--filter`.
  - `--sort relevance|mostRecent` (default `relevance`); `--sortBy` is an accepted alias.
- **Semantic / neural (`--neural`):** vector search over **conversations only**. The keyword-only flags (`--filter`/`--scope`/`--sort`/`--sortBy`) are rejected in this mode. Use it for fuzzy/conceptual recall ("find when I talked about feeling burned out").

`--since` and `--until` (epoch milliseconds) bound results by time and work in **both** modes.

```bash
bee search --query "project atlas deadline" --filter conversations --sort mostRecent
bee search --query "how I felt about the move" --neural --limit 10
bee search --query "dentist" --filter facts
```

Note: `--cursor` is **not** supported by search and will error; use `--since`/`--until` to page through time instead. Todos and insights are not searchable here - use `bee todos list` and `bee insights list`.

## Facts - Learn About the Owner

Facts are what Bee has learned about the owner from conversations - the primary way to understand who they are.

*