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 ...".

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:

bee --version

If not installed:

npm install -g @beeai/cli

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

Authentication

Check status:

bee status

If not authenticated:

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:

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.

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

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

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.

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.

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.

Confirmed vs. unconfirmed:

• Confirmed facts are verified by the owner or clearly stated. Trust them.
• Unconfirmed facts are inferred from context and may be misinterpretations. Use for context/speculation only, and flag the uncertainty when you act on them.

Prefer confirmed facts. List unconfirmed-only with --unconfirmed.

bee facts list [--limit N] [--cursor <cursor>] [--unconfirmed] [--json]
bee facts get <id> [--json]
bee facts search --query "allergies" [--limit N] [--json]
bee facts create --text "I prefer morning meetings" [--json]
bee facts update <id> --text "Updated text" [--confirmed <true|false>] [--json]
bee facts delete <id> [--json]

facts update requires --text; pass --confirmed true or --confirmed false to also change the confirmation state. Use bee facts search rather than paging through facts list when looking for something specific.

Conversations - Access Transcripts

Conversations are records of captured ambient audio.

bee conversations list [--limit N] [--cursor <cursor>] [--json]
bee conversations get <id> [--json]
bee conversations transcript <id> [--json]
bee conversations related <id> [--limit N] [--json]   # --limit max 10

• list returns summaries only - browse to find relevant conversations. The response includes next_cursor for paging.
• get returns the full conversation: utterances (verbatim, with speaker and timestamps), state, and metadata.
• transcript returns just the verbatim utterance transcript for one conversation.
• related finds conversations similar to a given one - useful for assembling all discussions on a thread/topic.

For accuracy, read utterances from get/transcript. Summaries from list are for browsing only.

For topic search, prefer bee search over listing everything manually.

Daily Summaries

bee daily list [--limit N] [--cursor <cursor>] [--json]   # browse day-by-day
bee daily get <id> [--json]
bee daily find <YYYY-MM-DD> [--json]                      # look up a specific date

There is no bare bee daily and no --date flag. To get a specific day, use bee daily find 2026-06-01.

Journals - Voice Memos

Journals are intentional voice memos the owner records (distinct from ambient conversations). Aka voice notes.

bee journals list [--limit N] [--cursor <cursor>] [--json]
bee journals search --query "ideas for the talk" [--limit N] [--json]
bee journals get <id> [--json]

list returns entries with id, state (PREPARING = recording, ANALYZING = processing, READY = complete), transcribed text, and timestamps. get returns the full transcribed text. Use journals search to find a memo by content.

Insights

AI-generated patterns and observations about the owner.

bee insights list [--limit N] [--json]   # --limit max 50
bee insights get <id> [--json]

Use when the user wants higher-level patterns rather than raw conversations.

Locations

Where the owner has been.

bee locations recent [--from <date>] [--to <date>] [--limit N] [--json]   # --limit max 100
bee locations clusters [--limit N] [--min-visits N] [--visits] [--json]   # frequent places; --limit max 20
bee locations current [--json]                                            # latest known location

--from/--to accept YYYY-MM-DD or an ISO timestamp (owner's timezone). clusters groups frequently visited places; --min-visits N filters by visit count and --visits includes per-visit detail. Use for "where was I on ...", "what places do I go", "where am I now".

Photos

Photos captured by the device.

bee photos list [--daily-id N] [--date YYYY-MM-DD] [--limit N] [--json]   # --limit max 20
bee photos get <id> [--output PATH] [--json]

Scope list by a daily summary id or by date. get retrieves a single photo; pass --output PATH to save it to disk.

Todos - Track Commitments

Action items and commitments, including ones Bee suggests from conversations.

bee todos list [--limit N] [--cursor <cursor>] [--json]
bee todos get <id> [--json]
bee todos create --text "Buy groceries" [--alarm-at <iso>] [--json]
bee todos update <id> [--text "Updated"] [--completed <true|false>] [--alarm-at <iso> | --clear-alarm] [--json]
bee todos complete <id> [--json]
bee todos delete <id> [--json]

• --completed takes a value: --completed true or --completed false. To simply mark done, use the dedicated bee todos complete <id>.
• On update, set a reminder with --alarm-at <iso> or remove one with --clear-alarm (mutually exclusive).

Suggestions workflow - Bee proposes todos from conversations; review and act on them:

bee todos suggestions [--limit N] [--json]      # --limit max 50; list proposed todos
bee todos accept-suggestion <id> [--json]       # promote a suggestion to a real todo
bee todos dismiss-suggestion <id> [--json]      # reject a suggestion

Monitoring Changes - bee changed vs bee sync

Two ways to stay current. Choose based on whether you want to know what changed or have a complete local copy.

bee changed - incremental changefeed (know what's new)

Best for periodic checks: it tells you exactly what changed and gives a cursor to resume from. Defaults to roughly the last 24 hours when no cursor is given.

bee changed [--cursor <cursor>] [--json]

Returns the covered time range, a Next Cursor: line (and next_cursor in JSON), and the changed facts, todos, daily summaries, conversations, and journals (new and updated).

Cursor handling - persist the cursor only after you finish processing the batch, so a failure lets you retry the same changes (exactly-once processing):

1. Read the stored cursor from .bee-cursor (if it exists). (.bee-cursor is a convention this skill uses, not a CLI feature.)
2. Run bee changed --cursor <cursor> (omit --cursor on the first run).
3. Note the Next Cursor: value but do not save it yet.
4. Process all returned changes (update notes, handle todos, etc.).
5. Only after success, save the new cursor: echo "<value>" > .bee-cursor.
6. Repeat.

bee sync - export to local markdown (have a copy)

Exports Bee data to markdown files for offline backup, full-text search, or feeding other tools.

bee sync [--output <dir>] [--recent-days N] [--full] [--since <epochMs>] [--only <facts|todos|daily|conversations>]

• Incremental by default. Re-runs re-fetch only changed daily summaries and conversations using a .bee-sync.json manifest stored in the output dir (facts and todos are always fully re-fetched). The first run is a full sync.
• --output <dir> - output directory (default bee-sync).
• --full - force a complete re-sync, ignoring the manifest.
• --since <epochMs> - advanced/recovery override of the saved incremental cursor.
• --recent-days N - limit daily/conversations to the last N days. Applies to full syncs only (first run or --full); ignored on incremental re-runs.
• --only <list> - sync only some types: facts, todos, daily, conversations (comma-separated).

Note: sync does not reconcile deletions (removed items are not pruned locally). If you need to know precisely what changed rather than maintain a mirror, use bee changed.

Common Workflows

Quick context about the owner

Run in this order:

bee now            # last 10h with full utterances - most important
bee facts list     # who the owner is: preferences, relationships, work
bee today --context  # today's aggregated wearable context

bee now makes help relevant and timely; facts and today's context fill in the bigger picture.

Find something from a past conversation

Prefer search over manual scanning:

bee search --query "the topic or person" --filter conversations --sort mostRecent
bee conversations get <id>     # read verbatim utterances for the best hit

If recall is fuzzy/conceptual, use --neural. Use bee conversations related <id> to gather the rest of a thread.

Where was I / where do I go

bee locations current
bee locations recent --from 2026-06-01 --to 2026-06-06
bee locations clusters --min-visits 5 --visits

Export all data for AI context

bee sync --output ./my-bee-data

Creates markdown for facts, todos, daily summaries, and conversation transcripts; re-run to incrementally update.

Deep Learning About the Owner

To build comprehensive knowledge of the owner by processing their full conversation history, use this multi-agent workflow. It processes conversations in batches via a chain of subagents, passing state through files to preserve context.

Each subagent: fetches a batch of conversations, reads the current user.md, extracts insights, updates user.md, writes a handoff summary, and spawns the next subagent for older conversations.

Tip: for targeted questions, bee search is usually faster than a full deep-learning pass. Use deep learning only when you genuinely need the whole history.

File Structure

In the working directory:

• user.md - cumulative profile of the owner (persistent, updated each batch).
• bee-learning-summary.md - handoff: latest summary plus the next_cursor for the next batch.
• bee-learning-progress.md - progress log of what was processed and when.

Step 1: Initialize (Main Agent)

Create user.md if absent:

# User Profile

Learned information about the owner from their Bee conversations.

## Basic Information
## Relationships
## Work & Projects
## Interests & Hobbies
## Preferences
## Important Dates & Events
## Notes

Step 2: First Processing Subagent

Spawn a subagent with this task:

Process Bee conversations to learn about the owner.

1. Fetch the 100 most recent conversations (use --json to parse reliably):
   bee conversations list --limit 100 --json

2. Read the current user.md file.

3. For each conversation, extract: who the owner talked to (relationships),
   topics (interests, work), personal details (preferences, facts),
   commitments made, and important dates/events.

4. Update user.md, merging (do not overwrite) and adding timestamps.

5. Write bee-learning-summary.md with: date range processed, key insights,
   the next_cursor value from the API response, and running count.

6. Update bee-learning-progress.md.

7. If next_cursor is non-null, spawn the next subagent to continue with
   older conversations. Pass only file paths, not content.

Step 3: Chain Processing Subagents

Each subsequent subagent:

Continue processing Bee conversations to learn about the owner.

1. Read bee-learning-summary.md to get the next_cursor for the next batch.

2. Fetch the next 100 conversations:
   bee conversations list --limit 100 --cursor <next_cursor_from_summary> --json

3. Read user.md.

4. Extract insights as before.

5. Update user.md (merge, do not overwrite).

6. Update bee-learning-summary.md with: new date range, new insights,
   the new next_cursor (or "complete" if null), updated total count.

7. Update bee-learning-progress.md.

8. If next_cursor is non-null, spawn the next subagent. If null (end reached),
   write the final summary and report completion.

Step 4: Progress Reporting

After roughly each week's worth of conversations, report to the main conversation: what was learned, notable events, and significant profile changes. This keeps the user informed without overwhelming detail.

Conversation List API

bee conversations list --limit 100 --json
bee conversations list --limit 100 --cursor <next_cursor> --json

The response includes a conversations array and a next_cursor field (null when there is no more data). Page by passing the previous next_cursor back via --cursor.

Best Practices

1. File-based handoff - pass state between subagents via files, never by copying large text into prompts.
2. Incremental merge - each subagent merges into user.md with clear headers and timestamps; never replace it.
3. Progress tracking - keep bee-learning-progress.md so you can resume after interruption.
4. Periodic summaries - report meaningfully (e.g., per week processed), not after every batch.
5. Graceful completion - when next_cursor is null, write a final summary and notify the user.
6. Error handling - on failure, the next attempt reads the progress files and resumes.

When to Use Deep Learning

Use it when: first establishing a relationship with a new user; the user requests a comprehensive history analysis; building context for a long-term assistant relationship; the user wants to understand patterns in their own conversations.

Do not use it for: quick questions about recent events (use bee now, bee daily find, or bee activity); looking up specific facts (use bee facts list / bee facts search); finding a particular conversation (use bee search).

MCP Server

The bee CLI is also an MCP server, so Bee tools can be exposed directly to MCP-aware clients.

bee mcp serve                              # stdio JSON-RPC server
bee mcp serve-http --token <value> [--port N]   # HTTP server; token >= 32 chars (or env BEE_MCP_HTTP_TOKEN)
bee mcp connect <claude|claude-code|codex>       # register Bee with a client
bee mcp disconnect <claude|claude-code|codex>
bee mcp status

Utility Commands

bee me [--json]            # authenticated profile
bee status                 # auth status
bee version [--json]
bee ping [--count N]       # connectivity check
bee stream [--types <list>] [--json] [--agent] [--webhook-endpoint <url> --webhook-body <template>]
bee proxy [--port N] [--socket [path]] [--idle-timeout SECONDS]