@neta-art/cohub-cli 6.7.0 → 6.8.0

package/README.md

@@ -299,10 +299,9 @@ Confirm before deleting files or directories.
 
 Publish and manage Apps from a Space workspace. Public App URLs require a username and a Space slug.
 
-`--file` and `--dir` take paths relative to the Space workspace — the same paths
-`spaces files ls` shows, not your local filesystem. To publish local build
-output, upload it first (`spaces files upload <dir>`), then publish the
-Space-side path.
+`apps publish` detects the source from the runtime by default: local CLI runs use local
+filesystem paths, while Cohub Sandbox runs use Space workspace paths. Pass
+`--source workspace` or `--source local` to override the default explicitly.
 
 ```bash
 cohub profile update --username <username>
@@ -311,8 +310,9 @@ cohub -s <spaceId> apps ls --json
 cohub apps get <appId|url|username/space/app> --json
 cohub apps stats <appId|url|username/space/app>
 cohub apps download <appId|url|username/space/app> --output <path>
-cohub -s <spaceId> apps publish demo --file dist/index.html
-cohub -s <spaceId> apps publish site --dir dist
+cohub -s <spaceId> apps publish demo --file ./dist/index.html
+cohub -s <spaceId> apps publish site --dir ./dist
+cohub -s <spaceId> apps publish site --source workspace --dir dist
 cohub -s <spaceId> apps publish app --port 3000
 cohub apps publish-version <appId>
 cohub apps versions <appId> --json

package/dist/commands/apps.js

@@ -1,7 +1,7 @@
 import { randomUUID } from "node:crypto";
 import { createReadStream } from "node:fs";
 import { basename } from "node:path";
-import { HttpError } from "@neta-art/cohub";
+import { getCohubContext, HttpError } from "@neta-art/cohub";
 import { createClient, createClientWithAccessToken } from "../client.js";
 import { error, handleHttp, json as outJson, jsonRequested, ok, table } from "../output.js";
 import { resolveSpace } from "../space.js";
@@ -124,6 +124,9 @@ async function uploadLocalAppSource(client, spaceId, source) {
     const manifestAsset = manifestPlan.asset;
     return { sourceRef: manifestAsset.objectKey, targetRef: source.targetType === "file" ? files[0]?.path ?? "" : "." };
 }
+function resolveDefaultAppSource() {
+    return getCohubContext().runtime.kind === "sandbox" ? "workspace" : "local";
+}
 function resolveTarget(opts) {
     const targets = [
         opts.file ? { targetType: "file", targetRef: opts.file } : null,
@@ -264,7 +267,7 @@ export function registerApps(program) {
         .description("List apps in the target space")
         .option("--json", "Output as JSON")
         .action(async (opts) => {
-        const spaceId = resolveSpace(appsCmd);
+        const spaceId = await resolveSpace(appsCmd);
         const client = createClient();
         try {
             const result = await client.apps.listBySpace(spaceId);
@@ -388,7 +391,7 @@ export function registerApps(program) {
     appsCmd
         .command("publish <slug>")
         .description("Create or publish an app in the target space")
-        .option("--source <source>", "Source: workspace (default) or local")
+        .option("--source <source>", "Source: workspace or local (auto-detected from runtime by default)")
         .option("--file <path>", "Publish a file from the selected source")
         .option("--dir <path>", "Publish a directory site from the selected source")
         .option("--port <port>", "Publish a public sandbox port")
@@ -407,10 +410,10 @@ export function registerApps(program) {
         const target = resolveTarget(opts);
         if (!target)
             return error("Missing target", "Use one of --file, --dir, or --port.");
-        const source = opts.source ? parseChoice(opts.source, "source", ["workspace", "local"]) : "workspace";
+        const source = opts.source ? parseChoice(opts.source, "source", ["workspace", "local"]) : resolveDefaultAppSource();
         if (target.targetType === "port" && opts.source)
             return error("Invalid source", "--source applies only to --file and --dir.");
-        const spaceId = resolveSpace(appsCmd);
+        const spaceId = await resolveSpace(appsCmd);
         const client = createClient();
         let { targetType, targetRef } = target;
         let sourceRef = null;

package/dist/commands/auth.js

@@ -1,4 +1,5 @@
 import { authSource, loginWithDeviceFlow, readAuthSession, refreshAccessToken, requestDeviceCode, revokeAndClearAuthSession, verifyDeviceCode } from "../auth.js";
+import { clearDefaultSpaceCache } from "../space.js";
 import { createClient } from "../client.js";
 import { table, json as outJson, jsonRequested, ok, error, spinner, handleHttp } from "../output.js";
 export function registerAuth(program) {
@@ -67,6 +68,7 @@ export function registerAuth(program) {
         .description("Clear stored Logto session")
         .action(async () => {
         await revokeAndClearAuthSession();
+        clearDefaultSpaceCache();
         if (process.env.COHUB_EXECUTION_TOKEN?.trim()) {
             ok("Local session cleared. COHUB_EXECUTION_TOKEN is still set.");
         }

package/dist/commands/boards/context.js

@@ -24,7 +24,7 @@ export function readOptions(command, label = "Comma-separated resource IDs") {
     return command.option("--ids <ids>", label);
 }
 export async function resolvedBoard(boards, target) {
-    const spaceId = resolveSpace(boards);
+    const spaceId = await resolveSpace(boards);
     const boardId = await resolveBoardId(spaceId, target);
     return createClient().space(spaceId).board(boardId);
 }

package/dist/commands/boards.js

@@ -171,7 +171,7 @@ function registerExportCommand(boards) {
             if (!out)
                 throw new Error("--out is required");
             const result = await runBoardExport({
-                spaceId: resolveSpace(boards),
+                spaceId: await resolveSpace(boards),
                 target: board,
                 region: parseExportRegion(options),
                 scale: parseNumber(options.scale ?? "2", "scale", { min: 0.01, max: 16 }),
@@ -213,7 +213,7 @@ export function registerBoards(program) {
     const boards = program
         .command("boards")
         .description("Inspect and update Boards by ID or .board path")
-        .hook("preAction", () => { resolveSpace(boards); });
+        .hook("preAction", async () => { await resolveSpace(boards); });
     withJson(boards.command("create <path>")
         .description("Create a Board")
         .option("--title <title>", "Board title")
@@ -239,7 +239,7 @@ Generate an editable seed:
                     (typeof content.mutationId === "string" ? content.mutationId : randomUUID()),
                 ...(options.title ? { title: options.title } : {}),
             };
-            const result = await createClient().space(resolveSpace(boards)).boards.create(input);
+            const result = await createClient().space(await resolveSpace(boards)).boards.create(input);
             if (jsonRequested(options))
                 return outJson({ ...result, path });
             ok(`Board created: ${path}`);
@@ -262,7 +262,7 @@ Apply multiple changes atomically:
   cohub boards batch <board> --input changes.json --dry-run`))
         .action(async (target, options) => {
         try {
-            const spaceId = resolveSpace(boards);
+            const spaceId = await resolveSpace(boards);
             const boardId = await resolveBoardId(spaceId, target);
             const result = await createClient().space(spaceId).board(boardId).summary();
             if (jsonRequested(options))
@@ -283,7 +283,7 @@ Coordinates:
 Use boards examples for editable starter JSON.`))
         .action(async (target, options) => {
         try {
-            const spaceId = resolveSpace(boards);
+            const spaceId = await resolveSpace(boards);
             const boardId = await resolveBoardId(spaceId, target);
             const result = await createClient().space(spaceId).board(boardId).capabilities();
             if (jsonRequested(options))
@@ -330,7 +330,7 @@ Use boards examples for editable starter JSON.`))
         .option("--command-id <id>", "Idempotency command ID"))
         .action(async (target, compositionId, options) => {
         try {
-            const spaceId = resolveSpace(boards);
+            const spaceId = await resolveSpace(boards);
             const boardId = await resolveBoardId(spaceId, target);
             const result = await createClient().space(spaceId).board(boardId).play({
                 commandId: commandId(options),
@@ -351,7 +351,7 @@ Use boards examples for editable starter JSON.`))
     });
     const playbackAction = (type) => async (target, playbackId, options) => {
         try {
-            const spaceId = resolveSpace(boards);
+            const spaceId = await resolveSpace(boards);
             const boardId = await resolveBoardId(spaceId, target);
             const board = createClient().space(spaceId).board(boardId);
             const id = commandId(options);
@@ -375,7 +375,7 @@ Use boards examples for editable starter JSON.`))
         .option("--command-id <id>", "Idempotency command ID"))
         .action(async (target, playbackId, position, options) => {
         try {
-            const spaceId = resolveSpace(boards);
+            const spaceId = await resolveSpace(boards);
             const boardId = await resolveBoardId(spaceId, target);
             const result = await createClient().space(spaceId).board(boardId).seek({
                 commandId: commandId(options),
@@ -399,7 +399,7 @@ Use boards examples for editable starter JSON.`))
         .description("Stream Board events"))
         .action(async (target, options) => {
         try {
-            const spaceId = resolveSpace(boards);
+            const spaceId = await resolveSpace(boards);
             const boardId = await resolveBoardId(spaceId, target);
             const client = createRealtimeClient();
             const board = client.space(spaceId).board(boardId);

package/dist/commands/desktop.js

@@ -7,6 +7,7 @@ import { getAppByRef } from "../app-ref.js";
 const FILE_SCHEME = "file://";
 const APP_SCHEME = "app://";
 const LEGACY_WORK_SCHEME = "work://";
+/** Optional disambiguation for file:// vs app:// — do not fall back to Home. */
 function optionalSpaceId(command) {
     let current = command;
     while (current) {

package/dist/commands/generations.js

@@ -257,7 +257,7 @@ Examples:
 `)
         .action(async (prompt, opts) => {
         try {
-            const spaceId = resolveSpace(program);
+            const spaceId = await resolveSpace(program);
             const content = [{ type: "text", text: prompt }];
             content.push(...await Promise.all(opts.image.map((value) => contentFromPathOrUrl("image", value))));
             content.push(...await Promise.all(opts.video.map((value) => contentFromPathOrUrl("video", value))));

package/dist/commands/public.js

@@ -179,7 +179,7 @@ function publicUrlPrefix(destination, entry) {
 }
 async function uploadPublic(command, source, destination, opts, deps) {
     const client = deps.createClient?.() ?? createClient();
-    const spaceId = resolveSpace(command);
+    const spaceId = await resolveSpace(command);
     try {
         const upload = await collectPublicUpload(source, destination);
         const plan = await client.space(spaceId).publicFiles.createUpload({
@@ -244,7 +244,7 @@ async function uploadPublic(command, source, destination, opts, deps) {
 async function listPublic(command, path, opts, deps) {
     const client = deps.createClient?.() ?? createClient();
     try {
-        const publicFiles = client.space(resolveSpace(command)).publicFiles;
+        const publicFiles = client.space(await resolveSpace(command)).publicFiles;
         const entries = [];
         let cursor;
         do {
@@ -271,7 +271,7 @@ async function listPublic(command, path, opts, deps) {
 async function printPublicUrl(command, path, deps) {
     const client = deps.createClient?.() ?? createClient();
     try {
-        const result = await client.space(resolveSpace(command)).publicFiles.url(path);
+        const result = await client.space(await resolveSpace(command)).publicFiles.url(path);
         console.log(result.url);
     }
     catch (exception) {

package/dist/commands/run.js

@@ -1,5 +1,6 @@
 import { createClient } from "../client.js";
 import { error, handleHttp, json as outJson, spinner } from "../output.js";
+import { missingSpaceError, resolveDefaultSpace } from "../space.js";
 const DEFAULT_WAIT_TIMEOUT_MS = (6 * 60 * 60 + 60) * 1000;
 const DEFAULT_POLL_INTERVAL_MS = 1500;
 function shellQuote(value) {
@@ -43,13 +44,13 @@ function parseSpaceId(tokens) {
     }
     return undefined;
 }
-function parseRunCliOptions(argv) {
+async function parseRunCliOptions(argv) {
     const runIndex = topLevelRunIndex(argv);
     if (runIndex < 0)
         return error("Invalid invocation", "Use `cohub run [options] <command>`");
     const beforeRun = argv.slice(0, runIndex);
     const afterRun = argv.slice(runIndex + 1);
-    let spaceId = parseSpaceId(beforeRun) ?? process.env.COHUB_SPACE_ID?.trim() ?? "";
+    const explicitSpaceId = parseSpaceId(beforeRun) ?? process.env.COHUB_SPACE_ID?.trim() ?? "";
     let json = beforeRun.includes("--json");
     let async = false;
     let commandOption = null;
@@ -103,9 +104,7 @@ function parseRunCliOptions(argv) {
     if (!command) {
         return error("No command", "Pass --command <shell command>, or use `--` followed by the command.");
     }
-    if (!spaceId) {
-        return error("Missing required space", "Add -s, --space <id> before `run` or set COHUB_SPACE_ID.");
-    }
+    const spaceId = explicitSpaceId || (await resolveDefaultSpace().catch(handleHttp)) || missingSpaceError();
     return { spaceId, json, async, command };
 }
 function printRunHelp() {
@@ -126,6 +125,7 @@ Examples:
   cohub -s <spaceId> run -- git status -sb
 
 Notes:
+  - Without -s or COHUB_SPACE_ID, the command targets your Home space.
   - Use --command for commands that contain leading flags, or use -- before the shell command.
   - The command runs in /workspace.
 `);
@@ -199,7 +199,7 @@ async function waitForRunCompletion(taskRunId, showSpinner) {
     }
 }
 async function handleRunCli(argv) {
-    const opts = parseRunCliOptions(argv);
+    const opts = await parseRunCliOptions(argv);
     const client = createClient();
     try {
         const { taskRunId } = await client.space(opts.spaceId).runCommand({ command: opts.command });

package/dist/commands/sandbox.js

@@ -5,7 +5,7 @@ import { basename, resolve } from "node:path";
 import { resolveCohubEnvironment, resolveWebsocketUrl } from "@neta-art/cohub";
 import { requireAccessToken } from "../auth.js";
 import { createClient } from "../client.js";
-import { error, json as outJson, jsonRequested, ok, spinner } from "../output.js";
+import { error, handleHttp, json as outJson, jsonRequested, ok, spinner } from "../output.js";
 import { resolveSpace } from "../space.js";
 import { ensureSandboxdBinary, SandboxdDownloadError } from "./sandboxd-binary.js";
 // Derive the gateway relay control endpoint from the realtime websocket URL,
@@ -154,18 +154,22 @@ export function registerSandbox(program) {
         .option("-s, --space <id>", "Target space ID")
         .option("--json", "Output as JSON")
         .action(async (opts) => {
-        const spaceId = opts.space?.trim() || resolveSpace(program);
+        const spaceId = opts.space?.trim() || await resolveSpace(program);
         const client = createClient();
-        const result = await client.space(spaceId).sandbox.get().catch(() => null);
-        const sandbox = result?.sandbox ?? null;
-        if (jsonRequested(opts))
-            return outJson({ spaceId, sandbox });
-        if (!sandbox) {
-            console.log("  (no sandbox)");
-            return;
+        try {
+            const sandbox = (await client.space(spaceId).sandbox.get()).sandbox ?? null;
+            if (jsonRequested(opts))
+                return outJson({ spaceId, sandbox });
+            if (!sandbox) {
+                console.log("  (no sandbox)");
+                return;
+            }
+            console.log(`  space:    ${spaceId}`);
+            console.log(`  provider: ${sandbox.provider ?? "cloud"}`);
+            console.log(`  status:   ${sandbox.status ?? "unknown"}`);
+        }
+        catch (cause) {
+            handleHttp(cause);
         }
-        console.log(`  space:    ${spaceId}`);
-        console.log(`  provider: ${sandbox.provider ?? "cloud"}`);
-        console.log(`  status:   ${sandbox.status ?? "unknown"}`);
     });
 }

package/dist/commands/sandboxd-binary.js

@@ -19,7 +19,7 @@ const BINARY_NAME = "cohub-sandboxd";
 // Public CDN prefix hosting the release archives (the repo is private, so the
 // GitHub Release assets are not publicly downloadable). Overridable for staging
 // or self-hosting.
-const cdnBaseUrl = () => (process.env.COHUB_SANDBOXD_CDN_BASE_URL?.trim() || "https://public.cohub.run/sandboxd").replace(/\/+$/, "");
+const cdnBaseUrl = () => (process.env.COHUB_SANDBOXD_CDN_BASE_URL?.trim() || "https://public.cohub.live/sandboxd").replace(/\/+$/, "");
 const DOWNLOAD_TIMEOUT_MS = 120_000;
 const LOCK_STALE_MS = 5 * 60 * 1000;
 // Map Node's platform/arch to the Go GOOS/GOARCH used in release asset names.

package/dist/commands/space-activity.js

@@ -124,7 +124,7 @@ export function registerSpaceActivity(spacesCmd, dependencies = {}) {
         .description("Space activity overview: usage, contributors, rankings")
         .option("--json", "Output as JSON")
         .action(async (days, opts) => {
-        const spaceId = resolveSpace(spacesCmd);
+        const spaceId = await resolveSpace(spacesCmd);
         let parsedDays;
         try {
             parsedDays = parseActivityDays(days);

package/dist/commands/space-commerce.js

@@ -153,8 +153,8 @@ async function confirmDanger(opts, detail) {
     if (answer !== "y" && answer !== "yes")
         return error("Cancelled");
 }
-function commerceClient(spacesCmd) {
-    const spaceId = resolveSpace(spacesCmd);
+async function commerceClient(spacesCmd) {
+    const spaceId = await resolveSpace(spacesCmd);
     return { spaceId, commerce: createClient().space(spaceId).commerce };
 }
 export function registerSpaceCommerce(spacesCmd) {
@@ -172,7 +172,7 @@ Examples:
         .description("Initialize commerce for the target space")
         .option("--json", "Output as JSON")
         .action(async (opts) => {
-        const { commerce } = commerceClient(spacesCmd);
+        const { commerce } = await commerceClient(spacesCmd);
         try {
             const result = await commerce.setup();
             if (jsonRequested(opts))
@@ -196,7 +196,7 @@ Examples:
         .description("List products")
         .option("--json", "Output as JSON")
         .action(async (opts) => {
-        const { commerce } = commerceClient(spacesCmd);
+        const { commerce } = await commerceClient(spacesCmd);
         try {
             const result = await commerce.listProducts();
             if (jsonRequested(opts))
@@ -235,7 +235,7 @@ Examples:
             status: parseChoice(opts.status, "status", PRODUCT_STATUSES),
             visibility: parseChoice(opts.visibility, "visibility", PRODUCT_VISIBILITIES),
         };
-        const { commerce } = commerceClient(spacesCmd);
+        const { commerce } = await commerceClient(spacesCmd);
         try {
             const result = await commerce.createProduct(input);
             if (jsonRequested(opts))
@@ -269,7 +269,7 @@ Examples:
         });
         if (Object.keys(input).length === 0)
             return error("Nothing to update", "Pass --name, --description, --clear-description, --status, or --visibility.");
-        const { commerce } = commerceClient(spacesCmd);
+        const { commerce } = await commerceClient(spacesCmd);
         try {
             const result = await commerce.updateProduct(productKey, input);
             if (jsonRequested(opts))
@@ -290,7 +290,7 @@ Examples:
         .action(async (opts) => {
         const productKey = requireText(opts.productKey, "product key", "--product-key <key>");
         await confirmDanger(opts, `archive product "${productKey}"`);
-        const { commerce } = commerceClient(spacesCmd);
+        const { commerce } = await commerceClient(spacesCmd);
         try {
             const result = await commerce.updateProduct(productKey, { status: "archived" });
             if (jsonRequested(opts))
@@ -314,7 +314,7 @@ Examples:
         .description("List benefits")
         .option("--json", "Output as JSON")
         .action(async (opts) => {
-        const { commerce } = commerceClient(spacesCmd);
+        const { commerce } = await commerceClient(spacesCmd);
         try {
             const result = await commerce.listBenefits();
             if (jsonRequested(opts))
@@ -353,7 +353,7 @@ Examples:
                     ? parseInteger(opts.expiresInDays, "expires-in-days", { fallback: 0, min: 1 })
                     : undefined,
             };
-            const { commerce } = commerceClient(spacesCmd);
+            const { commerce } = await commerceClient(spacesCmd);
             try {
                 const result = await commerce.createBenefit(input);
                 if (jsonRequested(opts))
@@ -373,7 +373,7 @@ Examples:
             type: "feature",
             metadata: parseMetadataJson(opts.metadataJson),
         };
-        const { commerce } = commerceClient(spacesCmd);
+        const { commerce } = await commerceClient(spacesCmd);
         try {
             const result = await commerce.createBenefit(input);
             if (jsonRequested(opts))
@@ -407,7 +407,7 @@ Examples:
         });
         if (Object.keys(input).length === 0)
             return error("Nothing to update", "Pass --name, --description, --clear-description, --status, or --metadata-json.");
-        const { commerce } = commerceClient(spacesCmd);
+        const { commerce } = await commerceClient(spacesCmd);
         try {
             const result = await commerce.updateBenefit(benefitKey, input);
             if (jsonRequested(opts))
@@ -428,7 +428,7 @@ Examples:
         .action(async (opts) => {
         const benefitKey = requireText(opts.benefitKey, "benefit key", "--benefit-key <key>");
         await confirmDanger(opts, `archive benefit "${benefitKey}"`);
-        const { commerce } = commerceClient(spacesCmd);
+        const { commerce } = await commerceClient(spacesCmd);
         try {
             const result = await commerce.updateBenefit(benefitKey, { status: "archived" });
             if (jsonRequested(opts))
@@ -450,7 +450,7 @@ Examples:
             productKey: requireText(opts.productKey, "product key", "--product-key <key>"),
             benefitKey: requireText(opts.benefitKey, "benefit key", "--benefit-key <key>"),
         };
-        const { commerce } = commerceClient(spacesCmd);
+        const { commerce } = await commerceClient(spacesCmd);
         try {
             const result = await commerce.bindProductBenefit(input);
             if (jsonRequested(opts))
@@ -474,7 +474,7 @@ Examples:
             benefitKey: requireText(opts.benefitKey, "benefit key", "--benefit-key <key>"),
         };
         await confirmDanger(opts, `unbind benefit "${input.benefitKey}" from product "${input.productKey}"`);
-        const { commerce } = commerceClient(spacesCmd);
+        const { commerce } = await commerceClient(spacesCmd);
         try {
             const result = await commerce.unbindProductBenefit(input);
             if (jsonRequested(opts))
@@ -495,7 +495,7 @@ Examples:
         .option("--limit <limit>", "Page size, max 50")
         .option("--json", "Output as JSON")
         .action(async (opts) => {
-        const { commerce } = commerceClient(spacesCmd);
+        const { commerce } = await commerceClient(spacesCmd);
         try {
             const result = await commerce.listOrders({
                 page: parseInteger(opts.page, "page", { fallback: 1, min: 1 }),

package/dist/commands/space-invitations.js

@@ -72,7 +72,7 @@ export function registerSpaceInvitations(spacesCommand, dependencies = {
         .option("--max-uses <count>", "Usage limit, or 0 for unlimited", "0")
         .option("--json", "Output as JSON")
         .action(async (options) => {
-        const spaceId = resolveSpace(spacesCommand);
+        const spaceId = await resolveSpace(spacesCommand);
         let input;
         try {
             input = parseSpaceInvitationCreateOptions(options);
@@ -111,7 +111,7 @@ export function registerSpaceInvitations(spacesCommand, dependencies = {
         .description("List invite links")
         .option("--json", "Output as JSON")
         .action(async (options) => {
-        const spaceId = resolveSpace(spacesCommand);
+        const spaceId = await resolveSpace(spacesCommand);
         try {
             const result = await dependencies
                 .createClient()
@@ -150,7 +150,7 @@ export function registerSpaceInvitations(spacesCommand, dependencies = {
         .option("--json", "Output as JSON")
         .action(async (code, options) => {
         await confirmRevoke(options);
-        const spaceId = resolveSpace(spacesCommand);
+        const spaceId = await resolveSpace(spacesCommand);
         try {
             const result = await dependencies
                 .createClient()

package/dist/commands/space-turns.js

@@ -82,8 +82,8 @@ export function registerSpaceTurns(spacesCmd, dependencies = {}) {
     const turnsCmd = spacesCmd
         .command("turns")
         .description("Browse turns across the space")
-        .hook("preAction", () => {
-        resolveSpace(spacesCmd);
+        .hook("preAction", async () => {
+        await resolveSpace(spacesCmd);
     });
     turnsCmd
         .command("ls")
@@ -108,7 +108,7 @@ export function registerSpaceTurns(spacesCmd, dependencies = {}) {
             }
             throw cause;
         }
-        const spaceId = resolveSpace(spacesCmd);
+        const spaceId = await resolveSpace(spacesCmd);
         const client = dependencies.createClient?.() ?? createClient();
         try {
             try {
@@ -179,7 +179,7 @@ export function registerSpaceTurns(spacesCmd, dependencies = {}) {
         .description("Read persisted intermediate messages from the CDN archive")
         .option("--json", "Output as JSON")
         .action(async (sessionId, turnId, options) => {
-        const spaceId = resolveSpace(spacesCmd);
+        const spaceId = await resolveSpace(spacesCmd);
         const client = dependencies.createClient?.() ?? createClient();
         try {
             const archive = await client.space(spaceId).session(sessionId).turns.intermediate.get(turnId);

package/dist/commands/spaces.js

@@ -168,7 +168,7 @@ async function putUploadEntry(entry, uploadUrl, headers) {
     }
 }
 async function uploadFiles(command, paths, opts) {
-    const spaceId = resolveSpace(command);
+    const spaceId = await resolveSpace(command);
     const client = createClient();
     try {
         const files = await collectUploadFiles(paths);
@@ -242,7 +242,7 @@ async function sendPrompt(command, words, opts) {
         && !new Set(["off", "minimal", "low", "medium", "high", "xhigh", "max"]).has(thinkingLevel)) {
         return error("Invalid thinking level", "Use off|minimal|low|medium|high|xhigh|max");
     }
-    const spaceId = resolveSpace(command);
+    const spaceId = await resolveSpace(command);
     const client = createClient();
     try {
         const schedule = opts.delayMs
@@ -304,7 +304,7 @@ async function sendPrompt(command, words, opts) {
     }
 }
 async function runCompletionCommand(command, words, opts) {
-    const spaceId = resolveSpace(command);
+    const spaceId = await resolveSpace(command);
     const content = words.join(" ").trim();
     if (!content && process.stdin.isTTY) {
         return error("Message required", "Pass content args or pipe via stdin");
@@ -490,7 +490,7 @@ export function registerSpaces(program) {
         .description("Show space details")
         .option("--json", "Output as JSON")
         .action(async (id, opts) => {
-        const spaceId = id?.trim() || resolveSpace(spacesCmd);
+        const spaceId = id?.trim() || await resolveSpace(spacesCmd);
         const client = createClient();
         try {
             const space = await client.spaces.get(spaceId);
@@ -562,7 +562,7 @@ export function registerSpaces(program) {
         .description("Upload the space avatar")
         .option("--json", "Output as JSON")
         .action(async (path, opts) => {
-        const spaceId = resolveSpace(spacesCmd);
+        const spaceId = await resolveSpace(spacesCmd);
         const client = createClient();
         try {
             const asset = await uploadAvatarAsset({ client, purpose: "space_avatar", spaceId, path });
@@ -699,7 +699,7 @@ export function registerSpaces(program) {
         .description("Space usage statistics (default: 30 days)")
         .option("--json", "Output as JSON")
         .action(async (days, opts) => {
-        const spaceId = resolveSpace(spacesCmd);
+        const spaceId = await resolveSpace(spacesCmd);
         const client = createClient();
         try {
             const usage = await client.space(spaceId).usage.get(parseInteger(days ?? "30", "days", { min: 1 }));
@@ -737,14 +737,14 @@ function registerLabels(spacesCmd) {
     const labelsCmd = spacesCmd
         .command("labels")
         .description("Manage labels")
-        .hook("preAction", () => { resolveSpace(spacesCmd); });
+        .hook("preAction", async () => { await resolveSpace(spacesCmd); });
     labelsCmd
         .command("ls")
         .alias("list")
         .description("List labels")
         .option("--json", "Output as JSON")
         .action(async (opts) => {
-        const spaceId = resolveSpace(spacesCmd);
+        const spaceId = await resolveSpace(spacesCmd);
         const client = createClient();
         try {
             const result = await client.space(spaceId).labels.list();
@@ -764,7 +764,7 @@ function registerLabels(spacesCmd) {
         .description("Create a label")
         .option("--json", "Output as JSON")
         .action(async (labelRef, opts) => {
-        const spaceId = resolveSpace(spacesCmd);
+        const spaceId = await resolveSpace(spacesCmd);
         const client = createClient();
         try {
             const result = await client.space(spaceId).labels.create(labelRef);
@@ -784,7 +784,7 @@ function registerLabels(spacesCmd) {
         .option("--rank <n>", "Sort rank")
         .option("--json", "Output as JSON")
         .action(async (labelRef, opts) => {
-        const spaceId = resolveSpace(spacesCmd);
+        const spaceId = await resolveSpace(spacesCmd);
         const client = createClient();
         try {
             const result = await client.space(spaceId).labels.update(labelRef, {
@@ -805,7 +805,7 @@ function registerLabels(spacesCmd) {
         .alias("delete")
         .description("Delete a label")
         .action(async (labelRef) => {
-        const spaceId = resolveSpace(spacesCmd);
+        const spaceId = await resolveSpace(spacesCmd);
         const client = createClient();
         try {
             await client.space(spaceId).labels.delete(labelRef);
@@ -820,7 +820,7 @@ function registerLabels(spacesCmd) {
         .description("Reorder labels")
         .option("--json", "Output as JSON")
         .action(async (labelRefs, opts) => {
-        const spaceId = resolveSpace(spacesCmd);
+        const spaceId = await resolveSpace(spacesCmd);
         const client = createClient();
         try {
             const result = await client.space(spaceId).labels.reorder(labelRefs);
@@ -839,7 +839,7 @@ function registerLabels(spacesCmd) {
         .option("--cursor <cursor>", "Page cursor")
         .option("--json", "Output as JSON")
         .action(async (labelRef, opts) => {
-        const spaceId = resolveSpace(spacesCmd);
+        const spaceId = await resolveSpace(spacesCmd);
         const client = createClient();
         try {
             const result = await client.space(spaceId).labels.listItems(labelRef, {
@@ -864,7 +864,7 @@ function registerLabels(spacesCmd) {
         .description("Attach a label")
         .option("--json", "Output as JSON")
         .action(async (labelRef, resourceType, resourceRef, opts) => {
-        const spaceId = resolveSpace(spacesCmd);
+        const spaceId = await resolveSpace(spacesCmd);
         const client = createClient();
         try {
             const result = await client.space(spaceId).labels.attach(labelRef, { resourceType: parseLabelResourceType(resourceType), resourceRef });
@@ -880,7 +880,7 @@ function registerLabels(spacesCmd) {
         .command("detach <labelRef> <resourceType> <resourceRef>")
         .description("Detach a label")
         .action(async (labelRef, resourceType, resourceRef) => {
-        const spaceId = resolveSpace(spacesCmd);
+        const spaceId = await resolveSpace(spacesCmd);
         const client = createClient();
         try {
             await client.space(spaceId).labels.detach(labelRef, { resourceType: parseLabelResourceType(resourceType), resourceRef });
@@ -897,7 +897,7 @@ function registerLabels(spacesCmd) {
         .option("--remove <refs>", "Comma-separated label refs to remove")
         .option("--json", "Output as JSON")
         .action(async (resourceType, resourceRef, opts) => {
-        const spaceId = resolveSpace(spacesCmd);
+        const spaceId = await resolveSpace(spacesCmd);
         const client = createClient();
         try {
             const result = await client.space(spaceId).labels.patchResourceLabels(parseLabelResourceType(resourceType), resourceRef, {
@@ -918,7 +918,7 @@ function registerLabels(spacesCmd) {
         .option("--labels <refs>", "Comma-separated label refs")
         .option("--json", "Output as JSON")
         .action(async (resourceType, resourceRef, labelRefs, opts) => {
-        const spaceId = resolveSpace(spacesCmd);
+        const spaceId = await resolveSpace(spacesCmd);
         const client = createClient();
         try {
             const refs = [...parseLabelRefs(opts.labels), ...labelRefs];
@@ -936,14 +936,14 @@ function registerMods(spacesCmd) {
     const modsCmd = spacesCmd
         .command("mods")
         .description("Manage space mods")
-        .hook("preAction", () => { resolveSpace(spacesCmd); });
+        .hook("preAction", async () => { await resolveSpace(spacesCmd); });
     modsCmd
         .command("ls")
         .alias("list")
         .description("List mods")
         .option("--json", "Output as JSON")
         .action(async (opts) => {
-        const spaceId = resolveSpace(spacesCmd);
+        const spaceId = await resolveSpace(spacesCmd);
         const client = createClient();
         try {
             const result = await client.space(spaceId).mods.list();
@@ -969,7 +969,7 @@ function registerMods(spacesCmd) {
         .option("--json", "Output as JSON")
         .action(async (modSpaceId, opts) => {
         await confirmRestart(opts);
-        const spaceId = resolveSpace(spacesCmd);
+        const spaceId = await resolveSpace(spacesCmd);
         const client = createClient();
         try {
             const result = await client.space(spaceId).mods.create({ modSpaceId, name: opts.name, mountSlug: opts.slug });
@@ -988,7 +988,7 @@ function registerMods(spacesCmd) {
         .option("--json", "Output as JSON")
         .action(async (modId, opts) => {
         await confirmRestart(opts);
-        const spaceId = resolveSpace(spacesCmd);
+        const spaceId = await resolveSpace(spacesCmd);
         const client = createClient();
         try {
             const result = await client.space(spaceId).mods.update(modId, { enabled: true });
@@ -1007,7 +1007,7 @@ function registerMods(spacesCmd) {
         .option("--json", "Output as JSON")
         .action(async (modId, opts) => {
         await confirmRestart(opts);
-        const spaceId = resolveSpace(spacesCmd);
+        const spaceId = await resolveSpace(spacesCmd);
         const client = createClient();
         try {
             const result = await client.space(spaceId).mods.update(modId, { enabled: false });
@@ -1027,7 +1027,7 @@ function registerMods(spacesCmd) {
         .option("--json", "Output as JSON")
         .action(async (modId, opts) => {
         await confirmRestart(opts);
-        const spaceId = resolveSpace(spacesCmd);
+        const spaceId = await resolveSpace(spacesCmd);
         const client = createClient();
         try {
             const result = await client.space(spaceId).mods.remove(modId);
@@ -1111,14 +1111,14 @@ function registerFiles(spacesCmd) {
     const filesCmd = spacesCmd
         .command("files")
         .description("File operations")
-        .hook("preAction", () => { resolveSpace(spacesCmd); });
+        .hook("preAction", async () => { await resolveSpace(spacesCmd); });
     filesCmd
         .command("ls [path]")
         .alias("list")
         .description("List directory tree")
         .option("--json", "Output as JSON")
         .action(async (path, opts) => {
-        const spaceId = resolveSpace(spacesCmd);
+        const spaceId = await resolveSpace(spacesCmd);
         const client = createClient();
         try {
             const tree = await client.space(spaceId).files.list(path ?? "");
@@ -1143,7 +1143,7 @@ function registerFiles(spacesCmd) {
         .command("cat <path>")
         .description("Read file content")
         .action(async (path) => {
-        const spaceId = resolveSpace(spacesCmd);
+        const spaceId = await resolveSpace(spacesCmd);
         const client = createClient();
         try {
             const file = await client.space(spaceId).files.read(path);
@@ -1173,7 +1173,7 @@ function registerFiles(spacesCmd) {
         }
         if (!content)
             return error("No content provided", "Use -c or pipe via stdin");
-        const spaceId = resolveSpace(spacesCmd);
+        const spaceId = await resolveSpace(spacesCmd);
         const client = createClient();
         try {
             const result = await client.space(spaceId).files.write({
@@ -1197,7 +1197,7 @@ function registerFiles(spacesCmd) {
         .command("mkdir <path>")
         .description("Create a directory")
         .action(async (path) => {
-        const spaceId = resolveSpace(spacesCmd);
+        const spaceId = await resolveSpace(spacesCmd);
         const client = createClient();
         try {
             await client.space(spaceId).files.createDir(path);
@@ -1212,7 +1212,7 @@ function registerFiles(spacesCmd) {
         .description("Delete a file or directory")
         .option("-r, --recursive", "Delete recursively")
         .action(async (path, opts) => {
-        const spaceId = resolveSpace(spacesCmd);
+        const spaceId = await resolveSpace(spacesCmd);
         const client = createClient();
         try {
             await client.space(spaceId).files.delete(path, opts.recursive ?? false);
@@ -1226,7 +1226,7 @@ function registerFiles(spacesCmd) {
         .command("mv <from> <to>")
         .description("Move or rename")
         .action(async (from, to) => {
-        const spaceId = resolveSpace(spacesCmd);
+        const spaceId = await resolveSpace(spacesCmd);
         const client = createClient();
         try {
             await client.space(spaceId).files.move({ fromPath: from, toPath: to });
@@ -1241,7 +1241,7 @@ function registerFiles(spacesCmd) {
         .description("Show pending workspace changes vs last checkpoint")
         .option("--json", "Output as JSON")
         .action(async (path, opts) => {
-        const spaceId = resolveSpace(spacesCmd);
+        const spaceId = await resolveSpace(spacesCmd);
         const client = createClient();
         try {
             if (path) {
@@ -1272,14 +1272,14 @@ function registerSessions(spacesCmd) {
     const sessionsCmd = spacesCmd
         .command("sessions")
         .description("Browse sessions and turns")
-        .hook("preAction", () => { resolveSpace(spacesCmd); });
+        .hook("preAction", async () => { await resolveSpace(spacesCmd); });
     sessionsCmd
         .command("ls")
         .alias("list")
         .description("List sessions")
         .option("--json", "Output as JSON")
         .action(async (opts) => {
-        const spaceId = resolveSpace(spacesCmd);
+        const spaceId = await resolveSpace(spacesCmd);
         const client = createClient();
         try {
             const result = await client.space(spaceId).sessions.list();
@@ -1306,7 +1306,7 @@ function registerSessions(spacesCmd) {
         .option("--label <ref>", "Attach a label, e.g. Bug or Area/Frontend", collectOption, [])
         .option("--json", "Output as JSON")
         .action(async (title, opts) => {
-        const spaceId = resolveSpace(spacesCmd);
+        const spaceId = await resolveSpace(spacesCmd);
         const client = createClient();
         try {
             const result = await client.space(spaceId).sessions.create({
@@ -1330,7 +1330,7 @@ function registerSessions(spacesCmd) {
         .description("Session details")
         .option("--json", "Output as JSON")
         .action(async (id, opts) => {
-        const spaceId = resolveSpace(spacesCmd);
+        const spaceId = await resolveSpace(spacesCmd);
         const client = createClient();
         try {
             const result = await client.space(spaceId).session(id).get();
@@ -1352,7 +1352,7 @@ function registerSessions(spacesCmd) {
         .command("rename <id> <name>")
         .description("Rename a session")
         .action(async (id, name) => {
-        const spaceId = resolveSpace(spacesCmd);
+        const spaceId = await resolveSpace(spacesCmd);
         const client = createClient();
         try {
             await client.space(spaceId).session(id).rename(name);
@@ -1368,7 +1368,7 @@ function registerSessions(spacesCmd) {
         .description("Stream realtime session events")
         .option("--json", "Output as JSON")
         .action(async (id, opts) => {
-        const spaceId = resolveSpace(spacesCmd);
+        const spaceId = await resolveSpace(spacesCmd);
         const client = createClient();
         const session = client.space(spaceId).session(id);
         process.stdout.write("  Listening for events...\n\n");
@@ -1423,7 +1423,7 @@ function registerTurns(sessionsCmd) {
         .option("--limit <n>", "Page size", "30")
         .option("--json", "Output as JSON")
         .action(async (sessionId, opts) => {
-        const spaceId = resolveSpace(sessionsCmd);
+        const spaceId = await resolveSpace(sessionsCmd);
         const client = createClient();
         try {
             const result = await client.space(spaceId).session(sessionId).turns.listPaginated({
@@ -1455,7 +1455,7 @@ function registerTurns(sessionsCmd) {
         .description("Show turn details")
         .option("--json", "Output as JSON")
         .action(async (sessionId, turnId, opts) => {
-        const spaceId = resolveSpace(sessionsCmd);
+        const spaceId = await resolveSpace(sessionsCmd);
         const client = createClient();
         try {
             const result = await client.space(spaceId).session(sessionId).turns.get(turnId);
@@ -1484,7 +1484,7 @@ function registerTurns(sessionsCmd) {
         .description("Run a queued follow-up now")
         .option("--json", "Output as JSON")
         .action(async (sessionId, turnId, opts) => {
-        const spaceId = resolveSpace(sessionsCmd);
+        const spaceId = await resolveSpace(sessionsCmd);
         const client = createClient();
         try {
             const result = await client.space(spaceId).session(sessionId).steerTurn(turnId);
@@ -1501,7 +1501,7 @@ function registerTurns(sessionsCmd) {
         .description("Cancel a queued follow-up")
         .option("--json", "Output as JSON")
         .action(async (sessionId, turnId, opts) => {
-        const spaceId = resolveSpace(sessionsCmd);
+        const spaceId = await resolveSpace(sessionsCmd);
         const client = createClient();
         try {
             const result = await client.space(spaceId).session(sessionId).cancelTurn(turnId);
@@ -1520,7 +1520,7 @@ function registerTurns(sessionsCmd) {
         .option("--limit <n>", "Page size", "100")
         .option("--json", "Output as JSON")
         .action(async (sessionId, opts) => {
-        const spaceId = resolveSpace(sessionsCmd);
+        const spaceId = await resolveSpace(sessionsCmd);
         const client = createClient();
         try {
             const result = await client.space(spaceId).session(sessionId).turns.index({
@@ -1554,7 +1554,7 @@ function registerTurns(sessionsCmd) {
         .option("--after <n>", "Turns after anchor", "20")
         .option("--json", "Output as JSON")
         .action(async (sessionId, opts) => {
-        const spaceId = resolveSpace(sessionsCmd);
+        const spaceId = await resolveSpace(sessionsCmd);
         if (!opts.sequence && !opts.turn)
             return error("Missing anchor", "Use --sequence <n> or --turn <id>");
         const client = createClient();
@@ -1647,14 +1647,14 @@ function registerMembers(spacesCmd) {
     const memCmd = spacesCmd
         .command("members")
         .description("Member management")
-        .hook("preAction", () => { resolveSpace(spacesCmd); });
+        .hook("preAction", async () => { await resolveSpace(spacesCmd); });
     memCmd
         .command("ls")
         .alias("list")
         .description("List space members")
         .option("--json", "Output as JSON")
         .action(async (opts) => {
-        const spaceId = resolveSpace(spacesCmd);
+        const spaceId = await resolveSpace(spacesCmd);
         const client = createClient();
         try {
             const result = await client.space(spaceId).members.list();
@@ -1678,7 +1678,7 @@ function registerMembers(spacesCmd) {
         .command("update <userId> <role>")
         .description("Change member role (host | builder | guest)")
         .action(async (userId, role) => {
-        const spaceId = resolveSpace(spacesCmd);
+        const spaceId = await resolveSpace(spacesCmd);
         const client = createClient();
         try {
             await client.space(spaceId).members.update(userId, parseChoice(role, "role", SPACE_ROLES));
@@ -1692,7 +1692,7 @@ function registerMembers(spacesCmd) {
         .command("remove <userId>")
         .description("Remove a member")
         .action(async (userId) => {
-        const spaceId = resolveSpace(spacesCmd);
+        const spaceId = await resolveSpace(spacesCmd);
         const client = createClient();
         try {
             await client.space(spaceId).members.remove(userId);
@@ -1708,13 +1708,13 @@ function registerAccess(spacesCmd) {
     const accCmd = spacesCmd
         .command("access")
         .description("Access control")
-        .hook("preAction", () => { resolveSpace(spacesCmd); });
+        .hook("preAction", async () => { await resolveSpace(spacesCmd); });
     accCmd
         .command("get")
         .description("Get access policy")
         .option("--json", "Output as JSON")
         .action(async (opts) => {
-        const spaceId = resolveSpace(spacesCmd);
+        const spaceId = await resolveSpace(spacesCmd);
         const client = createClient();
         try {
             const policy = await client.space(spaceId).access.get();
@@ -1736,7 +1736,7 @@ function registerAccess(spacesCmd) {
         .option("--anonymous <role>", "Role for anonymous users (host|builder|guest|null)")
         .option("--json", "Output as JSON")
         .action(async (opts) => {
-        const spaceId = resolveSpace(spacesCmd);
+        const spaceId = await resolveSpace(spacesCmd);
         const client = createClient();
         try {
             const policy = await client.space(spaceId).access.set({
@@ -1761,7 +1761,7 @@ function registerCheckpoints(spacesCmd) {
     const cpCmd = spacesCmd
         .command("checkpoints")
         .description("Checkpoint management")
-        .hook("preAction", () => { resolveSpace(spacesCmd); });
+        .hook("preAction", async () => { await resolveSpace(spacesCmd); });
     cpCmd
         .command("ls")
         .alias("list")
@@ -1770,7 +1770,7 @@ function registerCheckpoints(spacesCmd) {
         .option("--cursor <cursor>", "Pagination cursor")
         .option("--json", "Output as JSON")
         .action(async (opts) => {
-        const spaceId = resolveSpace(spacesCmd);
+        const spaceId = await resolveSpace(spacesCmd);
         const client = createClient();
         try {
             const result = await client.space(spaceId).checkpoints.list({
@@ -1799,7 +1799,7 @@ function registerCheckpoints(spacesCmd) {
         .description("Checkpoint details")
         .option("--json", "Output as JSON")
         .action(async (id, opts) => {
-        const spaceId = resolveSpace(spacesCmd);
+        const spaceId = await resolveSpace(spacesCmd);
         const client = createClient();
         try {
             const result = await client.space(spaceId).checkpoints.get(id);
@@ -1822,7 +1822,7 @@ function registerCheckpoints(spacesCmd) {
         .description("Create a checkpoint")
         .option("--json", "Output as JSON")
         .action(async (description, opts) => {
-        const spaceId = resolveSpace(spacesCmd);
+        const spaceId = await resolveSpace(spacesCmd);
         const client = createClient();
         try {
             const result = await client.space(spaceId).checkpoints.create(description ?? null);
@@ -1839,7 +1839,7 @@ function registerCheckpoints(spacesCmd) {
         .description("List checkpoint tree")
         .option("--json", "Output as JSON")
         .action(async (checkpointId, path, opts) => {
-        const spaceId = resolveSpace(spacesCmd);
+        const spaceId = await resolveSpace(spacesCmd);
         const client = createClient();
         try {
             const tree = await client.space(spaceId).checkpoints(checkpointId).files.list(path ?? "");
@@ -1866,7 +1866,7 @@ function registerCheckpoints(spacesCmd) {
         .description("Show checkpoint file content")
         .option("--json", "Output as JSON")
         .action(async (checkpointId, path, opts) => {
-        const spaceId = resolveSpace(spacesCmd);
+        const spaceId = await resolveSpace(spacesCmd);
         const client = createClient();
         try {
             const file = await client.space(spaceId).checkpoints(checkpointId).files.read(path);
@@ -1888,7 +1888,7 @@ function registerCheckpoints(spacesCmd) {
         .option("--base <checkpointId>", "Compare against another checkpoint")
         .option("--json", "Output as JSON")
         .action(async (checkpointId, path, opts) => {
-        const spaceId = resolveSpace(spacesCmd);
+        const spaceId = await resolveSpace(spacesCmd);
         const client = createClient();
         try {
             if (path) {

package/dist/index.js

@@ -36,7 +36,7 @@ program
     .summary("Work with Cohub from your terminal")
     .description("Send prompts, manage Space files, and publish public output.")
     .version(VERSION, "-v, --version", "Show version")
-    .option("-s, --space <id>", "Target Space ID")
+    .option("-s, --space <id>", "Target Space ID (defaults to your Home space)")
     .option("--json", "Print machine-readable JSON when supported")
     .helpOption("-h, --help", "Show help")
     .addHelpText("after", `
@@ -45,9 +45,9 @@ Common commands:
   cohub auth login
   cohub profile avatar ./avatar.png
   cohub spaces ls
-  cohub -s <space-id> prompt "Fix the failing tests"
-  cohub -s <space-id> completion "Summarize AGENTS.md" --system-prompt AGENTS.md --stream
-  cohub -s <space-id> run -- git status
+  cohub prompt "Fix the failing tests"
+  cohub completion "Summarize AGENTS.md" --system-prompt AGENTS.md --stream
+  cohub run -- git status
   cohub sandbox up ./my-project
   cohub search "release notes"
   cohub -s <space-id> boards inspect <board-id>
@@ -62,7 +62,11 @@ Common commands:
   cohub models ls --model-type multimodal
   cohub generate "A calm lake at sunrise" --model <model> --output lake.png
 
+Target space:
+  -s <space-id>, then COHUB_SPACE_ID, then your Home space
+
 Environment:
+  COHUB_SPACE_ID         Target Space ID when -s is omitted
   COHUB_EXECUTION_TOKEN  Use this token instead of the stored Logto session
   ENV=dev                Use the development Cohub environment
 `);

package/dist/space.d.ts

@@ -1,2 +1,32 @@
 import type { Command } from "commander";
-export declare function resolveSpace(program: Command): string;
+/**
+ * Cache key aligned with auth: execution token is exclusive (same as
+ * `resolveAccessToken`) and never falls back to a local Logto session.
+ * Execution grants identify the actor as `actorUserId`, not `sub`.
+ */
+export declare function identityKeyFrom(input: {
+    env: string;
+    executionToken?: string | null;
+    idToken?: string | null;
+    accessToken?: string | null;
+}): string | null;
+/** Exported for tests; production always uses `CACHE_PATH`. */
+export declare function readDefaultSpaceCache(path: string, key: string, now?: number): string | null;
+export declare function clearDefaultSpaceCache(): void;
+/** Explicit target from `-s/--space` (any ancestor) or `COHUB_SPACE_ID`, else null. */
+export declare function explicitSpace(program: Command): string | null;
+/**
+ * Resolve the user's home space when no target is given. Cached locally per
+ * identity so repeated invocations skip the network entirely, and memoized
+ * in-process so preAction hooks and actions share a single lookup.
+ * Network and auth failures propagate so callers can report them faithfully.
+ */
+export declare function resolveDefaultSpace(): Promise<string | null>;
+/** Shared exit for commands that need a space but resolved none. */
+export declare function missingSpaceError(): never;
+/**
+ * Target space for a command: explicit `-s`/`COHUB_SPACE_ID` first, then the
+ * user's home space. Exits with guidance when neither is available; request
+ * failures go through the shared HTTP error handler.
+ */
+export declare function resolveSpace(program: Command): Promise<string>;

package/dist/space.js

@@ -1,5 +1,85 @@
-import { error } from "./output.js";
-export function resolveSpace(program) {
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { resolveCohubEnvironment } from "@neta-art/cohub";
+import { readAuthSession } from "./auth.js";
+import { createClient } from "./client.js";
+import { error, handleHttp } from "./output.js";
+const CONFIG_DIR = join(homedir(), ".config", "cohub");
+const CACHE_PATH = join(CONFIG_DIR, "default-space.json");
+/** Home space is stable; a one-day TTL bounds how long a stale hit survives. */
+const CACHE_TTL_MS = 86_400_000;
+function jwtClaim(token, key) {
+    const payload = token?.split(".")[1];
+    if (!payload)
+        return null;
+    try {
+        const parsed = JSON.parse(Buffer.from(payload, "base64url").toString("utf-8"));
+        const value = parsed[key];
+        return typeof value === "string" && value ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Cache key aligned with auth: execution token is exclusive (same as
+ * `resolveAccessToken`) and never falls back to a local Logto session.
+ * Execution grants identify the actor as `actorUserId`, not `sub`.
+ */
+export function identityKeyFrom(input) {
+    if (input.executionToken) {
+        const actor = jwtClaim(input.executionToken, "actorUserId") ?? jwtClaim(input.executionToken, "sub");
+        return actor ? `${input.env}:${actor}` : null;
+    }
+    const sub = jwtClaim(input.idToken, "sub") ?? jwtClaim(input.accessToken, "sub");
+    return sub ? `${input.env}:${sub}` : null;
+}
+function identityKey() {
+    const session = readAuthSession();
+    return identityKeyFrom({
+        env: resolveCohubEnvironment(),
+        executionToken: process.env.COHUB_EXECUTION_TOKEN?.trim(),
+        idToken: session?.idToken,
+        accessToken: session?.accessToken,
+    });
+}
+/** Exported for tests; production always uses `CACHE_PATH`. */
+export function readDefaultSpaceCache(path, key, now = Date.now()) {
+    try {
+        const cache = JSON.parse(readFileSync(path, "utf-8"));
+        if (cache.key !== key || typeof cache.spaceId !== "string" || typeof cache.cachedAt !== "number")
+            return null;
+        if (now - cache.cachedAt > CACHE_TTL_MS)
+            return null;
+        return cache.spaceId;
+    }
+    catch {
+        return null;
+    }
+}
+function writeCachedDefaultSpace(key, spaceId) {
+    try {
+        mkdirSync(CONFIG_DIR, { recursive: true });
+        const cache = { key, spaceId, cachedAt: Date.now() };
+        writeFileSync(CACHE_PATH, `${JSON.stringify(cache, null, 2)}\n`, { encoding: "utf-8", mode: 0o600 });
+    }
+    catch {
+        // Cache is best-effort; never fail the command over it.
+    }
+}
+let defaultSpacePromise = null;
+export function clearDefaultSpaceCache() {
+    defaultSpacePromise = null;
+    try {
+        rmSync(CACHE_PATH, { force: true });
+    }
+    catch {
+        // Best-effort, same as writes.
+    }
+}
+/** Explicit target from `-s/--space` (any ancestor) or `COHUB_SPACE_ID`, else null. */
+export function explicitSpace(program) {
     let current = program;
     while (current) {
         const opts = current.opts();
@@ -7,8 +87,39 @@ export function resolveSpace(program) {
             return opts.space.trim();
         current = current.parent ?? null;
     }
-    const envSpace = process.env.COHUB_SPACE_ID?.trim();
-    if (envSpace)
-        return envSpace;
-    return error("Missing required space", "Add -s, --space <id> or set COHUB_SPACE_ID.");
+    return process.env.COHUB_SPACE_ID?.trim() || null;
+}
+/**
+ * Resolve the user's home space when no target is given. Cached locally per
+ * identity so repeated invocations skip the network entirely, and memoized
+ * in-process so preAction hooks and actions share a single lookup.
+ * Network and auth failures propagate so callers can report them faithfully.
+ */
+export function resolveDefaultSpace() {
+    defaultSpacePromise ??= (async () => {
+        const key = identityKey();
+        if (key) {
+            const cached = readDefaultSpaceCache(CACHE_PATH, key);
+            if (cached)
+                return cached;
+        }
+        const space = (await createClient().spaces.getDefault()).space ?? null;
+        // Recent-space fallback from getDefault() is not stable enough to cache.
+        if (space?.id && space.slug === "home" && key)
+            writeCachedDefaultSpace(key, space.id);
+        return space?.id ?? null;
+    })();
+    return defaultSpacePromise;
+}
+/** Shared exit for commands that need a space but resolved none. */
+export function missingSpaceError() {
+    return error("No target space", "Add -s, --space <id> or set COHUB_SPACE_ID. Run `cohub auth login` to use your home space.");
+}
+/**
+ * Target space for a command: explicit `-s`/`COHUB_SPACE_ID` first, then the
+ * user's home space. Exits with guidance when neither is available; request
+ * failures go through the shared HTTP error handler.
+ */
+export async function resolveSpace(program) {
+    return explicitSpace(program) ?? (await resolveDefaultSpace().catch(handleHttp)) ?? missingSpaceError();
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neta-art/cohub-cli",
-  "version": "6.7.0",
+  "version": "6.8.0",
   "description": "CLI for Cohub — spaces, sessions, and agent collaboration.",
   "type": "module",
   "license": "Apache-2.0",
@@ -19,7 +19,7 @@
     "commander": "^15.0.0",
     "pixi.js": "^8.20.1",
     "sharp": "^0.35.4",
-    "@neta-art/cohub": "8.10.0"
+    "@neta-art/cohub": "8.10.1"
   },
   "publishConfig": {
     "access": "public"