@tinybirdco/sdk 0.0.3 → 0.0.4

package/src/cli/commands/build.ts

@@ -2,11 +2,17 @@
  * Build command - generates and pushes resources to Tinybird
  */
 
-import { loadConfig, type ResolvedConfig } from "../config.js";
+import { loadConfig, LOCAL_BASE_URL, type ResolvedConfig, type DevMode } from "../config.js";
 import { buildFromInclude, type BuildFromIncludeResult } from "../../generator/index.js";
 import { buildToTinybird, type BuildApiResult } from "../../api/build.js";
 import { deployToMain } from "../../api/deploy.js";
 import { getOrCreateBranch } from "../../api/branches.js";
+import {
+  getLocalTokens,
+  getOrCreateLocalWorkspace,
+  getLocalWorkspaceName,
+  LocalNotRunningError,
+} from "../../api/local.js";
 
 /**
  * Build command options
@@ -20,6 +26,8 @@ export interface BuildCommandOptions {
   tokenOverride?: string;
   /** Use /v1/deploy instead of /v1/build (for main branch) */
   useDeployEndpoint?: boolean;
+  /** Override the devMode from config */
+  devModeOverride?: DevMode;
 }
 
 /**
@@ -86,84 +94,142 @@ export async function runBuild(options: BuildCommandOptions = {}): Promise<Build
     };
   }
 
-  // Deploy to Tinybird
-  // Determine token and endpoint based on git branch
-  let effectiveToken = options.tokenOverride ?? config.token;
-  let useDeployEndpoint = options.useDeployEndpoint ?? config.isMainBranch;
-
-  // For feature branches, get or create the Tinybird branch and use its token
+  // Determine devMode
+  const devMode = options.devModeOverride ?? config.devMode;
   const debug = !!process.env.TINYBIRD_DEBUG;
+
   if (debug) {
-    console.log(`[debug] isMainBranch: ${config.isMainBranch}`);
-    console.log(`[debug] tinybirdBranch: ${config.tinybirdBranch}`);
-    console.log(`[debug] tokenOverride: ${!!options.tokenOverride}`);
+    console.log(`[debug] devMode: ${devMode}`);
   }
-  if (!config.isMainBranch && config.tinybirdBranch && !options.tokenOverride) {
-    if (debug) {
-      console.log(`[debug] Getting/creating Tinybird branch: ${config.tinybirdBranch}`);
-    }
+
+  let deployResult: BuildApiResult;
+
+  // Handle local mode
+  if (devMode === "local") {
     try {
-      const tinybirdBranch = await getOrCreateBranch(
+      // Get tokens from local container
+      if (debug) {
+        console.log(`[debug] Getting local tokens from ${LOCAL_BASE_URL}/tokens`);
+      }
+
+      const localTokens = await getLocalTokens();
+
+      // Get or create workspace based on branch name
+      const workspaceName = getLocalWorkspaceName(config.tinybirdBranch, config.cwd);
+      if (debug) {
+        console.log(`[debug] Using local workspace: ${workspaceName}`);
+      }
+
+      const { workspace, wasCreated } = await getOrCreateLocalWorkspace(localTokens, workspaceName);
+      if (debug) {
+        console.log(`[debug] Workspace ${wasCreated ? "created" : "found"}: ${workspace.name}`);
+      }
+
+      // Always use /v1/build for local (no deploy endpoint)
+      deployResult = await buildToTinybird(
         {
-          baseUrl: config.baseUrl,
-          token: config.token,
+          baseUrl: LOCAL_BASE_URL,
+          token: workspace.token,
         },
-        config.tinybirdBranch
+        buildResult.resources
       );
-
-      if (!tinybirdBranch.token) {
+    } catch (error) {
+      if (error instanceof LocalNotRunningError) {
         return {
           success: false,
           build: buildResult,
-          error: `Branch '${config.tinybirdBranch}' was created but no token was returned.`,
+          error: error.message,
           durationMs: Date.now() - startTime,
         };
       }
+      return {
+        success: false,
+        build: buildResult,
+        error: `Local build failed: ${(error as Error).message}`,
+        durationMs: Date.now() - startTime,
+      };
+    }
+  } else {
+    // Branch mode (default) - existing logic
+    // Deploy to Tinybird
+    // Determine token and endpoint based on git branch
+    let effectiveToken = options.tokenOverride ?? config.token;
+    // Use deploy endpoint if on main branch OR if no branch can be detected
+    let useDeployEndpoint = options.useDeployEndpoint ?? (config.isMainBranch || !config.tinybirdBranch);
 
-      effectiveToken = tinybirdBranch.token;
-      useDeployEndpoint = false; // Always use /v1/build for branches
+    if (debug) {
+      console.log(`[debug] isMainBranch: ${config.isMainBranch}`);
+      console.log(`[debug] tinybirdBranch: ${config.tinybirdBranch}`);
+      console.log(`[debug] tokenOverride: ${!!options.tokenOverride}`);
+    }
+
+    // For feature branches, get or create the Tinybird branch and use its token
+    if (!config.isMainBranch && config.tinybirdBranch && !options.tokenOverride) {
       if (debug) {
-        console.log(`[debug] Using branch token for branch: ${config.tinybirdBranch}`);
+        console.log(`[debug] Getting/creating Tinybird branch: ${config.tinybirdBranch}`);
+      }
+      try {
+        const tinybirdBranch = await getOrCreateBranch(
+          {
+            baseUrl: config.baseUrl,
+            token: config.token,
+          },
+          config.tinybirdBranch
+        );
+
+        if (!tinybirdBranch.token) {
+          return {
+            success: false,
+            build: buildResult,
+            error: `Branch '${config.tinybirdBranch}' was created but no token was returned.`,
+            durationMs: Date.now() - startTime,
+          };
+        }
+
+        effectiveToken = tinybirdBranch.token;
+        useDeployEndpoint = false; // Always use /v1/build for branches
+        if (debug) {
+          console.log(`[debug] Using branch token for branch: ${config.tinybirdBranch}`);
+        }
+      } catch (error) {
+        return {
+          success: false,
+          build: buildResult,
+          error: `Failed to get/create branch: ${(error as Error).message}`,
+          durationMs: Date.now() - startTime,
+        };
+      }
+    }
+
+    try {
+      // Use /v1/deploy for main branch, /v1/build for feature branches
+      if (useDeployEndpoint) {
+        deployResult = await deployToMain(
+          {
+            baseUrl: config.baseUrl,
+            token: effectiveToken,
+          },
+          buildResult.resources
+        );
+      } else {
+        deployResult = await buildToTinybird(
+          {
+            baseUrl: config.baseUrl,
+            token: effectiveToken,
+          },
+          buildResult.resources
+        );
       }
     } catch (error) {
       return {
         success: false,
         build: buildResult,
-        error: `Failed to get/create branch: ${(error as Error).message}`,
+        error: `Deploy failed: ${(error as Error).message}`,
         durationMs: Date.now() - startTime,
       };
     }
   }
 
-  let deployResult: BuildApiResult;
-  try {
-    // Use /v1/deploy for main branch, /v1/build for feature branches
-    if (useDeployEndpoint) {
-      deployResult = await deployToMain(
-        {
-          baseUrl: config.baseUrl,
-          token: effectiveToken,
-        },
-        buildResult.resources
-      );
-    } else {
-      deployResult = await buildToTinybird(
-        {
-          baseUrl: config.baseUrl,
-          token: effectiveToken,
-        },
-        buildResult.resources
-      );
-    }
-  } catch (error) {
-    return {
-      success: false,
-      build: buildResult,
-      error: `Deploy failed: ${(error as Error).message}`,
-      durationMs: Date.now() - startTime,
-    };
-  }
-
   if (!deployResult.success) {
     return {
       success: false,

package/src/cli/commands/dev.ts

@@ -4,7 +4,7 @@
 
 import * as path from "path";
 import { watch } from "chokidar";
-import { loadConfig, configExists, findConfigFile, hasValidToken, updateConfig, type ResolvedConfig } from "../config.js";
+import { loadConfig, configExists, findConfigFile, hasValidToken, updateConfig, LOCAL_BASE_URL, type ResolvedConfig, type DevMode } from "../config.js";
 import { runBuild, type BuildCommandResult } from "./build.js";
 import { getOrCreateBranch, type TinybirdBranch } from "../../api/branches.js";
 import { browserLogin } from "../auth.js";
@@ -13,6 +13,12 @@ import {
   validatePipeSchemas,
   type SchemaValidationResult,
 } from "../utils/schema-validation.js";
+import {
+  getLocalTokens,
+  getOrCreateLocalWorkspace,
+  getLocalWorkspaceName,
+  type LocalWorkspace,
+} from "../../api/local.js";
 
 /**
  * Login result info
@@ -44,6 +50,8 @@ export interface DevCommandOptions {
   onLoginComplete?: (info: LoginInfo) => void;
   /** Callback when schema validation completes */
   onSchemaValidation?: (result: SchemaValidationResult) => void;
+  /** Override the devMode from config */
+  devModeOverride?: DevMode;
 }
 
 /**
@@ -54,10 +62,14 @@ export interface BranchReadyInfo {
   gitBranch: string | null;
   /** Whether we're on the main branch */
   isMainBranch: boolean;
-  /** Tinybird branch info (null if on main) */
+  /** Tinybird branch info (null if on main or local mode) */
   tinybirdBranch?: TinybirdBranch;
   /** Whether the branch was newly created */
   wasCreated?: boolean;
+  /** Whether using local mode */
+  isLocal?: boolean;
+  /** Local workspace info (only in local mode) */
+  localWorkspace?: LocalWorkspace;
 }
 
 /**
@@ -98,8 +110,19 @@ export async function runDev(options: DevCommandOptions = {}): Promise<DevContro
     );
   }
 
-  // Check if authentication is set up, if not trigger login
-  if (!hasValidToken(cwd)) {
+  // Load config first to determine devMode
+  let config: ResolvedConfig;
+  try {
+    config = loadConfig(cwd);
+  } catch (error) {
+    throw error;
+  }
+
+  // Determine devMode
+  const devMode = options.devModeOverride ?? config.devMode;
+
+  // Check if authentication is set up, if not trigger login (skip for local mode)
+  if (devMode !== "local" && !hasValidToken(cwd)) {
     console.log("No authentication found. Starting login flow...\n");
 
     const authResult = await browserLogin();
@@ -134,51 +157,65 @@ export async function runDev(options: DevCommandOptions = {}): Promise<DevContro
       workspaceName: authResult.workspaceName,
       userEmail: authResult.userEmail,
     });
-  }
 
-  // Load config (now should have valid token)
-  let config: ResolvedConfig;
-  try {
+    // Reload config after login
     config = loadConfig(cwd);
-  } catch (error) {
-    throw error;
   }
 
-  // Determine effective token based on git branch
+  // Determine effective token and branch info based on devMode
   let effectiveToken = config.token;
+  let effectiveBaseUrl = config.baseUrl;
   let branchInfo: BranchReadyInfo = {
     gitBranch: config.gitBranch,
     isMainBranch: config.isMainBranch,
   };
 
-  // If we're on a feature branch, get or create the Tinybird branch
-  // Use tinybirdBranch (sanitized name) for Tinybird API, gitBranch for display
-  if (!config.isMainBranch && config.tinybirdBranch) {
-    const branchName = config.tinybirdBranch; // Sanitized name for Tinybird
-
-    // Always fetch fresh from API to avoid stale cache issues
-    const tinybirdBranch = await getOrCreateBranch(
-      {
-        baseUrl: config.baseUrl,
-        token: config.token,
-      },
-      branchName
-    );
-
-    if (!tinybirdBranch.token) {
-      throw new Error(
-        `Branch '${branchName}' was created but no token was returned. ` +
-          `This may be an API issue.`
-      );
-    }
+  if (devMode === "local") {
+    // Local mode: get tokens from local container and set up workspace
+    const localTokens = await getLocalTokens();
+    const workspaceName = getLocalWorkspaceName(config.tinybirdBranch, config.cwd);
+    const { workspace, wasCreated } = await getOrCreateLocalWorkspace(localTokens, workspaceName);
 
-    effectiveToken = tinybirdBranch.token;
+    effectiveToken = workspace.token;
+    effectiveBaseUrl = LOCAL_BASE_URL;
     branchInfo = {
-      gitBranch: config.gitBranch, // Original git branch name for display
-      isMainBranch: false,
-      tinybirdBranch,
-      wasCreated: tinybirdBranch.wasCreated ?? false,
+      gitBranch: config.gitBranch,
+      isMainBranch: false, // Local mode always uses build, not deploy
+      isLocal: true,
+      localWorkspace: workspace,
+      wasCreated,
     };
+  } else {
+    // Branch mode: use Tinybird cloud with branches
+    // If we're on a feature branch, get or create the Tinybird branch
+    // Use tinybirdBranch (sanitized name) for Tinybird API, gitBranch for display
+    if (!config.isMainBranch && config.tinybirdBranch) {
+      const branchName = config.tinybirdBranch; // Sanitized name for Tinybird
+
+      // Always fetch fresh from API to avoid stale cache issues
+      const tinybirdBranch = await getOrCreateBranch(
+        {
+          baseUrl: config.baseUrl,
+          token: config.token,
+        },
+        branchName
+      );
+
+      if (!tinybirdBranch.token) {
+        throw new Error(
+          `Branch '${branchName}' was created but no token was returned. ` +
+            `This may be an API issue.`
+        );
+      }
+
+      effectiveToken = tinybirdBranch.token;
+      branchInfo = {
+        gitBranch: config.gitBranch, // Original git branch name for display
+        isMainBranch: false,
+        tinybirdBranch,
+        wasCreated: tinybirdBranch.wasCreated ?? false,
+      };
+    }
   }
 
   // Notify about branch readiness
@@ -212,7 +249,8 @@ export async function runDev(options: DevCommandOptions = {}): Promise<DevContro
       const result = await runBuild({
         cwd: config.cwd,
         tokenOverride: effectiveToken,
-        useDeployEndpoint: config.isMainBranch,
+        useDeployEndpoint: devMode !== "local" && config.isMainBranch,
+        devModeOverride: devMode,
       });
       options.onBuildComplete?.(result);
 
@@ -234,7 +272,7 @@ export async function runDev(options: DevCommandOptions = {}): Promise<DevContro
             const validation = await validatePipeSchemas({
               entities: result.build.entities,
               pipeNames: changedPipes,
-              baseUrl: config.baseUrl,
+              baseUrl: effectiveBaseUrl,
               token: effectiveToken,
             });
 

package/src/cli/config.test.ts

@@ -267,6 +267,53 @@ describe("Config", () => {
 
       expect(() => loadConfig(tempDir)).toThrow("Failed to parse");
     });
+
+    it("defaults devMode to branch when not specified", () => {
+      const config = {
+        include: ["lib/datasources.ts"],
+        token: "test-token",
+      };
+      fs.writeFileSync(
+        path.join(tempDir, "tinybird.json"),
+        JSON.stringify(config)
+      );
+
+      const result = loadConfig(tempDir);
+
+      expect(result.devMode).toBe("branch");
+    });
+
+    it("loads devMode as branch when explicitly set", () => {
+      const config = {
+        include: ["lib/datasources.ts"],
+        token: "test-token",
+        devMode: "branch",
+      };
+      fs.writeFileSync(
+        path.join(tempDir, "tinybird.json"),
+        JSON.stringify(config)
+      );
+
+      const result = loadConfig(tempDir);
+
+      expect(result.devMode).toBe("branch");
+    });
+
+    it("loads devMode as local when set", () => {
+      const config = {
+        include: ["lib/datasources.ts"],
+        token: "test-token",
+        devMode: "local",
+      };
+      fs.writeFileSync(
+        path.join(tempDir, "tinybird.json"),
+        JSON.stringify(config)
+      );
+
+      const result = loadConfig(tempDir);
+
+      expect(result.devMode).toBe("local");
+    });
   });
 
   describe("updateConfig", () => {

package/src/cli/config.ts

@@ -6,6 +6,13 @@ import * as fs from "fs";
 import * as path from "path";
 import { getCurrentGitBranch, isMainBranch, getTinybirdBranchName } from "./git.js";
 
+/**
+ * Development mode options
+ * - "branch": Use Tinybird cloud with branches (default)
+ * - "local": Use local Tinybird container at localhost:7181
+ */
+export type DevMode = "branch" | "local";
+
 /**
  * Tinybird configuration file structure
  */
@@ -18,6 +25,8 @@ export interface TinybirdConfig {
   token: string;
   /** Tinybird API base URL (optional, defaults to EU region) */
   baseUrl?: string;
+  /** Development mode: "branch" (default) or "local" */
+  devMode?: DevMode;
 }
 
 /**
@@ -40,6 +49,8 @@ export interface ResolvedConfig {
   tinybirdBranch: string | null;
   /** Whether we're on the main/master branch */
   isMainBranch: boolean;
+  /** Development mode: "branch" or "local" */
+  devMode: DevMode;
 }
 
 /**
@@ -47,6 +58,11 @@ export interface ResolvedConfig {
  */
 const DEFAULT_BASE_URL = "https://api.tinybird.co";
 
+/**
+ * Local Tinybird base URL
+ */
+export const LOCAL_BASE_URL = "http://localhost:7181";
+
 /**
  * Config file name
  */
@@ -243,6 +259,9 @@ export function loadConfig(cwd: string = process.cwd()): ResolvedConfig {
   const gitBranch = getCurrentGitBranch();
   const tinybirdBranch = getTinybirdBranchName();
 
+  // Resolve devMode (default to "branch")
+  const devMode: DevMode = config.devMode ?? "branch";
+
   return {
     include,
     token: resolvedToken,
@@ -252,6 +271,7 @@ export function loadConfig(cwd: string = process.cwd()): ResolvedConfig {
     gitBranch,
     tinybirdBranch,
     isMainBranch: isMainBranch(),
+    devMode,
   };
 }
 

package/src/cli/index.ts

@@ -23,6 +23,7 @@ import {
   runBranchStatus,
   runBranchDelete,
 } from "./commands/branch.js";
+import type { DevMode } from "./config.js";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const packageJson = JSON.parse(
@@ -137,14 +138,27 @@ function createCli(): Command {
     .description("Build and push resources to Tinybird")
     .option("--dry-run", "Generate without pushing to API")
     .option("--debug", "Show debug output including API requests/responses")
+    .option("--local", "Use local Tinybird container")
+    .option("--branch", "Use Tinybird cloud with branches")
     .action(async (options) => {
       if (options.debug) {
         process.env.TINYBIRD_DEBUG = "1";
       }
-      console.log(`[${formatTime()}] Building...\n`);
+
+      // Determine devMode override
+      let devModeOverride: DevMode | undefined;
+      if (options.local) {
+        devModeOverride = "local";
+      } else if (options.branch) {
+        devModeOverride = "branch";
+      }
+
+      const modeLabel = devModeOverride === "local" ? " (local)" : "";
+      console.log(`[${formatTime()}] Building${modeLabel}...\n`);
 
       const result = await runBuild({
         dryRun: options.dryRun,
+        devModeOverride,
       });
 
       if (!result.success) {
@@ -190,12 +204,23 @@ function createCli(): Command {
   program
     .command("dev")
     .description("Watch for changes and sync with Tinybird")
-    .action(async () => {
+    .option("--local", "Use local Tinybird container")
+    .option("--branch", "Use Tinybird cloud with branches")
+    .action(async (options) => {
+      // Determine devMode override
+      let devModeOverride: DevMode | undefined;
+      if (options.local) {
+        devModeOverride = "local";
+      } else if (options.branch) {
+        devModeOverride = "branch";
+      }
+
       console.log(`tinybird dev v${VERSION}`);
       console.log("Loading config from tinybird.json...\n");
 
       try {
         const controller = await runDev({
+          devModeOverride,
           onLoginComplete: (info) => {
             console.log("\nAuthentication successful!");
             if (info.workspaceName) {
@@ -207,7 +232,18 @@ function createCli(): Command {
             console.log("");
           },
           onBranchReady: (info) => {
-            if (info.isMainBranch) {
+            if (info.isLocal) {
+              // Local mode
+              const workspaceName = info.localWorkspace?.name ?? "unknown";
+              if (info.wasCreated) {
+                console.log(`Using local Tinybird container`);
+                console.log(`Creating local workspace '${workspaceName}'...`);
+                console.log("Workspace created.\n");
+              } else {
+                console.log(`Using local Tinybird container`);
+                console.log(`Using existing local workspace '${workspaceName}'\n`);
+              }
+            } else if (info.isMainBranch) {
               console.log("On main branch - deploying to workspace\n");
             } else if (info.gitBranch) {
               const tinybirdName = info.tinybirdBranch?.name ?? info.gitBranch;