sfora-cli 0.6.0 → 0.8.0

package/dist/cli.js

@@ -10,9 +10,10 @@ import * as readline from "node:readline";
 import { spawn } from "node:child_process";
 import { readFile as readLocalFile } from "node:fs/promises";
 import { basename } from "node:path";
-import { createSforaShell, SforaApiClient } from "./index.js";
+import { createSforaShell, createLocalShell, SforaApiClient } from "./index.js";
+import { LocalWorkspace, initWorkspace, findWorkspace, } from "./local/workspace.js";
 import { runMcpServer } from "./mcp-server.js";
-import { readConfig, writeConfig, resolveSettings, DEFAULT_URL, } from "./config.js";
+import { readConfig, writeConfig, resolveSettings, upsertProfile, effectiveProfiles, DEFAULT_URL, } from "./config.js";
 const colors = {
     reset: "\x1b[0m",
     bold: "\x1b[1m",
@@ -24,7 +25,7 @@ const colors = {
     red: "\x1b[31m",
 };
 function parseArgs(argv) {
-    const args = { rest: [], cwd: "/", mcp: false, help: false, draft: false };
+    const args = { rest: [], cwd: "/", mcp: false, help: false, draft: false, json: false, local: false, cloud: false };
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i];
         if (a === "--mcp")
@@ -53,6 +54,10 @@ function parseArgs(argv) {
             args.bot = a.slice("--bot=".length);
         else if (a.startsWith("--agent="))
             args.bot = a.slice("--agent=".length);
+        else if (a === "--as")
+            args.as = argv[++i];
+        else if (a.startsWith("--as="))
+            args.as = a.slice("--as=".length);
         else if (a === "--web")
             args.web = argv[++i];
         else if (a.startsWith("--web="))
@@ -67,6 +72,12 @@ function parseArgs(argv) {
             args.column = a.slice("--column=".length);
         else if (a === "--draft")
             args.draft = true;
+        else if (a === "--json")
+            args.json = true;
+        else if (a === "--local")
+            args.local = true;
+        else if (a === "--cloud")
+            args.cloud = true;
         else if (!a.startsWith("-")) {
             if (!args.command)
                 args.command = a;
@@ -78,34 +89,79 @@ function parseArgs(argv) {
 }
 const HELP = `sfora — the CLI for your sfora workspace
 
-Get started:
-  sfora login                         Authorize as you (saves your key)
+Get started (no account needed):
+  sfora init --local                  Create a .sfora/ workspace in this repo —
+                                      tasks/posts/docs as plain markdown files,
+                                      versioned with your code
+  sfora login                         Authorize with sfora cloud (saves your key)
   sfora login --bot <name>            Authorize as a named bot (its own key)
 
-Run as a bot: add --bot <name> to any command (default identity is you).
+Inside a .sfora/ repo the CLI works on the local files; pass --cloud (or
+--org/--url) to target sfora cloud instead. Run as a bot: add --bot <name>.
 
 Push markdown straight to sfora:
   sfora post <file.md> [--project <slug>] [--draft]   Publish (or draft) a post
   sfora task <file.md> [--project <slug>] [--column <name>]   Create a task
   sfora doc  <file.md> [--project <slug>]             Create a doc
 
+Act on a post:
+  sfora comment <post> "<message>"    Comment on a post
+  sfora react <post> <emoji>          Toggle a reaction (👍 🚀 …)
+  (<post> is a post file path or its id)
+
 Projects:
   sfora new "<name>"                  Create a project
   sfora projects                      List your projects
 
-Browse:
+Browse & read:
+  sfora posts <project>               List a project's posts
+  sfora tasks <project>               List a project's board, by column
+  sfora inbox                         Show your unread mentions
+  sfora me                            Show who you're signed in as
   sfora ls [path]                     List a path (default /projects)
   sfora cat <path>                    Print a file's markdown
   sfora                               Open the interactive shell
 
+  Add --json to any list command (projects/posts/tasks/ls/me) for
+  machine-readable output and stable scripting.
+
 Agents & config:
   sfora --mcp [--org <slug>]          Run as an MCP server (for agents)
   sfora mcp-config                    Print an MCP config snippet to paste
+  sfora contexts                      List saved deployment+org keys (● = active)
   sfora init                          Save URL + API key + org manually
 
 Config resolution: flags > env (SFORA_API_KEY / SFORA_URL / SFORA_ORG) >
 ~/.sfora/config.json > default (URL ${DEFAULT_URL}).
 `;
+// In-shell `help` (and `?`). The underlying engine (just-bash) ships its own
+// `help` builtin that prints "just-bash shell builtins" — internal branding we
+// never want users to see, and it can't be overridden via the command registry
+// (it's a hardcoded interpreter builtin). So the REPL intercepts `help` and
+// prints this sfora-native cheat sheet instead.
+const SHELL_HELP = `${colors.bold}sfora shell${colors.reset} ${colors.dim}— your workspace as a markdown filesystem${colors.reset}
+
+Standard tools work against your workspace:
+  ls   cat   grep   find   head   tail   wc   sed   awk   echo   cd   pwd
+
+${colors.dim}Where things live${colors.reset}
+  /projects                          your projects
+  /projects/<slug>/posts/<file>.md   published posts
+  /projects/<slug>/drafts/           drafts
+  /projects/<slug>/board/<col>/      board tasks
+  /projects/<slug>/docs/             docs
+  /inbox/mentions.md                 your mentions
+  /me/api-key                        who you're signed in as
+
+${colors.dim}Try${colors.reset}
+  ls /projects
+  cat /projects/<slug>/posts/<file>.md
+  grep -ri todo /projects
+  echo "# Hello" > /projects/<slug>/posts/hello.md
+
+${colors.dim}Outside the shell${colors.reset}, sfora has verbs: post · task · doc · new · projects   (run ${colors.cyan}sfora --help${colors.reset})
+Type ${colors.cyan}exit${colors.reset} to quit.
+`;
 // `sfora init` — persist url/apiKey/org to ~/.sfora/config.json. Uses flags
 // when given, otherwise prompts (on a TTY), defaulting to any existing config.
 async function runInit(args) {
@@ -131,8 +187,13 @@ async function runInit(args) {
         process.exitCode = 1;
         return;
     }
-    const path = await writeConfig({ url, apiKey: key, org: org || cfg.org });
-    console.log(`${colors.green}✓${colors.reset} Saved ${path}`);
+    const { cfg: next, key: profile } = upsertProfile(cfg, {
+        url,
+        org: org || cfg.org,
+        apiKey: key,
+    });
+    const path = await writeConfig(next);
+    console.log(`${colors.green}✓${colors.reset} Saved ${path} ${colors.dim}(${profile})${colors.reset}`);
 }
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 function openBrowser(url) {
@@ -195,17 +256,27 @@ async function runLogin(args, baseUrl) {
         }
         if (data.status === "approved" && data.apiKey) {
             const cfg = await readConfig();
-            const next = { ...cfg, url: base };
+            let next;
             if (args.bot) {
                 // Save under the bot's slot; keep the user's personal key intact.
-                next.bots = {
-                    ...cfg.bots,
-                    [args.bot]: { apiKey: data.apiKey, org: data.orgSlug ?? undefined },
+                next = {
+                    ...cfg,
+                    url: base,
+                    bots: {
+                        ...cfg.bots,
+                        [args.bot]: { apiKey: data.apiKey, org: data.orgSlug ?? undefined },
+                    },
                 };
             }
             else {
-                next.apiKey = data.apiKey;
-                next.org = data.orgSlug ?? cfg.org;
+                // Add/update this deployment+org as its own profile instead of
+                // overwriting one shared key — so logging in here never invalidates the
+                // key you hold for another deployment.
+                next = upsertProfile(cfg, {
+                    url: base,
+                    org: data.orgSlug ?? undefined,
+                    apiKey: data.apiKey,
+                }).cfg;
             }
             const path = await writeConfig(next);
             console.log(`\n${colors.green}✓${colors.reset} Logged in as ${data.name ?? "you"}${data.orgSlug ? ` ${colors.dim}(${data.orgSlug})${colors.reset}` : ""}${args.bot ? ` ${colors.dim}[bot: ${args.bot}]${colors.reset}` : ""} — saved ${path}`);
@@ -237,6 +308,37 @@ function printMcpConfig(s) {
     };
     process.stdout.write(`${JSON.stringify(snippet, null, 2)}\n`);
 }
+// `sfora contexts` — list the deployment+org identities saved in the config and
+// mark the one the current flags/env resolve to. Local-only (no network), so
+// you can always see which key you're about to use.
+function printContexts(cfg, resolved) {
+    const mask = (k) => k ? `${k.slice(0, 12)}…` : `${colors.dim}(no key)${colors.reset}`;
+    const entries = Object.entries(effectiveProfiles(cfg));
+    if (entries.length === 0) {
+        console.log(`${colors.dim}No saved contexts. Run \`sfora login\`.${colors.reset}`);
+    }
+    else {
+        console.log(`${colors.bold}Contexts${colors.reset} ${colors.dim}(~/.sfora/config.json)${colors.reset}`);
+        for (const [key, p] of entries) {
+            const isResolved = resolved.apiKey != null && p.apiKey === resolved.apiKey;
+            const isActive = key === cfg.activeProfile;
+            const marker = isResolved
+                ? `${colors.green}●${colors.reset}`
+                : isActive
+                    ? `${colors.cyan}○${colors.reset}`
+                    : " ";
+            console.log(`  ${marker} ${key.padEnd(28)} ${colors.dim}${p.url}${p.org ? ` · ${p.org}` : ""} · ${mask(p.apiKey)}${colors.reset}`);
+        }
+    }
+    const bots = Object.entries(cfg.bots ?? {});
+    if (bots.length) {
+        console.log(`${colors.bold}Bots${colors.reset}`);
+        for (const [name, b] of bots) {
+            console.log(`  ${colors.dim}${name.padEnd(28)} ${b.org ?? ""} · ${mask(b.apiKey)}${colors.reset}`);
+        }
+    }
+    console.log(`\n${colors.dim}Resolved now → ${resolved.url}${resolved.org ? ` (org: ${resolved.org})` : ""} ${colors.green}●${colors.reset}${colors.dim} = active key${colors.reset}`);
+}
 // ─── Structured verbs (post / task / doc / ls / cat / projects) ──
 // These talk to the workspace over the same /v1/fs the app + agents use, so the
 // CLI is a real product interface — not a generic shell.
@@ -263,6 +365,18 @@ async function resolveProject(fs, flag, md) {
         return slugs[0];
     throw new Error(`specify --project <slug>${slugs.length ? ` (yours: ${slugs.join(", ")})` : ""}`);
 }
+// A post reference can be a file path (we read its `id:` frontmatter) or a bare
+// post id. So `sfora comment /projects/x/posts/y.md "hi"` and `sfora comment
+// <id> "hi"` both work.
+async function resolvePostId(fs, ref) {
+    if (!ref.includes("/"))
+        return ref;
+    const md = await fs.readFile(ref, "utf8");
+    const id = frontmatterValue(md, "id");
+    if (!id)
+        throw new Error(`no post id found in ${ref} (is it a post file?)`);
+    return id;
+}
 const VERBS = new Set([
     "projects",
     "new",
@@ -271,12 +385,31 @@ const VERBS = new Set([
     "post",
     "task",
     "doc",
+    "posts",
+    "tasks",
+    "inbox",
+    "mentions",
+    "me",
+    "whoami",
+    "comment",
+    "react",
 ]);
 async function runVerb(args, fs, client) {
     const ok = (msg) => console.log(`${colors.green}✓${colors.reset} ${msg}`);
+    const emitJson = (v) => console.log(JSON.stringify(v, null, 2));
+    const plural = (n, w) => `${n} ${w}${n === 1 ? "" : "s"}`;
     if (args.command === "projects") {
-        const slugs = await fs.readdir("/projects");
-        console.log(slugs.length ? slugs.join("\n") : "(no projects)");
+        const projects = await client.listProjects();
+        if (args.json)
+            return emitJson(projects);
+        if (projects.length === 0) {
+            console.log(`${colors.dim}(no projects)${colors.reset}`);
+            return;
+        }
+        const width = Math.max(...projects.map((p) => p.name.length));
+        for (const p of projects) {
+            console.log(`${p.name.padEnd(width)}  ${colors.dim}${p.slug} · ${plural(p.postCount, "post")}${colors.reset}`);
+        }
         return;
     }
     if (args.command === "new") {
@@ -289,6 +422,8 @@ async function runVerb(args, fs, client) {
     }
     if (args.command === "ls") {
         const entries = await fs.readdir(args.rest[0] ?? "/projects");
+        if (args.json)
+            return emitJson(entries);
         console.log(entries.join("\n"));
         return;
     }
@@ -298,6 +433,91 @@ async function runVerb(args, fs, client) {
         process.stdout.write(await fs.readFile(args.rest[0], "utf8"));
         return;
     }
+    if (args.command === "me" || args.command === "whoami") {
+        const text = (await client.readMe()).trim();
+        if (args.json) {
+            const obj = {};
+            for (const ln of text.split("\n")) {
+                const m = /^([a-zA-Z][\w-]*):\s*(.*)$/.exec(ln);
+                if (m)
+                    obj[m[1]] = m[2];
+            }
+            return emitJson(obj);
+        }
+        console.log(text);
+        return;
+    }
+    if (args.command === "inbox" || args.command === "mentions") {
+        const md = (await client.readInbox()).trim();
+        if (args.json)
+            return emitJson({ markdown: md });
+        console.log(md || `${colors.dim}(no unread mentions)${colors.reset}`);
+        return;
+    }
+    if (args.command === "posts") {
+        const slug = args.project ?? args.rest[0];
+        if (!slug)
+            throw new Error("usage: sfora posts <project> [--json]");
+        const entries = await client.listPosts(slug);
+        if (args.json)
+            return emitJson(entries);
+        if (entries.length === 0) {
+            console.log(`${colors.dim}(no posts)${colors.reset}`);
+            return;
+        }
+        for (const e of entries) {
+            const flag = e.isDraft ? `${colors.yellow}draft${colors.reset} ` : "";
+            console.log(`${flag}${e.title}  ${colors.dim}${e.filename}${colors.reset}`);
+        }
+        return;
+    }
+    if (args.command === "tasks") {
+        const slug = args.project ?? args.rest[0];
+        if (!slug)
+            throw new Error("usage: sfora tasks <project> [--json]");
+        const columns = await client.listColumns(slug);
+        const board = await Promise.all(columns.map(async (col) => ({
+            column: col.name,
+            dirname: col.dirname,
+            cards: await client.listCards(slug, col.dirname),
+        })));
+        if (args.json)
+            return emitJson(board);
+        for (const group of board) {
+            console.log(`${colors.bold}${group.column}${colors.reset} ${colors.dim}(${group.cards.length})${colors.reset}`);
+            for (const c of group.cards) {
+                const dot = c.status === "closed"
+                    ? colors.green
+                    : c.status === "active"
+                        ? colors.cyan
+                        : colors.dim;
+                console.log(`  ${dot}●${colors.reset} ${colors.dim}#${c.number}${colors.reset} ${c.title}`);
+            }
+            if (group.cards.length === 0)
+                console.log(`  ${colors.dim}(empty)${colors.reset}`);
+        }
+        return;
+    }
+    if (args.command === "comment") {
+        const ref = args.rest[0];
+        const text = args.rest.slice(1).join(" ").trim();
+        if (!ref || !text)
+            throw new Error('usage: sfora comment <post> "<message>"');
+        const postId = await resolvePostId(fs, ref);
+        await client.createComment(postId, text);
+        ok(`Commented on ${ref}`);
+        return;
+    }
+    if (args.command === "react") {
+        const ref = args.rest[0];
+        const emoji = args.rest[1];
+        if (!ref || !emoji)
+            throw new Error("usage: sfora react <post> <emoji>");
+        const postId = await resolvePostId(fs, ref);
+        const r = await client.reactToPost(postId, emoji);
+        ok(`${r.reacted ? "Reacted" : "Removed reaction"} ${emoji} on ${ref}`);
+        return;
+    }
     // post / task / doc — push a local markdown file into the workspace.
     const file = args.rest[0];
     if (!file) {
@@ -337,6 +557,106 @@ async function runVerb(args, fs, client) {
         return;
     }
 }
+// ─── Local mode (a .sfora/ directory — no server, no account) ─────
+const LOCAL_ONLY_HINT = "cloud command — run it with --cloud (after `sfora login`), or outside the .sfora/ repo";
+async function runLocalVerb(args, root) {
+    const ws = new LocalWorkspace(root);
+    const { fs } = createLocalShell(root);
+    const ok = (msg) => console.log(`${colors.green}✓${colors.reset} ${msg}`);
+    const emitJson = (v) => console.log(JSON.stringify(v, null, 2));
+    switch (args.command) {
+        case "ls": {
+            const entries = await fs.readdir(args.rest[0] ?? "/");
+            if (args.json)
+                return emitJson(entries);
+            console.log(entries.join("\n"));
+            return;
+        }
+        case "cat": {
+            if (!args.rest[0])
+                throw new Error("usage: sfora cat <path>");
+            process.stdout.write(await fs.readFile(args.rest[0], "utf8"));
+            return;
+        }
+        case "tasks": {
+            const tasks = await ws.listTasks(args.column);
+            if (args.json)
+                return emitJson(tasks);
+            const columns = await ws.listColumns();
+            for (const col of args.column ? [] : columns) {
+                const inCol = tasks.filter((t) => t.column === col);
+                console.log(`${colors.bold}${col.replace(/^\d+-/, "")}${colors.reset} ${colors.dim}(${inCol.length})${colors.reset}`);
+                for (const t of inCol) {
+                    const dot = t.status === "closed" ? colors.green : colors.cyan;
+                    console.log(`  ${dot}●${colors.reset} ${colors.dim}#${t.number ?? "?"}${colors.reset} ${t.title}`);
+                }
+                if (inCol.length === 0)
+                    console.log(`  ${colors.dim}(empty)${colors.reset}`);
+            }
+            if (args.column) {
+                for (const t of tasks)
+                    console.log(`${colors.dim}#${t.number ?? "?"}${colors.reset} ${t.title}`);
+            }
+            return;
+        }
+        case "posts": {
+            const files = await ws.listPosts(args.draft ? "drafts" : "posts");
+            if (args.json)
+                return emitJson(files);
+            console.log(files.length ? files.join("\n") : `${colors.dim}(no posts)${colors.reset}`);
+            return;
+        }
+        case "me":
+        case "whoami": {
+            if (args.json)
+                return emitJson({ mode: "local", workspace: root });
+            console.log(`local workspace ${colors.dim}· ${root}${colors.reset}`);
+            return;
+        }
+        case "task":
+        case "post":
+        case "doc": {
+            const file = args.rest[0];
+            if (!file)
+                throw new Error(`usage: sfora ${args.command} <file.md>`);
+            const md = await readLocalFile(file, "utf8");
+            if (args.command === "task") {
+                const r = await ws.writeTask(md, { column: args.column });
+                ok(`Task #${r.number} created in ${r.column} · ${r.filename}`);
+            }
+            else if (args.command === "post") {
+                const r = await ws.writePost(md, { draft: args.draft });
+                ok(`${args.draft ? "Drafted" : "Posted"} · ${r.filename}`);
+            }
+            else {
+                const r = await ws.writeDoc(md);
+                ok(`Doc saved · ${r.filename}`);
+            }
+            return;
+        }
+        default:
+            throw new Error(`'${args.command}' is a ${LOCAL_ONLY_HINT}`);
+    }
+}
+const LOCAL_SHELL_HELP = `${colors.bold}sfora shell${colors.reset} ${colors.dim}— local workspace (.sfora/), plain files on disk${colors.reset}
+
+Standard tools work on the real files:
+  ls   cat   grep   find   head   tail   wc   sed   awk   echo   mv   cd   pwd
+
+${colors.dim}Where things live${colors.reset}
+  /board/<column>/NNNN-<slug>.md   tasks — mv between columns moves a task
+  /posts/YYYY-MM-DD-<slug>.md      posts
+  /docs/<slug>.md                  docs
+
+${colors.dim}Try${colors.reset}
+  ls /board/01-todo
+  grep -ri todo /board
+  echo "# Fix login" > /board/01-todo/fix-login.md
+  mv /board/01-todo/0003-*.md /board/03-done/
+
+Everything is git-versioned with your repo. ${colors.dim}Connect a team later with${colors.reset} ${colors.cyan}sfora login${colors.reset}.
+Type ${colors.cyan}exit${colors.reset} to quit.
+`;
 async function main() {
     const args = parseArgs(process.argv.slice(2));
     if (args.help) {
@@ -344,6 +664,13 @@ async function main() {
         return;
     }
     if (args.command === "init") {
+        if (args.local) {
+            const root = await initWorkspace(process.cwd());
+            console.log(`${colors.green}✓${colors.reset} Local workspace ready · ${root}`);
+            console.log(`${colors.dim}Tasks, posts, and docs live there as plain markdown — versioned with your repo.\n` +
+                `Try: sfora task plan.md · sfora tasks · sfora (shell). Connect a team later with sfora login.${colors.reset}`);
+            return;
+        }
         await runInit(args);
         return;
     }
@@ -354,10 +681,51 @@ async function main() {
         printMcpConfig(settings);
         return;
     }
+    if (args.command === "contexts") {
+        printContexts(cfg, settings);
+        return;
+    }
     if (args.command === "login") {
         await runLogin(args, baseUrl);
         return;
     }
+    // Local mode — a .sfora/ workspace in (an ancestor of) cwd wins, unless the
+    // user explicitly targets the cloud (--cloud / --url / --org / --key / --bot).
+    const cloudIntent = args.cloud || !!args.url || !!args.org || !!args.key || !!args.bot;
+    const localRoot = cloudIntent
+        ? undefined
+        : await findWorkspace(process.cwd());
+    if (args.local && !localRoot) {
+        process.stderr.write(`${colors.red}error:${colors.reset} no .sfora/ workspace found — run \`sfora init --local\` first.\n`);
+        process.exitCode = 1;
+        return;
+    }
+    if (localRoot) {
+        if (args.command && VERBS.has(args.command)) {
+            try {
+                await runLocalVerb(args, localRoot);
+            }
+            catch (e) {
+                process.stderr.write(`${colors.red}error:${colors.reset} ${e instanceof Error ? e.message : String(e)}\n`);
+                process.exitCode = 1;
+            }
+            return;
+        }
+        if (args.mcp) {
+            await runMcpServer({
+                baseUrl,
+                apiKey: apiKey ?? "",
+                org: settings.org ?? "",
+                localRoot,
+            });
+            return;
+        }
+        const { bash, fs } = createLocalShell(localRoot, args.cwd);
+        console.log(`${colors.cyan}${colors.bold}sfora${colors.reset} ${colors.dim}— local workspace · ${localRoot}${colors.reset}`);
+        console.log(`${colors.dim}Plain markdown files, versioned with your repo. Try: ls /board · ${colors.reset}${colors.cyan}help${colors.reset}${colors.dim} for commands · ${colors.reset}${colors.cyan}exit${colors.reset}${colors.dim} to quit${colors.reset}\n`);
+        await runShell(bash, fs, LOCAL_SHELL_HELP, args.cwd);
+        return;
+    }
     if (!apiKey) {
         process.stderr.write(args.bot
             ? `${colors.red}error:${colors.reset} no key for bot '${args.bot}'. Run \`sfora login --bot ${args.bot}\`.\n`
@@ -372,13 +740,21 @@ async function main() {
             baseUrl,
             apiKey,
             org: settings.org ?? "",
+            actAs: args.as,
         });
-        const client = new SforaApiClient({ baseUrl, apiKey });
+        const client = new SforaApiClient({ baseUrl, apiKey, actAs: args.as });
         try {
             await runVerb(args, fs, client);
         }
         catch (e) {
-            process.stderr.write(`${colors.red}error:${colors.reset} ${e instanceof Error ? e.message : String(e)}\n`);
+            const msg = e instanceof Error ? e.message : String(e);
+            // A 401 surfaces as EACCES once SforaFs maps it to an errno — translate it
+            // back into an actionable hint instead of a cryptic permission error.
+            const authExpired = e?.status === 401 ||
+                /EACCES|permission denied|invalid api key|unauthorized/i.test(msg);
+            process.stderr.write(`${colors.red}error:${colors.reset} ${authExpired
+                ? `your key is invalid or expired — run \`sfora login\`${args.bot ? ` --bot ${args.bot}` : ""}`
+                : msg}\n`);
             process.exitCode = 1;
         }
         return;
@@ -394,15 +770,11 @@ async function main() {
         return;
     }
     const org = settings.org;
-    const { bash } = createSforaShell({ baseUrl, apiKey, org, cwd: args.cwd });
-    // Shell state threaded across exec() calls — just-bash does not persist cwd/env
-    // between separate exec()s, so we carry them forward ourselves.
-    let cwd = args.cwd;
-    let env;
+    const { bash, fs } = createSforaShell({ baseUrl, apiKey, org, cwd: args.cwd });
     // Pre-flight: confirm auth + connectivity and greet with the resolved identity.
     let identity = "";
     try {
-        identity = (await bash.exec("cat /me/api-key", { cwd, env })).stdout.trim();
+        identity = (await bash.exec("cat /me/api-key", { cwd: args.cwd })).stdout.trim();
     }
     catch {
         identity = "";
@@ -418,7 +790,14 @@ async function main() {
     else {
         console.log(`${colors.yellow}warning:${colors.reset} could not reach ${baseUrl} or authenticate — commands may fail.`);
     }
-    console.log(`${colors.dim}Try: ls /projects · cat /projects/<slug>/posts/<file>.md · cat /inbox/mentions.md · 'exit' to quit${colors.reset}\n`);
+    console.log(`${colors.dim}Try: ls /projects · cat /inbox/mentions.md · ${colors.reset}${colors.cyan}help${colors.reset}${colors.dim} for commands · ${colors.reset}${colors.cyan}exit${colors.reset}${colors.dim} to quit${colors.reset}\n`);
+    await runShell(bash, fs, SHELL_HELP, args.cwd);
+}
+async function runShell(bash, fs, helpText, initialCwd) {
+    // Shell state threaded across exec() calls — just-bash does not persist cwd/env
+    // between separate exec()s, so we carry them forward ourselves.
+    let cwd = initialCwd;
+    let env;
     // Iterate stdin as an async iterable. This pattern serializes lines even
     // when stdin is piped (buffered) — the `for await` body completes before the
     // next line is consumed, and EOF naturally falls through to process exit
@@ -427,10 +806,46 @@ async function main() {
     // readline fired 'close' (→ process.exit(0)) while the first exec's PUT was
     // still in flight.
     const isTty = Boolean(process.stdin.isTTY);
+    // Tab completion: command names on the first token, workspace paths after.
+    // Path hits read the live fs, so completing `/projects/<Tab>` lists projects.
+    const COMMANDS = [
+        "ls", "cat", "cd", "pwd", "grep", "find", "echo", "head", "tail", "wc",
+        "sed", "awk", "sort", "uniq", "mkdir", "rm", "mv", "cp", "touch", "help",
+        "exit",
+    ];
+    async function completePath(token) {
+        const slash = token.lastIndexOf("/");
+        const dir = slash >= 0 ? token.slice(0, slash + 1) : "";
+        const prefix = slash >= 0 ? token.slice(slash + 1) : token;
+        const base = dir.startsWith("/")
+            ? dir || "/"
+            : `${cwd.replace(/\/+$/, "")}/${dir}`;
+        let names = [];
+        try {
+            names = await fs.readdir(base || "/");
+        }
+        catch {
+            return [];
+        }
+        return names.filter((n) => n.startsWith(prefix)).map((n) => dir + n);
+    }
+    const completer = (line, cb) => {
+        const tokens = line.split(/\s+/);
+        const last = tokens[tokens.length - 1] ?? "";
+        if (tokens.length <= 1) {
+            const hits = COMMANDS.filter((c) => c.startsWith(last));
+            cb(null, [hits.length ? hits : COMMANDS, last]);
+            return;
+        }
+        completePath(last)
+            .then((hits) => cb(null, [hits, last]))
+            .catch(() => cb(null, [[], last]));
+    };
     const rl = readline.createInterface({
         input: process.stdin,
         output: process.stdout,
         terminal: isTty,
+        completer,
     });
     const promptText = () => `${colors.cyan}sfora${colors.reset}:${colors.blue}${cwd}${colors.reset}$ `;
     // Print the first prompt; subsequent ones are printed after each handled line.
@@ -445,12 +860,21 @@ async function main() {
         }
         if (line === "exit" || line === "quit")
             break;
+        // Show sfora's own help instead of just-bash's builtin help banner.
+        if (line === "help" || line === "?" || line.startsWith("help ")) {
+            process.stdout.write(helpText);
+            if (isTty)
+                process.stdout.write(promptText());
+            continue;
+        }
         try {
             const res = await bash.exec(line, { cwd, env });
             if (res.stdout)
                 process.stdout.write(res.stdout);
+            // Rewrite the engine's "bash:" error prefix to "sfora:" so the shell
+            // reads as native — the user never typed `bash`.
             if (res.stderr)
-                process.stderr.write(res.stderr);
+                process.stderr.write(res.stderr.replace(/^bash:/gm, "sfora:"));
             env = res.env;
             cwd = res.env?.PWD ?? cwd;
         }