A command-line bot client for Chatto. beardicus.tngl.io/chatline
README.md

chatline #

A command-line client for Chatto that connects agents and scripts with a single static Go binary. It acts as one Chatto bot, and has three parts:

  • Commands and an agent skill. Give an agent the skill with chatline bootstrap, and it can post, read, ask people questions, and wait for answers in Chatto. The commands work from scripts too. It's modelled on slackline: send, read, ask, run, listen, react, permalink, download, profile, rooms, users, search, bot, auth, and init.
  • A Claude Code channel (chatline channel), using Claude Code's channels feature. It pushes Chatto mentions, DMs, thread replies, and reactions into a running Claude Code session, so you can work with the session from Chatto.
  • A bridge for other agent harnesses (chatline serve). It speaks JSON lines on stdio: events out, requests in. A harness adapter then only translates, and chatline handles resuming, dedupe, threads, and reconnects.

It works with Chatto servers from 0.5.0 on, and is built against 0.5.0. chatline auth status warns if the server is older than that minimum. The design is in docs/spec.md.

The full documentation is at beardicus.tngl.io/chatline.

Install #

Install the latest release with Homebrew:

brew install beardicus/tap/chatline

Or with Go 1.26 or newer:

go install tangled.org/beardic.us/chatline/cmd/chatline@latest

The binary lands in $(go env GOPATH)/bin (or $GOBIN, if set), which needs to be on your PATH.

Or download a release binary for Linux (amd64, arm64) or macOS (Apple silicon). The install script picks the right one, checks it against SHA256SUMS, and puts it in ~/.local/bin:

curl -fsSL https://tangled.org/beardic.us/chatline/raw/main/install.sh | sh

The binaries and SHA256SUMS are also on the v0.2.0 tag.

To build from a checkout of this repo instead:

make build            # ./chatline
make dist             # static linux/amd64, linux/arm64, darwin/arm64 binaries + SHA256SUMS in dist/

Put the binary somewhere on your PATH, such as ~/.local/bin.

Set up a bot #

  1. In Chatto, open App Preferences (the gear icon), then Bots under the Server heading. Create a bot, and copy its API key. Chatto shows it only once. Chatto's Bots & Webhooks guide has more on bot accounts.

  2. Select the bot under Bot Accounts, then Permissions, and grant it permissions in the columns for the rooms it should use. Bots start with none. Typical grants:

    • message.read + message.post-in-interactions to answer when spoken to
    • message.post to start threads
    • message.react
    • message.attach for files
  3. Add the bot to the room: check the Joined row in the room's column, and confirm. chatline never joins rooms by itself. With room.join, chatline rooms join ROOM works. Joining by name also needs room.list, because without it the bot can't see rooms it isn't in.

  4. For DMs, grant it message.read and message.post at the Direct messages scope. With those, chatline send --room @login opens a DM with that person, and people can DM the bot.

  5. Save the server and key. init asks for the key without echoing it, checks it against the server, and writes ~/.config/chatline/config.json (mode 0600). To keep the key out of that file, use one of the options after these steps instead.

    chatline init --server https://chatto.example
    
  6. Check the bot's identity and permissions:

    chatline auth status
    

    It prints the bot, its owner, the server version, where the key came from, and the bot's permissions in each room. perms none means step 2 isn't done yet.

Keep the key out of the config file #

  • A key file: write the key alone to a file only you can read, then run chatline init --server https://chatto.example --key-file ~/.config/chatline/bot.key. The config saves only the file's path.
  • Environment variables: CHATLINE_SERVER, CHATLINE_API_KEY, and CHATLINE_API_KEY_FILE override the config file, and work without init. init --no-store-key checks the key and saves only the server, for setups that inject CHATLINE_API_KEY at run time, such as 1Password's op run.

Run multiple bots #

For multiple bots on one machine, give each its own config file with --config or CHATLINE_CONFIG=~/.config/chatline/BOT.json.

Give it to an agent #

With chatline set up, tell your agent:

Run "chatline bootstrap" and follow what it says.

bootstrap prints instructions for the agent, the bot's status, and the using-chatto skill. The agent saves the skill in its skills directory (~/.claude/skills/using-chatto/ for Claude Code) and tells you which bot it is. To install the skill yourself, save the output of chatline skill:

mkdir -p ~/.claude/skills/using-chatto
chatline skill > ~/.claude/skills/using-chatto/SKILL.md

Don't paste the API key into an agent's conversation: run init yourself.

Commands #

--room takes a room ID, name, or #name, or @login for a DM, which send, ask, and run open if need be. chatline COMMAND --help lists every flag.

Task Command
Check the bot's identity and permissions chatline auth status
List the rooms the bot can see chatline rooms [--joined]
Find a user chatline users --match bear
Post (body from -m, --message-file, or stdin) chatline send --room ops -m "deploy done"
Open a thread chatline send --room ops --new-thread -m "status?"
Reply in a thread chatline send --room ops --thread ROOT_ID -m "…"
Attach files chatline send --room ops --file out.png -m "graph"
DM someone chatline send --room @dana -m "your export is ready"
Recent messages (with reactions=… per message) chatline read --room ops [--thread ID] [--limit 50]
Search past messages (the server must have search on) chatline search disk full [--room ops] [--from dana] [--newest]
Ask a question and wait for the answer chatline ask --room ops --from beardicus --timeout 10m -m "ok to restart?"
Run a command and post how it went chatline run --room ops --on-failure -- ./backup.sh
Stream events (types: mention, dm, reply, reaction by default; also message, edit, delete) chatline listen [--type mention,dm,reply,reaction] [--resume]
React chatline react --room ops --message-id ID --emoji thumbsup [--remove]
Link to a message chatline permalink --room ops --message-id ID
Show or change the bot's profile chatline profile [--display-name NAME] [--bio TEXT] [--avatar face.png | --no-avatar]
Download an attachment chatline download --room ops --asset ID [--out PATH|-]
Download only the inline preview chatline download --room ops --asset ID --thumbnail (images fit to 960×400, or a video's poster frame)
Create a bot, or manage bots' keys (needs bot.create or bot.manage) chatline bot create reportbot --save-key reportbot.key, chatline bot key create BOT NAME --save-key F

Output conventions:

  • Text output is compact and line-oriented, and safe for while read -r. Add --format json for JSON lines.
  • Status lines go to stderr. listen and ask print ready there once they're live.
  • send prints <room_id> <message_id> <thread_id|->, so scripts can thread follow-ups.

Exit codes:

Code Meaning
0 Success
1 Server error not covered below, or a network failure
2 Invalid or revoked key
3 Missing or invalid config, no key, or an unreadable key file
4 Bad flags or arguments, or an ambiguous room name
5 Timed out, such as ask getting no reply
6 Permission denied: not a member, or a missing grant
7 Room, user, or message not found

Errors are a single line on stderr, error: <code>: <detail>, or JSON with --format json.

if reply=$(chatline ask --room ops --from beardicus --timeout 5m -m "Restart nginx on storage?"); then
  echo "got: $reply"
elif [ $? -eq 5 ]; then
  echo "nobody answered"
fi

# Run the nightly backup from cron; post only if it fails, with the last
# 20 lines of output (and the full log attached if there was more) and a
# ping. The exit status is the backup's, and the backup runs even if Chatto
# is unreachable.
chatline run --room ops --on-failure --name "nightly backup" \
  -m "@beardicus the backup failed" -- /usr/local/bin/backup.sh

# Answer each mention in its thread (thread_id, or the message itself if it's a root).
# Assumes rooms with threads enabled; `rooms` shows each room's threading mode.
chatline listen --type mention --format json | while read -r ev; do
  room=$(printf '%s' "$ev" | jq -r .room_id)
  thread=$(printf '%s' "$ev" | jq -r '.thread_id // .message_id')
  chatline send --room "$room" --thread "$thread" -m "on it"
done

Claude Code channel #

Add chatline to the project's .mcp.json:

{ "mcpServers": { "chatline": { "command": "chatline", "args": ["channel"] } } }

Then start Claude Code:

claude --dangerously-load-development-channels server:chatline

How it works:

  • Who can reach the session. Only events from the bot's owner get through by default. Use --allow-from login,... to change that (or channel.allow_from in the config). Events from anyone else are dropped; with CHATLINE_LOG_LEVEL=info, each one is logged.
  • What reaches the session. By default: mentions, DMs, quote-replies to the bot and replies in its threads, and reactions on the bot's messages, so a 👍 can answer Claude's question. Plain room messages (message), edits (edit), and deletes (delete) are opt-in. List the types you want, such as "args": ["channel", "--type", "mention,dm,reply,reaction,message"] in .mcp.json, or set "channel": {"types": [...]} in the config. Other people's messages still need --allow-from.
  • What Claude can do. It answers with the reply tool. It also has react, read (which shows each message's reactions), search, send, profile, and fetch_attachment.
  • Attachments. fetch_attachment saves into .chatline/attachments/ in the project Claude Code runs in, with a .gitignore in .chatline/ (for this default directory only) so nothing gets committed. Files outside the project would make Claude stop on a permission prompt every time it opens one. Override the location with --attachments-dir or CHATLINE_ATTACHMENTS_DIR if you need to, but keep it inside the project. With thumbnail: true it fetches the small inline preview of an image or video instead.
  • What the user sees. While Claude works, the bot shows as typing in Chatto.
  • Approving tools from your phone. With --permission-relay, when Claude wants to run something that needs approval, the prompt also arrives in your DM with the bot, which it opens if need be. Answer yes abcde or no abcde with the five-letter ID from the prompt; chatline reacts ✅ or ❌ to show it passed your answer on. The terminal prompt stays open too, and the first answer wins. Only the bot's owner can approve, and only in that DM, whatever --allow-from says.
  • Restarts. Resume state is kept in ~/.local/state/chatline/PROFILE/ (--state-dir or CHATLINE_STATE_DIR to move it), so a restart within 15 minutes misses nothing. PROFILE is the config file's name, such as config.

Limitations (Claude Code research preview):

  • Custom channels need the --dangerously-load-development-channels flag.
  • Channels work in interactive sessions only, not -p.
  • They need a claude.ai login or Console key. On Team or Enterprise plans, an owner must enable channels.
  • If the session never shows chatline events, try MCP_PROTOCOL_NEGOTIATION=legacy and check claude --debug. chatline already refuses the protocol revision that blocks channels.

Logs go to stderr; set CHATLINE_LOG_LEVEL=info|debug for more. Message bodies are never logged. Claude Code keeps the channel's stderr, so to watch a live session add "--log-file", "/tmp/chatline.log" to the args in .mcp.json (or set CHATLINE_LOG_FILE) and tail -f it.

Other harnesses #

chatline serve runs the same live session as the channel, but as a JSON-lines protocol any language can drive: events and results on stdout, requests (send, edit, react, read, search, fetch, typing, room, dm, permalink, profile) on stdin. It exits when stdin closes. The protocol is in docs/serve.md.

chatline serve --type mention,dm,reply,reaction

Update the Chatto pin #

chatline builds against a pinned copy of the Chatto protocol, and auth status doesn't warn about newer servers. Chatto 0.5 is still a release candidate, so after a server upgrade, move the pin and run the contract tests to check that the behavior chatline relies on still holds:

make vendor-proto TAG=vX.Y.Z CHATTO_REPO=/path/to/chatto
make proto && go build ./... && go test ./...
CHATLINE_IT_IMAGE=ghcr.io/chattocorp/chatto:X.Y.Z make test-contract   # Chatto behavior chatline relies on
make test-integration
chatline auth status    # warns if the server is older than the minimum supported version

The minimum server version is MinimumChattoVersion in internal/cli/auth.go, separate from the build pin in proto/CHATTO_VERSION: updating the generated client doesn't necessarily require a newer server.

Development #

The generated code is committed, so you only need buf when regenerating it (make proto). The test and eval targets:

make test               # unit tests
make test-integration   # starts a throwaway Chatto in Docker: real users and bots
make test-contract      # only the Chatto contract tests (test/integration/chatto_contract_test.go)
make skill-evals        # agents use the skill against a throwaway Chatto; costs Claude tokens (test/skill-evals)
make channel-evals      # the same for the channel's tools and instructions
make sandbox            # a throwaway Chatto on localhost:4000 with a login link and a bot config; CHATTO=VERSION to pick one
make docs-ref           # regenerate the site's command reference from the help text
make site               # build the docs site into site/dist

Licensing #

chatline is licensed under the Apache License 2.0, © 2026 Brian Boucheron. See NOTICE for what it includes from others:

  • The protos under proto/chatto/, and the Go code generated from them in gen/, are Apache-2.0, © 2026 ChattoCorp GmbH (see proto/NOTICE). Only the Apache-2.0 api, realtime, and discovery packages are vendored; nothing from Chatto's AGPL code is used.
  • The NanoClaw adapter's test stand-ins include MIT-licensed code from NanoClaw (adapters/nanoclaw/test/stubs/LICENSE.nanoclaw).