@gobi-ai/cli 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Gobi AI
+
+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

@@ -0,0 +1,152 @@
+# gobi-cli
+
+[![CI](https://github.com/gobi-ai/gobi-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/gobi-ai/gobi-cli/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/@gobi-ai/cli)](https://www.npmjs.com/package/@gobi-ai/cli)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+Command-line interface for the [Gobi](https://joingobi.com) collaborative knowledge platform.
+
+## Installation
+
+### Homebrew
+
+```sh
+brew tap gobi-ai/tap
+brew install gobi
+```
+
+### npm
+
+```sh
+npm install -g @gobi-ai/cli
+```
+
+### From source
+
+```sh
+git clone https://github.com/gobi-ai/gobi-cli.git
+cd gobi-cli
+npm install
+npm run build
+npm link
+```
+
+## Quick start
+
+```sh
+# Authenticate with your Gobi account
+gobi auth login
+
+# Set up your space and vault
+gobi init
+
+# Search brains in your space
+gobi astra search-brain --query "machine learning"
+
+# Ask a brain a question
+gobi astra ask-brain --vault-slug my-vault --question "What is RAG?"
+```
+
+## Commands
+
+### Authentication
+
+| Command | Description |
+|---------|-------------|
+| `gobi auth login` | Sign in via device code flow |
+| `gobi auth status` | Show current auth status |
+| `gobi auth logout` | Sign out and clear credentials |
+
+### Setup
+
+| Command | Description |
+|---------|-------------|
+| `gobi init` | Interactive setup — select your vault and space |
+
+### Brains
+
+| Command | Description |
+|---------|-------------|
+| `gobi astra search-brain --query <q>` | Search brains in a space |
+| `gobi astra ask-brain --vault-slug <slug> --question <q>` | Ask a brain a question (creates a 1:1 session) |
+| `gobi astra publish-brain` | Upload `BRAIN.md` to your vault |
+| `gobi astra unpublish-brain` | Remove `BRAIN.md` from your vault |
+
+### Posts
+
+| Command | Description |
+|---------|-------------|
+| `gobi astra list-posts` | List posts in the current space |
+| `gobi astra get-post <id>` | Get a post and its replies |
+| `gobi astra create-post --title <t> --content <c>` | Create a post |
+| `gobi astra edit-post <id> --title <t>` | Edit a post |
+| `gobi astra delete-post <id>` | Delete a post |
+
+### Replies
+
+| Command | Description |
+|---------|-------------|
+| `gobi astra list-replies <postId>` | List replies to a post |
+| `gobi astra create-reply <postId> --content <c>` | Reply to a post |
+| `gobi astra edit-reply <replyId> --content <c>` | Edit a reply |
+| `gobi astra delete-reply <replyId>` | Delete a reply |
+
+### Sessions
+
+| Command | Description |
+|---------|-------------|
+| `gobi astra list-sessions` | List your sessions |
+| `gobi astra get-session <id>` | Get a session and its messages |
+| `gobi astra reply-session <id> --content <c>` | Send a message in a session |
+
+### Brain updates
+
+| Command | Description |
+|---------|-------------|
+| `gobi astra list-brain-updates` | List brain updates in the space |
+| `gobi astra create-brain-update --title <t> --content <c>` | Create a brain update |
+| `gobi astra edit-brain-update <id> --title <t>` | Edit a brain update |
+| `gobi astra delete-brain-update <id>` | Delete a brain update |
+
+### Global options
+
+| Option | Description |
+|--------|-------------|
+| `--json` | Output results as JSON |
+| `--space-slug <slug>` | Override the default space (astra commands) |
+
+## Configuration
+
+### Environment variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `GOBI_BASE_URL` | `https://backend.joingobi.com` | API server URL |
+| `GOBI_WEBDRIVE_BASE_URL` | `https://webdrive.joingobi.com` | File storage URL |
+
+### Files
+
+| Path | Description |
+|------|-------------|
+| `~/.gobi/credentials.json` | Stored authentication tokens |
+| `.gobi/settings.yaml` | Per-project vault and space configuration |
+
+## Development
+
+```sh
+git clone https://github.com/gobi-ai/gobi-cli.git
+cd gobi-cli
+npm install
+npm run build
+npm test
+```
+
+Run from source without compiling:
+
+```sh
+npm run dev -- auth status
+```
+
+## License
+
+[MIT](LICENSE)

package/dist/auth/credentials.js

@@ -0,0 +1,28 @@
+import { readFileSync, writeFileSync, mkdirSync, unlinkSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+const CREDENTIALS_DIR = join(homedir(), ".gobi");
+const CREDENTIALS_PATH = join(CREDENTIALS_DIR, "credentials.json");
+export async function loadCredentials() {
+    try {
+        const raw = readFileSync(CREDENTIALS_PATH, "utf-8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+export async function saveCredentials(creds) {
+    mkdirSync(CREDENTIALS_DIR, { recursive: true, mode: 0o700 });
+    writeFileSync(CREDENTIALS_PATH, JSON.stringify(creds, null, 2), {
+        mode: 0o600,
+    });
+}
+export async function clearCredentials() {
+    try {
+        unlinkSync(CREDENTIALS_PATH);
+    }
+    catch {
+        // ignore if file doesn't exist
+    }
+}

package/dist/auth/manager.js

@@ -0,0 +1,55 @@
+import { BASE_URL, TOKEN_REFRESH_BUFFER_MS } from "../constants.js";
+import { NotAuthenticatedError, TokenRefreshError } from "../errors.js";
+import { loadCredentials, saveCredentials, clearCredentials, } from "./credentials.js";
+let cachedCredentials = null;
+export async function initCredentials() {
+    cachedCredentials = await loadCredentials();
+}
+export function isAuthenticated() {
+    return cachedCredentials !== null;
+}
+export function getCurrentUser() {
+    if (cachedCredentials === null)
+        return null;
+    return cachedCredentials.user;
+}
+function isExpiringSoon(creds) {
+    return Date.now() >= creds.expiresAt - TOKEN_REFRESH_BUFFER_MS;
+}
+async function performRefresh(creds) {
+    const res = await fetch(`${BASE_URL}/auth/refresh`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ refreshToken: creds.refreshToken }),
+    });
+    if (!res.ok) {
+        const body = (await res.text()) || "(no body)";
+        throw new TokenRefreshError(`HTTP ${res.status}: ${body}`);
+    }
+    const data = (await res.json());
+    const updated = {
+        ...creds,
+        accessToken: data.accessToken,
+        refreshToken: data.refreshToken,
+        expiresAt: Date.now() + data.expiresIn * 1000,
+    };
+    await saveCredentials(updated);
+    return updated;
+}
+export async function getValidToken() {
+    if (cachedCredentials === null) {
+        throw new NotAuthenticatedError();
+    }
+    if (isExpiringSoon(cachedCredentials)) {
+        cachedCredentials = await performRefresh(cachedCredentials);
+    }
+    return cachedCredentials.accessToken;
+}
+export async function storeTokens(creds) {
+    await saveCredentials(creds);
+    cachedCredentials = creds;
+}
+export async function logout() {
+    await clearCredentials();
+    cachedCredentials = null;
+}

package/dist/client.js

@@ -0,0 +1,43 @@
+import { BASE_URL } from "./constants.js";
+import { ApiError } from "./errors.js";
+import { getValidToken } from "./auth/manager.js";
+async function request(method, path, options) {
+    const token = await getValidToken();
+    let url = `${BASE_URL}${path}`;
+    // Filter out null/undefined values from params
+    if (options?.params) {
+        const filtered = Object.entries(options.params)
+            .filter(([, v]) => v != null)
+            .map(([k, v]) => [k, String(v)]);
+        if (filtered.length > 0) {
+            url += "?" + new URLSearchParams(filtered).toString();
+        }
+    }
+    const headers = {
+        Authorization: `Bearer ${token}`,
+    };
+    const body = options?.body != null ? JSON.stringify(options.body) : undefined;
+    if (body !== undefined) {
+        headers["Content-Type"] = "application/json";
+    }
+    const res = await fetch(url, { method, headers, body });
+    if (!res.ok) {
+        const text = (await res.text()) || "(no body)";
+        throw new ApiError(res.status, path, text);
+    }
+    if (res.status === 204)
+        return null;
+    return res.json();
+}
+export function apiGet(path, params) {
+    return request("GET", path, { params });
+}
+export function apiPost(path, body) {
+    return request("POST", path, { body });
+}
+export function apiPatch(path, body) {
+    return request("PATCH", path, { body });
+}
+export function apiDelete(path) {
+    return request("DELETE", path);
+}

package/dist/commands/astra.js

@@ -0,0 +1,543 @@
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+import { apiGet, apiPost, apiPatch, apiDelete } from "../client.js";
+import { WEBDRIVE_BASE_URL } from "../constants.js";
+import { getValidToken } from "../auth/manager.js";
+import { getSpaceSlug, getVaultSlug } from "./init.js";
+function isJsonMode(cmd) {
+    return !!cmd.parent?.opts().json;
+}
+function jsonOut(data) {
+    console.log(JSON.stringify({ success: true, data }));
+}
+function resolveSpaceSlug(cmd) {
+    return cmd.opts().spaceSlug || getSpaceSlug();
+}
+function resolveVaultSlug(opts) {
+    return opts.vaultSlug || getVaultSlug();
+}
+function unwrapResp(resp) {
+    if (typeof resp === "object" && resp !== null && "data" in resp) {
+        return resp.data;
+    }
+    return resp;
+}
+export function registerAstraCommand(program) {
+    const astra = program
+        .command("astra")
+        .description("Astra commands (posts, sessions, brains, brain updates).")
+        .option("--space-slug <slug>", "Space slug (overrides .gobi/settings.yaml)");
+    // ── Brains ──
+    astra
+        .command("search-brain")
+        .description("Search brains (second brains/vaults) in a space using text and semantic search.")
+        .requiredOption("--query <query>", "Search query")
+        .action(async (opts) => {
+        const spaceSlug = resolveSpaceSlug(astra);
+        const resp = (await apiGet(`/spaces/${spaceSlug}/brains`, {
+            query: opts.query,
+        }));
+        const results = (Array.isArray(resp) ? resp : resp.data || resp);
+        if (isJsonMode(astra)) {
+            jsonOut(results || []);
+            return;
+        }
+        if (!results || results.length === 0) {
+            console.log(`No brains found matching "${opts.query}".`);
+            return;
+        }
+        const lines = [];
+        for (const entry of results) {
+            const vault = (entry.vault || entry);
+            const owner = (entry.owner || {});
+            const ownerName = owner.name ? ` by ${owner.name}` : "";
+            const sim = entry.similarity != null
+                ? ` [similarity: ${entry.similarity.toFixed(3)}]`
+                : "";
+            lines.push(`- ${vault.name || vault.title || "N/A"} (ID: ${vault.vaultId || vault.id || "N/A"})${ownerName}${sim}`);
+        }
+        console.log(`Brains matching "${opts.query}":\n` + lines.join("\n"));
+    });
+    astra
+        .command("ask-brain")
+        .description("Ask a brain a question. Creates a targeted session (1:1 conversation).")
+        .requiredOption("--vault-slug <vaultSlug>", "Slug of the brain/vault to ask")
+        .requiredOption("--question <question>", "The question to ask (markdown supported)")
+        .option("--mode <mode>", 'Session mode: "auto" or "manual"', "auto")
+        .action(async (opts) => {
+        const spaceSlug = resolveSpaceSlug(astra);
+        const resp = (await apiPost(`/session/targeted`, {
+            vaultSlug: opts.vaultSlug,
+            spaceSlug,
+            question: opts.question,
+            mode: opts.mode,
+        }));
+        const data = unwrapResp(resp);
+        if (isJsonMode(astra)) {
+            jsonOut(data);
+            return;
+        }
+        const session = (data.session || {});
+        const members = (data.members || []);
+        console.log(`Session created!\n` +
+            `  Session ID: ${session.id}\n` +
+            `  Mode: ${session.mode}\n` +
+            `  Members: ${members.length}\n` +
+            `  Question sent.`);
+    });
+    astra
+        .command("publish-brain")
+        .description("Upload BRAIN.md to the vault root on webdrive. Triggers post-processing (brain sync, metadata update, Discord notification).")
+        .action(async () => {
+        const vaultId = getVaultSlug();
+        const filePath = join(process.cwd(), "BRAIN.md");
+        if (!existsSync(filePath)) {
+            throw new Error(`BRAIN.md not found in ${process.cwd()}`);
+        }
+        const content = readFileSync(filePath, "utf-8");
+        const token = await getValidToken();
+        const url = `${WEBDRIVE_BASE_URL}/api/v1/vaults/${vaultId}/files/BRAIN.md`;
+        const res = await fetch(url, {
+            method: "PUT",
+            headers: {
+                Authorization: `Bearer ${token}`,
+                "Content-Type": "text/markdown",
+            },
+            body: content,
+        });
+        if (!res.ok) {
+            throw new Error(`Upload failed: HTTP ${res.status}: ${(await res.text()) || "(no body)"}`);
+        }
+        if (isJsonMode(astra)) {
+            jsonOut({ vaultId });
+            return;
+        }
+        console.log(`Published BRAIN.md to vault "${vaultId}"`);
+    });
+    astra
+        .command("unpublish-brain")
+        .description("Delete BRAIN.md from the vault on webdrive.")
+        .action(async () => {
+        const vaultId = getVaultSlug();
+        const token = await getValidToken();
+        const url = `${WEBDRIVE_BASE_URL}/api/v1/vaults/${vaultId}/files/BRAIN.md`;
+        const res = await fetch(url, {
+            method: "DELETE",
+            headers: { Authorization: `Bearer ${token}` },
+        });
+        if (!res.ok) {
+            throw new Error(`Delete failed: HTTP ${res.status}: ${(await res.text()) || "(no body)"}`);
+        }
+        if (isJsonMode(astra)) {
+            jsonOut({ vaultId });
+            return;
+        }
+        console.log(`Deleted BRAIN.md from vault "${vaultId}"`);
+    });
+    // ── Posts (get, list, create, edit, delete) ──
+    astra
+        .command("get-post <postId>")
+        .description("Get a post and its replies (paginated).")
+        .option("--limit <number>", "Replies per page", "20")
+        .option("--offset <number>", "Offset for reply pagination", "0")
+        .action(async (postId, opts) => {
+        const spaceSlug = resolveSpaceSlug(astra);
+        const resp = (await apiGet(`/spaces/${spaceSlug}/posts/${postId}`, {
+            limit: parseInt(opts.limit, 10),
+            offset: parseInt(opts.offset, 10),
+        }));
+        const data = unwrapResp(resp);
+        const pagination = (resp.pagination || {});
+        if (isJsonMode(astra)) {
+            jsonOut({ ...data, pagination });
+            return;
+        }
+        const msg = (data.post || data);
+        const replies = (data.replies || []);
+        const totalReplies = pagination.total ||
+            msg.replyCount ||
+            0;
+        const author = msg.author?.name ||
+            `User ${msg.authorId}`;
+        const replyLines = [];
+        for (const r of replies) {
+            const rAuthor = r.author?.name ||
+                `User ${r.authorId}`;
+            const text = r.content;
+            const truncated = text.length > 200 ? text.slice(0, 200) + "\u2026" : text;
+            replyLines.push(`  - ${rAuthor}: ${truncated} (${r.createdAt})`);
+        }
+        const output = [
+            `Post: ${msg.title}`,
+            `By: ${author} on ${msg.createdAt}`,
+            "",
+            msg.content,
+            "",
+            `Replies (${replies.length} of ${totalReplies}):`,
+            ...replyLines,
+        ].join("\n");
+        console.log(output);
+    });
+    astra
+        .command("list-posts")
+        .description("List posts in a space (paginated).")
+        .option("--limit <number>", "Items per page", "20")
+        .option("--offset <number>", "Offset for pagination", "0")
+        .action(async (opts) => {
+        const spaceSlug = resolveSpaceSlug(astra);
+        const resp = (await apiGet(`/spaces/${spaceSlug}/posts`, {
+            limit: parseInt(opts.limit, 10),
+            offset: parseInt(opts.offset, 10),
+        }));
+        if (isJsonMode(astra)) {
+            jsonOut({
+                items: resp.data || [],
+                pagination: resp.pagination || {},
+            });
+            return;
+        }
+        const items = (resp.data || []);
+        const pagination = (resp.pagination || {});
+        if (!items.length) {
+            console.log("No posts found.");
+            return;
+        }
+        const lines = [];
+        for (const msg of items) {
+            const author = msg.author?.name ||
+                `User ${msg.authorId}`;
+            lines.push(`- [${msg.id}] "${msg.title}" by ${author} (${msg.replyCount} replies, ${msg.createdAt})`);
+        }
+        const total = pagination.total || items.length;
+        console.log(`Posts (${items.length} of ${total}):\n` + lines.join("\n"));
+    });
+    astra
+        .command("create-post")
+        .description("Create a post in a space.")
+        .requiredOption("--title <title>", "Title of the post")
+        .requiredOption("--content <content>", "Post content (markdown supported)")
+        .action(async (opts) => {
+        const spaceSlug = resolveSpaceSlug(astra);
+        const resp = (await apiPost(`/spaces/${spaceSlug}/posts`, {
+            title: opts.title,
+            content: opts.content,
+        }));
+        const msg = unwrapResp(resp);
+        if (isJsonMode(astra)) {
+            jsonOut(msg);
+            return;
+        }
+        console.log(`Post created!\n` +
+            `  ID: ${msg.id}\n` +
+            `  Title: ${msg.title}\n` +
+            `  Created: ${msg.createdAt}`);
+    });
+    astra
+        .command("edit-post <postId>")
+        .description("Edit a post. You must be the author.")
+        .option("--title <title>", "New title for the post")
+        .option("--content <content>", "New content for the post (markdown supported)")
+        .action(async (postId, opts) => {
+        if (!opts.title && !opts.content) {
+            throw new Error("Provide at least --title or --content to update.");
+        }
+        const spaceSlug = resolveSpaceSlug(astra);
+        const body = {};
+        if (opts.title != null)
+            body.title = opts.title;
+        if (opts.content != null)
+            body.content = opts.content;
+        const resp = (await apiPatch(`/spaces/${spaceSlug}/posts/${postId}`, body));
+        const msg = unwrapResp(resp);
+        if (isJsonMode(astra)) {
+            jsonOut(msg);
+            return;
+        }
+        console.log(`Post edited!\n` +
+            `  ID: ${msg.id}\n` +
+            `  Title: ${msg.title}\n` +
+            `  Edited: ${msg.editedAt}`);
+    });
+    astra
+        .command("delete-post <postId>")
+        .description("Delete a post. You must be the author.")
+        .action(async (postId) => {
+        const spaceSlug = resolveSpaceSlug(astra);
+        await apiDelete(`/spaces/${spaceSlug}/posts/${postId}`);
+        if (isJsonMode(astra)) {
+            jsonOut({ id: postId });
+            return;
+        }
+        console.log(`Post ${postId} deleted.`);
+    });
+    // ── Replies (list, create, edit, delete) ──
+    astra
+        .command("list-replies <postId>")
+        .description("List replies to a post (paginated).")
+        .option("--limit <number>", "Replies per page", "20")
+        .option("--offset <number>", "Offset for reply pagination", "0")
+        .action(async (postId, opts) => {
+        const spaceSlug = resolveSpaceSlug(astra);
+        const resp = (await apiGet(`/spaces/${spaceSlug}/posts/${postId}`, {
+            limit: parseInt(opts.limit, 10),
+            offset: parseInt(opts.offset, 10),
+        }));
+        const data = unwrapResp(resp);
+        const pagination = (resp.pagination || {});
+        if (isJsonMode(astra)) {
+            jsonOut({
+                replies: data.replies || [],
+                pagination,
+            });
+            return;
+        }
+        const replies = (data.replies || []);
+        const totalReplies = pagination.total || replies.length;
+        if (!replies.length) {
+            console.log("No replies found.");
+            return;
+        }
+        const lines = [];
+        for (const r of replies) {
+            const author = r.author?.name ||
+                `User ${r.authorId}`;
+            const text = r.content;
+            const truncated = text.length > 200 ? text.slice(0, 200) + "\u2026" : text;
+            lines.push(`- [${r.id}] ${author}: ${truncated} (${r.createdAt})`);
+        }
+        console.log(`Replies (${replies.length} of ${totalReplies}):\n` +
+            lines.join("\n"));
+    });
+    astra
+        .command("create-reply <postId>")
+        .description("Create a reply to a post in a space.")
+        .requiredOption("--content <content>", "Reply content (markdown supported)")
+        .action(async (postId, opts) => {
+        const spaceSlug = resolveSpaceSlug(astra);
+        const resp = (await apiPost(`/spaces/${spaceSlug}/posts/${postId}/replies`, { content: opts.content }));
+        const msg = unwrapResp(resp);
+        if (isJsonMode(astra)) {
+            jsonOut(msg);
+            return;
+        }
+        console.log(`Reply created!\n  ID: ${msg.id}\n  Created: ${msg.createdAt}`);
+    });
+    astra
+        .command("edit-reply <replyId>")
+        .description("Edit a reply. You must be the author.")
+        .requiredOption("--content <content>", "New content for the reply (markdown supported)")
+        .action(async (replyId, opts) => {
+        const spaceSlug = resolveSpaceSlug(astra);
+        const resp = (await apiPatch(`/spaces/${spaceSlug}/replies/${replyId}`, { content: opts.content }));
+        const msg = unwrapResp(resp);
+        if (isJsonMode(astra)) {
+            jsonOut(msg);
+            return;
+        }
+        console.log(`Reply edited!\n  ID: ${msg.id}\n  Edited: ${msg.editedAt}`);
+    });
+    astra
+        .command("delete-reply <replyId>")
+        .description("Delete a reply. You must be the author.")
+        .action(async (replyId) => {
+        const spaceSlug = resolveSpaceSlug(astra);
+        await apiDelete(`/spaces/${spaceSlug}/replies/${replyId}`);
+        if (isJsonMode(astra)) {
+            jsonOut({ replyId });
+            return;
+        }
+        console.log(`Reply ${replyId} deleted.`);
+    });
+    // ── Sessions (get, list, reply) ──
+    astra
+        .command("get-session <sessionId>")
+        .description("Get a session and its messages (paginated).")
+        .option("--limit <number>", "Messages per page", "20")
+        .option("--offset <number>", "Offset for message pagination", "0")
+        .action(async (sessionId, opts) => {
+        const resp = (await apiGet(`/session/${sessionId}`, {
+            limit: parseInt(opts.limit, 10),
+            offset: parseInt(opts.offset, 10),
+        }));
+        const data = unwrapResp(resp);
+        if (isJsonMode(astra)) {
+            jsonOut(data);
+            return;
+        }
+        const session = (data.session || data);
+        const messages = (data.messages || []);
+        const pagination = (data.pagination || {});
+        const totalMessages = pagination.total || messages.length;
+        const msgLines = [];
+        for (const m of messages) {
+            const author = m.author?.name ||
+                m.source ||
+                `User ${m.authorId}`;
+            const text = m.content;
+            const truncated = text.length > 200 ? text.slice(0, 200) + "\u2026" : text;
+            msgLines.push(`  - ${author}: ${truncated} (${m.createdAt})`);
+        }
+        const output = [
+            `Session: ${session.title}`,
+            `  ID: ${session.id}`,
+            `  Mode: ${session.mode}`,
+            `  Last activity: ${session.lastMessageAt}`,
+            "",
+            `Messages (${messages.length} of ${totalMessages}):`,
+            ...msgLines,
+        ].join("\n");
+        console.log(output);
+    });
+    astra
+        .command("list-sessions")
+        .description("List all sessions you are part of, sorted by most recent activity.")
+        .option("--limit <number>", "Items per page", "20")
+        .option("--offset <number>", "Offset for pagination", "0")
+        .action(async (opts) => {
+        const spaceSlug = resolveSpaceSlug(astra);
+        const limit = parseInt(opts.limit, 10);
+        const offset = parseInt(opts.offset, 10);
+        const resp = (await apiGet(`/session/my-sessions`, {
+            spaceSlug,
+            limit,
+            offset,
+        }));
+        const data = unwrapResp(resp);
+        const items = (data.sessions || []);
+        const total = data.total ?? items.length;
+        if (isJsonMode(astra)) {
+            jsonOut({
+                sessions: items,
+                pagination: { total, limit, offset },
+            });
+            return;
+        }
+        if (!items.length) {
+            console.log("No sessions found.");
+            return;
+        }
+        const lines = [];
+        for (const s of items) {
+            const title = s.title || "(no title)";
+            lines.push(`- [${s.id}] "${title}" (mode: ${s.mode}, last activity: ${s.lastMessageAt})`);
+        }
+        console.log(`Sessions (${items.length} of ${total}):\n` + lines.join("\n"));
+    });
+    astra
+        .command("reply-session <sessionId>")
+        .description("Send a human reply to a session you are a member of.")
+        .requiredOption("--content <content>", "Reply content (markdown supported)")
+        .action(async (sessionId, opts) => {
+        const resp = (await apiPost(`/session/${sessionId}/reply`, {
+            content: opts.content,
+        }));
+        const msg = unwrapResp(resp);
+        if (isJsonMode(astra)) {
+            jsonOut(msg);
+            return;
+        }
+        console.log(`Reply sent!\n` +
+            `  Message ID: ${msg.id}\n` +
+            `  Source: ${msg.source}\n` +
+            `  Created: ${msg.createdAt}`);
+    });
+    // ── Brain Updates (list, create, edit, delete) ──
+    astra
+        .command("list-brain-updates")
+        .description("List recent brain updates in a space (paginated).")
+        .option("--limit <number>", "Items per page", "20")
+        .option("--offset <number>", "Offset for pagination", "0")
+        .action(async (opts) => {
+        const spaceSlug = resolveSpaceSlug(astra);
+        const resp = (await apiGet(`/spaces/${spaceSlug}/brain-updates`, {
+            limit: parseInt(opts.limit, 10),
+            offset: parseInt(opts.offset, 10),
+        }));
+        if (isJsonMode(astra)) {
+            jsonOut({
+                items: resp.data || [],
+                pagination: resp.pagination || {},
+            });
+            return;
+        }
+        const items = (resp.data || []);
+        const pagination = (resp.pagination || {});
+        if (!items.length) {
+            console.log("No brain updates found.");
+            return;
+        }
+        const lines = [];
+        for (const u of items) {
+            const author = u.author?.name ||
+                `User ${u.authorId}`;
+            const vaultSlug = u.vault?.vaultSlug ||
+                "?";
+            lines.push(`- [${u.id}] "${u.title}" by ${author} (vault: ${vaultSlug}, ${u.createdAt})`);
+        }
+        const total = pagination.total || items.length;
+        console.log(`Brain updates (${items.length} of ${total}):\n` + lines.join("\n"));
+    });
+    astra
+        .command("create-brain-update")
+        .description("Create a brain update in a space. Uses the vault from settings.")
+        .option("--vault-slug <vaultSlug>", "Vault slug (overrides .gobi/settings.yaml)")
+        .requiredOption("--title <title>", "Title of the update")
+        .requiredOption("--content <content>", "Update content (markdown supported)")
+        .action(async (opts) => {
+        const spaceSlug = resolveSpaceSlug(astra);
+        const vaultSlug = resolveVaultSlug(opts);
+        const resp = (await apiPost(`/spaces/${spaceSlug}/brain-updates`, {
+            vaultSlug,
+            title: opts.title,
+            content: opts.content,
+        }));
+        const u = unwrapResp(resp);
+        if (isJsonMode(astra)) {
+            jsonOut(u);
+            return;
+        }
+        console.log(`Brain update created!\n` +
+            `  ID: ${u.id}\n` +
+            `  Title: ${u.title}\n` +
+            `  Vault: ${u.vaultSlug || vaultSlug}\n` +
+            `  Created: ${u.createdAt}`);
+    });
+    astra
+        .command("edit-brain-update <updateId>")
+        .description("Edit a published brain update. You must be the author.")
+        .option("--title <title>", "New title for the update")
+        .option("--content <content>", "New content for the update (markdown supported)")
+        .action(async (updateId, opts) => {
+        if (!opts.title && !opts.content) {
+            throw new Error("Provide at least --title or --content to update.");
+        }
+        const spaceSlug = resolveSpaceSlug(astra);
+        const body = {};
+        if (opts.title != null)
+            body.title = opts.title;
+        if (opts.content != null)
+            body.content = opts.content;
+        const resp = (await apiPatch(`/spaces/${spaceSlug}/brain-updates/${updateId}`, body));
+        const u = unwrapResp(resp);
+        if (isJsonMode(astra)) {
+            jsonOut(u);
+            return;
+        }
+        console.log(`Brain update edited!\n` +
+            `  ID: ${u.id}\n` +
+            `  Title: ${u.title}\n` +
+            `  Updated: ${u.updatedAt}`);
+    });
+    astra
+        .command("delete-brain-update <updateId>")
+        .description("Delete a published brain update. You must be the author.")
+        .action(async (updateId) => {
+        const spaceSlug = resolveSpaceSlug(astra);
+        await apiDelete(`/spaces/${spaceSlug}/brain-updates/${updateId}`);
+        if (isJsonMode(astra)) {
+            jsonOut({ id: updateId });
+            return;
+        }
+        console.log(`Brain update ${updateId} deleted.`);
+    });
+}

package/dist/commands/auth.js

@@ -0,0 +1,96 @@
+import { BASE_URL, POLL_MAX_DURATION_MS } from "../constants.js";
+import { DeviceCodeError } from "../errors.js";
+import { storeTokens, logout, isAuthenticated, getCurrentUser, } from "../auth/manager.js";
+import { printContext, readSettings, runInitFlow } from "./init.js";
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export function registerAuthCommand(program) {
+    const auth = program
+        .command("auth")
+        .description("Authentication commands.");
+    auth
+        .command("login")
+        .description("Log in to Gobi. Opens a browser URL for Google OAuth, then polls until authentication is complete.")
+        .action(async () => {
+        const res = await fetch(`${BASE_URL}/auth/device`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+        });
+        if (!res.ok) {
+            const body = (await res.text()) || "(no body)";
+            throw new DeviceCodeError(`Failed to initiate login: HTTP ${res.status}: ${body}`);
+        }
+        const deviceData = (await res.json());
+        const intervalS = deviceData.interval || 5;
+        const startMs = Date.now();
+        console.log(`Open this URL in your browser to log in:\n  ${deviceData.verificationUri}`);
+        console.log(`Your user code: ${deviceData.userCode}`);
+        console.log("Waiting for authentication...");
+        while (Date.now() - startMs < POLL_MAX_DURATION_MS) {
+            await sleep(intervalS * 1000);
+            const tokenRes = await fetch(`${BASE_URL}/auth/device/token`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({ deviceCode: deviceData.deviceCode }),
+            });
+            if (!tokenRes.ok) {
+                const body = (await tokenRes.text()) || "(no body)";
+                throw new DeviceCodeError(`Token poll failed: HTTP ${tokenRes.status}: ${body}`);
+            }
+            const tokenData = (await tokenRes.json());
+            if ("accessToken" in tokenData) {
+                const user = tokenData.user;
+                const creds = {
+                    accessToken: tokenData.accessToken,
+                    refreshToken: tokenData.refreshToken,
+                    expiresAt: Date.now() + tokenData.expiresIn * 1000,
+                    user: {
+                        id: user.id,
+                        email: user.email,
+                        name: user.name,
+                        pictureUrl: user.pictureUrl || null,
+                    },
+                };
+                await storeTokens(creds);
+                console.log(`Successfully logged in as ${user.name} (${user.email}).`);
+                const settings = readSettings();
+                if (settings && settings.selectedSpaceSlug) {
+                    printContext();
+                    console.log("Run 'gobi init' to change.");
+                }
+                else {
+                    console.log("");
+                    await runInitFlow();
+                }
+                return;
+            }
+            if (tokenData.status === "expired") {
+                throw new DeviceCodeError("Login session expired. Please try 'gobi auth login' again.");
+            }
+        }
+        throw new DeviceCodeError("Login timed out. Please try 'gobi auth login' again.");
+    });
+    auth
+        .command("status")
+        .description("Check whether you are currently authenticated with Gobi.")
+        .action(() => {
+        if (isAuthenticated()) {
+            const user = getCurrentUser();
+            const name = user?.name || "Unknown";
+            const email = user?.email || "Unknown";
+            console.log(`Authenticated as ${name} (${email})`);
+            printContext();
+        }
+        else {
+            console.log("You are not authenticated. Use 'gobi auth login' to log in.");
+        }
+    });
+    auth
+        .command("logout")
+        .description("Log out of Gobi and remove stored credentials.")
+        .action(async () => {
+        await logout();
+        console.log("Logged out. Credentials removed.");
+    });
+}

package/dist/commands/init.js

@@ -0,0 +1,212 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { join } from "path";
+import inquirer from "inquirer";
+import yaml from "js-yaml";
+import { apiGet, apiPost } from "../client.js";
+import { isAuthenticated } from "../auth/manager.js";
+const SETTINGS_DIR = ".gobi";
+const SETTINGS_FILE = "settings.yaml";
+function settingsPath() {
+    return join(process.cwd(), SETTINGS_DIR, SETTINGS_FILE);
+}
+export function readSettings() {
+    const path = settingsPath();
+    if (!existsSync(path))
+        return null;
+    const content = readFileSync(path, "utf-8");
+    return yaml.load(content);
+}
+export function getSpaceSlug() {
+    const settings = readSettings();
+    const slug = settings?.selectedSpaceSlug;
+    if (!slug) {
+        throw new Error("Not initialized. Run 'gobi init' first.");
+    }
+    return slug;
+}
+export function getVaultSlug() {
+    const settings = readSettings();
+    const vault = settings?.vaultSlug;
+    if (!vault) {
+        throw new Error("Not initialized. Run 'gobi init' first.");
+    }
+    return vault;
+}
+export function printContext() {
+    const settings = readSettings();
+    const slug = settings?.selectedSpaceSlug;
+    if (!slug) {
+        console.log("Not initialized. Run 'gobi init' to set up.");
+        return;
+    }
+    const vaultId = settings?.vaultSlug || "?";
+    console.log(`Space: ${slug} | Vault: ${vaultId}`);
+}
+function writeSettings(vaultId, spaceSlug) {
+    const path = settingsPath();
+    const dir = join(process.cwd(), SETTINGS_DIR);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    const content = yaml.dump({ vaultSlug: vaultId, selectedSpaceSlug: spaceSlug }, { flowLevel: -1 });
+    writeFileSync(path, content, "utf-8");
+}
+async function selectSpace() {
+    const resp = (await apiGet("/spaces"));
+    const spaces = (Array.isArray(resp) ? resp : resp.data || resp);
+    if (!spaces || spaces.length === 0) {
+        throw new Error("You are not a member of any spaces. Join or create a space first.");
+    }
+    const choices = spaces.map((s) => ({
+        name: `${s.name} (${s.slug})`,
+        value: s,
+    }));
+    if (choices.length > 1) {
+        choices.push({ name: "Go back", value: null });
+    }
+    const { selected } = await inquirer.prompt([
+        {
+            type: "list",
+            name: "selected",
+            message: "Select a space:",
+            choices,
+        },
+    ]);
+    if (selected === null)
+        return null;
+    return { slug: selected.slug, name: selected.name };
+}
+async function selectExistingVault() {
+    const resp = (await apiGet("/vault"));
+    const vaults = (Array.isArray(resp) ? resp : resp.data || resp);
+    if (!vaults || vaults.length === 0) {
+        console.log("You don't have any vaults yet. Let's create one.");
+        return createNewVault();
+    }
+    const choices = vaults.map((v) => ({
+        name: `${v.name} (${v.vaultId})`,
+        value: v,
+    }));
+    choices.push({ name: "Go back", value: null });
+    const { selected } = await inquirer.prompt([
+        {
+            type: "list",
+            name: "selected",
+            message: "Select a vault:",
+            choices,
+        },
+    ]);
+    if (selected === null)
+        return null;
+    return {
+        vaultId: selected.vaultId,
+        name: selected.name,
+    };
+}
+async function createNewVault() {
+    let vaultId;
+    while (true) {
+        const { id } = await inquirer.prompt([
+            {
+                type: "input",
+                name: "id",
+                message: "Enter a unique vault ID:",
+            },
+        ]);
+        if (!id.trim()) {
+            console.log("Vault ID cannot be empty.");
+            continue;
+        }
+        vaultId = id.trim();
+        const resp = (await apiGet(`/vault/check/${vaultId}`));
+        const available = typeof resp === "object" && resp !== null
+            ? resp.available
+            : false;
+        if (available) {
+            console.log(`ID "${vaultId}" is available!`);
+            break;
+        }
+        else {
+            console.log(`ID "${vaultId}" is already taken. Try another.`);
+        }
+    }
+    const { vaultName } = await inquirer.prompt([
+        {
+            type: "input",
+            name: "vaultName",
+            message: "Enter vault name:",
+        },
+    ]);
+    const name = vaultName.trim() || vaultId;
+    const resp = (await apiPost("/vault", {
+        vaultId,
+        name,
+    }));
+    const vault = (typeof resp === "object" && resp !== null && "data" in resp
+        ? resp.data
+        : resp);
+    console.log(`Created vault "${vault.name}" (${vault.vaultId})`);
+    return { vaultId: vault.vaultId, name: vault.name };
+}
+export async function runInitFlow() {
+    if (!isAuthenticated()) {
+        throw new Error("Not authenticated. Run 'gobi auth login' first.");
+    }
+    // Step 1: Select or create vault
+    let vaultId;
+    let vaultName;
+    while (true) {
+        const { action } = await inquirer.prompt([
+            {
+                type: "list",
+                name: "action",
+                message: "How would you like to set up your vault?",
+                choices: [
+                    { name: "Select an existing vault", value: "existing" },
+                    { name: "Create a new vault", value: "new" },
+                ],
+            },
+        ]);
+        if (action === "existing") {
+            const result = await selectExistingVault();
+            if (result === null)
+                continue;
+            vaultId = result.vaultId;
+            vaultName = result.name;
+        }
+        else {
+            const result = await createNewVault();
+            vaultId = result.vaultId;
+            vaultName = result.name;
+        }
+        break;
+    }
+    // Step 2: Select space
+    let spaceSlug;
+    let spaceName;
+    while (true) {
+        const result = await selectSpace();
+        if (result === null)
+            continue;
+        spaceSlug = result.slug;
+        spaceName = result.name;
+        break;
+    }
+    writeSettings(vaultId, spaceSlug);
+    console.log(`Linked to space "${spaceName}" (${spaceSlug}) with vault "${vaultName}" (${vaultId})`);
+    console.log(`Created ${SETTINGS_DIR}/${SETTINGS_FILE}`);
+    // Create default BRAIN.md if it doesn't exist
+    const brainPath = join(process.cwd(), "BRAIN.md");
+    if (!existsSync(brainPath)) {
+        writeFileSync(brainPath, `---\ntitle: ${vaultName}\ntags: []\ndescription:\nthumbnail:\nprompt:\n---\n`, "utf-8");
+        console.log("Created BRAIN.md");
+    }
+}
+export function registerInitCommand(program) {
+    program
+        .command("init")
+        .description("Set up or change the space and vault linked to the current directory.")
+        .action(async () => {
+        await runInitFlow();
+    });
+}

package/dist/constants.js

@@ -0,0 +1,6 @@
+export const BASE_URL = process.env.GOBI_BASE_URL || "https://backend.joingobi.com";
+export const WEBDRIVE_BASE_URL = process.env.GOBI_WEBDRIVE_BASE_URL || "https://webdrive.joingobi.com";
+// Refresh access token when less than 5 minutes remain
+export const TOKEN_REFRESH_BUFFER_MS = 5 * 60 * 1000;
+// Max polling duration before giving up (ms) - 10 minutes
+export const POLL_MAX_DURATION_MS = 10 * 60 * 1000;

package/dist/errors.js

@@ -0,0 +1,45 @@
+export class AstraError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = "AstraError";
+    }
+}
+export class NotAuthenticatedError extends AstraError {
+    constructor() {
+        super("Not authenticated. Use 'gobi auth login' to begin the login flow.", "NOT_AUTHENTICATED");
+        this.name = "NotAuthenticatedError";
+    }
+}
+export class TokenRefreshError extends AstraError {
+    constructor(detail) {
+        super(`Failed to refresh access token: ${detail}. Please run 'gobi auth login' to re-authenticate.`, "TOKEN_REFRESH_FAILED");
+        this.name = "TokenRefreshError";
+    }
+}
+export class ApiError extends AstraError {
+    status;
+    endpoint;
+    constructor(status, endpoint, body) {
+        let message = body;
+        try {
+            const parsed = JSON.parse(body);
+            if (parsed.message)
+                message = parsed.message;
+        }
+        catch {
+            // use raw body as-is
+        }
+        super(message, "API_ERROR");
+        this.status = status;
+        this.endpoint = endpoint;
+        this.name = "ApiError";
+    }
+}
+export class DeviceCodeError extends AstraError {
+    constructor(detail) {
+        super(`Device code flow error: ${detail}`, "DEVICE_CODE_ERROR");
+        this.name = "DeviceCodeError";
+    }
+}

package/dist/index.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { cli } from "./main.js";
+cli();

package/dist/main.js

@@ -0,0 +1,82 @@
+import { createRequire } from "module";
+import { Command } from "commander";
+import { initCredentials } from "./auth/manager.js";
+import { ApiError, AstraError } from "./errors.js";
+import { registerAuthCommand } from "./commands/auth.js";
+import { registerInitCommand, printContext } from "./commands/init.js";
+import { registerAstraCommand } from "./commands/astra.js";
+const require = createRequire(import.meta.url);
+const { version } = require("../package.json");
+const SKIP_BANNER_COMMANDS = new Set(["auth", "init"]);
+function shouldShowBanner() {
+    const args = process.argv.slice(2);
+    if (args.length === 0)
+        return true;
+    return !SKIP_BANNER_COMMANDS.has(args[0]);
+}
+export async function cli() {
+    const program = new Command();
+    program
+        .name("gobi")
+        .version(version)
+        .description("CLI client for the Gobi collaborative knowledge platform")
+        .option("--json", "Output results as JSON instead of human-readable text")
+        .configureHelp({ helpWidth: process.stdout.columns || 200 });
+    // Register all command groups
+    registerAuthCommand(program);
+    registerInitCommand(program);
+    registerAstraCommand(program);
+    // Propagate helpWidth to all subcommands
+    const helpWidth = process.stdout.columns || 200;
+    for (const cmd of program.commands) {
+        cmd.configureHelp({ helpWidth });
+        for (const sub of cmd.commands) {
+            sub.configureHelp({ helpWidth });
+        }
+    }
+    // Hook into the pre-action to init credentials and show banner
+    program.hook("preAction", async () => {
+        await initCredentials();
+        if (!program.opts().json && shouldShowBanner()) {
+            printContext();
+            console.log("");
+        }
+    });
+    try {
+        await program.parseAsync(process.argv);
+    }
+    catch (err) {
+        const isJson = program.opts().json;
+        if (err instanceof ApiError) {
+            if (isJson) {
+                console.log(JSON.stringify({ success: false, error: `API error (HTTP ${err.status}): ${err.message}` }));
+                process.exit(1);
+            }
+            let hint = "";
+            if (err.status === 403) {
+                hint = " You may not have permission to perform this action.";
+            }
+            else if (err.status === 404) {
+                hint = " The requested resource was not found.";
+            }
+            console.error(`Error: API error (HTTP ${err.status}): ${err.message}${hint}`);
+            process.exit(1);
+        }
+        else if (err instanceof AstraError) {
+            if (isJson) {
+                console.log(JSON.stringify({ success: false, error: err.message }));
+                process.exit(1);
+            }
+            console.error(`Error: ${err.message}`);
+            process.exit(1);
+        }
+        const msg = err instanceof Error ? err.message : String(err);
+        if (isJson) {
+            console.log(JSON.stringify({ success: false, error: msg }));
+        }
+        else {
+            console.error(`Error: ${msg}`);
+        }
+        process.exit(1);
+    }
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@gobi-ai/cli",
+  "version": "0.1.1",
+  "description": "CLI client for the Gobi collaborative knowledge platform",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/gobi-ai/gobi-cli.git"
+  },
+  "homepage": "https://github.com/gobi-ai/gobi-cli",
+  "bugs": {
+    "url": "https://github.com/gobi-ai/gobi-cli/issues"
+  },
+  "keywords": [
+    "gobi",
+    "cli",
+    "second-brain",
+    "knowledge"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.test.js"
+  ],
+  "bin": {
+    "gobi": "./dist/index.js"
+  },
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "npm run clean && tsc && chmod +x dist/index.js",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js",
+    "test": "node --test dist/*.test.js",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "inquirer": "^12.3.0",
+    "js-yaml": "^4.1.0"
+  },
+  "devDependencies": {
+    "@types/inquirer": "^9.0.7",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0"
+  }
+}