@instafy/cli 0.1.8-staging.365 → 0.1.8-staging.368

package/README.md

@@ -9,26 +9,27 @@ Run Instafy projects locally and connect them back to Instafy Studio — from an
 0. Log in once: `instafy login`
    - Opens a Studio URL; the CLI continues automatically after you sign in.
    - Also enables Git auth (credential helper) for Instafy Git Service. Disable with `instafy login --no-git-setup`.
-   - Multiple accounts: `instafy login --profile work` (then bind folders with `instafy project:init --profile work` or `instafy project:profile work`).
+   - Multiple accounts: `instafy login --profile work` (then bind folders with `instafy project init --profile work` or `instafy project profile work`).
    - Optional: set defaults with `instafy config set controller-url <url>` / `instafy config set studio-url <url>`
 1. Link a folder to a project:
    - VS Code: install the Instafy extension and run `Instafy: Link Workspace to Project`, or
-   - Terminal: `instafy project:init`
-2. Start the runtime: `instafy runtime:start`
+   - Terminal: `instafy project init`
+2. Start the runtime: `instafy runtime start`
 3. Check status / stop:
-   - `instafy runtime:status`
-   - `instafy runtime:stop`
+   - `instafy runtime status`
+   - `instafy runtime stop`
 
 ## Common commands
 
-- `instafy runtime:start` — start a local runtime (agent + origin).
-- `instafy runtime:status` — show health of the last started runtime.
-- `instafy runtime:stop` — stop the last started runtime.
-- `instafy tunnel` — start a detached tunnel for a local port.
-  - `instafy tunnel:list` — list local tunnels started by the CLI.
-  - `instafy tunnel:logs <tunnelId> --follow` — tail tunnel logs.
-  - `instafy tunnel:stop <tunnelId>` — stop + revoke a tunnel.
-- `instafy api:get` — query controller endpoints (conversations, messages, runs, etc).
+ - `instafy runtime start` — start a local runtime (agent + origin).
+- `instafy runtime status` — show health of the last started runtime.
+ - `instafy runtime stop` — stop the last started runtime.
+- `instafy git <args...>` — run git commands against an Instafy canonical checkout (`.instafy/.git`) when present.
+- `instafy tunnel start` — start a detached tunnel for a local port.
+  - `instafy tunnel list` — list local tunnels started by the CLI.
+  - `instafy tunnel logs <tunnelId> --follow` — tail tunnel logs.
+  - `instafy tunnel stop <tunnelId>` — stop + revoke a tunnel.
+- `instafy api get` — query controller endpoints (conversations, messages, runs, etc).
 
 Run `instafy --help` for the full command list and options.
 

package/dist/auth.js

@@ -390,8 +390,8 @@ export async function login(options) {
     }
     console.log("");
     console.log("Next:");
-    console.log(`- ${kleur.cyan("instafy project:init")}`);
-    console.log(`- ${kleur.cyan("instafy runtime:start")}`);
+    console.log(`- ${kleur.cyan("instafy project init")}`);
+    console.log(`- ${kleur.cyan("instafy runtime start")}`);
 }
 export async function logout(options) {
     if (options?.profile) {

package/dist/git-setup.js

@@ -1,7 +1,7 @@
 import { spawnSync } from "node:child_process";
-const INSTAFY_GIT_HELPER_VALUE = "!instafy git:credential";
+const INSTAFY_GIT_HELPER_VALUE = "!instafy git credential";
 function isLikelySameHelper(value) {
-    return value.includes("instafy git:credential");
+    return value.includes("instafy git credential");
 }
 function runGit(args) {
     const result = spawnSync("git", args, { encoding: "utf8" });

package/dist/git-wrapper.js

@@ -0,0 +1,497 @@
+import { spawnSync } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import kleur from "kleur";
+function pathExists(candidate) {
+    try {
+        fs.statSync(candidate);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function findInstafyGitContext(startDir) {
+    let current = path.resolve(startDir);
+    const root = path.parse(current).root;
+    while (true) {
+        const gitDir = path.join(current, ".instafy", ".git");
+        if (pathExists(gitDir)) {
+            return { workTree: current, gitDir };
+        }
+        if (current === root)
+            break;
+        current = path.dirname(current);
+    }
+    return null;
+}
+function splitGitCommand(userArgs) {
+    const globalArgs = [];
+    let index = 0;
+    while (index < userArgs.length) {
+        const arg = userArgs[index] ?? "";
+        if (arg === "--") {
+            index += 1;
+            break;
+        }
+        if (!arg.startsWith("-") || arg === "-") {
+            break;
+        }
+        globalArgs.push(arg);
+        // Skip values for global options that consume the next token.
+        if (arg === "-c" || arg === "--config-env" || arg === "--exec-path" || arg === "--namespace") {
+            if (index + 1 < userArgs.length) {
+                globalArgs.push(userArgs[index + 1] ?? "");
+                index += 2;
+                continue;
+            }
+        }
+        index += 1;
+    }
+    const command = index < userArgs.length ? (userArgs[index] ?? null) : null;
+    const commandArgs = command ? userArgs.slice(index + 1) : [];
+    return { globalArgs, command, commandArgs };
+}
+function validateGitArgs(userArgs) {
+    let parsingGlobalOptions = true;
+    for (let index = 0; index < userArgs.length; index += 1) {
+        const arg = userArgs[index] ?? "";
+        if (!parsingGlobalOptions) {
+            continue;
+        }
+        if (arg === "--") {
+            parsingGlobalOptions = false;
+            continue;
+        }
+        if (!arg.startsWith("-") || arg === "-") {
+            parsingGlobalOptions = false;
+            continue;
+        }
+        if (arg === "--git-dir" || arg.startsWith("--git-dir=") || arg === "--work-tree" || arg.startsWith("--work-tree=") || arg === "-C") {
+            throw new Error(`Unsupported argument "${arg}". Use ${kleur.cyan("cd")} instead; ${kleur.cyan("instafy git")} manages --git-dir/--work-tree automatically.`);
+        }
+        // Skip the value for global options that consume the next token.
+        if (arg === "-c" || arg === "--config-env" || arg === "--exec-path" || arg === "--namespace") {
+            index += 1;
+        }
+    }
+}
+export function buildInstafyGitArgs(context, userArgs) {
+    validateGitArgs(userArgs);
+    return ["--git-dir", context.gitDir, "--work-tree", context.workTree, ...userArgs];
+}
+function normalizePathSpec(raw) {
+    return (raw ?? "").replace(/\\/g, "/").trim().replace(/^\/+/, "");
+}
+function isReservedSyncPath(pathSpec) {
+    const normalized = normalizePathSpec(pathSpec);
+    if (!normalized) {
+        return false;
+    }
+    if (normalized === ".instafy" || normalized.startsWith(".instafy/")) {
+        return true;
+    }
+    if (normalized === ".instafy/origin-staging" || normalized.startsWith(".instafy/origin-staging/")) {
+        return true;
+    }
+    return normalized.split("/").some((segment) => segment === ".git" || segment.startsWith(".git.instafy-hidden-"));
+}
+function gitCapture(context, args, options) {
+    const result = spawnSync("git", ["--git-dir", context.gitDir, "--work-tree", context.workTree, ...args], {
+        cwd: options.cwd,
+        encoding: "utf8",
+        env: { ...process.env, GIT_TERMINAL_PROMPT: "0" },
+    });
+    return {
+        status: typeof result.status === "number" ? result.status : 1,
+        stdout: typeof result.stdout === "string" ? result.stdout : "",
+        stderr: typeof result.stderr === "string" ? result.stderr : "",
+        error: result.error,
+    };
+}
+function collectDirtyPaths(context, options) {
+    const result = gitCapture(context, ["status", "--porcelain=v1"], options);
+    if (result.error) {
+        throw new Error(`Failed to run git status: ${result.error.message}`);
+    }
+    if (result.status !== 0) {
+        throw new Error(`git status failed (${result.status}): ${result.stderr.trim()}`);
+    }
+    const paths = [];
+    for (const line of result.stdout.split(/\r?\n/)) {
+        if (!line.trim())
+            continue;
+        if (line.length < 4)
+            continue;
+        const raw = line.slice(3).trim();
+        if (!raw)
+            continue;
+        const rename = raw.split(" -> ");
+        if (rename.length === 2) {
+            for (const entry of rename) {
+                const normalized = normalizePathSpec(entry).replace(/\/+$/, "");
+                if (normalized)
+                    paths.push(normalized);
+            }
+            continue;
+        }
+        const normalized = normalizePathSpec(raw).replace(/\/+$/, "");
+        if (normalized)
+            paths.push(normalized);
+    }
+    paths.sort((a, b) => a.localeCompare(b));
+    const unique = [];
+    for (const value of paths) {
+        if (unique.length === 0 || unique[unique.length - 1] !== value) {
+            unique.push(value);
+        }
+    }
+    return unique;
+}
+function findEmbeddedGitDirs(context, pathSpecs) {
+    const instafyGitDir = path.resolve(context.gitDir);
+    const seen = new Set();
+    for (const rawPath of pathSpecs) {
+        const normalized = normalizePathSpec(rawPath).replace(/\/+$/, "");
+        if (!normalized || normalized === "." || normalized === "/") {
+            continue;
+        }
+        let cursor = normalized;
+        while (cursor && cursor !== ".") {
+            const candidate = path.join(context.workTree, ...cursor.split("/"), ".git");
+            if (pathExists(candidate) && path.resolve(candidate) !== instafyGitDir) {
+                seen.add(path.resolve(candidate));
+            }
+            const next = path.posix.dirname(cursor);
+            if (next === "." || next === cursor) {
+                break;
+            }
+            cursor = next;
+        }
+    }
+    const candidates = Array.from(seen);
+    candidates.sort((a, b) => {
+        const depthA = a.split(path.sep).length;
+        const depthB = b.split(path.sep).length;
+        return depthB - depthA;
+    });
+    return candidates;
+}
+function hideEmbeddedGitDirs(context, pathSpecs) {
+    const candidates = findEmbeddedGitDirs(context, pathSpecs);
+    if (candidates.length === 0) {
+        return [];
+    }
+    const stagingBase = path.join(context.workTree, ".instafy", "origin-staging", "embedded-git");
+    fs.mkdirSync(stagingBase, { recursive: true });
+    const renames = [];
+    for (const candidate of candidates) {
+        let hidden = path.join(stagingBase, randomUUID());
+        for (let attempt = 0; attempt < 8; attempt += 1) {
+            if (!pathExists(hidden))
+                break;
+            hidden = path.join(stagingBase, randomUUID());
+        }
+        fs.renameSync(candidate, hidden);
+        renames.push({ original: candidate, hidden });
+    }
+    return renames;
+}
+function restoreEmbeddedGitDirs(renames) {
+    for (let index = renames.length - 1; index >= 0; index -= 1) {
+        const rename = renames[index];
+        if (!rename)
+            continue;
+        try {
+            fs.renameSync(rename.hidden, rename.original);
+        }
+        catch {
+            // ignore restore failures; leave evidence in .instafy/origin-staging for debugging
+        }
+    }
+}
+function parseAddArgs(commandArgs) {
+    const addOptions = [];
+    const pathSpecs = [];
+    let inPaths = false;
+    for (const arg of commandArgs) {
+        if (inPaths) {
+            pathSpecs.push(arg);
+            continue;
+        }
+        if (arg === "--") {
+            inPaths = true;
+            continue;
+        }
+        if (arg.startsWith("-") && arg !== "-") {
+            addOptions.push(arg);
+            continue;
+        }
+        inPaths = true;
+        pathSpecs.push(arg);
+    }
+    return { addOptions, pathSpecs };
+}
+function runInstafyGitAdd(context, globalArgs, commandArgs, options) {
+    const parsed = parseAddArgs(commandArgs);
+    const normalizedPathSpecs = parsed.pathSpecs
+        .map((spec) => normalizePathSpec(spec))
+        .filter((spec) => spec && spec !== "." && spec !== "/");
+    const stageAll = normalizedPathSpecs.length === 0;
+    const stagePaths = stageAll
+        ? collectDirtyPaths(context, options).filter((entry) => !isReservedSyncPath(entry))
+        : normalizedPathSpecs.filter((entry) => !isReservedSyncPath(entry));
+    if (stagePaths.length === 0) {
+        return 0;
+    }
+    const addOptions = [...parsed.addOptions];
+    if (stageAll && !addOptions.some((opt) => opt === "-A" || opt === "--all")) {
+        addOptions.unshift("-A");
+    }
+    const renames = hideEmbeddedGitDirs(context, stagePaths);
+    try {
+        const result = spawnSync("git", [
+            "--git-dir",
+            context.gitDir,
+            "--work-tree",
+            context.workTree,
+            ...globalArgs,
+            "add",
+            ...addOptions,
+            "--",
+            ...stagePaths,
+        ], { stdio: "inherit", cwd: options.cwd, env: { ...process.env, GIT_TERMINAL_PROMPT: "0" } });
+        if (result.error) {
+            throw new Error(`Failed to run git add: ${result.error.message}`);
+        }
+        return typeof result.status === "number" ? result.status : 1;
+    }
+    finally {
+        restoreEmbeddedGitDirs(renames);
+    }
+}
+export function runInstafyGit(userArgs, options) {
+    const cwd = options?.cwd ?? process.cwd();
+    if (userArgs.length === 0 || userArgs[0] === "--help" || userArgs[0] === "-h") {
+        // Keep this minimal so it doesn't diverge from Git help output.
+        console.log("instafy git <git-args...>");
+        console.log("");
+        console.log(`Runs ${kleur.cyan("git")} against the Instafy canonical repo at ${kleur.cyan(".instafy/.git")} (auto-detected by walking up from cwd).`);
+        console.log("");
+        console.log("Example:");
+        console.log(`  ${kleur.cyan('instafy git status')}`);
+        console.log(`  ${kleur.cyan('instafy git add -A')}`);
+        console.log(`  ${kleur.cyan('instafy git commit -am "instafy: checkpoint"')}`);
+        return 0;
+    }
+    const context = findInstafyGitContext(cwd);
+    if (!context) {
+        throw new Error([
+            "No Instafy canonical git checkout found (expected .instafy/.git).",
+            "",
+            "Tips:",
+            `- Run this inside a git-canonical workspace (where ${kleur.cyan(".instafy/.git")} exists).`,
+            `- If you're trying to operate on a user repo, use normal ${kleur.cyan("git")} (it uses .git).`,
+        ].join("\n"));
+    }
+    validateGitArgs(userArgs);
+    const split = splitGitCommand(userArgs);
+    if (split.command === "add") {
+        return runInstafyGitAdd(context, split.globalArgs, split.commandArgs, { cwd });
+    }
+    const args = buildInstafyGitArgs(context, userArgs);
+    const result = spawnSync("git", args, { stdio: "inherit", cwd });
+    if (result.error) {
+        throw new Error(`Failed to run git: ${result.error.message}`);
+    }
+    return typeof result.status === "number" ? result.status : 1;
+}
+function printGitSyncHelp() {
+    console.log("instafy git sync [options]");
+    console.log("");
+    console.log("Calls the Origin git sync endpoint (POST /git/sync) for the current runtime/workspace.");
+    console.log("");
+    console.log("Options:");
+    console.log("  -m, --message <msg>       Commit message (recommended)");
+    console.log("  --path <relativePath>     Only sync selected path(s) (repeatable)");
+    console.log("  --origin-endpoint <url>   Override Origin base URL (default: $ORIGIN_ENDPOINT or localhost)");
+    console.log("  --origin-token <token>    Override Origin bearer token (default: $ORIGIN_INTERNAL_TOKEN)");
+    console.log("  --json                    Output JSON");
+    console.log("");
+    console.log("Env fallback:");
+    console.log("  ORIGIN_ENDPOINT, ORIGIN_BIND_PORT, ORIGIN_INTERNAL_TOKEN, RUNTIME_ACCESS_TOKEN");
+}
+function normalizeToken(raw) {
+    if (typeof raw !== "string")
+        return null;
+    const trimmed = raw.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+function normalizeUrl(raw) {
+    return raw.trim().replace(/\/+$/, "");
+}
+function resolveOriginEndpoint(override) {
+    const direct = normalizeToken(override) ?? normalizeToken(process.env["ORIGIN_ENDPOINT"]);
+    if (direct) {
+        return normalizeUrl(direct);
+    }
+    const portRaw = normalizeToken(process.env["ORIGIN_BIND_PORT"]);
+    const port = portRaw ? Number.parseInt(portRaw, 10) : 54332;
+    const resolvedPort = Number.isFinite(port) && port > 0 ? port : 54332;
+    return `http://127.0.0.1:${resolvedPort}`;
+}
+function resolveOriginToken(override) {
+    const token = normalizeToken(override) ??
+        normalizeToken(process.env["ORIGIN_INTERNAL_TOKEN"]) ??
+        normalizeToken(process.env["RUNTIME_ACCESS_TOKEN"]);
+    if (!token) {
+        throw new Error([
+            "Origin bearer token missing.",
+            "",
+            "Provide one of:",
+            "- --origin-token <token>",
+            "- ORIGIN_INTERNAL_TOKEN=<token> (recommended inside runtimes)",
+            "- RUNTIME_ACCESS_TOKEN=<token>",
+        ].join("\n"));
+    }
+    return token;
+}
+function parseGitSyncArgs(args) {
+    let message = null;
+    let json = false;
+    let originEndpointOverride = null;
+    let originTokenOverride = null;
+    const paths = [];
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index] ?? "";
+        if (arg === "--help" || arg === "-h") {
+            return "help";
+        }
+        if (arg === "--json") {
+            json = true;
+            continue;
+        }
+        if (arg === "-m" || arg === "--message") {
+            const value = args[index + 1];
+            if (typeof value !== "string" || value.trim().length === 0) {
+                throw new Error(`${arg} requires a non-empty value`);
+            }
+            message = value.trim();
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith("--message=")) {
+            const value = arg.slice("--message=".length).trim();
+            if (!value) {
+                throw new Error("--message requires a non-empty value");
+            }
+            message = value;
+            continue;
+        }
+        if (arg === "--origin-endpoint") {
+            const value = args[index + 1];
+            if (typeof value !== "string" || value.trim().length === 0) {
+                throw new Error("--origin-endpoint requires a URL");
+            }
+            originEndpointOverride = value.trim();
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith("--origin-endpoint=")) {
+            const value = arg.slice("--origin-endpoint=".length).trim();
+            if (!value) {
+                throw new Error("--origin-endpoint requires a URL");
+            }
+            originEndpointOverride = value;
+            continue;
+        }
+        if (arg === "--origin-token") {
+            const value = args[index + 1];
+            if (typeof value !== "string" || value.trim().length === 0) {
+                throw new Error("--origin-token requires a token");
+            }
+            originTokenOverride = value.trim();
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith("--origin-token=")) {
+            const value = arg.slice("--origin-token=".length).trim();
+            if (!value) {
+                throw new Error("--origin-token requires a token");
+            }
+            originTokenOverride = value;
+            continue;
+        }
+        if (arg === "--path") {
+            const value = args[index + 1];
+            if (typeof value !== "string" || value.trim().length === 0) {
+                throw new Error("--path requires a relative path");
+            }
+            paths.push(value.trim());
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith("--path=")) {
+            const value = arg.slice("--path=".length).trim();
+            if (!value) {
+                throw new Error("--path requires a relative path");
+            }
+            paths.push(value);
+            continue;
+        }
+        throw new Error(`Unknown argument: ${arg}`);
+    }
+    const originEndpoint = resolveOriginEndpoint(originEndpointOverride);
+    const originToken = resolveOriginToken(originTokenOverride);
+    const resolvedMessage = message ?? `instafy: sync ${new Date().toISOString().replace(/\..*$/, "")}Z`;
+    return {
+        message: resolvedMessage,
+        json,
+        originEndpoint,
+        originToken,
+        paths: paths.length > 0 ? paths : null,
+    };
+}
+export async function runInstafyGitSync(args, options) {
+    void options;
+    const parsed = parseGitSyncArgs(args);
+    if (parsed === "help") {
+        printGitSyncHelp();
+        return 0;
+    }
+    const url = `${parsed.originEndpoint.replace(/\/+$/, "")}/git/sync`;
+    const response = await fetch(url, {
+        method: "POST",
+        headers: {
+            accept: "application/json",
+            authorization: `Bearer ${parsed.originToken}`,
+            "content-type": "application/json",
+        },
+        body: JSON.stringify({
+            message: parsed.message,
+            paths: parsed.paths ?? undefined,
+        }),
+    }).catch((error) => {
+        throw new Error(`Origin git sync request failed: ${String(error)}`);
+    });
+    const text = await response.text().catch(() => "");
+    if (!response.ok) {
+        const suffix = text.trim() ? `: ${text.trim()}` : "";
+        console.error(kleur.red(`Origin git sync failed (${response.status} ${response.statusText})${suffix}`));
+        return 1;
+    }
+    const payload = text.trim() ? JSON.parse(text) : null;
+    const rev = typeof payload?.rev === "string" ? payload.rev.trim() : "";
+    if (!rev) {
+        console.error(kleur.red("Origin git sync response missing rev field."));
+        return 1;
+    }
+    if (parsed.json) {
+        console.log(JSON.stringify({ rev }, null, 2));
+    }
+    else {
+        console.log(rev);
+    }
+    return 0;
+}

package/dist/index.js

@@ -4,13 +4,13 @@ import { createRequire } from "node:module";
 import kleur from "kleur";
 import { runtimeStart, runtimeStatus, runtimeStop, runtimeToken, findProjectManifest, } from "./runtime.js";
 import { login, logout } from "./auth.js";
-import { gitToken } from "./git.js";
 import { runGitCredentialHelper } from "./git-credential.js";
 import { projectInit, projectProfile } from "./project.js";
 import { listTunnelSessions, startTunnelDetached, stopTunnelSession, tailTunnelLogs, runTunnelCommand } from "./tunnel.js";
 import { requestControllerApi } from "./api.js";
 import { configGet, configList, configPath, configSet, configUnset } from "./config-command.js";
 import { getInstafyProfileConfigPath, listInstafyProfileNames, readInstafyProfileConfig } from "./config.js";
+import { runInstafyGit, runInstafyGitSync } from "./git-wrapper.js";
 export const program = new Command();
 const require = createRequire(import.meta.url);
 const pkg = require("../package.json");
@@ -77,8 +77,12 @@ program
         process.exit(1);
     }
 });
-const projectInitCommand = program
-    .command("project:init")
+const projectCommand = program
+    .command("project")
+    .description("Create/link and manage Instafy projects");
+projectCommand.action(() => projectCommand.outputHelp());
+const projectInitCommand = projectCommand
+    .command("init")
     .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);
@@ -111,8 +115,8 @@ projectInitCommand
         process.exit(1);
     }
 });
-program
-    .command("project:profile")
+projectCommand
+    .command("profile")
     .description("Get/set the CLI profile for this folder (.instafy/project.json)")
     .argument("[profile]", "Profile name to set (omit to print current)")
     .option("--unset", "Clear the configured profile for this folder")
@@ -132,38 +136,24 @@ program
         process.exit(1);
     }
 });
-program
-    .command("profile:list")
-    .description("List saved CLI profiles (~/.instafy/profiles)")
+const projectListCommand = projectCommand
+    .command("list")
+    .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 {
-        const names = listInstafyProfileNames();
-        const profiles = names.map((name) => {
-            const config = readInstafyProfileConfig(name);
-            return {
-                name,
-                path: getInstafyProfileConfigPath(name),
-                controllerUrl: config.controllerUrl ?? null,
-                studioUrl: config.studioUrl ?? null,
-                accessTokenSet: Boolean(config.accessToken),
-                updatedAt: config.updatedAt ?? null,
-            };
+        await (await import("./project.js")).listProjects({
+            controllerUrl: opts.serverUrl ?? opts.controllerUrl,
+            accessToken: opts.accessToken,
+            orgId: opts.orgId,
+            orgSlug: opts.orgSlug,
+            json: opts.json,
         });
-        if (opts.json) {
-            console.log(JSON.stringify({ profiles }, null, 2));
-            return;
-        }
-        if (profiles.length === 0) {
-            console.log(kleur.yellow("No profiles found."));
-            console.log(`Create one with: ${kleur.cyan("instafy login --profile <name>")}`);
-            return;
-        }
-        console.log(kleur.green("Instafy CLI profiles"));
-        for (const profile of profiles) {
-            const token = profile.accessTokenSet ? kleur.green("token") : kleur.yellow("no-token");
-            console.log(`- ${kleur.cyan(profile.name)} (${token})`);
-        }
     }
     catch (error) {
         console.error(kleur.red(String(error)));
@@ -171,6 +161,7 @@ program
     }
 });
 const configCommand = program.command("config").description("Get/set saved CLI configuration");
+configCommand.action(() => configCommand.outputHelp());
 configCommand
     .command("path")
     .description("Print the config file path")
@@ -240,8 +231,12 @@ configCommand
         process.exit(1);
     }
 });
-const runtimeStartCommand = program
-    .command("runtime:start")
+const runtimeCommand = program
+    .command("runtime")
+    .description("Start/stop the local Instafy runtime");
+runtimeCommand.action(() => runtimeCommand.outputHelp());
+const runtimeStartCommand = runtimeCommand
+    .command("start")
     .description("Start a local runtime for this project")
     .option("--project <id>", "Project UUID");
 addServerUrlOptions(runtimeStartCommand);
@@ -280,8 +275,8 @@ runtimeStartCommand
         process.exit(1);
     }
 });
-program
-    .command("runtime:status")
+runtimeCommand
+    .command("status")
     .description("Show runtime health")
     .option("--json", "Output status as JSON")
     .action(async (opts) => {
@@ -293,8 +288,8 @@ program
         process.exit(1);
     }
 });
-program
-    .command("runtime:stop")
+runtimeCommand
+    .command("stop")
     .description("Stop the local Instafy runtime")
     .option("--json", "Output result as JSON")
     .action(async (opts) => {
@@ -306,8 +301,8 @@ program
         process.exit(1);
     }
 });
-const runtimeTokenCommand = program
-    .command("runtime:token")
+const runtimeTokenCommand = runtimeCommand
+    .command("token")
     .description("Mint a runtime access token")
     .option("--project <id>", "Project UUID (defaults to .instafy/project.json)");
 addServerUrlOptions(runtimeTokenCommand);
@@ -322,7 +317,7 @@ runtimeTokenCommand
             ? opts.project.trim()
             : findProjectManifest(process.cwd()).manifest?.projectId ?? null;
         if (!project) {
-            throw new Error("No project configured. Run `instafy project:init` or pass --project.");
+            throw new Error("No project configured. Run `instafy project init` or pass --project.");
         }
         await runtimeToken({
             project,
@@ -338,69 +333,23 @@ runtimeTokenCommand
         process.exit(1);
     }
 });
-const gitTokenCommand = program
-    .command("git:token", { hidden: true })
-    .description("Advanced: mint a git access token for the project repo")
-    .option("--project <id>", "Project UUID (defaults to .instafy/project.json)");
-addServerUrlOptions(gitTokenCommand);
-addAccessTokenOptions(gitTokenCommand, "Instafy access token (required)");
-gitTokenCommand
-    .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("--scope <scope...>", "Requested scopes (git.read, git.write)")
-    .option("--ttl-seconds <seconds>", "Token TTL in seconds (default server policy)")
-    .option("--json", "Output token response as JSON")
-    .action(async (opts) => {
-    try {
-        const project = typeof opts.project === "string" && opts.project.trim()
-            ? opts.project.trim()
-            : findProjectManifest(process.cwd()).manifest?.projectId ?? null;
-        if (!project) {
-            throw new Error("No project configured. Run `instafy project:init` or pass --project.");
-        }
-        const ttlSecondsRaw = typeof opts.ttlSeconds === "string" ? opts.ttlSeconds.trim() : "";
-        const ttlSeconds = ttlSecondsRaw.length > 0 ? Number.parseInt(ttlSecondsRaw, 10) : undefined;
-        if (ttlSecondsRaw.length > 0 && (!Number.isFinite(ttlSeconds) || ttlSeconds <= 0)) {
-            throw new Error("--ttl-seconds must be a positive integer");
-        }
-        await gitToken({
-            project,
-            controllerUrl: opts.serverUrl ?? opts.controllerUrl,
-            controllerAccessToken: opts.accessToken ?? opts.controllerAccessToken,
-            supabaseAccessToken: opts.supabaseAccessToken,
-            supabaseAccessTokenFile: opts.supabaseAccessTokenFile,
-            scopes: opts.scope,
-            ttlSeconds,
-            json: opts.json,
-        });
-    }
-    catch (error) {
-        console.error(kleur.red(String(error)));
-        process.exit(1);
-    }
-});
 program
-    .command("git:credential", { hidden: true })
-    .description("Internal: git credential helper (used by Git when configured)")
-    .argument("<operation>", "Operation (get|store|erase)")
-    .action(async (operation) => {
-    try {
-        await runGitCredentialHelper(operation);
-    }
-    catch (error) {
-        console.error(String(error));
-        process.exit(1);
-    }
-});
+    .command("git")
+    .description("Run git against the Instafy canonical checkout (.instafy/.git)")
+    .allowUnknownOption(true);
 const tunnelCommand = program
     .command("tunnel")
-    .description("Start a shareable tunnel URL for a local port (defaults to detached)")
+    .description("Create and manage shareable tunnels");
+tunnelCommand.action(() => tunnelCommand.outputHelp());
+const tunnelStartCommand = tunnelCommand
+    .command("start")
+    .description("Create a shareable tunnel URL for a local port (defaults to detached)")
     .option("--port <port>", "Local port to expose (default 3000)")
     .option("--project <id>", "Project UUID (defaults to .instafy/project.json or PROJECT_ID)");
-addServerUrlOptions(tunnelCommand);
-addAccessTokenOptions(tunnelCommand, "Instafy access token (defaults to saved `instafy login` token)");
-addServiceTokenOptions(tunnelCommand, "Instafy service token (advanced)");
-tunnelCommand
+addServerUrlOptions(tunnelStartCommand);
+addAccessTokenOptions(tunnelStartCommand, "Instafy access token (defaults to saved `instafy login` token)");
+addServiceTokenOptions(tunnelStartCommand, "Instafy service token (advanced)");
+tunnelStartCommand
     .option("--no-detach", "Run in foreground until interrupted")
     .option("--rathole-bin <path>", "Path to rathole binary (or set RATHOLE_BIN)")
     .option("--log-file <path>", "Write tunnel logs to a file (default: ~/.instafy/cli-tunnel-logs/*)")
@@ -439,9 +388,9 @@ tunnelCommand
         console.log(kleur.gray(`log: ${started.logFile}`));
         console.log("");
         console.log("Next:");
-        console.log(`- ${kleur.cyan(`instafy tunnel:list`)}`);
-        console.log(`- ${kleur.cyan(`instafy tunnel:logs ${started.tunnelId} --follow`)}`);
-        console.log(`- ${kleur.cyan(`instafy tunnel:stop ${started.tunnelId}`)}`);
+        console.log(`- ${kleur.cyan(`instafy tunnel list`)}`);
+        console.log(`- ${kleur.cyan(`instafy tunnel logs ${started.tunnelId} --follow`)}`);
+        console.log(`- ${kleur.cyan(`instafy tunnel stop ${started.tunnelId}`)}`);
         if (process.platform !== "win32") {
             console.log(kleur.gray(`(or) tail -n 200 -f ${started.logFile}`));
         }
@@ -451,8 +400,8 @@ tunnelCommand
         process.exit(1);
     }
 });
-program
-    .command("tunnel:list")
+tunnelCommand
+    .command("list")
     .description("List local tunnel sessions started by this CLI")
     .option("--all", "Include stopped/stale tunnels")
     .option("--json", "Output JSON")
@@ -476,8 +425,8 @@ program
         process.exit(1);
     }
 });
-program
-    .command("tunnel:stop")
+tunnelCommand
+    .command("stop")
     .description("Stop a local tunnel session and revoke it")
     .argument("[tunnelId]", "Tunnel ID (defaults to the only active tunnel)")
     .option("--server-url <url>", "Instafy server URL")
@@ -503,8 +452,8 @@ program
         process.exit(1);
     }
 });
-program
-    .command("tunnel:logs")
+tunnelCommand
+    .command("logs")
     .description("Show logs for a local tunnel session")
     .argument("[tunnelId]", "Tunnel ID (defaults to the only active tunnel)")
     .option("--lines <n>", "Number of lines to show", "200")
@@ -525,8 +474,12 @@ program
         process.exit(1);
     }
 });
-const orgListCommand = program
-    .command("org:list")
+const orgCommand = program
+    .command("org")
+    .description("Organization utilities");
+orgCommand.action(() => orgCommand.outputHelp());
+const orgListCommand = orgCommand
+    .command("list")
     .description("List organizations for your account");
 addServerUrlOptions(orgListCommand);
 orgListCommand
@@ -545,24 +498,42 @@ orgListCommand
         process.exit(1);
     }
 });
-const projectListCommand = program
-    .command("project:list")
-    .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")
+const profileCommand = program
+    .command("profile")
+    .description("Manage saved CLI profiles (~/.instafy/profiles)");
+profileCommand.action(() => profileCommand.outputHelp());
+profileCommand
+    .command("list")
+    .description("List saved CLI profiles")
     .option("--json", "Output JSON")
     .action(async (opts) => {
     try {
-        await (await import("./project.js")).listProjects({
-            controllerUrl: opts.serverUrl ?? opts.controllerUrl,
-            accessToken: opts.accessToken,
-            orgId: opts.orgId,
-            orgSlug: opts.orgSlug,
-            json: opts.json,
+        const names = listInstafyProfileNames();
+        const profiles = names.map((name) => {
+            const config = readInstafyProfileConfig(name);
+            return {
+                name,
+                path: getInstafyProfileConfigPath(name),
+                controllerUrl: config.controllerUrl ?? null,
+                studioUrl: config.studioUrl ?? null,
+                accessTokenSet: Boolean(config.accessToken),
+                updatedAt: config.updatedAt ?? null,
+            };
         });
+        if (opts.json) {
+            console.log(JSON.stringify({ profiles }, null, 2));
+            return;
+        }
+        if (profiles.length === 0) {
+            console.log(kleur.yellow("No profiles found."));
+            console.log(`Create one with: ${kleur.cyan("instafy login --profile <name>")}`);
+            return;
+        }
+        console.log(kleur.green("Instafy CLI profiles"));
+        for (const profile of profiles) {
+            const token = profile.accessTokenSet ? kleur.green("token") : kleur.yellow("no-token");
+            console.log(`- ${kleur.cyan(profile.name)} (${token})`);
+        }
     }
     catch (error) {
         console.error(kleur.red(String(error)));
@@ -600,23 +571,27 @@ function configureApiCommand(command, method) {
         }
     });
 }
-const apiGetCommand = program
-    .command("api:get", { hidden: true })
+const apiCommand = program
+    .command("api", { hidden: true })
+    .description("Advanced: authenticated requests to the controller API");
+apiCommand.action(() => apiCommand.outputHelp());
+const apiGetCommand = apiCommand
+    .command("get")
     .description("Advanced: authenticated GET request to the controller API")
     .argument("<path>", "API path (or full URL), e.g. /conversations/<id>/messages?limit=50");
 configureApiCommand(apiGetCommand, "GET");
-const apiPostCommand = program
-    .command("api:post", { hidden: true })
+const apiPostCommand = apiCommand
+    .command("post")
     .description("Advanced: authenticated POST request to the controller API")
     .argument("<path>", "API path (or full URL)");
 configureApiCommand(apiPostCommand, "POST");
-const apiPatchCommand = program
-    .command("api:patch", { hidden: true })
+const apiPatchCommand = apiCommand
+    .command("patch")
     .description("Advanced: authenticated PATCH request to the controller API")
     .argument("<path>", "API path (or full URL)");
 configureApiCommand(apiPatchCommand, "PATCH");
-const apiDeleteCommand = program
-    .command("api:delete", { hidden: true })
+const apiDeleteCommand = apiCommand
+    .command("delete")
     .description("Advanced: authenticated DELETE request to the controller API")
     .argument("<path>", "API path (or full URL)");
 configureApiCommand(apiDeleteCommand, "DELETE");
@@ -625,6 +600,27 @@ export async function runCli(argv = process.argv) {
         program.outputHelp();
         return;
     }
+    const args = argv.slice(2);
+    if (args[0] === "git") {
+        if (args[1] === "credential") {
+            try {
+                await runGitCredentialHelper(args[2] ?? "");
+            }
+            catch (error) {
+                console.error(String(error));
+                process.exitCode = 1;
+            }
+            return;
+        }
+        if (args[1] === "sync") {
+            const code = await runInstafyGitSync(args.slice(2));
+            process.exitCode = code;
+            return;
+        }
+        const code = runInstafyGit(args.slice(1));
+        process.exitCode = code;
+        return;
+    }
     await program.parseAsync(argv);
 }
 if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {

package/dist/org.js

@@ -5,7 +5,7 @@ export async function listOrganizations(params) {
     const controllerUrl = resolveControllerUrl({ controllerUrl: params.controllerUrl ?? null });
     const token = resolveUserAccessToken({ accessToken: params.accessToken ?? null });
     if (!token) {
-        throw formatAuthRequiredError({ retryCommand: "instafy org:list" });
+        throw formatAuthRequiredError({ retryCommand: "instafy org list" });
     }
     const response = await fetch(`${controllerUrl}/orgs`, {
         headers: { authorization: `Bearer ${token}` },

package/dist/project.js

@@ -67,7 +67,7 @@ export async function listProjects(options) {
     const controllerUrl = resolveControllerUrl({ controllerUrl: options.controllerUrl ?? null });
     const token = resolveUserAccessToken({ accessToken: options.accessToken ?? null });
     if (!token) {
-        throw formatAuthRequiredError({ retryCommand: "instafy project:list" });
+        throw formatAuthRequiredError({ retryCommand: "instafy project list" });
     }
     const orgs = await fetchOrganizations(controllerUrl, token);
     let targetOrgs = orgs;
@@ -124,7 +124,7 @@ export async function projectInit(options) {
     });
     if (!token) {
         throw formatAuthRequiredError({
-            retryCommand: "instafy project:init",
+            retryCommand: "instafy project init",
             advancedHint: "pass --access-token or set INSTAFY_ACCESS_TOKEN / SUPABASE_ACCESS_TOKEN",
         });
     }
@@ -185,7 +185,7 @@ 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.");
+        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()

package/dist/runtime.js

@@ -29,7 +29,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 {
@@ -289,7 +289,7 @@ export async function runtimeStart(options) {
     const manifestInfo = findProjectManifest(process.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);

package/dist/tunnel.js

@@ -32,7 +32,7 @@ function resolveProject(opts) {
     if (manifest?.projectId) {
         return manifest.projectId;
     }
-    throw new Error("No project configured for this folder.\n\nNext:\n- instafy project:init\n\nOr pass --project <uuid> / set PROJECT_ID.");
+    throw new Error("No project configured for this folder.\n\nNext:\n- instafy project init\n\nOr pass --project <uuid> / set PROJECT_ID.");
 }
 function resolveControllerUrl(opts) {
     const explicit = opts.controllerUrl?.trim();
@@ -53,7 +53,7 @@ function resolveControllerUrl(opts) {
     }
     return resolveConfiguredControllerUrl() ?? "http://127.0.0.1:8788";
 }
-function resolveControllerToken(opts) {
+function resolveControllerToken(opts, retryCommand = "instafy tunnel start") {
     const explicit = opts.controllerToken?.trim();
     if (explicit) {
         return explicit;
@@ -74,7 +74,7 @@ function resolveControllerToken(opts) {
         return serviceToken;
     }
     throw formatAuthRequiredError({
-        retryCommand: "instafy tunnel",
+        retryCommand,
         advancedHint: "pass --access-token / --service-token, or set INSTAFY_ACCESS_TOKEN / SUPABASE_ACCESS_TOKEN / INSTAFY_SERVICE_TOKEN",
     });
 }
@@ -336,7 +336,7 @@ export async function startTunnelDetached(opts) {
         exitedEarly = true;
         exitMessage = code !== null ? `code ${code}` : `signal ${signal}`;
     });
-    // Give rathole a moment to fail fast, so `instafy tunnel` can report errors.
+    // Give rathole a moment to fail fast, so `instafy tunnel start` can report errors.
     await new Promise((resolve) => setTimeout(resolve, 250));
     if (exitedEarly || !isProcessAlive(child.pid ?? -1)) {
         const logTail = (() => {
@@ -382,7 +382,7 @@ export async function stopTunnelSession(opts) {
         if (active.length === 1) {
             return stopTunnelSession({ ...opts, tunnelId: active[0]?.tunnelId });
         }
-        throw new Error("Tunnel id is required. Use `instafy tunnel:list` to find it.");
+        throw new Error("Tunnel id is required. Use `instafy tunnel list` to find it.");
     }
     const entry = removeTunnelState(tunnelId);
     if (!entry) {
@@ -405,7 +405,7 @@ export async function stopTunnelSession(opts) {
             }
         }
     }
-    const controllerToken = resolveControllerToken(opts);
+    const controllerToken = resolveControllerToken(opts, `instafy tunnel stop ${tunnelId}`);
     await revokeTunnel(entry.controllerUrl, controllerToken, entry.projectId, entry.tunnelId);
     try {
         fs.rmSync(entry.workdir, { recursive: true, force: true });
@@ -429,7 +429,7 @@ export function resolveTunnelLogFile(tunnelId) {
     if (active.length === 1) {
         return active[0];
     }
-    throw new Error("Tunnel id is required. Use `instafy tunnel:list` to find it.");
+    throw new Error("Tunnel id is required. Use `instafy tunnel list` to find it.");
 }
 export async function tailTunnelLogs(options) {
     const entry = resolveTunnelLogFile(options.tunnelId);

package/package.json

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