@andocorp/cli 0.1.3 → 0.2.0

package/README.md

@@ -1,7 +1,9 @@
-# Ando CLI
+# Ando CLI (Agent-First)
 
 `ando` is a terminal client for humans and agents.
 
+This README documents the agent-first command surface where commands are predictable, flag-driven, and easy for automation to script. The classic human-friendly commands and interactive TUI are still supported.
+
 ## Installation
 
 ### npm (Recommended)
@@ -20,71 +22,180 @@ npx @andocorp/cli
 
 Standalone binaries are available for users who prefer not to install Node.js/npm. Contact hello@ando.so for access.
 
-## Commands
+## Authentication
 
-Open the interactive terminal UI:
+Login once with email OTP:
 
 ```sh
-ando
+ando login --email alex@ando.so
 ```
 
-Show help:
+Optional login flags:
+
+- `--workspace` / `-w`: pick workspace by id/slug/name
+- `--convex-url`: override Convex deployment URL
+- `--api-host`: override backend API host used for agent-first commands
+
+Session config is saved at `~/.config/ando/config.json`.
+
+## Agent-first command model
+
+### 1) `messages` — fetch conversation messages
 
 ```sh
-ando help
-ando --help
+ando messages --channel engineering --limit 10
+ando messages -c engineering -m 10
+ando messages --dm alex --before <cursor> --json
+ando messages --conversation <conversation-id>
 ```
 
-List channels:
+Flags:
+
+- `--channel` / `-c`
+- `--dm` / `-d`
+- `--conversation`
+- `--limit` / `-m`
+- `--before`
+- `--json`
+
+### 2) `search` — search entities
 
 ```sh
-ando list-channels
-ando list-channels --json
+ando search "incident"
+ando search "alice" --type members
+ando search "standup" --type conversations
+ando search "launch checklist" --type clipboard
+ando search "migration" --type calls --after 2026-01-01T00:00:00.000Z
 ```
 
-List direct-message conversations:
+`search` defaults to `--type messages`.
+
+Supported types:
+
+- `messages`
+- `members`
+- `conversations`
+- `clipboard`
+- `calls`
+
+#### Message search filters
 
 ```sh
-ando list-dms
-ando list-dms --json
+ando search "oauth" --type messages \
+  --author <member-id>[,<member-id>] \
+  --conversation <conversation-id>[,<conversation-id>] \
+  --thread <thread-root-message-id> \
+  --after 2026-01-01T00:00:00.000Z \
+  --before 2026-02-01T00:00:00.000Z \
+  --mode semantic
 ```
 
-List messages from a channel, DM, or conversation id:
+Common flags:
+
+- `--type` / `-t`
+- `--json`
+
+Additional filters (depending on type):
+
+- `--author`
+- `--conversation`
+- `--thread`
+- `--after`
+- `--before`
+- `--mode` (`full-text` or `semantic`, message search only)
+
+### 3) `get` — fetch one entity by id
 
 ```sh
-ando list-messages --channel engineering
-ando list-messages --dm alex
-ando list-messages --conversation <conversation-id>
-ando list-messages --channel engineering --limit 20
-ando list-messages -c engineering -n 20 --json
+ando get message <message-id>
+ando get member <member-id>
+ando get clipboard <clipboard-id>
+ando get call <call-id>
+ando get transcript <call-id> --limit 100 --cursor <cursor>
 ```
 
-Read a thread by message id:
+Entities:
+
+- `message`
+- `member`
+- `clipboard`
+- `call`
+- `transcript`
+
+Transcript flags:
+
+- `--limit`
+- `--cursor`
+
+### 4) `thread` — fetch thread replies
 
 ```sh
-ando thread --message-id <message-id>
+ando thread <thread-root-message-id>
+ando thread <thread-root-message-id> --limit 50 --after <cursor>
 ando thread -m <message-id> --json
 ```
 
-Post a new message to a channel, DM, or conversation id:
+Flags:
+
+- positional `<thread-root-message-id>` or `--message-id` / `-m`
+- `--limit`
+- `--after`
+- `--json`
+
+## Output
+
+Every agent-first command supports `--json` for machine-readable output. Without `--json`, commands print tab-separated rows designed for piping into `awk`, `cut`, `jq`, etc.
+
+## Human-friendly commands (still supported)
+
+The following commands are still available for humans working in a terminal:
+
+- `ando` — interactive terminal UI
+- `ando list-channels [--limit|-n <n>]` — 10 most recently active channels by default
+- `ando list-dms [--limit|-n <n>]` — 10 most recently active DMs by default
+- `ando list-messages` — requires `--channel`, `--dm`, or `--conversation`
+- `ando post-message` — requires `--channel/--dm/--conversation` and `--text`
+- `ando reply` — requires `--message-id` and `--text`
+- `ando react` — requires `--message-id` and `--emoji`
+
+Examples:
 
 ```sh
-ando post-message --channel engineering --text "hello"
-ando post-message --dm alex --text "want to pair?"
-ando post-message --conversation <conversation-id> --text "status update"
-ando post-message -c engineering -t "hello" --json
+ando list-channels
+ando list-dms --json
+ando list-messages -c engineering -n 20
+ando post-message -c engineering -t "hello"
+ando reply -m <message-id> -t "on it"
+ando react -m <message-id> -e 👍
 ```
 
-Reply inside an existing thread:
+## Environment variables
+
+- `ANDO_CONVEX_URL`: Convex deployment URL
+- `ANDO_API_HOST`: backend API host for agent-first commands (default: `https://api.app.ando.so`)
+- `VITE_CONVEX_URL`: fallback Convex URL
+- `NEXT_PUBLIC_CONVEX_URL`: fallback Convex URL
+- `ANDO_SESSION_JWT`: override saved session token for one run
+
+Flags take precedence over environment variables, and environment variables take precedence over the saved config.
+
+## Interactive mode
+
+Running plain `ando` opens a keyboard-driven terminal client.
 
 ```sh
-ando reply --message-id <message-id> --text "on it"
-ando reply -m <message-id> -t "on it" --json
+ando
 ```
 
-Add a reaction to a message:
+Keys:
+
+- `[c]` Channels, `[d]` DMs, `[/]` Search, `[Tab]` Focus panes
+- `[Enter]` Open, `[t]` Thread, `[u]` Older, `[n]` Newer
+- `[p]` Post, `[r]` Reply, `[a]` React, `[b]` Back, `[q]` Quit
+
+## Help
 
 ```sh
-ando react --message-id <message-id> --emoji 👍
-ando react -m <message-id> -e 👍 --json
+ando help
+ando --help
 ```