@instafy/cli 0.1.1 → 0.1.3

package/README.md

@@ -1,68 +1,29 @@
-# Instafy CLI (Developer Preview)
+<p align="center"><code>npm i -g @instafy/cli</code></p>
 
-Use this CLI to link a folder to an Instafy project and run a self-hosted runtime (desktop or server) that connects back to Instafy Studio (including tunnels).
+# Instafy CLI (Preview)
 
-Primary commands:
+Run Instafy projects locally and connect them back to Instafy Studio — from any terminal.
 
-- `instafy runtime:start` — launch the runtime in the current machine (foreground by default, `--detach` to background).
-- `instafy runtime:status` — report health of the last started runtime.
-- `instafy runtime:stop` — stop the last started runtime.
-- `instafy runtime:token` — mint a runtime access token with agent + origin scopes.
-- `instafy project:init` — create a project via the controller and write `.instafy/project.json` in the chosen folder.
-- `instafy project:list` — list projects for the orgs available to the current controller token.
-- `instafy org:list` — list orgs available to the current controller token.
-
-## Quick start
-
-```bash
-# From repo root (assumes runtime-agent is built): pnpm --filter @instafy/cli dev -- --help
-pnpm --filter @instafy/cli dev -- runtime:start \
-  --project 00000000-0000-0000-0000-000000000000 \
-  --controller-url http://127.0.0.1:8788 \
-  --controller-access-token "$CONTROLLER_ACCESS_TOKEN"
-
-# Inspect status
-pnpm --filter @instafy/cli dev -- runtime:status
-
-# Stop
-pnpm --filter @instafy/cli dev -- runtime:stop
-
-# Create a project manifest for the current directory
-pnpm --filter @instafy/cli dev -- project:init --controller-url http://127.0.0.1:8788 --access-token "$SUPABASE_ACCESS_TOKEN"
+## Quickstart
 
-# List projects for your orgs
-pnpm --filter @instafy/cli dev -- project:list --controller-url http://127.0.0.1:8788 --access-token "$SUPABASE_ACCESS_TOKEN"
-```
+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`
+3. Check status / stop:
+   - `instafy runtime:status`
+   - `instafy runtime:stop`
 
-## Auth model
+## Common commands
 
-- The CLI mints a **runtime access token** via `/projects/:projectId/runtime/token` when a controller access token is provided (`--controller-access-token` or `CONTROLLER_ACCESS_TOKEN`).
-- That token is exported to the runtime as `RUNTIME_ACCESS_TOKEN` and mirrored to `ORIGIN_INTERNAL_TOKEN` for the bundled origin server.
-- You can supply a pre-minted token with `--runtime-token` / `RUNTIME_ACCESS_TOKEN` (also reused for origin). Legacy `--origin-token` still maps to the same value.
-- If you only have a Supabase session (service role or user JWT), pass it via `--supabase-access-token`, `--supabase-access-token-file`, or `SUPABASE_ACCESS_TOKEN`. The CLI uses that session to mint the controller and runtime tokens automatically so you do not need to juggle controller-issued keys locally.
-
-## Important flags
-
-- `--project` / `PROJECT_ID` — project UUID to associate the runtime with (defaults to `.instafy/project.json` if present).
-- `--controller-url` / `CONTROLLER_BASE_URL` — controller base URL (defaults to `http://127.0.0.1:8788`).
-- `--controller-access-token` — user/controller token used to mint the runtime token if `--runtime-token` is not provided.
-- `--supabase-access-token` / `SUPABASE_ACCESS_TOKEN` — Supabase session token the CLI can exchange for controller and runtime tokens when you do not have a controller key handy.
-- `--runtime-token` / `RUNTIME_ACCESS_TOKEN` — pre-minted runtime/origin token to bypass minting.
-- `--origin-id` — optionally fix the origin id (otherwise auto-generated).
-- `--origin-endpoint` — skip tunnels entirely and publish a fixed, reachable origin URL (useful for servers with a stable public endpoint).
-- `--workspace` / `WORKSPACE_DIR` — workspace root for the runtime (default `./.instafy/workspace`).
-- `--provider` / `RUNTIME_PROVIDER` — runtime provider label (defaults to the org in `.instafy/project.json`, otherwise `self-hosted`).
-- `--detach` — background the runtime; pid/log state is recorded under `~/.instafy/cli-runtime-state.json`.
-- `--org-id` — target an existing org when running `project:init` (otherwise the CLI creates or reuses a personal org).
-
-## Tunnels (self-hosted)
-
-Tunnels are controller-managed: the runtime-agent requests a tunnel assignment from the controller and then launches the appropriate client locally.
+- `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` — request a tunnel and forward a local port.
+- `instafy workspace:mount` — mount project files locally (SSHFS).
 
-- **Self-hosted tunnels (recommended)**: controller is configured with `TUNNEL_BROKER_BASE_URL` / `TUNNEL_BROKER_TOKEN` and returns `provider=self_hosted`. The runtime-agent launches `rathole` (outbound-only). The CLI will try to resolve `RATHOLE_BIN` (PATH or cached download). On macOS arm64, it falls back to `cargo install rathole` when no prebuilt is available.
+Run `instafy --help` for the full command list and options.
 
-## Notes
+## Docs
 
-- The CLI reuses the locally built `runtime-agent` binary from `target/{debug,release}`. Run `cargo build -p runtime-agent` first or set `INSTAFY_RUNTIME_AGENT_BIN` to an explicit path.
-- Runtime/origin tokens require the controller to be configured with the Ed25519 signing pair (`RUNTIME_SIGNING_PRIVATE_KEY` / `RUNTIME_SIGNING_PUBLIC_KEY`).
-- Logs for detached runs are written to `~/.instafy/cli-runtime-logs/*`.
+- CLI reference & troubleshooting: https://github.com/instafy-dev/instafy/blob/main/docs/CLI.md

package/bin/instafy.js

@@ -1,5 +1,9 @@
 #!/usr/bin/env node
-import('../dist/index.js').catch((err) => {
+import { runCli } from "../dist/index.js";
+
+try {
+  await runCli(process.argv);
+} catch (err) {
   console.error(err);
   process.exit(1);
-});
+}

package/dist/index.js

@@ -1,14 +1,17 @@
 import { Command } from "commander";
 import { pathToFileURL } from "node:url";
+import { createRequire } from "node:module";
 import kleur from "kleur";
 import { runtimeStart, runtimeStatus, runtimeStop, runtimeToken, mountWorkspace, } from "./runtime.js";
 import { projectInit } from "./project.js";
 import { runTunnelCommand } from "./tunnel.js";
-const program = new Command();
+export const program = new Command();
+const require = createRequire(import.meta.url);
+const pkg = require("../package.json");
 program
     .name("instafy")
     .description("Instafy CLI — manage local/self-hosted runtimes")
-    .version("0.1.0");
+    .version(pkg.version ?? "0.1.0");
 program
     .command("runtime:start")
     .description("Start a local Instafy runtime (agent + origin)")
@@ -238,8 +241,15 @@ program
         process.exit(1);
     }
 });
+export async function runCli(argv = process.argv) {
+    if (argv.length <= 2) {
+        program.outputHelp();
+        return;
+    }
+    await program.parseAsync(argv);
+}
 if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
-    program.parseAsync(process.argv);
+    void runCli(process.argv);
 }
 // Re-export programmatic APIs for embedders (e.g., VS Code extension).
 export { runtimeStart as startRuntime, runtimeStatus as getRuntimeStatus, runtimeStop as stopRuntime, runtimeToken as mintRuntimeToken, mintRuntimeAccessToken, findProjectManifest, mountWorkspace, } from "./runtime.js";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@instafy/cli",
-  "version": "0.1.1",
-  "description": "CLI for connecting local folders to Instafy projects and running self-hosted runtimes (including tunnels).",
+  "version": "0.1.3",
+  "description": "Run Instafy projects locally, link folders to Studio, and share previews/webhooks via tunnels.",
   "private": false,
   "publishConfig": {
     "access": "public"