---
name: enclave
description: Post to, read from and manage Enclave bots with the `enclave` command-line tool on this Mac or server. Use when the user asks to send a message, alert, report or file to an Enclave community, channel or feed; to read what a bot has received; to add a bot to a conversation; or to set up, run or check an Enclave bot.
---

# Enclave bots (`enclave` CLI)

`enclave` runs Enclave bot accounts. A bot belongs to one community, can only join the
conversations an admin allowed, and every message it sends is end-to-end encrypted on this machine.
Docs for people: https://useenclave.com/docs/bots/ (this skill is added by `enclave add skill`; run it again
after `enclave update`).

## First, look

```sh
enclave status          # JSON: daemon running?, each bot (name, username, access, org)
enclave conversations   # tab-separated: id, kind, title — where the bot is now
```

- With several bots, every command needs `--bot NAME` (the `name` from `status`).
- `access: "write"` = posts only: it **cannot read**, so `history` and `listen` show nothing.
  `read_write` reads and posts.
- If `enclave` isn't found, it's usually in `~/.local/bin` or `/usr/local/bin`. If it isn't installed,
  tell the user: the Enclave team sends the install command.

## Send

```sh
enclave send --to feed "Weekly numbers are in"                  # the community feed (a post)
enclave send --to "#christmas-carnival" "Stalls open at 5pm"    # a channel or group by title
enclave send --to <conversation-id> "text" --file report.pdf   # by id; --file repeatable
enclave send --to "#alerts" "db-1 disk at 92%" --loud           # notifies people
enclave send --to "#ops" "Done" --reply-to <message-id>
```

- Quiet by default: the message arrives but nobody's phone buzzes. Use `--loud` only when the user
  wants people alerted.
- Output is JSON: `{"conversation", "id", "seq"}`. Keep `id` to reply to or react to it later.
- Text supports Slack-style Markdown (`*bold*`, `_italic_`, `` `code` ``, fenced code blocks).
- Limit: 30 messages a minute, bursts of 10. On `rate_limited`, wait the `retryAfter` seconds.
  Don't loop sends; batch into one message.

## Not in the conversation yet

`send` fails with "not in a conversation called …". Then:

```sh
enclave join "#channel-name"    # or: enclave join feed / enclave join <id>
```

- It works only if an admin turned the conversation on under the bot's **Can join** (in the app:
  You → the community → Bots → the bot). If it says the bot isn't allowed in, the error lists where it
  may go; ask the user to turn the conversation on. You can't grant it from the CLI.
- After asking, a member's device adds the bot when Enclave is open on it. That usually takes
  seconds, and longer if nobody is online. Check with `enclave conversations` before sending. A
  running daemon (`enclave run`) asks by itself every 30 s.

## Read (bots that read and post)

```sh
enclave history --to "#ops" --limit 50        # recent messages, JSON
enclave listen                                 # one JSON object per line until stopped
enclave react --to "#ops" <message-id> "👍"    # --remove to take it back
```

`listen` runs until stopped. Run it with a timeout or in the background, and never block on it.
Events: `item` (text, post, comment, reaction, edit, delete, poll, …), `joined`, `left`, `members`.

## The daemon

`enclave run` keeps bots connected, joins newly allowed conversations and serves a local API on
`$state/enclave.sock`. While it runs, other commands go through it automatically. Long-lived uses
(watching, replying) need it. Don't start a second one; check `enclave status` first.

## Setting up a bot (only with the user's token)

An admin creates the bot in the app, which shows `enclave enroll <token> --relay https://relay.useenclave.com`
once. Run exactly what the user gives you. The token works once, for 24 hours. If it's used or expired,
the admin opens the pending bot and taps **New enrollment command**.

## Don't

- Don't run `enclave remove`: it deletes the bot's keys on this machine. Only do it if the user asks.
- Don't post to the feed or send `--loud` unless the user asked for that.
- Don't copy or print anything from the state folder (`~/Library/Application Support/Enclave CLI`,
  `/var/lib/enclave`): it holds the bot's private keys and session.
- Don't promise someone saw a message. Bots don't get read receipts.
