CLI Reference
Install the CLI first if you have not set it up yet:
npm
npm install -g @beeai/cliVerify installation:
bee versionAuthentication
bee login
Authenticate with your Bee account.
bee login
bee login --qr
bee login --no-wait
bee login --token <token>
bee login --token-stdin
bee login --proxy http://127.0.0.1:8787
bee login --proxy ~/.bee/proxy.sockBy default bee login prints an authentication link and then blocks, polling until you approve the connection (up to ~5 minutes). Use --no-wait to print the link and exit immediately without polling — useful for agents and automation: send the link to the user, then run bee status to confirm, or re-run bee login to resume the same (unexpired) session and finish.
Use --proxy <url|socket> when another trusted local process handles Bee API authentication and this CLI should send requests through it. See API documentation for proxy details.
bee status
Check your authentication status.
bee statusbee logout
Clear your stored credentials.
bee logoutUser Data
bee me
Fetch your user profile information.
markdown
bee meExample output
# Profile
- timezone: America/Los_Angeles
- first_name: Alex
- last_name: Riverabee today
Get today’s brief including calendar events and emails. Use --context for Bee wearable context (daily summary, active todos, notes, conversations) instead.
markdown
bee today
bee today --contextExample output
# Today Brief
- timezone: America/Los_Angeles
- calendar_events: (none)
- emails: (none)bee now
Fetch recent conversations with utterances. See Agentic Now for agent-focused guidance.
markdown
bee nowExample output
# Now
- timezone: America/Los_Angeles
## Conversation 987654
> To read the full conversation, run: `bee conversations get 987654`
- start_time: 2026-02-10 09:00 [3 hours ago]
- end_time: 2026-02-10 09:25 [2 hours ago]
- state: COMPLETED
Roadmap planning for Q1 milestones
Utterances
- Alex: Let's lock scope for the next sprint.
- Sam: I will draft the release checklist today.bee activity
Show recent activity across conversations, summaries, notes, todos, and insights.
markdown
bee activity
bee activity --limit 20bee changed
Retrieve recently changed entities. See Agentic Sync for details.
markdown
bee changed
bee changed --cursor <cursor>Example output
# Changed
From: 2026-02-09 13:43 [1 day ago]
Until: 2026-02-10 13:43 [0 seconds ago]
Next Cursor: v1-1770759786297
# Confirmed Facts
- Prefers morning meetings
-----
# Pending Facts
- Steve is confused about where current AMIs come from in his deployment pipeline
- Steve needs cloud-init functionality to touch functions on the fly during deployment
-----
# Conversations
- timezone: America/Los_Angeles
### Conversation 6531525
- start_time: 2026-02-10 10:14 [3 hours ago]
- end_time: 2026-02-10 10:54 [3 hours ago]Facts
Manage your personal facts and preferences.
bee facts list
List your facts.
markdown
bee facts list
bee facts list --limit 50
bee facts list --cursor <cursor>
bee facts list --unconfirmedExample output
# Confirmed Facts
- User prefers morning standups.
- User keeps project notes in markdown.
-----
## Pagination
- next_cursor: v1-1762285321128-6777613bee facts get
Retrieve a specific fact by ID.
markdown
bee facts get <id>bee facts create
Create a new fact.
markdown
bee facts create --text "Prefers morning meetings"Example output
# Fact 9001
- timezone: America/Los_Angeles
- created_at: 2026-02-10 12:30 [just now]
- confirmed: false
- text: Prefers morning meetingsbee facts update
Update an existing fact. Omit --text when you only want to change confirmation status; the CLI preserves the existing fact text.
markdown
bee facts update <id> --text "Updated fact"
bee facts update <id> --text "Updated fact" --confirmed true
bee facts update <id> --confirmed trueExample output
# Fact 9001
- timezone: America/Los_Angeles
- created_at: 2026-02-10 12:30 [5 minutes ago]
- confirmed: true
- text: Updated factbee facts confirm
Confirm a fact while preserving its existing text. This is a shortcut for bee facts update <id> --confirmed true.
markdown
bee facts confirm <id>bee facts delete
Delete a fact.
markdown
bee facts delete <id>Example output
Deleted fact 9001.bee facts search
Search your saved facts by text query.
markdown
bee facts search --query "morning meetings"
bee facts search --query "morning meetings" --limit 20Todos
Manage your todos.
bee todos list
List your todos.
markdown
bee todos list
bee todos list --limit 50
bee todos list --cursor <cursor>Example output
# Todos
## Open
### Todo 1001
- timezone: America/Los_Angeles
- created_at: 2026-02-10 08:30 [4 hours ago]
- alarm_at: n/a
- completed: false
- text: Draft release notes
## Completed
- (none)bee todos get
Retrieve a specific todo by ID.
markdown
bee todos get <id>bee todos create
Create a new todo.
markdown
bee todos create --text "Review the roadmap"
bee todos create --text "Review the roadmap" --alarm-at 2026-02-11T09:00:00ZExample output
# Todo 1002
- timezone: America/Los_Angeles
- created_at: 2026-02-10 12:40 [just now]
- alarm_at: 2026-02-11 01:00 [in 12 hours]
- completed: false
- text: Review the roadmapbee todos update
Update an existing todo.
markdown
bee todos update <id> --text "Updated todo"
bee todos update <id> --completed true
bee todos update <id> --alarm-at 2026-02-11T09:00:00Z
bee todos update <id> --clear-alarmExample output
# Todo 1002
- timezone: America/Los_Angeles
- created_at: 2026-02-10 12:40 [10 minutes ago]
- alarm_at: n/a
- completed: true
- text: Updated todobee todos complete
Mark a todo complete. A shortcut for bee todos update <id> --completed true.
markdown
bee todos complete <id>bee todos delete
Delete a todo.
markdown
bee todos delete <id>Example output
Deleted todo 1002.bee todos suggestions
List pending Bee-suggested todos. These are action items Bee proposed from your conversations that you have not yet accepted or dismissed.
markdown
bee todos suggestions
bee todos suggestions --limit 20bee todos accept-suggestion
Accept a suggested todo, turning it into a real todo.
markdown
bee todos accept-suggestion <id>bee todos dismiss-suggestion
Dismiss a suggested todo.
markdown
bee todos dismiss-suggestion <id>Conversations
Access your conversation history.
bee conversations list
List conversations.
markdown
bee conversations list
bee conversations list --limit 20
bee conversations list --cursor <cursor>bee conversations get
Retrieve a specific conversation by ID, including its full transcript.
markdown
bee conversations get <id>bee conversations transcript
Retrieve just the transcript utterances for a conversation. Use --since <epochMs> to return only utterances spoken at or after a timestamp, which is useful when polling for new transcript lines.
markdown
bee conversations transcript <id>
bee conversations transcript <id> --since 1770700000000bee conversations related
Find conversations related to a given conversation.
markdown
bee conversations related <id>
bee conversations related <id> --limit 10Daily Summaries
Access daily summaries.
bee daily list
List daily summaries.
markdown
bee daily list
bee daily list --limit 20
bee daily list --cursor <cursor>bee daily get
Retrieve a specific daily summary by ID.
markdown
bee daily get <id>bee daily find
Find the daily summary for a specific date (YYYY-MM-DD).
markdown
bee daily find 2026-02-10Journals
Access your journals.
bee journals list
List journals.
markdown
bee journals list
bee journals list --limit 20
bee journals list --cursor <cursor>bee journals get
Retrieve a specific journal by ID.
markdown
bee journals get <id>bee journals search
Search your voice notes and journal entries by text query.
markdown
bee journals search --query "car"
bee journals search --query "car" --limit 20Insights
Access Bee’s insights about you.
bee insights list
List recent insights.
markdown
bee insights list
bee insights list --limit 20
bee insights list --cursor <cursor>bee insights get
Retrieve a specific insight by ID.
markdown
bee insights get <id>External Access
See which external services Bee used on your behalf and what data they received.
bee external-access list
List external access records, newest first. Each record includes the service, data type, a
human-readable summary, the description of what was sent, whether a connected account was
used (uses_connected_account), and created_at/updated_at timestamps.
markdown
bee external-access list
bee external-access list --limit 20
bee external-access list --cursor <cursor>Locations
Access where you have been.
bee locations clusters
Show places grouped by visit frequency.
markdown
bee locations clusters
bee locations clusters --limit 20
bee locations clusters --min-visits 3
bee locations clusters --visitsUse --min-visits N to only include places visited at least N times, and --visits to include the individual visits within each cluster.
bee locations recent
Show recent individual visits.
markdown
bee locations recent
bee locations recent --limit 20
bee locations recent --from 2026-02-01 --to 2026-02-10Bound the window with --from <date> and --to <date>.
bee locations current
Show your latest known location.
markdown
bee locations currentPhotos
Access photos synced from your photo gallery. Photos are imported from your phone’s photo library, not captured by the device.
bee photos list
List photos, newest first. Filter by daily summary or date.
markdown
bee photos list
bee photos list --limit 20
bee photos list --daily-id 100
bee photos list --date 2026-02-10bee photos get
Download one photo by ID. Use --output <path> to choose where to write the file.
markdown
bee photos get <id>
bee photos get <id> --output ~/Downloads/photo.jpgSearch
Search your Bee data. See Search for default vs neural guidance.
bee search
Keyword search (default) runs a BM25 index across conversations, daily summaries, and facts. Scope it with --filter conversations|daily|facts|all and order it with --sort relevance|mostRecent. Use --neural for semantic conversation search (conversations only; --filter and --sort do not apply). Bound either mode by time with --since/--until (epoch milliseconds).
markdown
bee search --query "project roadmap"
bee search --query "project roadmap" --limit 20
bee search --query "project roadmap" --filter conversations
bee search --query "project roadmap" --filter daily --sort mostRecent
bee search --query "project roadmap" --since 1770700000000 --until 1770759786297
bee search --query "What do you know about me?" --neural
bee search --query "project roadmap" --neural --limit 10| Option | Applies to | Description |
|---|---|---|
--query <text> | both | The search query (required). |
--limit N | both | Maximum number of results (1–100). |
--neural | — | Use semantic conversation search instead of keyword search. |
--filter conversations|daily|facts|all | keyword | Scope which entity types are searched. Defaults to all. |
--scope conversations|all | keyword | Alias for --filter (conversations or all). |
--sort relevance|mostRecent | keyword | Order results by relevance or recency. Defaults to relevance. |
--since <epochMs> | both | Only return items at or after this time (epoch milliseconds). |
--until <epochMs> | both | Only return items at or before this time (epoch milliseconds). |
--json | both | Print raw JSON instead of markdown. |
--filter, --scope, and --sort cannot be combined with --neural. Neural search is conversation-only and always ordered by relevance.
Threads
Chat with the Bee agent in threads, the same chats you see in the app. These commands use the Threads API.
Preview: test users only. Other accounts get test_user_required, and the commands may still change.
bee threads list
List your threads with their id, name, and state (idle or running), most recently active first.
markdown
bee threads listExample output
# Threads
- Trip planning (idle)
- thread_id: 5f1c2a9e-0b7d-5a3e-a1c4-7d2e9b8f6a01
- updated_at: 2026-02-10 12:30 [5 minutes ago]bee threads create
Start a new thread with a first message and wait for the agent’s answer. Attach photos with --photo and other files with --file. Both are repeatable, up to 20 per message and 25 MB each.
markdown
bee threads create --text "Plan my day"
bee threads create --text "What is in this photo?" --photo ./photo.jpg
bee threads create --text "Summarize these" --file ./notes.pdf --file ./budget.xlsx
bee threads create --text "Plan my day" --timeout 5m
bee threads create --text "Plan my day" --client-message-id plan-day-1Example output
You have two meetings this morning, then the afternoon is free for the release checklist.
- thread_id: 5f1c2a9e-0b7d-5a3e-a1c4-7d2e9b8f6a01
- message_id: 8a3b6c1d-2e4f-5a6b-a7c8-9d0e1f2a3b4c
- status: completed
- client_message_id: bee-cli-3f2b8c1e-6d4a-4b9e-9c7f-2a1d0e5b8f63The answer text comes first in markdown output. --json prints the full result: status, thread_id, message_id, client_message_id, plus hint while not answered, text and messages once completed, and files when you attached any.
bee threads send
Send a message to an existing thread and wait for the answer. It takes the same options as create.
markdown
bee threads send <thread-id> --text "Move the dentist to Friday"
bee threads send <thread-id> --text "And this one?" --photo ./receipt.png
bee threads send <thread-id> --text "Move the dentist to Friday" --timeout 0bee threads wait
Keep waiting for the agent’s answer. By default it waits after the thread’s latest user message. Pass --after <message-id> to wait after a specific message.
markdown
bee threads wait <thread-id>
bee threads wait <thread-id> --after <message-id>
bee threads wait <thread-id> --timeout 10mbee threads messages
Show a thread’s messages, oldest first. Use --limit N to show only the latest N.
markdown
bee threads messages <thread-id>
bee threads messages <thread-id> --limit 10When --limit leaves messages out, the JSON output includes omitted_earlier, the number of older messages not shown.
bee threads abort
Stop the agent’s current work on a thread. The thread becomes idle. Send a new message to continue.
markdown
bee threads abort <thread-id>Send and wait options
| Option | Applies to | Description |
|---|---|---|
--text <text> | create, send | Message text, up to 100,000 characters. Optional when you attach files. |
--photo <path> | create, send | Attach an image, such as jpg, png, gif, webp or heic. Repeatable. |
--file <path> | create, send | Attach any other file. Repeatable. The content type comes from the extension. |
--timeout <duration> | create, send, wait | How long to wait for the answer overall, for example 30s, 5m or 1h (a bare number is seconds, maximum 24h). Defaults to 90s. 0 sends without waiting. |
--client-message-id <id> | create, send | Idempotency key, 1 to 128 characters from A-Z a-z 0-9 . _ : -. Generated when omitted. |
--after <message-id> | wait | Wait after this message instead of the latest user message. |
--json | all | Print raw JSON instead of markdown. |
If the answer isn’t ready in time, the command still succeeds. It prints status: pending with the thread id, the message id, and a hint to run bee threads wait <thread-id>. status: stalled means the agent hasn’t reported progress for a while. Wait again, or run bee threads abort and send again.
--timeout covers the whole send and wait, retries included. Uploads happen first and don’t count against it. The send itself always gets at least 10 seconds, so --timeout 0 still delivers the message.
Every send prints its client_message_id, and retries reuse it, so a message is never sent twice. If a run is interrupted, or shows message_id: (not confirmed), re-run the same command with --client-message-id <id>. That resumes the message instead of sending a new one, and for create it returns the same thread. Photos and files are uploaded before the message is sent. If any upload fails, nothing is sent. Attachments also need the Bee agent consent in the Bee app.
Utility Commands
bee sync
Export your Bee data to local markdown files. Re-runs into the same output directory are incremental by default — only daily summaries, conversations, and insights that changed since the last run are re-fetched (facts and todos are always synced in full). See Full Sync for details.
bee sync
bee sync --output ~/my-bee-data
bee sync --only facts,todos
bee sync --only insights
bee sync --recent-days 7
bee sync --full
bee sync --since 1770700000000| Option | Default | Description |
|---|---|---|
--output <dir> | bee-sync | Output directory for synced files. |
--recent-days N | all | Limit daily summaries, conversations, and insights to the last N days. Applies to full syncs only; ignored on an incremental run. |
--only <targets> | all | Comma-separated list to limit the sync: facts, todos, daily, conversations, insights (or all). |
--full | off | Force a complete re-sync, ignoring the saved manifest, and rewrite it with fresh cursors. |
--since <epochMs> | — | Advanced/recovery: override the saved incremental cursor with an explicit epoch-milliseconds timestamp. |
bee stream
Stream real-time events from Bee. See Realtime Sync for details.
# Human-readable with colors (default)
bee stream
# Human-readable, token-optimized for inference (no colors)
bee stream --agent
# Structured JSON output
bee stream --json
# Optional event filtering
bee stream --types new-utterance,update-conversation --agent
bee stream --types new-utterance,update-conversation --jsonbee proxy
Start a local Bee API proxy. See API documentation for details. Authenticate with bee login before starting it.
# TCP listener (default auto-picks from 8787)
bee proxy
bee proxy --port 8787
bee proxy --idle-timeout 300
# Unix socket listener (default: ~/.bee/proxy.sock)
bee proxy --socket
bee proxy --socket /tmp/bee-proxy.sock| Option | Default | Description |
|---|---|---|
--port N | auto from 8787 | TCP port to listen on. |
--socket [path] | ~/.bee/proxy.sock | Listen on a Unix socket instead of TCP. Optionally provide a path. |
--idle-timeout SECONDS | 120 | Server idle timeout. Use 0 to disable idle request timeouts (helpful for large exports). |
bee mcp
Run or connect the CLI as a Model Context Protocol server so assistants like Claude and Codex can read your Bee context. See MCP for the full guide, the serve-http security model, and the tool catalog.
bee mcp connect claude # Claude Desktop (one-click install)
bee mcp connect claude-code # Claude Code (CLI)
bee mcp connect codex # Codex
bee mcp status # show what's connected
bee mcp disconnect claude-code # remove a connection
bee mcp serve # stdio JSON-RPC (what the connectors launch)
bee mcp serve-http --token <value> # local HTTP on 127.0.0.1:8790 (default port), bearer-token auth
bee mcp serve-http --port 9000 --token <value> # ...or choose a port with --portThe connectors authenticate with your existing Bee login (run bee login first); there is no extra token to manage for the stdio transport. serve-http requires an auth token of at least 32 characters via --token or the BEE_MCP_HTTP_TOKEN environment variable, binds to 127.0.0.1 only, and clients send it as Authorization: Bearer <token>. See MCP for details.
bee ping
Check connectivity to Bee servers.
bee ping
bee ping --count 5bee version
Display the CLI version.
markdown
bee versionGlobal Options
These options are available at the top-level command:
| Option | Description |
|---|---|
--help | Show help |
--version | Show version number |
Run bee <command> --help for detailed information about any command.