@andocorp/cli 0.2.0 → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ando Corp
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,13 +1,10 @@
-# Ando CLI (Agent-First)
+# Ando CLI
 
-`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.
+`ando` provides agent-first terminal commands for Ando. It is built on the
+public `@andocorp/sdk` package and authenticates with an Ando API key.
 
 ## Installation
 
-### npm (Recommended)
-
 ```sh
 npm install -g @andocorp/cli
 ```
@@ -18,93 +15,102 @@ Or run without installing:
 npx @andocorp/cli
 ```
 
-### Alternative: Standalone Binaries
-
-Standalone binaries are available for users who prefer not to install Node.js/npm. Contact hello@ando.so for access.
-
 ## Authentication
 
-Login once with email OTP:
+Log in once:
 
 ```sh
-ando login --email alex@ando.so
+ando login
 ```
 
-Optional login flags:
+The command opens a browser authorization page, prints a verification code to
+confirm in the browser, and stores the returned API key in the system keyring
+by default. Non-secret metadata is stored at `~/.config/ando/config.json`.
 
-- `--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
+For remote shells or agents that cannot open a browser directly, start a
+two-step login:
 
-Session config is saved at `~/.config/ando/config.json`.
+```sh
+ando login --no-browser
+```
 
-## Agent-first command model
+Open the printed URL, confirm the verification code, then run the printed
+`ando login poll` command in the original shell to finish authentication.
 
-### 1) `messages` — fetch conversation messages
+For headless scripts and CI, provide an API key directly:
 
 ```sh
-ando messages --channel engineering --limit 10
-ando messages -c engineering -m 10
-ando messages --dm alex --before <cursor> --json
-ando messages --conversation <conversation-id>
+ando login --api-key ando_sk_...
 ```
 
-Flags:
+You can also set `ANDO_API_KEY` for one-off or CI usage.
+
+Set `ANDO_KEYRING=0` to use file-based auth instead of the system keyring. In
+that mode the API key is stored in `auth.json` under the Ando config directory.
+Set `ANDO_HOME` to override the config and auth state directory; otherwise the
+CLI uses the platform config directory.
+
+Optional endpoint flags:
 
-- `--channel` / `-c`
-- `--dm` / `-d`
-- `--conversation`
-- `--limit` / `-m`
-- `--before`
-- `--json`
+- `--base-url`: login and SDK REST base URL
+- `--api-host`: public API base URL for agent-first commands
+- `--realtime-host`: realtime host for SDK subscriptions
 
-### 2) `search` — search entities
+Check local auth health or remove local credentials:
 
 ```sh
-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
+ando doctor
+ando doctor --json
+ando whoami
+ando whoami --json
+ando logout
 ```
 
-`search` defaults to `--type messages`.
+`ando whoami` prints the member and workspace resolved by the active API key.
+`ando logout` revokes browser-created CLI credentials before removing local auth
+state. API keys supplied manually or through `ANDO_API_KEY` remain local-only.
 
-Supported types:
+## Commands
 
-- `messages`
-- `members`
-- `conversations`
-- `clipboard`
-- `calls`
-
-#### Message search filters
+The raw public API escape hatch mirrors the generated Ando API surface. It is
+useful for scripts and agents that need an endpoint before a dedicated CLI
+workflow exists.
 
 ```sh
-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
+ando api ls
+ando api ls --json
+ando api searchMessages q==incident mode==semantic
+ando api getMember memberId=<member-id>
+ando api /v1/search/messages q==incident mode==semantic
+ando api /v1/conversations/<conversation-id>/messages \
+  markdown_content="hello" \
+  Idempotency-Key:<key>
+echo '{"markdown_content":"hello"}' | ando api /v1/conversations/<conversation-id>/messages --data -
+ando api /v1/search/messages --help
+ando api /v1/search/messages --spec
 ```
 
-Common flags:
-
-- `--type` / `-t`
-- `--json`
+`ando api` accepts `name==value` query parameters, `Header:Value` declared
+request headers, `field=value` JSON string body fields, `field:=json` typed JSON
+body fields, and `--data <json|->` for complete request bodies. The target can
+be a public path or an operation ID from `ando api ls`; query and header names
+are validated against the generated public API metadata. For operation ID
+targets, supply required path parameters as `name=value`.
 
-Additional filters (depending on type):
-
-- `--author`
-- `--conversation`
-- `--thread`
-- `--after`
-- `--before`
-- `--mode` (`full-text` or `semantic`, message search only)
+```sh
+ando messages --channel engineering --limit 10
+ando messages -c engineering -m 10
+ando messages --dm alex --before <cursor> --json
+ando messages --conversation <conversation-id>
+```
 
-### 3) `get` — fetch one entity by id
+```sh
+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
+```
 
 ```sh
 ando get message <message-id>
@@ -114,88 +120,24 @@ ando get call <call-id>
 ando get transcript <call-id> --limit 100 --cursor <cursor>
 ```
 
-Entities:
-
-- `message`
-- `member`
-- `clipboard`
-- `call`
-- `transcript`
-
-Transcript flags:
-
-- `--limit`
-- `--cursor`
-
-### 4) `thread` — fetch thread replies
-
 ```sh
 ando thread <thread-root-message-id>
 ando thread <thread-root-message-id> --limit 50 --after <cursor>
 ando thread -m <message-id> --json
 ```
 
-Flags:
+Every agent-first command supports `--json` for machine-readable output.
+Without `--json`, commands print tab-separated rows.
 
-- positional `<thread-root-message-id>` or `--message-id` / `-m`
-- `--limit`
-- `--after`
-- `--json`
+## Environment
 
-## Output
+- `ANDO_API_KEY`: API key for SDK and public API requests
+- `ANDO_KEYRING`: set to `0` to use file-based auth instead of keyring
+- `ANDO_HOME`: config and auth state directory
+- `ANDO_BASE_URL`: login and SDK REST base URL
+- `ANDO_API_HOST`: public API base URL for agent-first commands
+- `ANDO_REALTIME_HOST`: realtime host for SDK subscriptions
+- `XDG_CONFIG_HOME`: fallback base directory for config/auth state
 
-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 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 👍
-```
-
-## 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
-```
-
-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 help
-ando --help
-```
+Flags take precedence over environment variables, and environment variables
+take precedence over saved config.

package/dist/agent-commands.js

@@ -0,0 +1,297 @@
+import { getStringFlag, hasFlag } from "./args.js";
+import { resolveConversation } from "./cli-helpers.js";
+import { printJson } from "./output.js";
+async function resolveConversationId(cliClient, parsedArgs) {
+    const channelQuery = getStringFlag(parsedArgs, "channel", "c");
+    const dmQuery = getStringFlag(parsedArgs, "dm", "d");
+    const conversationQuery = getStringFlag(parsedArgs, "conversation");
+    if (conversationQuery != null && channelQuery == null && dmQuery == null) {
+        return conversationQuery;
+    }
+    const query = channelQuery ?? dmQuery ?? conversationQuery;
+    if (query == null) {
+        throw new Error("messages requires --channel, --dm, or --conversation.");
+    }
+    const memberships = await cliClient.getAllMemberships();
+    const membership = resolveConversation(memberships, {
+        allowChannels: dmQuery == null,
+        allowDms: channelQuery == null,
+        query,
+    });
+    return membership.conversation.id;
+}
+export async function runMessagesCommand(params) {
+    const conversationId = await resolveConversationId(params.cliClient, params.parsedArgs);
+    const limit = getStringFlag(params.parsedArgs, "limit", "m") ??
+        getStringFlag(params.parsedArgs, "n", "n");
+    const before = getStringFlag(params.parsedArgs, "before");
+    const messageParams = {
+        conversationId,
+    };
+    if (limit != null) {
+        messageParams.limit = limit;
+    }
+    if (before != null) {
+        messageParams.before = before;
+    }
+    const response = await params.apiClient.listConversationMessages(messageParams);
+    if (hasFlag(params.parsedArgs, "json")) {
+        printJson(response);
+        return;
+    }
+    printMessageResults(response.items);
+}
+function printMessageResults(items) {
+    for (const item of items) {
+        const author = item.author_name ?? "unknown";
+        const content = (item.content ?? "").replace(/\s+/g, " ").trim();
+        process.stdout.write(`${item.id}\t${item.created_at}\t${author}\t${content}\n`);
+    }
+}
+async function runSearchMessages(apiClient, parsedArgs, query, jsonFlag) {
+    const searchParams = { q: query };
+    const author = getStringFlag(parsedArgs, "author");
+    const conversation = getStringFlag(parsedArgs, "conversation");
+    const thread = getStringFlag(parsedArgs, "thread");
+    const after = getStringFlag(parsedArgs, "after");
+    const before = getStringFlag(parsedArgs, "before");
+    const mode = parseSearchMode(getStringFlag(parsedArgs, "mode"));
+    if (author != null) {
+        searchParams.author = author;
+    }
+    if (conversation != null) {
+        searchParams.conversation = conversation;
+    }
+    if (thread != null) {
+        searchParams.thread = thread;
+    }
+    if (after != null) {
+        searchParams.after = after;
+    }
+    if (before != null) {
+        searchParams.before = before;
+    }
+    if (mode != null) {
+        searchParams.mode = mode;
+    }
+    const response = await apiClient.searchMessages(searchParams);
+    if (jsonFlag) {
+        printJson(response);
+        return;
+    }
+    printMessageResults(response.items);
+}
+async function runSearchMembers(apiClient, query, jsonFlag) {
+    const response = await apiClient.searchMembers({ q: query });
+    if (jsonFlag) {
+        printJson(response);
+        return;
+    }
+    for (const item of response.items) {
+        const title = item.title == null || item.title === "" ? "" : ` (${item.title})`;
+        process.stdout.write(`${item.id}\t${item.display_name ?? ""}\t${item.email ?? ""}${title}\n`);
+    }
+}
+async function runSearchConversations(apiClient, query, jsonFlag) {
+    const response = await apiClient.searchConversations({ q: query });
+    if (jsonFlag) {
+        printJson(response);
+        return;
+    }
+    for (const item of response.items) {
+        process.stdout.write(`${item.id}\t${item.type}\t${item.name ?? ""}\t${item.human_members_count} members\n`);
+    }
+}
+async function runSearchClipboard(apiClient, query, jsonFlag) {
+    const response = await apiClient.searchClipboards({ q: query });
+    if (jsonFlag) {
+        printJson(response);
+        return;
+    }
+    for (const item of response.items) {
+        process.stdout.write(`${item.id}\t${item.created_at}\t${item.title ?? ""}\t${item.item_count} items\n`);
+    }
+}
+async function runSearchCalls(apiClient, parsedArgs, query, jsonFlag) {
+    const searchParams = { q: query };
+    const conversation = getStringFlag(parsedArgs, "conversation");
+    const after = getStringFlag(parsedArgs, "after");
+    const before = getStringFlag(parsedArgs, "before");
+    if (conversation != null) {
+        searchParams.conversation = conversation;
+    }
+    if (after != null) {
+        searchParams.after = after;
+    }
+    if (before != null) {
+        searchParams.before = before;
+    }
+    const response = await apiClient.searchCalls(searchParams);
+    if (jsonFlag) {
+        printJson(response);
+        return;
+    }
+    for (const item of response.items) {
+        process.stdout.write(`${item.id}\t${item.status}\t${item.conversation_name ?? ""}\t${item.duration_seconds ?? "-"}s\n`);
+    }
+}
+export async function runSearchCommand(params) {
+    const query = params.parsedArgs.positionals[1];
+    const type = (getStringFlag(params.parsedArgs, "type", "t") ?? "messages").toLowerCase();
+    const jsonFlag = hasFlag(params.parsedArgs, "json");
+    if (query == null || query.trim() === "") {
+        throw new Error('search requires a query, e.g. ando search "incident".');
+    }
+    switch (type) {
+        case "messages": {
+            await runSearchMessages(params.apiClient, params.parsedArgs, query, jsonFlag);
+            return;
+        }
+        case "members": {
+            await runSearchMembers(params.apiClient, query, jsonFlag);
+            return;
+        }
+        case "conversations": {
+            await runSearchConversations(params.apiClient, query, jsonFlag);
+            return;
+        }
+        case "clipboard": {
+            await runSearchClipboard(params.apiClient, query, jsonFlag);
+            return;
+        }
+        case "calls": {
+            await runSearchCalls(params.apiClient, params.parsedArgs, query, jsonFlag);
+            return;
+        }
+        default:
+            throw new Error(`Unknown search --type "${type}". Expected messages, members, conversations, clipboard, or calls.`);
+    }
+}
+function parseSearchMode(value) {
+    if (value == null) {
+        return undefined;
+    }
+    if (value === "full-text" || value === "semantic") {
+        return value;
+    }
+    throw new Error(`Unknown --mode "${value}". Expected full-text or semantic.`);
+}
+async function runGetMessage(apiClient, id, jsonFlag) {
+    const response = await apiClient.getConversationMessageResult(id);
+    if (jsonFlag) {
+        printJson(response);
+        return;
+    }
+    printMessageResults([response]);
+}
+async function runGetMember(apiClient, id, jsonFlag) {
+    const response = await apiClient.getMember(id);
+    if (jsonFlag) {
+        printJson(response);
+        return;
+    }
+    const title = response.title == null ? "" : ` (${response.title})`;
+    process.stdout.write(`${response.id}\t${response.display_name ?? ""}\t${response.email ?? ""}${title}\n`);
+}
+async function runGetClipboard(apiClient, id, jsonFlag) {
+    const response = await apiClient.getClipboard(id);
+    if (jsonFlag) {
+        printJson(response);
+        return;
+    }
+    process.stdout.write(`${response.id}\t${response.title ?? ""}\t${response.created_at}\n`);
+    for (const item of response.items) {
+        process.stdout.write(`  - ${item.type}\t${item.id}\t${item.name ?? item.display_name ?? item.author_name ?? ""}\n`);
+    }
+}
+async function runGetCall(apiClient, id, jsonFlag) {
+    const response = await apiClient.getCall(id);
+    if (jsonFlag) {
+        printJson(response);
+        return;
+    }
+    process.stdout.write(`${response.id}\t${response.status}\t${response.conversation_name ?? ""}\t${response.duration_seconds ?? "-"}s\n`);
+    for (const participant of response.participants) {
+        process.stdout.write(`  - ${participant.id}\t${participant.name ?? ""}\n`);
+    }
+}
+async function runGetTranscript(apiClient, parsedArgs, id, jsonFlag) {
+    const transcriptParams = {
+        callId: id,
+    };
+    const limit = getStringFlag(parsedArgs, "limit");
+    const cursor = getStringFlag(parsedArgs, "cursor");
+    if (limit != null) {
+        transcriptParams.limit = limit;
+    }
+    if (cursor != null) {
+        transcriptParams.cursor = cursor;
+    }
+    const response = await apiClient.getCallTranscript(transcriptParams);
+    if (jsonFlag) {
+        printJson(response);
+        return;
+    }
+    for (const segment of response.segments) {
+        process.stdout.write(`${segment.start_ms}\t${segment.end_ms}\t${segment.speaker_name ?? ""}\t${segment.content}\n`);
+    }
+}
+export async function runGetCommand(params) {
+    const entity = params.parsedArgs.positionals[1];
+    const id = params.parsedArgs.positionals[2];
+    const jsonFlag = hasFlag(params.parsedArgs, "json");
+    if (entity == null || id == null || id.trim() === "") {
+        throw new Error("get requires an entity type and id, e.g. ando get message <id>.");
+    }
+    switch (entity) {
+        case "message": {
+            await runGetMessage(params.apiClient, id, jsonFlag);
+            return;
+        }
+        case "member": {
+            await runGetMember(params.apiClient, id, jsonFlag);
+            return;
+        }
+        case "clipboard": {
+            await runGetClipboard(params.apiClient, id, jsonFlag);
+            return;
+        }
+        case "call": {
+            await runGetCall(params.apiClient, id, jsonFlag);
+            return;
+        }
+        case "transcript": {
+            await runGetTranscript(params.apiClient, params.parsedArgs, id, jsonFlag);
+            return;
+        }
+        default:
+            throw new Error(`Unknown get entity "${entity}". Expected message, member, clipboard, call, or transcript.`);
+    }
+}
+export async function runAgentThreadCommand(params) {
+    const positionalId = params.parsedArgs.positionals[1];
+    const messageId = positionalId ?? getStringFlag(params.parsedArgs, "message-id", "m");
+    if (messageId == null || messageId.trim() === "") {
+        throw new Error("thread requires a thread root message id.");
+    }
+    const threadParams = {
+        messageId,
+    };
+    const limit = getStringFlag(params.parsedArgs, "limit");
+    const after = getStringFlag(params.parsedArgs, "after");
+    if (limit != null) {
+        threadParams.limit = limit;
+    }
+    if (after != null) {
+        threadParams.after = after;
+    }
+    const response = await params.apiClient.listThreadReplies(threadParams);
+    if (hasFlag(params.parsedArgs, "json")) {
+        printJson(response);
+        return;
+    }
+    for (const reply of response.items) {
+        const content = (reply.content ?? "").replace(/\s+/g, " ").trim();
+        process.stdout.write(`${reply.id}\t${reply.created_at}\t${reply.author_name ?? ""}\t${content}\n`);
+    }
+}