convos-cli

Category: Tools & Productivity | Uploader: xmtplabs | Downloads: 0 | Version: v1.0（Latest）
Use when working with Convos messaging - privacy-focused ephemeral messaging with per-conversation identities, invites, profiles, and group management via the convos CLI tool
Changelog: Source: GitHub https://github.com/xmtplabs/convos-cli
Directory Structure

Current level: skills/convos-cli/
📄 SKILL.md 28.9 KB
SKILL.md

---
name: convos-cli
description: Use when working with Convos messaging - privacy-focused ephemeral messaging with per-conversation identities, invites, profiles, and group management via the convos CLI tool
---

# Convos CLI

The Convos CLI (`convos`) is a command-line tool for privacy-focused ephemeral messaging built on [XMTP](https://xmtp.org). Unlike standard XMTP, Convos creates a **unique identity per conversation** so conversations cannot be linked or correlated.

Key differences from standard XMTP:

- **Per-conversation identities**: Each conversation gets its own wallet, inbox, and database
- **No global wallet key**: Identities are created automatically when creating/joining conversations
- **Invite system**: Serverless QR code + URL invites for joining conversations
- **Per-conversation profiles**: Different display name and avatar in each conversation
- **Explode**: Permanently destroy a conversation and all cryptographic keys
- **Lock**: Prevent new members from being added

## Prerequisites

### Initialize Configuration

```bash
# generate config and save to default path (~/.convos/.env)
convos init

# output config to console instead of writing to file
convos init --stdout

# initialize for production environment
convos init --env production

# overwrite existing config
convos init --force

# initialize with a custom data directory (useful for multiple agents)
convos init --home /path/to/agent1-data

# or use the CONVOS_HOME environment variable
CONVOS_HOME=/path/to/agent1-data convos init
```

This creates a `.env` file with:

- `CONVOS_ENV` - Network environment (local, dev, production)
- `CONVOS_API_KEY` - Agent API key for uploads (auto-selects `convos-api` provider)
- `CONVOS_UPLOAD_PROVIDER` - Upload provider override (`convos-api`, `pinata`, `s3`)

**Note:** Unlike standard XMTP, there is no global wallet key. Each conversation creates its own identity stored in `~/.convos/identities/`.

### Custom Data Directory

By default, all data is stored in `~/.convos/`. To use a different directory (e.g., when running multiple agents on one machine), use the `--home` flag or the `CONVOS_HOME` environment variable:

```bash
# via flag (works on any command)
convos conversations list --home /path/to/agent-data

# via environment variable
export CONVOS_HOME=/path/to/agent-data
convos conversations list
```

Priority: `--home` flag > `CONVOS_HOME` env var > `~/.convos`

### Configuration Loading Priority

1. CLI flags (highest priority)
2. Explicit `--env-file <path>`
3. `.env` in the current working directory
4. `<convos-home>/.env` (default: `~/.convos/.env`)

## Command Structure

```
convos [TOPIC] [COMMAND] [ARGUMENTS] [FLAGS]
```

### Topics

| Topic | Purpose |
| ----- | ------- |
| `agent` | Agent mode — long-running sessions with streaming I/O |
| `identity` | Manage per-conversation identities (inboxes) |
| `conversations` | List, create, join, and stream conversations |
| `conversation` | Interact with a specific conversation |

### Standalone Commands

| Command | Purpose |
| ------- | ------- |
| `init` | Initialize configuration and directory structure |
| `reset` | Delete all identities and conversation data (preserves .env) |
| `schema` | Introspect CLI commands as machine-readable JSON (args, flags, examples) |

## Output Modes

All commands support `--json` for machine-readable JSON output:

```bash
convos conversations list --json
```

Use `--fields` to limit JSON output to specific fields (implicitly enables `--json`). Supports dot notation for nested paths:

```bash
# only get message id, content, and sender
convos conversation messages <id> --fields id,content,senderInboxId

# nested field extraction
convos conversation messages <id> --fields id,content,contentType.typeId,sentAt

# works on any command
convos conversation profiles <id> --fields profiles
convos conversations list --fields conversationId,name
```

Use `--verbose` to see detailed client initialization logs. When combined with `--json`, verbose output goes to stderr:

```bash
convos identity info <id> --verbose
convos conversations list --json --verbose 2>/dev/null
```

## Common Workflows

### Create a Conversation

```bash
# create a conversation (auto-creates a per-conversation identity)
convos conversations create --name "My Group" --profile-name "Alice"

# create with admin-only permissions
convos conversations create --name "Announcement Channel" --permissions admin-only

# create and capture the conversation ID
CONV_ID=$(convos conversations create --name "Test" --json | jq -r '.conversationId')
```

### Send Messages

```bash
# send a text message
convos conversation send-text <conversation-id> "Hello, world!"

# send a reaction
convos conversation send-reaction <conversation-id> <message-id> add "👍"
# remove a reaction
convos conversation send-reaction <conversation-id> <message-id> remove "👍"

# send a reply referencing another message
convos conversation send-reply <conversation-id> <message-id> "Replying to you"

# reply with a photo
convos conversation send-reply <conversation-id> <message-id> --file ./photo.jpg

# reply with a large file (auto-uploaded via provider)
convos conversation send-reply <conversation-id> <message-id> --file ./video.mp4
```

### Send Attachments

```bash
# send a photo (small files ≤1MB sent inline, large files auto-uploaded via provider)
convos conversation send-attachment <conversation-id> ./photo.jpg

# force remote upload even for small files
convos conversation send-attachment <conversation-id> ./photo.jpg --remote

# override MIME type
convos conversation send-attachment <conversation-id> ./file.bin --mime-type image/png

# use upload provider via flags (no .env needed)
convos conversation send-attachment <conversation-id> ./photo.jpg \
  --upload-provider pinata --upload-provider-token <jwt>

# encrypt only — outputs encrypted file + decryption keys for manual upload
convos conversation send-attachment <conversation-id> ./photo.jpg --encrypt

# send a pre-uploaded encrypted file with decryption keys
convos conversation send-remote-attachment <conversation-id> <url> \
  --content-digest <hex> --secret <base64> --salt <base64> \
  --nonce <base64> --content-length <bytes> --filename photo.jpg

# download an attachment (handles both inline and remote transparently)
convos conversation download-attachment <conversation-id> <message-id>

# download to a specific path
convos conversation download-attachment <conversation-id> <message-id> --output ./photo.jpg

# save encrypted payload without decrypting
convos conversation download-attachment <conversation-id> <message-id> --raw
```

To enable automatic upload for large files, set your agent API key in `.env`:

```bash
CONVOS_API_KEY=<your-agent-api-key>
```

This auto-selects the `convos-api` upload provider. Other providers (`pinata`, `s3`) are also available via `CONVOS_UPLOAD_PROVIDER`.

### Read Messages

```bash
# list messages (default: descending order)
convos conversation messages <conversation-id>
# sync from network and limit results
convos conversation messages <conversation-id> --sync --limit 10
```

### Stream Messages in Real-Time

```bash
# stream messages from a single conversation
convos conversation stream <conversation-id>
# stop after 60 seconds
convos conversation stream <conversation-id> --timeout 60
```

### List Conversations

```bash
# list all conversations across all identities
convos conversations list
# sync from network before listing
convos conversations list --sync
```

### Invite System

Convos uses a serverless invite system. The creator generates a cryptographic invite URL; the person joining must open the URL in the Convos app (or scan the QR code); then the creator processes the join request to add them to the group.

**Important: Adding someone to a conversation is a multi-step process:**

1. **Generate an invite** (creator side) — produces a URL and QR code
2. **Person opens the invite URL in Convos or scans the QR code** — this sends a join request to the creator via DM
3. **Creator processes the join request** — this validates the request and adds the person to the group

The creator must process join requests *after* the person has opened/scanned the invite. If you don't know when that will happen, use `--watch` with a timeout to stream and process requests as they arrive.

#### Create an Invite

```bash
# generate invite — displays QR code in terminal
convos conversation invite <conversation-id>

# generate invite with 1-hour expiry
convos conversation invite <conversation-id> --expires-in 3600

# single-use invite
convos conversation invite <conversation-id> --single-use

# JSON output (suppresses QR code)
convos conversation invite <conversation-id> --json

# capture invite URL for scripting
INVITE_URL=$(convos conversation invite <conversation-id> --json | jq -r '.url')
```

#### Person Joins via Invite

The person being invited must open the invite URL in the Convos app or scan the QR code with Convos. This can be done:

- **On iOS**: Open the URL in Safari (redirects to Convos app) or scan the QR code from within the app
- **Via CLI**: Use `convos conversations join`

```bash
# join using a raw invite slug
convos conversations join <invite-slug>

# join using a full invite URL
convos conversations join "https://dev.convos.org/v2?i=<slug>"

# join with a display name
convos conversations join <slug> --profile-name "Bob"

# send join request without waiting for acceptance
convos conversations join <slug> --no-wait

# wait up to 2 minutes for acceptance
convos conversations join <slug> --timeout 120
```

#### Process Join Requests (Creator Side)

After the person has opened/scanned the invite, the creator must process the join request:

```bash
# process all pending join requests (use when you know the invite has already been opened)
convos conversations process-join-requests

# process for a specific conversation only
convos conversations process-join-requests --conversation <id>

# watch for join requests with a timeout (use when you don't know when the invite will be opened)
convos conversations process-join-requests --watch --conversation <id>
# note: use ctrl-c or a timeout to stop watching

# continuously watch for all join requests (keep running in background)
convos conversations process-join-requests --watch
```

### Per-Conversation Profiles

Each conversation has independent profiles — you can have a different name and avatar in each.

Profile updates are sent as **ProfileUpdate messages** to the group. The CLI no longer writes profiles to `appData` (this was removed to fix a data corruption bug where concurrent read-modify-write cycles could erase invite tags and other members' profiles). When reading profiles, message-sourced profiles take precedence, with `appData` as a read-only fallback for profiles written by older clients (e.g., iOS).

When new members are added (via invite or directly), a **ProfileSnapshot message** is sent containing all current member profiles so the new joiner has everyone's data immediately — solving the MLS forward secrecy problem where older messages may be undecryptable.

Profile resolution precedence:
1. **Latest ProfileUpdate from that member** — highest priority, most recent self-authored update
2. **Most recent ProfileSnapshot containing that member** — fallback when no ProfileUpdate exists
3. **appData profiles** — legacy fallback for backward compatibility with older clients
4. **No profile** — member has no name/avatar set

Both ProfileUpdate and ProfileSnapshot are silent messages (`shouldPush = false`) — they do not appear in chat or trigger notifications.

```bash
# set display name
convos conversation update-profile <conversation-id> --name "Alice"

# set name and avatar
convos conversation update-profile <conversation-id> --name "Alice" --image "https://example.com/avatar.jpg"

# go anonymous (clear profile)
convos conversation update-profile <conversation-id> --name "" --image ""

# view all member profiles
convos conversation profiles <conversation-id>
convos conversation profiles <conversation-id> --json
```

### Identity Management

Identities are created automatically when creating/joining conversations, but you can manage them directly.

```bash
# list all identities
convos identity list

# create an identity manually
convos identity create --label "Work Chat" --profile-name "Alice"

# view identity details (connects to XMTP to show inbox ID)
convos identity info <identity-id>

# remove an identity (destroys all keys — irreversible)
convos identity remove <identity-id> --force
```

### Reset All Data

Delete all identities and conversation data. The `.env` configuration is preserved.

```bash
# reset with confirmation prompt
convos reset

# reset without confirmation
convos reset --force
```

### Group Management

```bash
# view members
convos conversation members <conversation-id>

# add members by inbox ID
convos conversation add-members <conversation-id> <inbox-id>

# remove members
convos conversation remove-members <conversation-id> <inbox-id>

# update group name
convos conversation update-name <conversation-id> "New Name"

# update group description
convos conversation update-description <conversation-id> "New description"

# view permissions
convos conversation permissions <conversation-id>
```

### Lock a Conversation

Prevent new members from joining by setting the addMember permission to deny. This also invalidates all existing invites. Only super admins can lock/unlock.

```bash
# lock
convos conversation lock <conversation-id>

# unlock (previously shared invites remain invalid — generate new ones)
convos conversation lock <conversation-id> --unlock
```

### Explode a Conversation

Permanently destroy a conversation and all its cryptographic keys. Sends an ExplodeSettings notification to all members (so iOS and other clients can trigger their cleanup), updates group metadata with the expiration timestamp, removes all members, then destroys the local identity. **Irreversible.**

```bash
# explode immediately
convos conversation explode <conversation-id> --force

# schedule explosion for a future date (ISO8601)
convos conversation explode <conversation-id> --scheduled "2025-03-01T00:00:00Z"
```

When scheduled, the ExplodeSettings message is sent with a future `expiresAt` date. Members are notified but not removed — clients handle cleanup when the time arrives. When immediate (no `--scheduled`), members are removed and the local identity is destroyed right away.

### Sync Data from Network

```bash
# sync conversation list
convos conversations sync

# sync a single conversation
convos conversation sync <conversation-id>
```

## Agent Mode

The `agent serve` command runs a long-running process that combines conversation creation, message streaming, join request processing, and stdin command handling — ideal for AI agents and bots.

### Quick Start (Agent)

```bash
# create a new conversation and start serving
convos agent serve --name "My Bot" --profile-name "Assistant"

# attach to an existing conversation
convos agent serve <conversation-id>

# create with admin-only permissions
convos agent serve --name "Agent" --permissions admin-only
```

### Protocol

The agent uses an **ndjson** (newline-delimited JSON) protocol:

- **stdout**: Events (one JSON object per line)
- **stdin**: Commands (one JSON object per line)
- **stderr**: QR code + diagnostic logs

#### Events (stdout)

| Event | Description | Key Fields |
| ----- | ----------- | ---------- |
| `ready` | Session started | `conversationId`, `inviteUrl`, `inboxId` |
| `message` | New message received | `id`, `senderInboxId`, `senderProfile` (optional: `name`, `image`), `content`, `contentType`, `sentAt`, `catchup` (optional) |
| `member_joined` | Member joined via invite | `inboxId`, `conversationId`, `catchup` (optional) |
| `sent` | Message sent confirmation | `id`, `text`, `replyTo` (optional), `type` (optional) |
| `heartbeat` | Periodic health check | `conversationId`, `activeStreams` |
| `error` | Error occurred | `message` |

Messages with `catchup: true` were fetched during stream reconnection (missed while disconnected).

#### Commands (stdin)

```jsonl
{"type":"send","text":"Hello, world!"}
{"type":"send","text":"Replying to you","replyTo":"<message-id>"}
{"type":"react","messageId":"<message-id>","emoji":"👍"}
{"type":"react","messageId":"<message-id>","emoji":"👍","action":"remove"}
{"type":"attach","file":"./photo.jpg"}
{"type":"attach","file":"./photo.jpg","replyTo":"<message-id>"}
{"type":"attach","file":"./photo.jpg","mimeType":"image/jpeg"}
{"type":"remote-attach","url":"https://...","contentDigest":"<hex>","secret":"<base64>","salt":"<base64>","nonce":"<base64>","contentLength":12345,"filename":"photo.jpg"}
{"type":"rename","name":"New Group Name"}
{"type":"lock"}
{"type":"unlock"}
{"type":"explode"}
{"type":"explode","scheduled":"2025-03-01T00:00:00Z"}
{"type":"stop"}
```

| Command | Required Fields | Optional Fields |
| ------- | --------------- | --------------- |
| `send` | `text` | `replyTo` |
| `react` | `messageId`, `emoji` | `action` (`add`/`remove`, default: `add`) |
| `attach` | `file` (local path) | `mimeType`, `replyTo` |
| `remote-attach` | `url`, `contentDigest`, `secret`, `salt`, `nonce`, `contentLength` | `filename`, `scheme` |
| `rename` | `name` | — |
| `lock` | — | — |
| `unlock` | — | — |
| `explode` | — | `scheduled` (ISO8601 date) |
| `stop` | — | — |

Small attachments (≤1MB) are sent inline. Larger files are auto-encrypted and uploaded via the configured upload provider (e.g., Pinata).

**Lock** prevents new members from joining by rotating the invite tag and setting addMember permission to deny. **Unlock** reverses this (previously shared invites remain invalid). **Explode** permanently destroys the conversation — sends ExplodeSettings notification, removes members, and deletes the local identity. Immediate explode triggers agent shutdown. **Rename** updates the conversation name visible to all members.

### How It Works

When started, `agent serve`:

1. **Creates or attaches** to a conversation
2. **Displays QR code** invite on stderr (so users can scan and join)
3. **Emits `ready` event** with conversation ID, invite URL, and identity info
4. **Processes pending join requests** from before the agent started
5. **Streams messages** — emits `message` events as they arrive in real-time
6. **Streams DM join requests** — automatically adds new members and emits `member_joined`
7. **Reads stdin** — accepts `send`, `rename`, `lock`, `unlock`, `explode`, and `stop` commands
8. **Emits heartbeat** (optional) — periodic health check events when `--heartbeat` is set
9. **Catches up on reconnect** — if a stream disconnects and reconnects, fetches any missed messages since the last seen timestamp

All of these run concurrently. The agent stays alive until `SIGINT`, `SIGTERM`, stdin close, a `stop` command, or an immediate `explode`.

### Example: Agent Integration

```bash
# Start the agent, pipe commands in, read events out
convos agent serve --name "Bot" --profile-name "AI Assistant" | while IFS= read -r event; do
  type=$(echo "$event" | jq -r '.event')
  case "$type" in
    ready)
      echo "Bot ready! Invite URL: $(echo "$event" | jq -r '.inviteUrl')" >&2
      ;;
    message)
      content=$(echo "$event" | jq -r '.content')
      echo "Received: $content" >&2
      # Send a reply (write JSON command to agent's stdin)
      msg_id=$(echo "$event" | jq -r '.id')
      echo "{\"type\":\"send\",\"text\":\"You said: $content\",\"replyTo\":\"$msg_id\"}"
      ;;
    member_joined)
      inbox=$(echo "$event" | jq -r '.inboxId')
      echo "New member: $inbox" >&2
      echo "{\"type\":\"send\",\"text\":\"Welcome!\"}"
      ;;
  esac
done
```

### Agent Flags

| Flag | Description |
| ---- | ----------- |
| `--name` | Conversation name (when creating new) |
| `--description` | Conversation description (when creating new) |
| `--permissions` | `all-members` or `admin-only` (when creating new) |
| `--profile-name` | Display name for this conversation |
| `--identity` | Use an existing unlinked identity |
| `--label` | Local label for the identity |
| `--no-invite` | Skip generating an invite (attach mode) |
| `--heartbeat` | Emit heartbeat events every N seconds (0 to disable, default: 0) |

## Important Concepts

### Per-Conversation Identities

Every conversation has its own:

- **Wallet key** (secp256k1 private key)
- **DB encryption key** (32-byte key)
- **XMTP inbox** (unique inbox ID)
- **Local database** (SQLite)

Identities are stored in `<convos-home>/identities/<id>.json`. Databases are stored in `<convos-home>/db/<env>/<id>.db3`. The data directory defaults to `~/.convos/` but can be overridden with `--home` or `CONVOS_HOME`.

### Invite Flow

1. **Creator** generates an invite URL/QR code (contains encrypted conversation token + creator's inbox ID)
2. **Person opens the invite URL in Convos app** (or scans the QR code) — this creates a per-conversation identity and sends a DM join request to the creator
3. **Creator processes the join request** — validates the invite signature, decrypts the conversation token, and adds the person to the group
4. Person is now a member with their own isolated identity

**Key point:** Step 3 must happen *after* step 2. The creator must either run `process-join-requests` after the invite has been opened, or use `--watch` to stream and process requests as they arrive.

### Profile Messages

Member profiles are stored as XMTP group messages using two custom content types:

- **`ProfileUpdate`** (`convos.org/profile_update:1.0`) — sent by a member when they change their own name or avatar. The sender's inbox ID is implicit from the XMTP message, preventing spoofing.
- **`ProfileSnapshot`** (`convos.org/profile_snapshot:1.0`) — sent after adding members to a group. Contains all current member profiles so new joiners have data immediately (solves MLS forward secrecy gap).

Both are silent (no push notification, not displayed in chat). The CLI reads `appData` profiles as a fallback for backward compatibility with older clients, but does not write profiles there. Custom XMTP content codecs (`ProfileUpdateCodec`, `ProfileSnapshotCodec`) are registered with the XMTP client at creation time so the SDK can decode these message types natively.

Profiles support typed **metadata** — arbitrary key-value pairs where values can be string, number (double), or boolean. Metadata is carried in both `ProfileUpdate` and `ProfileSnapshot` messages via a `map<string, MetadataValue>` protobuf field. Use `--metadata key=value` on `update-profile` (repeatable, auto-typed: "true"/"false" → bool, numeric → number, else string). Metadata merges with existing values (new keys overwrite, unmentioned keys preserved).

Profile **images** are encrypted end-to-end using the same scheme as iOS: HKDF-SHA256 derives a per-image AES-256-GCM key from the group's `imageEncryptionKey` (stored in appData) + random 32-byte salt, then encrypts with a random 12-byte nonce. The encrypted blob is uploaded via the configured upload provider and the URL + salt + nonce are sent as `EncryptedProfileImageRef` in the `ProfileUpdate` message. If no `imageEncryptionKey` exists for the group, the CLI generates one and writes it to appData.

Supported upload providers:
- **Convos API:** `CONVOS_UPLOAD_PROVIDER=convos-api`, `CONVOS_API_KEY=<agent-assets-api-key>`, optional `CONVOS_API_BASE_URL=<url>` (auto-derived from XMTP env: dev → `https://api.dev.convos.xyz/api`, production → `https://api.convos.xyz/api`). Uses the agent asset upload endpoint (`GET /v2/agents/assets/presigned`) with `X-Agent-API-Key` header auth — no JWT step needed.
- **Pinata (IPFS):** `CONVOS_UPLOAD_PROVIDER=pinata`, `CONVOS_UPLOAD_PROVIDER_TOKEN=<jwt>`, optional `CONVOS_UPLOAD_PROVIDER_GATEWAY=<url>`
- **S3 (direct):** `CONVOS_UPLOAD_PROVIDER=s3`, `CONVOS_UPLOAD_PROVIDER_TOKEN=<accessKeyId>:<secretAccessKey>`, `CONVOS_S3_BUCKET=<bucket>`, optional `CONVOS_S3_REGION=<region>` (default: us-east-1), optional `CONVOS_S3_ENDPOINT=<url>` (for S3-compatible services like MinIO, R2), optional `CONVOS_UPLOAD_PROVIDER_GATEWAY=<public-url-prefix>`

### Join Request Messages

Join requests use a structured content type instead of plain text:

- **`JoinRequest`** (`convos.org/join_request:1.0`) — sent as a DM to the conversation creator when joining via invite. Contains the invite slug, joiner's profile (name, image, memberKind), and optional metadata.

The CLI sets `memberKind: "agent"` by default on all join requests so the creator knows a bot is joining. For backward compatibility, the CLI sends both the JoinRequestContent message and a plain text slug — older clients that don't understand the new content type will read the text fallback. When processing incoming join requests, the CLI tries JoinRequestContent first, then falls back to plain text.

### Consent States

| State | Meaning |
| ----- | ------- |
| `allowed` | Messages are welcome |
| `denied` | Messages are blocked |
| `unknown` | No decision made |

### Environment Networks

| Network | Use Case |
| ------- | -------- |
| `local` | Local XMTP node |
| `dev` | Development/testing (default) |
| `production` | Production use |

### Data Directory

The data directory defaults to `~/.convos/` but can be overridden with `--home` or `CONVOS_HOME`:

```
<convos-home>/              # default: ~/.convos/
├── .env                    # Global config (env only)
├── identities/
│   ├── <id-1>.json         # Identity: wallet key, db key, conversation link
│   └── <id-2>.json
└── db/
    └── dev/                # XMTP databases by environment
        ├── <id-1>.db3
        └── <id-2>.db3
```

## Error Handling

1. **Not initialized**: Run `convos init` to create configuration
2. **No identities**: Create a conversation or identity first
3. **Identity not found**: Use `convos identity list` to see available identities
4. **Conversation not found**: Sync first with `convos conversations sync`
5. **Permission denied**: Check group permissions with `convos conversation permissions`
6. **Invite expired or invalid**: Generate a new invite with `convos conversation invite`

## Complete Example

```bash
# 1. initialize (first time only)
convos init --env dev

# 2. create a conversation
CONV=$(convos conversations create --name "Project Team" --profile-name "Alice" --json)
CONV_ID=$(echo "$CONV" | jq -r '.conversationId')

# 3. generate an invite for others to join
convos conversation invite "$CONV_ID"

# 4. wait for the person to open the invite URL or scan the QR code,
#    then process their join request
convos conversations process-join-requests --conversation "$CONV_ID"

# OR: if you don't know when they'll open it, watch for requests
# convos conversations process-join-requests --watch --conversation "$CONV_ID"

# 5. send a message
convos conversation send-text "$CONV_ID" "Welcome to the team!"

# 6. stream messages
convos conversation stream "$CONV_ID" --timeout 300
```

## Tips

1. **Always display the full QR code**: The `conversation invite` and `conversations create` commands output a scannable QR code rendered in Unicode block characters followed by the invite URL. When showing the user the result, you **must** display the complete, unmodified command output so the QR code renders correctly in the terminal. Do not summarize, truncate, or omit the QR code — it is the primary way users share invites. Always show the full stdout output to the user. When running `agent serve`, the QR code is saved as a PNG file (path in the `qrCodePath` field of the `ready` event) — display it to the user using the read tool so they can scan it.
2. **Never use markdown in messages**: Convos does not render markdown. When sending messages (via `send-text`, `send-reply`, or agent `send` commands), always use plain text. Do not use markdown formatting like `**bold**`, `*italic*`, `# headings`, `` `code` ``, `[links](url)`, or bullet lists with `- ` or `* `. Write naturally in plain text instead.
3. **Identities are automatic**: You rarely need to manage them directly — creating/joining conversations handles it
4. **Use JSON output for scripting**: Add `--json` flag when extracting data programmatically
5. **Use `--fields` to limit output**: When fetching messages or other large responses, use `--fields` to include only the fields you need — this saves context window tokens and reduces noise. e.g. `--fields id,content,senderInboxId`
6. **Sync before reading**: Add `--sync` flag when reading messages to ensure fresh data
6. **Process join requests after invite is opened**: After generating an invite, wait for the person to open/scan it, then run `process-join-requests`. If you don't know when they'll open it, use `--watch` to stream requests as they arrive
7. **Lock before exploding**: Lock a conversation first to prevent new joins, then explode when ready
8. **Dangerous operations require --force**: Commands like `explode`, `identity remove`, and `lock` prompt for confirmation unless `--force` is passed
9. **Check command help**: Run `convos <command> --help` for full flag documentation
10. **Use `convos schema` for runtime introspection**: `convos schema` lists all commands as JSON, `convos schema <command>` shows full args/flags/examples for a specific command. Useful for discovering capabilities without pre-loaded docs
Comments 0
Latest | Hot
Please login before commenting.
No comments yet. Be the first one!
convos-cli

Directory Structure

SKILL.md

Report

Notice
