@instafy/cli 0.1.8 → 0.1.10

package/dist/project.js

@@ -1,76 +1,235 @@
 import fs from "node:fs";
 import path from "node:path";
 import kleur from "kleur";
-import { resolveControllerUrl, resolveUserAccessToken } from "./config.js";
-function formatAuthRequiredError() {
-    return new Error("Login required. Run `instafy login` (recommended) or pass --access-token / set SUPABASE_ACCESS_TOKEN.");
+import { stdin as input } from "node:process";
+import { getInstafyProfileConfigPath, resolveConfiguredStudioUrl, resolveControllerUrl, resolveUserAccessTokenWithSource, } from "./config.js";
+import { formatAuthRejectedError, formatAuthRequiredError } from "./errors.js";
+import { findProjectManifest } from "./project-manifest.js";
+import { fetchWithControllerAuth } from "./controller-fetch.js";
+let promptsModule = null;
+async function loadPrompts() {
+    promptsModule ?? (promptsModule = import("@clack/prompts"));
+    return promptsModule;
 }
-async function fetchOrganizations(controllerUrl, token) {
-    const response = await fetch(`${controllerUrl}/orgs`, {
-        headers: {
-            authorization: `Bearer ${token}`,
-        },
+async function controllerFetch(controllerUrl, auth, pathname, init) {
+    const { response, accessToken } = await fetchWithControllerAuth({
+        url: `${controllerUrl}${pathname}`,
+        init,
+        accessToken: auth.accessToken,
+        tokenSource: auth.tokenSource,
+        profile: auth.profile,
+        cwd: auth.cwd,
     });
+    auth.accessToken = accessToken;
+    return response;
+}
+async function fetchOrganizations(controllerUrl, auth, retryCommand) {
+    const response = await controllerFetch(controllerUrl, auth, "/orgs");
     if (!response.ok) {
         const text = await response.text().catch(() => "");
+        if (response.status === 401 || response.status === 403) {
+            throw formatAuthRejectedError({
+                status: response.status,
+                responseBody: text,
+                retryCommand,
+            });
+        }
         throw new Error(`Organization list failed (${response.status} ${response.statusText}): ${text}`);
     }
     const body = (await response.json());
     return Array.isArray(body.orgs) ? body.orgs : [];
 }
-async function fetchOrgProjects(controllerUrl, token, orgId) {
-    const response = await fetch(`${controllerUrl}/orgs/${encodeURIComponent(orgId)}/projects`, {
-        headers: {
-            authorization: `Bearer ${token}`,
-        },
-    });
+async function fetchOrgProjects(controllerUrl, auth, orgId, retryCommand) {
+    const response = await controllerFetch(controllerUrl, auth, `/orgs/${encodeURIComponent(orgId)}/projects`);
     if (!response.ok) {
         const text = await response.text().catch(() => "");
+        if (response.status === 401 || response.status === 403) {
+            throw formatAuthRejectedError({
+                status: response.status,
+                responseBody: text,
+                retryCommand,
+            });
+        }
         throw new Error(`Project list failed (${response.status} ${response.statusText}): ${text}`);
     }
     const body = (await response.json());
     return Array.isArray(body.projects) ? body.projects : [];
 }
-async function resolveOrg(controllerUrl, token, options) {
-    if (options.orgId) {
-        return { orgId: options.orgId, orgName: options.orgName ?? null };
-    }
-    const payload = {};
-    if (options.orgName) {
-        payload.orgName = options.orgName;
-    }
-    if (options.orgSlug) {
-        payload.orgSlug = options.orgSlug;
-    }
-    if (options.ownerUserId) {
-        payload.ownerUserId = options.ownerUserId;
-    }
-    const response = await fetch(`${controllerUrl}/orgs`, {
+async function createOrganization(controllerUrl, auth, payload, retryCommand) {
+    const response = await controllerFetch(controllerUrl, auth, "/orgs", {
         method: "POST",
         headers: {
-            authorization: `Bearer ${token}`,
             "content-type": "application/json",
         },
         body: JSON.stringify(payload),
     });
     if (!response.ok) {
         const text = await response.text().catch(() => "");
+        if (response.status === 401 || response.status === 403) {
+            throw formatAuthRejectedError({
+                status: response.status,
+                responseBody: text,
+                retryCommand,
+            });
+        }
         throw new Error(`Organization creation failed (${response.status} ${response.statusText}): ${text}`);
     }
     const json = (await response.json());
-    const orgId = json.org_id;
+    const orgId = json.org_id ?? json.orgId ?? json.id;
     if (!orgId) {
-        throw new Error("Organization creation response missing org_id");
+        throw new Error(`Organization creation response missing org id (expected org_id/orgId/id). Raw: ${JSON.stringify(json)}`);
+    }
+    return { orgId, orgName: json.org_name ?? json.orgName ?? null };
+}
+async function resolveOrg(controllerUrl, auth, options, retryCommand) {
+    if (options.orgId) {
+        return { orgId: options.orgId, orgName: options.orgName ?? null };
+    }
+    const orgSlug = options.orgSlug?.trim() || null;
+    const orgName = options.orgName?.trim() || null;
+    const studioUrl = resolveConfiguredStudioUrl({ profile: options.profile ?? null }) ?? "https://staging.instafy.dev";
+    const studioOrgUrl = `${studioUrl.replace(/\/$/, "")}/studio?panel=settings`;
+    const allowInteractive = Boolean(input.isTTY && process.stdout.isTTY && options.json !== true && process.env.CI !== "true");
+    async function promptAndCreateOrg() {
+        const { isCancel, text } = await loadPrompts();
+        const enteredName = await text({
+            message: "Organization name",
+            defaultValue: "Personal",
+        });
+        if (isCancel(enteredName)) {
+            throw new Error("Cancelled.");
+        }
+        const chosenName = String(enteredName).trim() || "Personal";
+        const enteredSlug = await text({
+            message: "Organization slug (optional)",
+        });
+        if (isCancel(enteredSlug)) {
+            throw new Error("Cancelled.");
+        }
+        const chosenSlug = String(enteredSlug).trim();
+        const payload = {
+            orgName: chosenName,
+        };
+        if (options.ownerUserId) {
+            payload.ownerUserId = options.ownerUserId;
+        }
+        if (chosenSlug) {
+            payload.orgSlug = chosenSlug;
+        }
+        const created = await createOrganization(controllerUrl, auth, payload, retryCommand);
+        return { orgId: created.orgId, orgName: created.orgName ?? chosenName };
+    }
+    if (orgSlug) {
+        const orgs = await fetchOrganizations(controllerUrl, auth, retryCommand);
+        const matches = orgs.filter((org) => org.slug === orgSlug);
+        if (matches.length === 1) {
+            return { orgId: matches[0].id, orgName: matches[0].name ?? null };
+        }
+    }
+    if (!orgSlug && !orgName) {
+        const orgs = await fetchOrganizations(controllerUrl, auth, retryCommand);
+        if (orgs.length === 0) {
+            if (allowInteractive) {
+                const { confirm, isCancel } = await loadPrompts();
+                console.log(kleur.yellow("No organizations found for this account."));
+                console.log("");
+                console.log(`Create one in Studio: ${kleur.cyan(studioOrgUrl)}`);
+                console.log("");
+                const shouldCreate = await confirm({
+                    message: "Create a new organization now?",
+                    initialValue: true,
+                });
+                if (isCancel(shouldCreate) || !shouldCreate) {
+                    throw new Error("No organization selected.");
+                }
+                return await promptAndCreateOrg();
+            }
+            throw new Error(`No organizations found.\n\nNext:\n- Create an org in Studio: ${studioOrgUrl}\n- Or rerun: instafy project init --org-name \"My Org\"`);
+        }
+        if (orgs.length === 1) {
+            return { orgId: orgs[0].id, orgName: orgs[0].name ?? null };
+        }
+        if (allowInteractive) {
+            const { isCancel, select } = await loadPrompts();
+            const selection = await select({
+                message: "Choose an organization for this project",
+                options: [
+                    { value: "__create__", label: "+ Create a new organization" },
+                    ...orgs.map((org) => ({
+                        value: org.id,
+                        label: org.name,
+                        hint: `${org.slug ? `${org.slug} · ` : ""}${org.id}`,
+                    })),
+                ],
+                initialValue: orgs[0].id,
+            });
+            if (isCancel(selection)) {
+                throw new Error("Cancelled.");
+            }
+            if (selection === "__create__") {
+                return await promptAndCreateOrg();
+            }
+            const pickedOrg = orgs.find((org) => org.id === selection);
+            if (!pickedOrg) {
+                throw new Error("Selected organization not found.");
+            }
+            return { orgId: pickedOrg.id, orgName: pickedOrg.name ?? null };
+        }
+        throw new Error("Multiple organizations found.\n\nNext:\n- instafy org list\n- instafy project init --org-id <uuid>");
+    }
+    if (orgSlug && !orgName) {
+        if (allowInteractive) {
+            const { isCancel, text } = await loadPrompts();
+            console.log(kleur.yellow("Organization slug did not match an existing org."));
+            console.log(`Create one in Studio: ${kleur.cyan(studioOrgUrl)}`);
+            console.log("");
+            const enteredName = await text({
+                message: "Organization name",
+                defaultValue: "Personal",
+            });
+            if (isCancel(enteredName)) {
+                throw new Error("Cancelled.");
+            }
+            const chosenName = String(enteredName).trim() || "Personal";
+            const payload = { orgName: chosenName, orgSlug };
+            if (options.ownerUserId) {
+                payload.ownerUserId = options.ownerUserId;
+            }
+            const created = await createOrganization(controllerUrl, auth, payload, retryCommand);
+            return { orgId: created.orgId, orgName: created.orgName ?? chosenName };
+        }
+        throw new Error(`Organization slug "${orgSlug}" did not match an existing org, and org name is required to create one.\n\nNext:\n- Create an org in Studio: ${studioOrgUrl}\n- Or rerun: instafy project init --org-name \"My Org\" --org-slug "${orgSlug}"`);
+    }
+    const payload = {};
+    if (orgName) {
+        payload.orgName = orgName;
+    }
+    if (orgSlug) {
+        payload.orgSlug = orgSlug;
+    }
+    if (options.ownerUserId) {
+        payload.ownerUserId = options.ownerUserId;
+    }
+    if (!payload.orgName) {
+        throw new Error(`Organization name is required.\n\nNext:\n- Create an org in Studio: ${studioOrgUrl}\n- Or rerun: instafy project init --org-name \"My Org\"`);
     }
-    return { orgId, orgName: json.org_name ?? null };
+    const created = await createOrganization(controllerUrl, auth, payload, retryCommand);
+    return { orgId: created.orgId, orgName: created.orgName ?? orgName ?? null };
 }
 export async function listProjects(options) {
     const controllerUrl = resolveControllerUrl({ controllerUrl: options.controllerUrl ?? null });
-    const token = resolveUserAccessToken({ accessToken: options.accessToken ?? null });
-    if (!token) {
-        throw formatAuthRequiredError();
+    const resolved = resolveUserAccessTokenWithSource({ accessToken: options.accessToken ?? null });
+    if (!resolved.token) {
+        throw formatAuthRequiredError({ retryCommand: "instafy project list" });
     }
-    const orgs = await fetchOrganizations(controllerUrl, token);
+    const retryCommand = "instafy project list";
+    const auth = {
+        accessToken: resolved.token,
+        tokenSource: resolved.source,
+        profile: resolved.profile,
+        cwd: process.cwd(),
+    };
+    const orgs = await fetchOrganizations(controllerUrl, auth, retryCommand);
     let targetOrgs = orgs;
     if (options.orgId) {
         targetOrgs = orgs.filter((org) => org.id === options.orgId);
@@ -86,7 +245,7 @@ export async function listProjects(options) {
     }
     const summaries = [];
     for (const org of targetOrgs) {
-        const projects = await fetchOrgProjects(controllerUrl, token, org.id);
+        const projects = await fetchOrgProjects(controllerUrl, auth, org.id, retryCommand);
         summaries.push({ org, projects });
     }
     if (options.json) {
@@ -113,29 +272,65 @@ export async function listProjects(options) {
 }
 export async function projectInit(options) {
     const rootDir = path.resolve(options.path ?? process.cwd());
-    const controllerUrl = resolveControllerUrl({ controllerUrl: options.controllerUrl ?? null });
-    const token = resolveUserAccessToken({ accessToken: options.accessToken ?? null });
-    if (!token) {
-        throw formatAuthRequiredError();
+    const controllerUrl = resolveControllerUrl({
+        controllerUrl: options.controllerUrl ?? null,
+        profile: options.profile ?? null,
+        cwd: rootDir,
+    });
+    const resolved = resolveUserAccessTokenWithSource({
+        accessToken: options.accessToken ?? null,
+        profile: options.profile ?? null,
+        cwd: rootDir,
+    });
+    if (!resolved.token) {
+        throw formatAuthRequiredError({
+            retryCommand: "instafy project init",
+            advancedHint: "pass --access-token or set INSTAFY_ACCESS_TOKEN / SUPABASE_ACCESS_TOKEN",
+        });
     }
-    const org = await resolveOrg(controllerUrl, token, options);
+    const retryCommand = "instafy project init";
+    const auth = {
+        accessToken: resolved.token,
+        tokenSource: resolved.source,
+        profile: resolved.profile,
+        cwd: rootDir,
+    };
+    const org = await resolveOrg(controllerUrl, auth, options, retryCommand);
     const body = {
         projectType: options.projectType,
         ownerUserId: options.ownerUserId,
     };
-    const response = await fetch(`${controllerUrl}/orgs/${encodeURIComponent(org.orgId)}/projects`, {
+    const response = await controllerFetch(controllerUrl, auth, `/orgs/${encodeURIComponent(org.orgId)}/projects`, {
         method: "POST",
         headers: {
-            authorization: `Bearer ${token}`,
             "content-type": "application/json",
         },
         body: JSON.stringify(body),
     });
     if (!response.ok) {
         const text = await response.text().catch(() => "");
+        if (response.status === 401 || response.status === 403) {
+            throw formatAuthRejectedError({
+                status: response.status,
+                responseBody: text,
+                retryCommand,
+            });
+        }
         throw new Error(`Project creation failed (${response.status} ${response.statusText}): ${text}`);
     }
     const json = (await response.json());
+    if (!json.project_id && json.projectId) {
+        json.project_id = json.projectId;
+    }
+    if (!json.org_id && json.orgId) {
+        json.org_id = json.orgId;
+    }
+    if (!json.org_name && json.orgName) {
+        json.org_name = json.orgName;
+    }
+    if (!json.project_id) {
+        throw new Error(`Project creation response missing project id (expected project_id/projectId). Raw: ${JSON.stringify(json)}`);
+    }
     const manifestDir = path.join(rootDir, ".instafy");
     const manifestPath = path.join(manifestDir, "project.json");
     try {
@@ -145,6 +340,7 @@ export async function projectInit(options) {
             orgId: json.org_id ?? org.orgId ?? null,
             orgName: json.org_name ?? org.orgName ?? null,
             controllerUrl,
+            profile: options.profile ?? null,
             createdAt: new Date().toISOString(),
         }, null, 2), "utf8");
     }
@@ -170,3 +366,47 @@ export async function projectInit(options) {
     }
     return json;
 }
+export function projectProfile(options) {
+    const rootDir = path.resolve(options.path ?? process.cwd());
+    const manifestInfo = findProjectManifest(rootDir);
+    if (!manifestInfo.path || !manifestInfo.manifest) {
+        throw new Error("No project configured. Run `instafy project init` in this folder first.");
+    }
+    const shouldUpdate = options.unset === true || typeof options.profile === "string";
+    const currentProfile = typeof manifestInfo.manifest.profile === "string" && manifestInfo.manifest.profile.trim()
+        ? manifestInfo.manifest.profile.trim()
+        : null;
+    if (!shouldUpdate) {
+        if (options.json) {
+            console.log(JSON.stringify({ ok: true, path: manifestInfo.path, profile: currentProfile }, null, 2));
+        }
+        else {
+            console.log(kleur.green("Project profile"));
+            console.log(`Manifest: ${manifestInfo.path}`);
+            console.log(`Profile: ${currentProfile ?? kleur.yellow("(none)")}`);
+        }
+        return { path: manifestInfo.path, profile: currentProfile };
+    }
+    const nextProfileRaw = options.unset === true ? null : typeof options.profile === "string" ? options.profile.trim() : null;
+    const nextProfile = nextProfileRaw && nextProfileRaw.length > 0 ? nextProfileRaw : null;
+    if (nextProfile) {
+        getInstafyProfileConfigPath(nextProfile);
+    }
+    const updated = { ...manifestInfo.manifest };
+    if (nextProfile) {
+        updated.profile = nextProfile;
+    }
+    else {
+        delete updated.profile;
+    }
+    fs.writeFileSync(manifestInfo.path, JSON.stringify(updated, null, 2), "utf8");
+    if (options.json) {
+        console.log(JSON.stringify({ ok: true, path: manifestInfo.path, profile: nextProfile }, null, 2));
+    }
+    else {
+        console.log(kleur.green("Updated project profile."));
+        console.log(`Manifest: ${manifestInfo.path}`);
+        console.log(`Profile: ${nextProfile ?? kleur.yellow("(none)")}`);
+    }
+    return { path: manifestInfo.path, profile: nextProfile };
+}

package/dist/rathole.js

@@ -52,18 +52,22 @@ export async function ensureRatholeBinary(options = {}) {
 function resolveInstallPlan() {
     const arch = process.arch;
     const platform = process.platform;
-    if (platform === "darwin" && arch === "arm64") {
-        return { method: "cargo", binaryName: "rathole" };
-    }
     if (platform === "darwin") {
-        if (arch !== "x64") {
-            throw new Error(`Unsupported platform ${platform}/${arch} for prebuilt rathole; set RATHOLE_BIN or install via cargo.`);
+        if (arch === "arm64") {
+            return {
+                method: "download",
+                assetName: "rathole-x86_64-apple-darwin.zip",
+                binaryName: "rathole",
+            };
         }
-        return {
-            method: "download",
-            assetName: "rathole-x86_64-apple-darwin.zip",
-            binaryName: "rathole",
-        };
+        if (arch === "x64") {
+            return {
+                method: "download",
+                assetName: "rathole-x86_64-apple-darwin.zip",
+                binaryName: "rathole",
+            };
+        }
+        throw new Error(`Unsupported platform ${platform}/${arch} for prebuilt rathole; set RATHOLE_BIN or install via cargo.`);
     }
     if (platform === "linux") {
         if (arch === "arm64") {

package/dist/runtime.js

@@ -6,7 +6,10 @@ import { fileURLToPath } from "node:url";
 import { randomUUID } from "node:crypto";
 import os from "node:os";
 import { ensureRatholeBinary } from "./rathole.js";
-import { resolveConfiguredAccessToken } from "./config.js";
+import { resolveActiveProfileName, resolveConfiguredAccessToken } from "./config.js";
+import { formatAuthRejectedError } from "./errors.js";
+import { findProjectManifest } from "./project-manifest.js";
+import { fetchWithControllerAuth } from "./controller-fetch.js";
 const INSTAFY_DIR = path.join(os.homedir(), ".instafy");
 const STATE_FILE = path.join(INSTAFY_DIR, "cli-runtime-state.json");
 const LOG_DIR = path.join(INSTAFY_DIR, "cli-runtime-logs");
@@ -28,7 +31,7 @@ function resolveRuntimeBinary() {
             return candidate;
         }
     }
-    throw new Error("runtime-agent binary not found. If you're in the instafy repo, run `cargo build -p runtime-agent`. Otherwise install Docker and rerun `instafy runtime:start`.");
+    throw new Error("runtime-agent binary not found. If you're in the instafy repo, run `cargo build -p runtime-agent`. Otherwise install Docker and rerun `instafy runtime start`.");
 }
 function tryResolveRuntimeBinary() {
     try {
@@ -142,28 +145,7 @@ function normalizeToken(value) {
     const trimmed = value.trim();
     return trimmed.length > 0 ? trimmed : null;
 }
-export function findProjectManifest(startDir) {
-    let current = path.resolve(startDir);
-    const root = path.parse(current).root;
-    while (true) {
-        const candidate = path.join(current, ".instafy", "project.json");
-        if (existsSync(candidate)) {
-            try {
-                const parsed = JSON.parse(readFileSync(candidate, "utf8"));
-                if (parsed?.projectId) {
-                    return { manifest: parsed, path: candidate };
-                }
-            }
-            catch {
-                // ignore malformed manifest
-            }
-        }
-        if (current === root)
-            break;
-        current = path.dirname(current);
-    }
-    return { manifest: null, path: null };
-}
+export { findProjectManifest };
 function readTokenFromFile(filePath) {
     const normalized = normalizeToken(filePath);
     if (!normalized) {
@@ -207,13 +189,28 @@ function findRatholeOnPath() {
     }
     return null;
 }
-function resolveControllerAccessTokenForCli(options, env, supabaseAccessToken) {
-    return (normalizeToken(options.controllerAccessToken) ??
-        normalizeToken(env["INSTAFY_ACCESS_TOKEN"]) ??
-        normalizeToken(env["CONTROLLER_ACCESS_TOKEN"]) ??
-        supabaseAccessToken ??
-        normalizeToken(env["SUPABASE_ACCESS_TOKEN"]) ??
-        resolveConfiguredAccessToken());
+function resolveControllerAccessTokenForCliWithSource(options, env, supabaseAccessToken, profile, cwd) {
+    const explicit = normalizeToken(options.controllerAccessToken);
+    if (explicit) {
+        return { token: explicit, source: "explicit" };
+    }
+    const envToken = normalizeToken(env["INSTAFY_ACCESS_TOKEN"]) ??
+        normalizeToken(env["CONTROLLER_ACCESS_TOKEN"]);
+    if (envToken) {
+        return { token: envToken, source: "env" };
+    }
+    if (supabaseAccessToken) {
+        return { token: supabaseAccessToken, source: "explicit" };
+    }
+    const supabaseEnvToken = normalizeToken(env["SUPABASE_ACCESS_TOKEN"]);
+    if (supabaseEnvToken) {
+        return { token: supabaseEnvToken, source: "env" };
+    }
+    const stored = resolveConfiguredAccessToken({ profile, cwd });
+    if (stored) {
+        return { token: stored, source: "config" };
+    }
+    return { token: null, source: "none" };
 }
 export async function resolveRatholeBinaryForCli(options) {
     const warn = options.warn ??
@@ -264,19 +261,31 @@ export async function resolveRatholeBinaryForCli(options) {
 export async function mintRuntimeAccessToken(params) {
     const url = params.controllerUrl.replace(/\/$/, "");
     const target = `${url}/projects/${encodeURIComponent(params.projectId)}/runtime/token`;
-    const response = await fetch(target, {
-        method: "POST",
-        headers: {
-            authorization: `Bearer ${params.controllerAccessToken}`,
-            "content-type": "application/json",
+    const { response } = await fetchWithControllerAuth({
+        url: target,
+        init: {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+            },
+            body: JSON.stringify({
+                runtimeId: params.runtimeId,
+                scopes: params.scopes,
+            }),
         },
-        body: JSON.stringify({
-            runtimeId: params.runtimeId,
-            scopes: params.scopes,
-        }),
+        accessToken: params.controllerAccessToken,
+        tokenSource: params.tokenSource ?? "env",
+        profile: params.profile ?? null,
+        cwd: params.cwd ?? null,
     });
     if (!response.ok) {
         const text = await response.text().catch(() => "");
+        if (response.status === 401 || response.status === 403) {
+            throw formatAuthRejectedError({
+                status: response.status,
+                responseBody: text,
+            });
+        }
         throw new Error(`Instafy server rejected runtime token request (${response.status} ${response.statusText}): ${text}`);
     }
     const payload = (await response.json());
@@ -297,6 +306,7 @@ function isProcessAlive(pid) {
 }
 export async function runtimeStart(options) {
     const env = { ...process.env };
+    const cwd = process.cwd();
     const existing = readState();
     if (existing) {
         if (existing.runner === "docker" && existing.containerId && dockerContainerRunning(existing.containerId)) {
@@ -306,17 +316,20 @@ export async function runtimeStart(options) {
             throw new Error(`Runtime already running (pid ${existing.pid}) for project ${existing.projectId}. Stop it first.`);
         }
     }
-    const manifestInfo = findProjectManifest(process.cwd());
+    const manifestInfo = findProjectManifest(cwd);
     const projectId = options.project ?? env["PROJECT_ID"] ?? manifestInfo.manifest?.projectId ?? null;
     if (!projectId) {
-        throw new Error("No project configured. Run `instafy project:init` in this folder (recommended) or pass --project.");
+        throw new Error("No project configured. Run `instafy project init` in this folder (recommended) or pass --project.");
     }
     env["PROJECT_ID"] = projectId;
     const supabaseAccessToken = resolveSupabaseAccessToken(options, env);
     if (supabaseAccessToken) {
         env["SUPABASE_ACCESS_TOKEN"] = supabaseAccessToken;
     }
-    let controllerAccessToken = resolveControllerAccessTokenForCli(options, env, supabaseAccessToken);
+    const profile = resolveActiveProfileName({ cwd });
+    const controllerAccessTokenResult = resolveControllerAccessTokenForCliWithSource(options, env, supabaseAccessToken, profile, cwd);
+    let controllerAccessToken = controllerAccessTokenResult.token;
+    const controllerAccessTokenSource = controllerAccessTokenResult.source;
     let runtimeAccessToken = normalizeToken(options.runtimeToken) ?? normalizeToken(env["RUNTIME_ACCESS_TOKEN"]);
     const agentKey = options.controllerToken ??
         env["INSTAFY_SERVICE_TOKEN"] ??
@@ -342,6 +355,9 @@ export async function runtimeStart(options) {
             controllerUrl: env["CONTROLLER_BASE_URL"],
             controllerAccessToken,
             projectId,
+            tokenSource: controllerAccessTokenSource,
+            profile,
+            cwd,
         });
     }
     if (runtimeAccessToken) {
@@ -375,6 +391,9 @@ export async function runtimeStart(options) {
             controllerAccessToken,
             projectId,
             runtimeId: env["RUNTIME_ID"],
+            tokenSource: controllerAccessTokenSource,
+            profile,
+            cwd,
         });
     }
     if (!originToken) {
@@ -513,7 +532,14 @@ export async function runtimeStart(options) {
     const started = spawnSync("docker", runArgs, { encoding: "utf8" });
     if (started.status !== 0) {
         const stderr = String(started.stderr ?? "").trim();
-        throw new Error(`docker run failed: ${stderr || "unknown error"}`);
+        const normalized = (stderr || "").toLowerCase();
+        const hints = [];
+        if (image.startsWith("ghcr.io/") && (normalized.includes("not found") || normalized.includes("denied") || normalized.includes("unauthorized") || normalized.includes("manifest unknown"))) {
+            hints.push("If this is a GHCR image, ensure it's published and you are authenticated (`docker login ghcr.io`).");
+        }
+        hints.push("Override the image with `INSTAFY_RUNTIME_AGENT_IMAGE=... instafy runtime start`.");
+        const suffix = hints.length > 0 ? `\n\nNext:\n- ${hints.join("\n- ")}` : "";
+        throw new Error(`docker run failed: ${stderr || "unknown error"}${suffix}`);
     }
     const containerId = String(started.stdout ?? "").trim();
     if (!containerId) {
@@ -753,15 +779,27 @@ export async function runtimeStop(options) {
     }
 }
 export async function runtimeToken(options) {
+    const cwd = process.cwd();
     const controllerUrl = options.controllerUrl ??
         process.env["INSTAFY_SERVER_URL"] ??
         process.env["CONTROLLER_BASE_URL"] ??
         "http://127.0.0.1:8788";
+    const profile = resolveActiveProfileName({ cwd });
+    const stored = resolveConfiguredAccessToken({ profile, cwd });
+    const tokenSource = options.controllerAccessToken
+        ? "explicit"
+        : process.env["INSTAFY_ACCESS_TOKEN"] ||
+            process.env["CONTROLLER_ACCESS_TOKEN"] ||
+            process.env["SUPABASE_ACCESS_TOKEN"]
+            ? "env"
+            : stored
+                ? "config"
+                : "none";
     const token = options.controllerAccessToken ??
         process.env["INSTAFY_ACCESS_TOKEN"] ??
         process.env["CONTROLLER_ACCESS_TOKEN"] ??
         process.env["SUPABASE_ACCESS_TOKEN"] ??
-        resolveConfiguredAccessToken();
+        stored;
     if (!token) {
         throw new Error("Login required. Run `instafy login` or pass --access-token / set SUPABASE_ACCESS_TOKEN.");
     }
@@ -771,6 +809,9 @@ export async function runtimeToken(options) {
         projectId: options.project,
         runtimeId: options.runtimeId,
         scopes: options.scopes,
+        tokenSource: tokenSource === "none" ? "env" : tokenSource,
+        profile,
+        cwd,
     });
     if (options.json) {
         console.log(JSON.stringify({ token: minted }));