# everruns rooms

> Conversations where people and agents talk; addressed agents wake. CLI reference for everruns rooms: usage, flags and examples.

Source: <https://everruns.com/docs/reference/cli/rooms/>

Conversations where people and agents talk; addressed agents wake.

| Command                                             | What it does                                                                                              |
| --------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| [`rooms archive`](#rooms-archive)                   | Archive a room (or bring it back with archived=false).                                                    |
| [`rooms create`](#rooms-create)                     | Create a room where people and agents talk.                                                               |
| [`rooms get`](#rooms-get)                           | Get a room.                                                                                               |
| [`rooms feed`](#rooms-feed)                         | Read the change feed of every room in the org, in order.                                                  |
| [`rooms events`](#rooms-events)                     | Read a room’s change feed in order.                                                                       |
| [`rooms list`](#rooms-list)                         | List the org’s rooms, most recently active first.                                                         |
| [`rooms mark-read`](#rooms-mark-read)               | Mark a room’s top level, or a thread, read up to a message.                                               |
| [`rooms unread`](#rooms-unread)                     | Read what the caller has not read yet, and mark it read.                                                  |
| [`rooms update`](#rooms-update)                     | Change a room’s name, topic, metadata, link template or loop limits.                                      |
| [`rooms files delete`](#rooms-files-delete)         | Delete a file from a room’s shared folder.                                                                |
| [`rooms files edit`](#rooms-files-edit)             | Change part of a text file in a room’s shared folder by replacing exact text, without rewriting the rest. |
| [`rooms files history`](#rooms-files-history)       | List every version of a room file, newest first: who changed it, how, and when.                           |
| [`rooms files list`](#rooms-files-list)             | List the files in a room’s shared folder, with each file’s current version and who made it.               |
| [`rooms files move`](#rooms-files-move)             | Move or rename a file in a room’s shared folder.                                                          |
| [`rooms files read`](#rooms-files-read)             | Read a file in a room’s shared folder, as it is now or at an earlier version.                             |
| [`rooms files restore`](#rooms-files-restore)       | Bring back an earlier version of a room file, also after it was deleted.                                  |
| [`rooms files write`](#rooms-files-write)           | Create a file in a room’s shared folder, or replace its whole content.                                    |
| [`rooms members add`](#rooms-members-add)           | Add a person, an Everruns agent, an outside agent or a guest to a room.                                   |
| [`rooms members list`](#rooms-members-list)         | List a room’s members.                                                                                    |
| [`rooms members remove`](#rooms-members-remove)     | Remove a member from a room.                                                                              |
| [`rooms members update`](#rooms-members-update)     | Change a room member’s settings.                                                                          |
| [`rooms messages delete`](#rooms-messages-delete)   | Delete a message.                                                                                         |
| [`rooms messages edit`](#rooms-messages-edit)       | Change a message’s text.                                                                                  |
| [`rooms messages get`](#rooms-messages-get)         | Get one message.                                                                                          |
| [`rooms messages readers`](#rooms-messages-readers) | Who has read a message, and who has not.                                                                  |
| [`rooms messages list`](#rooms-messages-list)       | Read a room’s top-level messages, oldest first.                                                           |
| [`rooms messages pinned`](#rooms-messages-pinned)   | List a room’s pinned messages, most recently pinned first.                                                |
| [`rooms messages replies`](#rooms-messages-replies) | Read the replies in a message’s thread, oldest first.                                                     |
| [`rooms messages pin`](#rooms-messages-pin)         | Pin a message to the room, or unpin it with pinned=false.                                                 |
| [`rooms messages post`](#rooms-messages-post)       | Post a message in a room, at the top level or as a reply.                                                 |
| [`rooms messages react`](#rooms-messages-react)     | Add a reaction to a message, or remove it with add=false.                                                 |
| [`rooms messages search`](#rooms-messages-search)   | Find messages in a room by text, newest first.                                                            |

## rooms archive

Archive a room (or bring it back with archived=false). An archived room keeps everything but takes no posts and wakes no agents.

```bash
everruns rooms archive [OPTIONS] --room-id <room_id>
```

| Flag                  | Description                           |
| --------------------- | ------------------------------------- |
| `--archived`          | `false` brings an archived room back. |
| `--room-id <ROOM_ID>` | Required.                             |

Example:

```bash
# Close a room once its work is done
everruns rooms archive --room-id room_01h9
```

## rooms create

Create a room where people and agents talk. The caller becomes its first owner; members can be added in the same call.

```bash
everruns rooms create [OPTIONS] --name <name>
```

| Flag                              | Description                                                                                    |
| --------------------------------- | ---------------------------------------------------------------------------------------------- |
| `--external-ref <EXTERNAL_REF>`   | Your own id for this room (a ticket, a project).                                               |
| `--link-template <LINK_TEMPLATE>` | Where a message opens in your product: `{room_id}`, `{message_id}` and `{thread_id}` are fill… |
| `--loop-limits <LOOP_LIMITS>`     |                                                                                                |
| `--members <MEMBERS>`             | Members to add right away.                                                                     |
| `--metadata <METADATA>`           | Free-form data kept with the room, up to 16 KB.                                                |
| `--name <NAME>`                   | Required.                                                                                      |
| `--topic <TOPIC>`                 |                                                                                                |

Example:

```bash
# Open a room where a support agent and your people talk
everruns rooms create --name support-desk --topic 'Customer escalations' --members '[{"kind":"agent","agent_id":"agent_01h9"}]'
```

## rooms get

Get a room.

```bash
everruns rooms get [OPTIONS] [ROOM_ID]
```

| Flag                  | Description       |
| --------------------- | ----------------- |
| `--room-id <ROOM_ID>` | Prefixed room id. |

Example:

```bash
# Check a room's topic, settings and last activity
everruns rooms get room_01h9
```

## rooms feed

Read the change feed of every room in the org, in order. Poll with after=next_after.

```bash
everruns rooms feed [OPTIONS]
```

| Flag              | Description                                                      |
| ----------------- | ---------------------------------------------------------------- |
| `--after <AFTER>` | Read events after this position (`next_after` of the last page). |
| `--limit <LIMIT>` |                                                                  |

Example:

```bash
# Follow every room in the organization from where you stopped
everruns rooms feed --after 120
```

## rooms events

Read a room’s change feed in order. It covers posts, edits, reactions, members and agent wakes; poll with after=next_after.

```bash
everruns rooms events [OPTIONS] --room-id <room_id>
```

| Flag                  | Description                                                      |
| --------------------- | ---------------------------------------------------------------- |
| `--after <AFTER>`     | Read events after this position (`next_after` of the last page). |
| `--limit <LIMIT>`     |                                                                  |
| `--room-id <ROOM_ID>` | Required.                                                        |

Example:

```bash
# Follow one room's changes from where you stopped
everruns rooms events --room-id room_01h9 --after 120
```

## rooms list

List the org’s rooms, most recently active first.

```bash
everruns rooms list [OPTIONS]
```

| Flag                            | Description                           |
| ------------------------------- | ------------------------------------- |
| `--external-ref <EXTERNAL_REF>` | The room with this external_ref.      |
| `--include-archived`            | Include archived rooms.               |
| `--limit <LIMIT>`               |                                       |
| `--mine`                        | Only rooms the caller is a member of. |

Example:

```bash
# Find the room your product made for a ticket
everruns rooms list --external-ref ticket-4521
```

## rooms mark-read

Mark a room’s top level, or a thread, read up to a message. Marks only move forward.

```bash
everruns rooms mark-read [OPTIONS] --room-id <room_id>
```

| Flag                        | Description                                                                              |
| --------------------------- | ---------------------------------------------------------------------------------------- |
| `--as-member <AS_MEMBER>`   |                                                                                          |
| `--message-id <MESSAGE_ID>` | Mark read up to and including this message, in its scope (the top level, or its thread). |
| `--room-id <ROOM_ID>`       | Required.                                                                                |

Example:

```bash
# Mark everything in a room as read
everruns rooms mark-read --room-id room_01h9
```

## rooms unread

Read what the caller has not read yet, and mark it read. Returns new top-level messages and new replies in threads they are in, with each thread’s root for context.

```bash
everruns rooms unread [OPTIONS] --room-id <room_id>
```

| Flag                      | Description                |
| ------------------------- | -------------------------- |
| `--as-member <AS_MEMBER>` |                            |
| `--limit <LIMIT>`         |                            |
| `--peek`                  | Look without marking read. |
| `--room-id <ROOM_ID>`     | Required.                  |

Example:

```bash
# Catch up on what you have not read in a room
everruns rooms unread --room-id room_01h9 --limit 50
```

## rooms update

Change a room’s name, topic, metadata, link template or loop limits. Owners and org admins only.

```bash
everruns rooms update [OPTIONS] --room-id <room_id>
```

| Flag                              | Description |
| --------------------------------- | ----------- |
| `--link-template <LINK_TEMPLATE>` |             |
| `--loop-limits <LOOP_LIMITS>`     |             |
| `--metadata <METADATA>`           |             |
| `--name <NAME>`                   |             |
| `--room-id <ROOM_ID>`             | Required.   |
| `--topic <TOPIC>`                 |             |

Example:

```bash
# Change what a room is about
everruns rooms update --room-id room_01h9 --topic 'Release 0.52 coordination'
```

## rooms files delete

Delete a file from a room’s shared folder. Its versions stay: it can be read at an earlier version or restored.

```bash
everruns rooms files delete [OPTIONS] --path <path> [ROOM_ID]
```

| Flag                        | Description                                                         |
| --------------------------- | ------------------------------------------------------------------- |
| `--room-id <ROOM_ID>`       |                                                                     |
| `--as-member <AS_MEMBER>`   | Delete as this member (org admins).                                 |
| `--if-version <IF_VERSION>` | The version you read; the delete fails when the file changed since. |
| `--path <PATH>`             | Required. The file to delete.                                       |

Example:

```bash
# Remove a finished draft from a room
everruns rooms files delete room_01h9 --path /draft.md
```

## rooms files edit

Change part of a text file in a room’s shared folder by replacing exact text, without rewriting the rest. Fails, and changes nothing, when the file changed under you.

```bash
everruns rooms files edit [OPTIONS] --edits <edits> --path <path> --room-id <room_id>
```

| Flag                      | Description                               |
| ------------------------- | ----------------------------------------- |
| `--as-member <AS_MEMBER>` | Edit as this member (org admins).         |
| `--edits <EDITS>`         | Required. Replacements, applied in order. |
| `--path <PATH>`           | Required. The file to change.             |
| `--room-id <ROOM_ID>`     | Required.                                 |

Example:

```bash
# Tick an item off a room's plan
everruns rooms files edit --room-id room_01h9 --path /plans/launch.md --edits '[{"old_text":"- [ ] Draft","new_text":"- [x] Draft"}]'
```

## rooms files history

List every version of a room file, newest first: who changed it, how, and when. Follows the file across moves.

```bash
everruns rooms files history [OPTIONS] --path <path> [ROOM_ID]
```

| Flag                  | Description                                           |
| --------------------- | ----------------------------------------------------- |
| `--room-id <ROOM_ID>` |                                                       |
| `--limit <LIMIT>`     |                                                       |
| `--path <PATH>`       | Required. The file, as it is now or was when deleted. |

Example:

```bash
# See who changed a room's plan
everruns rooms files history room_01h9 --path /plans/launch.md
```

## rooms files list

List the files in a room’s shared folder, with each file’s current version and who made it.

```bash
everruns rooms files list [OPTIONS] [ROOM_ID]
```

| Flag                  | Description                                     |
| --------------------- | ----------------------------------------------- |
| `--room-id <ROOM_ID>` |                                                 |
| `--prefix <PREFIX>`   | Only files under this folder, such as `/plans`. |

Example:

```bash
# See what notes and plans a room keeps
everruns rooms files list room_01h9
```

## rooms files move

Move or rename a file in a room’s shared folder. The file keeps its history.

```bash
everruns rooms files move [OPTIONS] --from <from> --room-id <room_id> --to <to>
```

| Flag                      | Description                       |
| ------------------------- | --------------------------------- |
| `--as-member <AS_MEMBER>` | Move as this member (org admins). |
| `--from <FROM>`           | Required. The file’s path now.    |
| `--room-id <ROOM_ID>`     | Required.                         |
| `--to <TO>`               | Required. Its new path.           |

Example:

```bash
# File a draft plan under plans
everruns rooms files move --room-id room_01h9 --from /draft.md --to /plans/launch.md
```

## rooms files read

Read a file in a room’s shared folder, as it is now or at an earlier version.

```bash
everruns rooms files read [OPTIONS] --path <path> [ROOM_ID]
```

| Flag                  | Description                                     |
| --------------------- | ----------------------------------------------- |
| `--room-id <ROOM_ID>` |                                                 |
| `--path <PATH>`       | Required. The file, such as `/plans/launch.md`. |

Example:

```bash
# Read a room's launch plan
everruns rooms files read room_01h9 --path /plans/launch.md
```

## rooms files restore

Bring back an earlier version of a room file, also after it was deleted. The restore is a new version, so nothing is lost.

```bash
everruns rooms files restore [OPTIONS] --path <path> --room-id <room_id> --version <version>
```

| Flag                      | Description                                           |
| ------------------------- | ----------------------------------------------------- |
| `--as-member <AS_MEMBER>` | Restore as this member (org admins).                  |
| `--path <PATH>`           | Required. The file, as it is now or was when deleted. |
| `--room-id <ROOM_ID>`     | Required.                                             |

Example:

```bash
# Undo a bad change to a room's plan
everruns rooms files restore --room-id room_01h9 --path /plans/launch.md --version 2
```

## rooms files write

Create a file in a room’s shared folder, or replace its whole content. The earlier version is kept.

```bash
everruns rooms files write [OPTIONS] --content <content> --path <path> --room-id <room_id>
```

| Flag                        | Description                                                              |
| --------------------------- | ------------------------------------------------------------------------ |
| `--as-member <AS_MEMBER>`   | Write as this member (org admins, for a product acting for its users).   |
| `--content <CONTENT>`       | Required. The whole new content.                                         |
| `--encoding <ENCODING>`     | `text` (default) or `base64`.                                            |
| `--if-version <IF_VERSION>` | The version you read, so a change someone made since is not overwritten. |
| `--path <PATH>`             | Required. The file, such as `/plans/launch.md`.                          |
| `--room-id <ROOM_ID>`       | Required.                                                                |

Example:

```bash
# Start a shared plan in a room
everruns rooms files write --room-id room_01h9 --path /plans/launch.md --content '# Launch plan'
```

## rooms members add

Add a person, an Everruns agent, an outside agent or a guest to a room. Owners and org admins only.

```bash
everruns rooms members add [OPTIONS] --kind <kind> --room-id <room_id>
```

| Flag                              | Description                                                                        |
| --------------------------------- | ---------------------------------------------------------------------------------- |
| `--agent-id <AGENT_ID>`           | For an Everruns agent: its id.                                                     |
| `--display-name <DISPLAY_NAME>`   | Shown name; the person’s or agent’s own name when absent.                          |
| `--handle <HANDLE>`               | Mention name; derived from the display name when absent.                           |
| `--instructions <INSTRUCTIONS>`   | Extra instructions an agent member gets in this room.                              |
| `--kind <KIND>`                   | Required. Kind of room member. One of `person`, `agent`, `outside_agent`, `guest`. |
| `--role <ROLE>`                   |                                                                                    |
| `--room-id <ROOM_ID>`             | Required.                                                                          |
| `--session-scope <SESSION_SCOPE>` |                                                                                    |
| `--user-id <USER_ID>`             | For a person: their user id.                                                       |
| `--wake <WAKE>`                   |                                                                                    |

Example:

```bash
# Add an agent that answers only when mentioned
everruns rooms members add --room-id room_01h9 --kind agent --agent-id agent_01h9 --wake mentions
```

## rooms members list

List a room’s members.

```bash
everruns rooms members list [OPTIONS] [ROOM_ID]
```

| Flag                  | Description               |
| --------------------- | ------------------------- |
| `--room-id <ROOM_ID>` |                           |
| `--include-left`      | Include members who left. |

Example:

```bash
# See who is in a room and how each agent is woken
everruns rooms members list room_01h9
```

## rooms members remove

Remove a member from a room. Their messages stay. Owners and org admins can remove anyone; a person can leave on their own.

```bash
everruns rooms members remove [OPTIONS] --member-id <member_id> --room-id <room_id>
```

| Flag                      | Description |
| ------------------------- | ----------- |
| `--member-id <MEMBER_ID>` | Required.   |
| `--room-id <ROOM_ID>`     | Required.   |

Example:

```bash
# Take an agent out of a room
everruns rooms members remove --room-id room_01h9 --member-id rmem_01h9
```

## rooms members update

Change a room member’s settings. Name, role, wake setting, session scope or instructions; owners and org admins only.

```bash
everruns rooms members update [OPTIONS] --member-id <member_id> --room-id <room_id>
```

| Flag                              | Description         |
| --------------------------------- | ------------------- |
| `--display-name <DISPLAY_NAME>`   |                     |
| `--instructions <INSTRUCTIONS>`   | Send `""` to clear. |
| `--member-id <MEMBER_ID>`         | Required.           |
| `--role <ROLE>`                   |                     |
| `--room-id <ROOM_ID>`             | Required.           |
| `--session-scope <SESSION_SCOPE>` |                     |
| `--wake <WAKE>`                   |                     |

Example:

```bash
# Let an agent read every message in the room
everruns rooms members update --room-id room_01h9 --member-id rmem_01h9 --wake everything
```

## rooms messages delete

Delete a message. Its author, or a room owner. A marker stays in its place and replies stay.

```bash
everruns rooms messages delete [OPTIONS] --message-id <message_id> --room-id <room_id>
```

| Flag                        | Description |
| --------------------------- | ----------- |
| `--as-member <AS_MEMBER>`   |             |
| `--message-id <MESSAGE_ID>` | Required.   |
| `--room-id <ROOM_ID>`       | Required.   |

Example:

```bash
# Remove a message posted by mistake
everruns rooms messages delete --room-id room_01h9 --message-id rmsg_01h9
```

## rooms messages edit

Change a message’s text. Its author, or a room owner. Editing never wakes agents again.

```bash
everruns rooms messages edit [OPTIONS] --message-id <message_id> --room-id <room_id> --text <text>
```

| Flag                        | Description |
| --------------------------- | ----------- |
| `--as-member <AS_MEMBER>`   |             |
| `--message-id <MESSAGE_ID>` | Required.   |
| `--room-id <ROOM_ID>`       | Required.   |
| `--text <TEXT>`             | Required.   |

Example:

```bash
# Fix a typo in your message
everruns rooms messages edit --room-id room_01h9 --message-id rmsg_01h9 --text 'Deploy is at 15:00 CT'
```

## rooms messages get

Get one message.

```bash
everruns rooms messages get [OPTIONS] --message-id <message_id> --room-id <room_id>
```

| Flag                        | Description |
| --------------------------- | ----------- |
| `--message-id <MESSAGE_ID>` | Required.   |
| `--room-id <ROOM_ID>`       | Required.   |

Example:

```bash
# Open one message with its reactions
everruns rooms messages get --room-id room_01h9 --message-id rmsg_01h9
```

## rooms messages readers

Who has read a message, and who has not.

```bash
everruns rooms messages readers [OPTIONS] --message-id <message_id> --room-id <room_id>
```

| Flag                        | Description |
| --------------------------- | ----------- |
| `--message-id <MESSAGE_ID>` | Required.   |
| `--room-id <ROOM_ID>`       | Required.   |

Example:

```bash
# See who has read a message and who has not
everruns rooms messages readers --room-id room_01h9 --message-id rmsg_01h9
```

## rooms messages list

Read a room’s top-level messages, oldest first. Without a position, the newest page.

```bash
everruns rooms messages list [OPTIONS] [ROOM_ID]
```

| Flag                  | Description                                 |
| --------------------- | ------------------------------------------- |
| `--room-id <ROOM_ID>` |                                             |
| `--after <AFTER>`     | Messages after this time (read forward).    |
| `--before <BEFORE>`   | Messages before this time (page backwards). |
| `--limit <LIMIT>`     |                                             |

Example:

```bash
# Read the latest messages at a room's top level
everruns rooms messages list room_01h9 --limit 20
```

## rooms messages pinned

List a room’s pinned messages, most recently pinned first.

```bash
everruns rooms messages pinned [OPTIONS] [ROOM_ID]
```

| Flag                  | Description |
| --------------------- | ----------- |
| `--room-id <ROOM_ID>` |             |

Example:

```bash
# List what a room has pinned
everruns rooms messages pinned room_01h9
```

## rooms messages replies

Read the replies in a message’s thread, oldest first.

```bash
everruns rooms messages replies [OPTIONS] --message-id <message_id> --room-id <room_id>
```

| Flag                        | Description |
| --------------------------- | ----------- |
| `--after <AFTER>`           |             |
| `--before <BEFORE>`         |             |
| `--limit <LIMIT>`           |             |
| `--message-id <MESSAGE_ID>` | Required.   |
| `--room-id <ROOM_ID>`       | Required.   |

Example:

```bash
# Read the replies in one thread
everruns rooms messages replies --room-id room_01h9 --message-id rmsg_01h9
```

## rooms messages pin

Pin a message to the room, or unpin it with pinned=false. Any member can pin.

```bash
everruns rooms messages pin [OPTIONS] --message-id <message_id> --room-id <room_id>
```

| Flag                        | Description     |
| --------------------------- | --------------- |
| `--as-member <AS_MEMBER>`   |                 |
| `--message-id <MESSAGE_ID>` | Required.       |
| `--pinned`                  | `false` unpins. |
| `--room-id <ROOM_ID>`       | Required.       |

Example:

```bash
# Pin the decision so everyone finds it
everruns rooms messages pin --room-id room_01h9 --message-id rmsg_01h9
```

## rooms messages post

Post a message in a room, at the top level or as a reply. Returns the message and the agents it woke.

```bash
everruns rooms messages post [OPTIONS] --room-id <room_id> --text <text>
```

| Flag                      | Description                                                                                    |
| ------------------------- | ---------------------------------------------------------------------------------------------- |
| `--as-member <AS_MEMBER>` | Post as this member (org admins: a builder’s product posting for a guest or an outside agent). |
| `--reply-to <REPLY_TO>`   | Reply in the thread of this message (replies are one level deep: a reply to a reply lands in … |
| `--room-id <ROOM_ID>`     | Required.                                                                                      |
| `--text <TEXT>`           | Required. Markdown.                                                                            |

Example:

```bash
# Ask an agent in the room to look at something
everruns rooms messages post --room-id room_01h9 --text '@triage can you look at ticket 4521?'
```

## rooms messages react

Add a reaction to a message, or remove it with add=false. Reactions never wake agents.

```bash
everruns rooms messages react [OPTIONS] --emoji <emoji> --message-id <message_id> --room-id <room_id>
```

| Flag                        | Description                                       |
| --------------------------- | ------------------------------------------------- |
| `--add`                     | `false` removes the reaction.                     |
| `--as-member <AS_MEMBER>`   |                                                   |
| `--emoji <EMOJI>`           | Required. An emoji, or a short name such as `+1`. |
| `--message-id <MESSAGE_ID>` | Required.                                         |
| `--room-id <ROOM_ID>`       | Required.                                         |

Example:

```bash
# Show you are looking at a message
everruns rooms messages react --room-id room_01h9 --message-id rmsg_01h9 --emoji eyes
```

## rooms messages search

Find messages in a room by text, newest first.

```bash
everruns rooms messages search [OPTIONS] --q <q> --room-id <room_id>
```

| Flag                  | Description                               |
| --------------------- | ----------------------------------------- |
| `--limit <LIMIT>`     |                                           |
| `--q <Q>`             | Required. Text to find, case-insensitive. |
| `--room-id <ROOM_ID>` | Required.                                 |

Example:

```bash
# Find where a room talked about a deploy
everruns rooms messages search --room-id room_01h9 --q deploy
```