@instafy/cli 0.1.3 → 0.1.6

package/README.md

@@ -20,7 +20,7 @@ Run Instafy projects locally and connect them back to Instafy Studio — from an
 - `instafy runtime:status` — show health of the last started runtime.
 - `instafy runtime:stop` — stop the last started runtime.
 - `instafy tunnel` — request a tunnel and forward a local port.
-- `instafy workspace:mount` — mount project files locally (SSHFS).
+- `instafy project:mount` — mount project files locally (SSHFS).
 
 Run `instafy --help` for the full command list and options.
 

package/dist/index.js

@@ -1,4 +1,4 @@
-import { Command } from "commander";
+import { Command, Option } from "commander";
 import { pathToFileURL } from "node:url";
 import { createRequire } from "node:module";
 import kleur from "kleur";
@@ -8,18 +8,34 @@ import { runTunnelCommand } from "./tunnel.js";
 export const program = new Command();
 const require = createRequire(import.meta.url);
 const pkg = require("../package.json");
+function addServerUrlOptions(command) {
+    return command
+        .option("--server-url <url>", "Instafy server URL")
+        .addOption(new Option("--controller-url <url>").hideHelp());
+}
+function addAccessTokenOptions(command, description) {
+    return command
+        .option("--access-token <token>", description)
+        .addOption(new Option("--controller-access-token <token>").hideHelp());
+}
+function addServiceTokenOptions(command, description) {
+    return command
+        .option("--service-token <token>", description)
+        .addOption(new Option("--controller-token <token>").hideHelp());
+}
 program
     .name("instafy")
-    .description("Instafy CLI — manage local/self-hosted runtimes")
+    .description("Instafy CLI — run your project locally and connect to Studio")
     .version(pkg.version ?? "0.1.0");
-program
+const runtimeStartCommand = program
     .command("runtime:start")
-    .description("Start a local Instafy runtime (agent + origin)")
-    .option("--project <id>", "Project UUID")
-    .option("--controller-url <url>", "Controller base URL")
-    .option("--controller-token <token>", "Controller access token")
-    .option("--controller-access-token <token>", "Controller-issued user token used to mint runtime/origin credentials")
-    .option("--supabase-access-token <token>", "Supabase session token used to mint controller/runtime tokens")
+    .description("Start a local runtime for this project")
+    .option("--project <id>", "Project UUID");
+addServerUrlOptions(runtimeStartCommand);
+addServiceTokenOptions(runtimeStartCommand, "Instafy service token (advanced)");
+addAccessTokenOptions(runtimeStartCommand, "Instafy access token (from Studio)");
+runtimeStartCommand
+    .option("--supabase-access-token <token>", "Supabase session token (alternative to Studio token)")
     .option("--supabase-access-token-file <path>", "File containing the Supabase session token")
     .option("--runtime-token <token>", "Pre-minted runtime access token (bypasses agent key)")
     .option("--codex-bin <path>", "Path to codex binary (fallback to PATH)")
@@ -27,19 +43,27 @@ program
     .option("--workspace <path>", "Workspace directory (defaults to ./.instafy/workspace)")
     .option("--origin-id <uuid>", "Origin ID to use (auto-generated if omitted)")
     .option("--origin-endpoint <url>", "Explicit origin endpoint (skip tunnel setup when provided)")
-    .option("--origin-token <token>", "Runtime/origin access token for controller registration")
-    .option("--runtime-id <uuid>", "Runtime ID to use (bypass controller allocation)")
-    .option("--runtime-lease-id <uuid>", "Runtime lease ID to use (bypass controller allocation)")
+    .option("--origin-token <token>", "Runtime/origin access token for Studio registration")
+    .option("--runtime-id <uuid>", "Runtime ID to use (advanced)")
+    .option("--runtime-lease-id <uuid>", "Runtime lease ID to use (advanced)")
     .option("--display-name <name>", "Human-friendly runtime name")
     .option("--provider <provider>", "Runtime provider label (default: self-hosted)")
     .option("--bind-host <host>", "Origin bind host (default 127.0.0.1)")
     .option("--bind-port <port>", "Origin bind port (default 54332)")
-    .option("--mount-controller-fs", "Mount controller workspace via SSHFS using mount-token API")
+    .option("--mount-project-files", "Mount project files from Instafy (SSHFS)")
+    .addOption(new Option("--mount-controller-fs").hideHelp())
     .option("--detach", "Run runtime in background and exit immediately")
     .option("--log-file <path>", "Write runtime stdout/stderr to a file (implied when detached)")
     .action(async (opts) => {
     try {
-        await runtimeStart(opts);
+        await runtimeStart({
+            ...opts,
+            controllerUrl: opts.serverUrl ?? opts.controllerUrl,
+            controllerToken: opts.serviceToken ?? opts.controllerToken,
+            controllerAccessToken: opts.accessToken ?? opts.controllerAccessToken,
+            mountProjectFiles: Boolean(opts.mountProjectFiles),
+            mountControllerFs: Boolean(opts.mountControllerFs),
+        });
     }
     catch (error) {
         console.error(kleur.red(String(error)));
@@ -48,7 +72,7 @@ program
 });
 program
     .command("runtime:status")
-    .description("Show runtime health (codex/proxy/controller/origin)")
+    .description("Show runtime health")
     .option("--json", "Output status as JSON")
     .action(async (opts) => {
     try {
@@ -61,7 +85,7 @@ program
 });
 program
     .command("runtime:sshfs:check")
-    .description("Verify sshfs availability and print platform-specific install hints")
+    .description("Check SSHFS availability (needed for file mounts)")
     .option("--sshfs-bin <path>", "sshfs binary (default: sshfs or SHARED_FS_BIN)")
     .action(async (opts) => {
     try {
@@ -87,12 +111,13 @@ program
         process.exit(1);
     }
 });
-program
+const runtimeTokenCommand = program
     .command("runtime:token")
-    .description("Mint a runtime access token (unified agent/origin scopes)")
-    .requiredOption("--project <id>", "Project UUID")
-    .option("--controller-url <url>", "Controller base URL")
-    .option("--controller-access-token <token>", "Controller access token (required)")
+    .description("Mint a runtime access token")
+    .requiredOption("--project <id>", "Project UUID");
+addServerUrlOptions(runtimeTokenCommand);
+addAccessTokenOptions(runtimeTokenCommand, "Instafy access token (required)");
+runtimeTokenCommand
     .option("--runtime-id <uuid>", "Runtime ID to bind token to")
     .option("--scope <scope...>", "Override scopes (default agent.* + origin.*)")
     .option("--json", "Output token as JSON")
@@ -100,8 +125,8 @@ program
     try {
         await runtimeToken({
             project: opts.project,
-            controllerUrl: opts.controllerUrl,
-            controllerAccessToken: opts.controllerAccessToken,
+            controllerUrl: opts.serverUrl ?? opts.controllerUrl,
+            controllerAccessToken: opts.accessToken ?? opts.controllerAccessToken,
             runtimeId: opts.runtimeId,
             scopes: opts.scope,
             json: opts.json,
@@ -112,12 +137,13 @@ program
         process.exit(1);
     }
 });
-program
+const projectInitCommand = program
     .command("project:init")
-    .description("Create a project via the controller and write .instafy/project.json in the target path")
-    .option("--path <dir>", "Directory where the manifest should be written (default: cwd)")
-    .option("--controller-url <url>", "Controller base URL")
-    .option("--access-token <token>", "Controller or Supabase access token")
+    .description("Create an Instafy project and link this folder (.instafy/project.json)")
+    .option("--path <dir>", "Directory where the manifest should be written (default: cwd)");
+addServerUrlOptions(projectInitCommand);
+projectInitCommand
+    .option("--access-token <token>", "Instafy or Supabase access token")
     .option("--project-type <type>", "Project type (customer|sandbox)")
     .option("--org-id <uuid>", "Optional organization id")
     .option("--org-name <name>", "Optional organization name")
@@ -128,7 +154,7 @@ program
     try {
         await projectInit({
             path: opts.path,
-            controllerUrl: opts.controllerUrl,
+            controllerUrl: opts.serverUrl ?? opts.controllerUrl,
             accessToken: opts.accessToken,
             projectType: opts.projectType,
             orgId: opts.orgId,
@@ -143,12 +169,13 @@ program
         process.exit(1);
     }
 });
-program
+const tunnelCommand = program
     .command("tunnel")
-    .description("Request a tunnel from the controller and forward a local port via rathole")
-    .option("--project <id>", "Project UUID (or set PROJECT_ID)")
-    .option("--controller-url <url>", "Controller base URL (or CONTROLLER_URL)")
-    .option("--controller-token <token>", "Controller access token (service-role/internal)")
+    .description("Create a shareable tunnel URL for a local port")
+    .option("--project <id>", "Project UUID (or set PROJECT_ID)");
+addServerUrlOptions(tunnelCommand);
+addServiceTokenOptions(tunnelCommand, "Instafy service token (advanced)");
+tunnelCommand
     .option("--port <port>", "Local port to expose (default 3000)")
     .option("--rathole-bin <path>", "Path to rathole binary (or set RATHOLE_BIN)")
     .action(async (opts) => {
@@ -156,8 +183,8 @@ program
         const port = opts.port ? Number(opts.port) : undefined;
         await runTunnelCommand({
             project: opts.project,
-            controllerUrl: opts.controllerUrl,
-            controllerToken: opts.controllerToken,
+            controllerUrl: opts.serverUrl ?? opts.controllerUrl,
+            controllerToken: opts.serviceToken ?? opts.controllerToken,
             port,
             ratholeBin: opts.ratholeBin,
         });
@@ -167,16 +194,17 @@ program
         process.exit(1);
     }
 });
-program
+const orgListCommand = program
     .command("org:list")
-    .description("List organizations accessible to the current access token")
-    .option("--controller-url <url>", "Controller base URL")
-    .option("--access-token <token>", "Controller or Supabase access token")
+    .description("List organizations for your account");
+addServerUrlOptions(orgListCommand);
+orgListCommand
+    .option("--access-token <token>", "Instafy or Supabase access token")
     .option("--json", "Output JSON")
     .action(async (opts) => {
     try {
         await (await import("./org.js")).listOrganizations({
-            controllerUrl: opts.controllerUrl,
+            controllerUrl: opts.serverUrl ?? opts.controllerUrl,
             accessToken: opts.accessToken,
             json: opts.json,
         });
@@ -186,18 +214,19 @@ program
         process.exit(1);
     }
 });
-program
+const projectListCommand = program
     .command("project:list")
-    .description("List projects in your organizations")
-    .option("--controller-url <url>", "Controller base URL")
-    .option("--access-token <token>", "Controller or Supabase access token")
+    .description("List projects for your account")
+    .option("--access-token <token>", "Instafy or Supabase access token");
+addServerUrlOptions(projectListCommand);
+projectListCommand
     .option("--org-id <uuid>", "Filter by organization id")
     .option("--org-slug <slug>", "Filter by organization slug")
     .option("--json", "Output JSON")
     .action(async (opts) => {
     try {
         await (await import("./project.js")).listProjects({
-            controllerUrl: opts.controllerUrl,
+            controllerUrl: opts.serverUrl ?? opts.controllerUrl,
             accessToken: opts.accessToken,
             orgId: opts.orgId,
             orgSlug: opts.orgSlug,
@@ -209,38 +238,52 @@ program
         process.exit(1);
     }
 });
-program
-    .command("workspace:mount")
-    .description("Mount the controller-managed workspace locally over SSHFS")
-    .requiredOption("--project <id>", "Project UUID")
-    .requiredOption("--path <dir>", "Local mount directory")
-    .option("--controller-url <url>", "Controller base URL", "http://127.0.0.1:8788")
-    .option("--controller-access-token <token>", "Controller access token (service-role or project member)")
-    .option("--sshfs-bin <path>", "sshfs binary (default: sshfs or SHARED_FS_BIN)")
-    .option("--options <opts>", "Extra sshfs options")
-    .action(async (opts) => {
-    try {
-        const token = opts.controllerAccessToken ??
-            process.env.CONTROLLER_ACCESS_TOKEN ??
-            process.env.CONTROLLER_TOKEN;
-        if (!token) {
-            throw new Error("controller access token is required for workspace:mount");
-        }
-        const mountDir = await mountWorkspace({
-            project: opts.project,
-            controllerUrl: opts.controllerUrl,
-            controllerAccessToken: token,
-            mountPath: opts.path,
-            sshfsBin: opts.sshfsBin,
-            extraOptions: opts.options,
-        });
-        console.log(kleur.green(`Mounted controller workspace to ${mountDir}`));
-    }
-    catch (error) {
-        console.error(kleur.red(String(error)));
-        process.exit(1);
+async function runProjectMount(opts) {
+    const token = opts.accessToken ??
+        opts.controllerAccessToken ??
+        process.env.INSTAFY_ACCESS_TOKEN ??
+        process.env.CONTROLLER_ACCESS_TOKEN ??
+        process.env.CONTROLLER_TOKEN;
+    if (!token) {
+        throw new Error("Access token is required for project:mount.");
     }
-});
+    const serverUrl = opts.serverUrl ??
+        opts.controllerUrl ??
+        process.env.INSTAFY_SERVER_URL ??
+        process.env.CONTROLLER_BASE_URL ??
+        "http://127.0.0.1:8788";
+    const mountDir = await mountWorkspace({
+        project: opts.project,
+        controllerUrl: serverUrl,
+        controllerAccessToken: token,
+        mountPath: opts.path,
+        sshfsBin: opts.sshfsBin,
+        extraOptions: opts.options,
+    });
+    console.log(kleur.green(`Mounted project files to ${mountDir}`));
+}
+function configureProjectMountCommand(command) {
+    addServerUrlOptions(command);
+    addAccessTokenOptions(command, "Instafy access token");
+    command
+        .option("--sshfs-bin <path>", "sshfs binary (default: sshfs or SHARED_FS_BIN)")
+        .option("--options <opts>", "Extra sshfs options")
+        .action(async (opts) => {
+        try {
+            await runProjectMount(opts);
+        }
+        catch (error) {
+            console.error(kleur.red(String(error)));
+            process.exit(1);
+        }
+    });
+}
+const projectMountCommand = program
+    .command("project:mount")
+    .description("Mount project files into a local folder (SSHFS, shared storage)")
+    .requiredOption("--project <id>", "Project UUID")
+    .requiredOption("--path <dir>", "Local mount directory");
+configureProjectMountCommand(projectMountCommand);
 export async function runCli(argv = process.argv) {
     if (argv.length <= 2) {
         program.outputHelp();

package/dist/org.js

@@ -12,12 +12,13 @@ function normalizeToken(raw) {
     return trimmed.length ? trimmed : null;
 }
 export async function listOrganizations(params) {
-    const controllerUrl = normalizeUrl(params.controllerUrl ?? process.env["CONTROLLER_BASE_URL"]);
+    const controllerUrl = normalizeUrl(params.controllerUrl ?? process.env["INSTAFY_SERVER_URL"] ?? process.env["CONTROLLER_BASE_URL"]);
     const token = normalizeToken(params.accessToken) ??
+        normalizeToken(process.env["INSTAFY_ACCESS_TOKEN"]) ??
         normalizeToken(process.env["CONTROLLER_ACCESS_TOKEN"]) ??
         normalizeToken(process.env["SUPABASE_ACCESS_TOKEN"]);
     if (!token) {
-        throw new Error("Controller access token is required (--access-token, CONTROLLER_ACCESS_TOKEN, or SUPABASE_ACCESS_TOKEN).");
+        throw new Error("Instafy or Supabase access token is required (--access-token, INSTAFY_ACCESS_TOKEN, or SUPABASE_ACCESS_TOKEN).");
     }
     const response = await fetch(`${controllerUrl}/orgs`, {
         headers: { authorization: `Bearer ${token}` },

package/dist/project.js

@@ -73,12 +73,13 @@ async function resolveOrg(controllerUrl, token, options) {
     return { orgId, orgName: json.org_name ?? null };
 }
 export async function listProjects(options) {
-    const controllerUrl = normalizeUrl(options.controllerUrl ?? process.env["CONTROLLER_BASE_URL"]);
+    const controllerUrl = normalizeUrl(options.controllerUrl ?? process.env["INSTAFY_SERVER_URL"] ?? process.env["CONTROLLER_BASE_URL"]);
     const token = normalizeToken(options.accessToken) ??
+        normalizeToken(process.env["INSTAFY_ACCESS_TOKEN"]) ??
         normalizeToken(process.env["CONTROLLER_ACCESS_TOKEN"]) ??
         normalizeToken(process.env["SUPABASE_ACCESS_TOKEN"]);
     if (!token) {
-        throw new Error("Controller or Supabase access token is required (--access-token, CONTROLLER_ACCESS_TOKEN, or SUPABASE_ACCESS_TOKEN).");
+        throw new Error("Instafy or Supabase access token is required (--access-token, INSTAFY_ACCESS_TOKEN, or SUPABASE_ACCESS_TOKEN).");
     }
     const orgs = await fetchOrganizations(controllerUrl, token);
     let targetOrgs = orgs;
@@ -123,12 +124,13 @@ export async function listProjects(options) {
 }
 export async function projectInit(options) {
     const rootDir = path.resolve(options.path ?? process.cwd());
-    const controllerUrl = normalizeUrl(options.controllerUrl ?? process.env["CONTROLLER_BASE_URL"]);
+    const controllerUrl = normalizeUrl(options.controllerUrl ?? process.env["INSTAFY_SERVER_URL"] ?? process.env["CONTROLLER_BASE_URL"]);
     const token = normalizeToken(options.accessToken) ??
+        normalizeToken(process.env["INSTAFY_ACCESS_TOKEN"]) ??
         normalizeToken(process.env["CONTROLLER_ACCESS_TOKEN"]) ??
         normalizeToken(process.env["SUPABASE_ACCESS_TOKEN"]);
     if (!token) {
-        throw new Error("Controller or Supabase access token is required (--access-token, CONTROLLER_ACCESS_TOKEN, or SUPABASE_ACCESS_TOKEN).");
+        throw new Error("Instafy or Supabase access token is required (--access-token, INSTAFY_ACCESS_TOKEN, or SUPABASE_ACCESS_TOKEN).");
     }
     const org = await resolveOrg(controllerUrl, token, options);
     const body = {

package/dist/runtime.js

@@ -324,12 +324,12 @@ export async function mintRuntimeAccessToken(params) {
     });
     if (!response.ok) {
         const text = await response.text().catch(() => "");
-        throw new Error(`Controller rejected runtime token request (${response.status} ${response.statusText}): ${text}`);
+        throw new Error(`Instafy server rejected runtime token request (${response.status} ${response.statusText}): ${text}`);
     }
     const payload = (await response.json());
     const token = typeof payload.token === "string" ? payload.token.trim() : "";
     if (!token) {
-        throw new Error("Controller response missing token field while minting runtime token.");
+        throw new Error("Instafy server response missing token field while minting runtime token.");
     }
     return token;
 }
@@ -360,12 +360,16 @@ export async function runtimeStart(options) {
         env["SUPABASE_ACCESS_TOKEN"] = supabaseAccessToken;
     }
     let controllerAccessToken = normalizeToken(options.controllerAccessToken) ??
+        normalizeToken(env["INSTAFY_ACCESS_TOKEN"]) ??
         normalizeToken(env["CONTROLLER_ACCESS_TOKEN"]) ??
         supabaseAccessToken;
     let runtimeAccessToken = normalizeToken(options.runtimeToken) ?? normalizeToken(env["RUNTIME_ACCESS_TOKEN"]);
-    const agentKey = options.controllerToken ?? env["AGENT_LOGIN_KEY"] ?? env["AGENT_KEY"];
+    const agentKey = options.controllerToken ??
+        env["INSTAFY_SERVICE_TOKEN"] ??
+        env["AGENT_LOGIN_KEY"] ??
+        env["AGENT_KEY"];
     if (!agentKey && !controllerAccessToken && !runtimeAccessToken) {
-        throw new Error("Provide either --runtime-token/RUNTIME_ACCESS_TOKEN, --controller-access-token/CONTROLLER_ACCESS_TOKEN, --supabase-access-token/SUPABASE_ACCESS_TOKEN, or --controller-token/AGENT_LOGIN_KEY (legacy)");
+        throw new Error("Provide either --runtime-token/RUNTIME_ACCESS_TOKEN, --access-token/INSTAFY_ACCESS_TOKEN, --supabase-access-token/SUPABASE_ACCESS_TOKEN, or --service-token/INSTAFY_SERVICE_TOKEN (advanced).");
     }
     if (agentKey) {
         env["AGENT_LOGIN_KEY"] = agentKey;
@@ -374,7 +378,10 @@ export async function runtimeStart(options) {
         env["CONTROLLER_ACCESS_TOKEN"] = controllerAccessToken;
     }
     env["CONTROLLER_BASE_URL"] =
-        options.controllerUrl ?? env["CONTROLLER_BASE_URL"] ?? "http://127.0.0.1:8788";
+        options.controllerUrl ??
+            env["INSTAFY_SERVER_URL"] ??
+            env["CONTROLLER_BASE_URL"] ??
+            "http://127.0.0.1:8788";
     if (!runtimeAccessToken && controllerAccessToken) {
         runtimeAccessToken = await mintRuntimeAccessToken({
             controllerUrl: env["CONTROLLER_BASE_URL"],
@@ -386,7 +393,8 @@ export async function runtimeStart(options) {
         env["RUNTIME_ACCESS_TOKEN"] = runtimeAccessToken;
     }
     // Auto-fetch workspace mount token if requested
-    if (options.mountControllerFs && controllerAccessToken && env["CONTROLLER_BASE_URL"]) {
+    const shouldMountProjectFiles = Boolean(options.mountProjectFiles || options.mountControllerFs);
+    if (shouldMountProjectFiles && controllerAccessToken && env["CONTROLLER_BASE_URL"]) {
         const token = await fetchWorkspaceMountToken({
             controllerUrl: env["CONTROLLER_BASE_URL"],
             controllerAccessToken,
@@ -616,7 +624,7 @@ export async function runtimeStatus(options) {
     printStatus("Project:", state.projectId);
     printStatus("Workspace:", state.workspace);
     if (state.controllerUrl)
-        printStatus("Controller:", state.controllerUrl);
+        printStatus("Server:", state.controllerUrl);
     if (state.originId)
         printStatus("Origin:", state.originId);
     if (state.runtimeId)
@@ -685,12 +693,16 @@ export async function runtimeStop(options) {
     }
 }
 export async function runtimeToken(options) {
-    const controllerUrl = options.controllerUrl ?? process.env["CONTROLLER_BASE_URL"] ?? "http://127.0.0.1:8788";
+    const controllerUrl = options.controllerUrl ??
+        process.env["INSTAFY_SERVER_URL"] ??
+        process.env["CONTROLLER_BASE_URL"] ??
+        "http://127.0.0.1:8788";
     const token = options.controllerAccessToken ??
+        process.env["INSTAFY_ACCESS_TOKEN"] ??
         process.env["CONTROLLER_ACCESS_TOKEN"] ??
         process.env["SUPABASE_ACCESS_TOKEN"];
     if (!token) {
-        throw new Error("Controller access token is required (--controller-access-token or CONTROLLER_ACCESS_TOKEN)");
+        throw new Error("Access token is required (--access-token, INSTAFY_ACCESS_TOKEN, or SUPABASE_ACCESS_TOKEN).");
     }
     const minted = await mintRuntimeAccessToken({
         controllerUrl,

package/dist/tunnel.js

@@ -23,18 +23,21 @@ function resolveProject(opts) {
 }
 function resolveControllerUrl(opts) {
     return (opts.controllerUrl?.trim() ||
+        readEnv("INSTAFY_SERVER_URL") ||
+        readEnv("INSTAFY_URL") ||
         readEnv("CONTROLLER_URL") ||
         readEnv("CONTROLLER_BASE_URL") ||
-        "http://localhost:8788");
+        "http://127.0.0.1:8788");
 }
 function resolveControllerToken(opts) {
     return (opts.controllerToken?.trim() ||
+        readEnv("INSTAFY_SERVICE_TOKEN") ||
         readEnv("CONTROLLER_BEARER") ||
         readEnv("SERVICE_ROLE_KEY") ||
         readEnv("SUPABASE_SERVICE_ROLE_KEY") ||
         readEnv("CONTROLLER_INTERNAL_TOKEN") ||
         (() => {
-            throw new Error("Controller token is required (--controller-token or SERVICE_ROLE_KEY)");
+            throw new Error("Service token is required (--service-token, INSTAFY_SERVICE_TOKEN, or SERVICE_ROLE_KEY).");
         })());
 }
 function resolvePort(opts) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@instafy/cli",
-  "version": "0.1.3",
+  "version": "0.1.6",
   "description": "Run Instafy projects locally, link folders to Studio, and share previews/webhooks via tunnels.",
   "private": false,
   "publishConfig": {