powersync-ja · stevensJourney · Mar 5, 2026 · Mar 6, 2026 · Mar 6, 2026 · Mar 16, 2026
diff --git a/.changeset/nice-pears-find.md b/.changeset/nice-pears-find.md
@@ -0,0 +1,5 @@
+---
+'powersync': patch
+---
+
+Added `--sync-config-file-path` so local sync YAML can be read from a path other than `sync-config.yaml` for **`powersync deploy`**, **`powersync deploy sync-config`**, **`powersync validate`**, and **`powersync generate schema`**.
diff --git a/cli/src/api/BaseDeployCommand.ts b/cli/src/api/BaseDeployCommand.ts
@@ -12,7 +12,7 @@ import { DEFAULT_DEPLOY_TIMEOUT_MS, waitForOperationStatusChange } from './cloud
 import { parseLocalCloudServiceConfig } from './parse-local-cloud-service-config.js';
 
 export default abstract class BaseDeployCommand extends CloudInstanceCommand {
-  static flags = {
+  static baseFlags = {
     'deploy-timeout': Flags.integer({
       default: DEFAULT_DEPLOY_TIMEOUT_MS / 1000,
       description:
@@ -26,7 +26,7 @@ export default abstract class BaseDeployCommand extends CloudInstanceCommand {
         return value;
       }
     }),
-    ...CloudInstanceCommand.flags
+    ...CloudInstanceCommand.baseFlags
   };
 
   protected async deployAll(params: {

diff --git a/cli/src/api/cloud/fetch-cloud-sync-rules-content.ts b/cli/src/api/cloud/fetch-cloud-sync-rules-content.ts
@@ -1,21 +1,19 @@
-import { CloudProject, createCloudClient, SYNC_FILENAME } from '@powersync/cli-core';
-import { existsSync, readFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { CloudProject, createCloudClient } from '@powersync/cli-core';
 
 /**
  * Fetches the sync config content for a cloud project.
  * @param project - The project to fetch the sync config content for.
  * @returns The sync config content.
  */
 export async function fetchCloudSyncRulesContent(project: CloudProject): Promise<string> {
-  const { linked } = project;
-  const client = await createCloudClient();
-
   // First try and use the local file
-  if (existsSync(join(project.projectDirectory, SYNC_FILENAME))) {
-    return readFileSync(join(project.projectDirectory, SYNC_FILENAME), 'utf8');
+  if (project.syncRulesContent) {
+    return project.syncRulesContent;
   }
 
+  const { linked } = project;
+  const client = createCloudClient();
+
   // Try and fetch from the cloud config
   const instanceConfig = await client.getInstanceConfig({
     app_id: linked.project_id,

diff --git a/cli/src/api/self-hosted/fetch-self-hosted-sync-rules-content.ts b/cli/src/api/self-hosted/fetch-self-hosted-sync-rules-content.ts
@@ -1,25 +1,23 @@
-import { createSelfHostedClient, SelfHostedProject, SYNC_FILENAME } from '@powersync/cli-core';
-import { existsSync, readFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { createSelfHostedClient, SelfHostedProject } from '@powersync/cli-core';
 
 /**
  * Fetches the sync config content for a self-hosted project.
  * @param project - The project to fetch the sync config content for.
  * @returns The sync config content.
  */
 export async function fetchSelfHostedSyncRulesContent(project: SelfHostedProject): Promise<string> {
+  // First try and use the local file
+  if (project.syncRulesContent) {
+    return project.syncRulesContent;
+  }
+
   const { linked } = project;
   const client = createSelfHostedClient({
     apiKey: linked.api_key,
     apiUrl: linked.api_url
   });
 
-  // First try and use the local file
-  if (existsSync(join(project.projectDirectory, SYNC_FILENAME))) {
-    return readFileSync(join(project.projectDirectory, SYNC_FILENAME), 'utf8');
-  }
-
-  // Try and fetch from the cloud config
+  // Try and fetch from the self-hosted config
   const instanceConfig = await client.diagnostics({});
   const content = instanceConfig.active_sync_rules?.content;
 

diff --git a/cli/src/api/validations/validations.ts b/cli/src/api/validations/validations.ts
@@ -97,16 +97,14 @@ export async function runSyncConfigTestCloud(project: CloudProject): Promise<Syn
  * Runs self-hosted sync-rules validation and maps diagnostics into warning/error message arrays.
  */
 export async function runSyncConfigTestSelfHosted(project: SelfHostedProject): Promise<SyncValidationTestRunResult> {
-  const syncRulesPath = join(project.projectDirectory, SYNC_FILENAME);
-  const syncRulesContent = existsSync(syncRulesPath) ? readFileSync(syncRulesPath, 'utf8') : undefined;
-  const syncText = syncRulesContent ?? '';
+  const syncRulesContent = project.syncRulesContent ?? '';
   try {
     return wrapsSyncValidation({
       result: await validateSelfHostedSyncRules({
         linked: project.linked,
-        syncRulesContent: syncText
+        syncRulesContent
       }),
-      syncText
+      syncText: syncRulesContent
     });
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);

diff --git a/cli/src/commands/deploy/index.ts b/cli/src/commands/deploy/index.ts
@@ -1,4 +1,5 @@
 import { ux } from '@oclif/core';
+import { WithSyncConfigFilePath } from '@powersync/cli-core';
 
 import BaseDeployCommand from '../../api/BaseDeployCommand.js';
 import { DEFAULT_DEPLOY_TIMEOUT_MS } from '../../api/cloud/wait-for-operation.js';
@@ -8,7 +9,7 @@ import { formatValidationHuman } from '../../api/validations/validation-utils.js
 import { ValidationsRunner } from '../../api/validations/ValidationsRunner.js';
 import { ValidationTest } from '../../api/validations/ValidationTestDefinition.js';
 
-export default class DeployAll extends BaseDeployCommand {
+export default class DeployAll extends WithSyncConfigFilePath(BaseDeployCommand) {
   static description = [
     'Deploy local config (service.yaml, sync config) to the linked PowerSync Cloud instance.',
     'Validates connections and sync config before deploying.',
@@ -20,7 +21,6 @@ export default class DeployAll extends BaseDeployCommand {
     '<%= config.bin %> <%= command.id %> --instance-id=<id> --project-id=<id>'
   ];
   static flags = {
-    ...BaseDeployCommand.flags,
     ...GENERAL_VALIDATION_FLAG_HELPERS.flags
   };
   static summary = '[Cloud only] Deploy local config to the linked Cloud instance (connections + auth + sync config).';
@@ -29,15 +29,13 @@ export default class DeployAll extends BaseDeployCommand {
     const { flags } = await this.parse(DeployAll);
 
     const project = await this.loadProject(flags, {
-      // local config state is required when deploying all
       configFileRequired: true
     });
 
     const deployTimeoutMs = (flags['deploy-timeout'] ?? DEFAULT_DEPLOY_TIMEOUT_MS / 1000) * 1000;
 
     const validationTestsFilter = GENERAL_VALIDATION_FLAG_HELPERS.parseValidationTestFlags(flags);
 
-    // The existing config is required to deploy changes. The instance should have been created already.
     const cloudConfigState = await this.loadCloudConfigState();
 
     // Parse and store for later

diff --git a/cli/src/commands/deploy/service-config.ts b/cli/src/commands/deploy/service-config.ts
@@ -17,8 +17,7 @@ export default class DeployServiceConfig extends BaseDeployCommand {
     '<%= config.bin %> <%= command.id %> --instance-id=<id> --project-id=<id>'
   ];
   static flags = {
-    ...SERVICE_CONFIG_VALIDATION_FLAGS.flags,
-    ...BaseDeployCommand.flags
+    ...SERVICE_CONFIG_VALIDATION_FLAGS.flags
   };
   static summary = '[Cloud only] Deploy only local service config to the linked Cloud instance.';
 

diff --git a/cli/src/commands/deploy/sync-config.ts b/cli/src/commands/deploy/sync-config.ts
@@ -1,8 +1,7 @@
-import { Flags } from '@oclif/core';
 import { ux } from '@oclif/core/ux';
+import { WithSyncConfigFilePath } from '@powersync/cli-core';
 import { routes } from '@powersync/management-types';
 import { ObjectId } from 'bson';
-import { readFileSync } from 'node:fs';
 
 import BaseDeployCommand from '../../api/BaseDeployCommand.js';
 import { DEFAULT_DEPLOY_TIMEOUT_MS } from '../../api/cloud/wait-for-operation.js';
@@ -16,20 +15,14 @@ const SYNC_CONFIG_VALIDATION_FLAGS = generateValidationTestFlags({
   limitOptions: [ValidationTest['SYNC-CONFIG']]
 });
 
-export default class DeploySyncConfig extends BaseDeployCommand {
+export default class DeploySyncConfig extends WithSyncConfigFilePath(BaseDeployCommand) {
   static description = 'Deploy only sync config changes.';
   static examples = [
     '<%= config.bin %> <%= command.id %>',
     '<%= config.bin %> <%= command.id %> --instance-id=<id> --project-id=<id>'
   ];
   static flags = {
-    ...BaseDeployCommand.flags,
-    ...SYNC_CONFIG_VALIDATION_FLAGS.flags,
-    'sync-config-file-path': Flags.file({
-      description:
-        'Path to a sync config file. If provided, this file will be validated and deployed instead of the default sync-config.yaml.',
-      exists: true
-    })
+    ...SYNC_CONFIG_VALIDATION_FLAGS.flags
   };
   static summary = '[Cloud only] Deploy only local sync config to the linked Cloud instance.';
 
@@ -84,9 +77,10 @@ export default class DeploySyncConfig extends BaseDeployCommand {
     const { linked } = project;
     const deployTimeoutMs = (flags['deploy-timeout'] ?? DEFAULT_DEPLOY_TIMEOUT_MS / 1000) * 1000;
 
-    const syncConfigFilePath = flags['sync-config-file-path'];
-    if (syncConfigFilePath) {
-      project.syncRulesContent = readFileSync(syncConfigFilePath, 'utf8');
+    if (!project.syncRulesContent) {
+      this.styledError({
+        message: `Sync config content not loaded. Ensure sync config is present and valid.`
+      });
     }
 
     if (!project.syncRulesContent) {

diff --git a/cli/src/commands/destroy.ts b/cli/src/commands/destroy.ts
@@ -11,8 +11,7 @@ export default class Destroy extends CloudInstanceCommand {
     confirm: Flags.string({
       description: 'Set to "yes" to confirm destruction of the instance.',
       options: ['yes']
-    }),
-    ...CloudInstanceCommand.flags
+    })
   };
   static summary = '[Cloud only] Permanently destroy the linked Cloud instance.';
 

diff --git a/cli/src/commands/fetch/config.ts b/cli/src/commands/fetch/config.ts
@@ -12,8 +12,7 @@ export default class FetchConfig extends CloudInstanceCommand {
       default: 'yaml',
       description: 'Output format: yaml or json.',
       options: ['json', 'yaml']
-    }),
-    ...CloudInstanceCommand.flags
+    })
   };
   static summary = '[Cloud only] Print linked Cloud instance config (YAML or JSON).';
 

diff --git a/cli/src/commands/fetch/status.ts b/cli/src/commands/fetch/status.ts
@@ -17,8 +17,7 @@ export default class FetchStatus extends SharedInstanceCommand {
       default: 'human',
       description: 'Output format: human-readable, json, or yaml.',
       options: ['human', 'json', 'yaml']
-    }),
-    ...SharedInstanceCommand.flags
+    })
   };
   static summary = 'Show instance diagnostics (connections, sync config, replication).';
 

diff --git a/cli/src/commands/generate/schema.ts b/cli/src/commands/generate/schema.ts
@@ -4,7 +4,8 @@ import {
   createCloudClient,
   createSelfHostedClient,
   SelfHostedProject,
-  SharedInstanceCommand
+  SharedInstanceCommand,
+  WithSyncConfigFilePath
 } from '@powersync/cli-core';
 import { routes } from '@powersync/management-types';
 import { schemaGenerators, SqlSyncRules, StaticSchema } from '@powersync/service-sync-rules';
@@ -13,7 +14,7 @@ import { writeFileSync } from 'node:fs';
 import { fetchCloudSyncRulesContent } from '../../api/cloud/fetch-cloud-sync-rules-content.js';
 import { fetchSelfHostedSyncRulesContent } from '../../api/self-hosted/fetch-self-hosted-sync-rules-content.js';
 
-export default class GenerateSchema extends SharedInstanceCommand {
+export default class GenerateSchema extends WithSyncConfigFilePath(SharedInstanceCommand) {
   static description =
     'Generate a client-side schema file from the instance database schema and sync config. Supports multiple output types (e.g. type, dart). Requires a linked instance. Cloud and self-hosted.';
   static examples = [
@@ -30,14 +31,13 @@ export default class GenerateSchema extends SharedInstanceCommand {
     'output-path': Flags.string({
       description: 'Path to output the schema file.',
       required: true
-    }),
-    ...SharedInstanceCommand.flags
+    })
   };
   static summary = 'Generate client schema file from instance schema and sync config.';
 
   async getCloudSchema(project: CloudProject): Promise<routes.GetSchemaResponse> {
     const { linked } = project;
-    const client = await createCloudClient();
+    const client = createCloudClient();
     return client.getInstanceSchema({
       app_id: linked.project_id,
       id: linked.instance_id,

diff --git a/cli/src/commands/generate/token.ts b/cli/src/commands/generate/token.ts
@@ -37,8 +37,7 @@ export default class GenerateToken extends SharedInstanceCommand {
     subject: Flags.string({
       description: 'Subject of the token.',
       required: true
-    }),
-    ...SharedInstanceCommand.flags
+    })
   };
   static summary = 'Generate a development JWT for client connections.';
 

diff --git a/cli/src/commands/init/cloud.ts b/cli/src/commands/init/cloud.ts
@@ -27,9 +27,6 @@ export default class InitCloud extends InstanceCommand {
     '<%= config.bin %> <%= command.id %>',
     '<%= config.bin %> <%= command.id %> --directory=powersync'
   ];
-  static flags = {
-    ...InstanceCommand.flags
-  };
   static summary = 'Scaffold a PowerSync Cloud config directory from a template.';
 
   async run(): Promise<void> {

diff --git a/cli/src/commands/init/self-hosted.ts b/cli/src/commands/init/self-hosted.ts
@@ -27,9 +27,6 @@ export default class InitSelfHosted extends InstanceCommand {
     '<%= config.bin %> <%= command.id %>',
     '<%= config.bin %> <%= command.id %> --directory=powersync'
   ];
-  static flags = {
-    ...InstanceCommand.flags
-  };
   static summary = 'Scaffold a PowerSync self-hosted config directory from a template.';
 
   async run(): Promise<void> {

diff --git a/cli/src/commands/link/cloud.ts b/cli/src/commands/link/cloud.ts
@@ -6,7 +6,6 @@ import {
   ensureServiceTypeMatches,
   env,
   getDefaultOrgId,
-  InstanceCommand,
   ServiceType
 } from '@powersync/cli-core';
 
@@ -44,8 +43,7 @@ export default class LinkCloud extends CloudInstanceCommand {
       default: env.PROJECT_ID,
       description: 'Project ID. Resolved: flag → PROJECT_ID → cli.yaml.',
       required: true
-    }),
-    ...InstanceCommand.flags
+    })
   };
   static summary = '[Cloud only] Link to a PowerSync Cloud instance (or create one with --create).';
 

diff --git a/cli/src/commands/link/self-hosted.ts b/cli/src/commands/link/self-hosted.ts
@@ -5,7 +5,6 @@ import {
   CommandHelpGroup,
   ensureServiceTypeMatches,
   env,
-  InstanceCommand,
   parseYamlFile,
   SelfHostedInstanceCommand,
   ServiceType
@@ -25,8 +24,7 @@ export default class LinkSelfHosted extends SelfHostedInstanceCommand {
     'api-url': Flags.string({
       description: 'Self-hosted PowerSync API base URL (e.g. https://powersync.example.com).',
       required: true
-    }),
-    ...InstanceCommand.flags
+    })
   };
   static summary = 'Link to a self-hosted PowerSync instance by API URL.';
 

diff --git a/cli/src/commands/migrate/sync-rules.ts b/cli/src/commands/migrate/sync-rules.ts
@@ -15,8 +15,7 @@ export default class MigrateSyncRules extends SharedInstanceCommand {
     'output-file': Flags.string({
       description: 'Path to the output sync streams file. Defaults to overwrite the input file.',
       required: false
-    }),
-    ...SharedInstanceCommand.flags
+    })
   };
   static summary = 'Migrates Sync Rules to Sync Streams';
 

diff --git a/cli/src/commands/pull/instance.ts b/cli/src/commands/pull/instance.ts
@@ -36,7 +36,6 @@ export default class PullInstance extends CloudInstanceCommand {
     '<%= config.bin %> <%= command.id %> --instance-id=<id> --project-id=<id> --org-id=<org-id>'
   ];
   static flags = {
-    ...CloudInstanceCommand.flags,
     overwrite: Flags.boolean({
       description:
         'Overwrite existing service.yaml and sync-config.yaml if they exist. By default, if these files already exist, the fetched configs will be written to service-fetched.yaml and sync-fetched.yaml to avoid overwriting local changes.'

diff --git a/cli/src/commands/stop.ts b/cli/src/commands/stop.ts
@@ -12,8 +12,7 @@ export default class Stop extends CloudInstanceCommand {
     confirm: Flags.string({
       description: 'Set to "yes" to confirm stopping the instance.',
       options: ['yes']
-    }),
-    ...CloudInstanceCommand.flags
+    })
   };
   static summary = '[Cloud only] Stop the linked Cloud instance (restart with deploy).';
 

diff --git a/cli/src/commands/validate.ts b/cli/src/commands/validate.ts
@@ -1,5 +1,11 @@
 import { Flags } from '@oclif/core';
-import { CloudProject, SelfHostedProject, SharedInstanceCommand, ValidationResult } from '@powersync/cli-core';
+import {
+  CloudProject,
+  SelfHostedProject,
+  SharedInstanceCommand,
+  ValidationResult,
+  WithSyncConfigFilePath
+} from '@powersync/cli-core';
 
 import { parseLocalCloudServiceConfig } from '../api/parse-local-cloud-service-config.js';
 import { getCloudValidations } from '../api/validations/cloud-validations.js';
@@ -9,7 +15,7 @@ import { formatValidationJson, formatValidationYaml } from '../api/validations/v
 import { ValidationsRunner } from '../api/validations/ValidationsRunner.js';
 import { ValidationTest } from '../api/validations/ValidationTestDefinition.js';
 
-export default class Validate extends SharedInstanceCommand {
+export default class Validate extends WithSyncConfigFilePath(SharedInstanceCommand) {
   static description =
     'Run validation checks on local config: config schema, database connections, and sync config. Requires a linked instance. Works with Cloud and self-hosted.';
   static examples = [
@@ -23,8 +29,7 @@ export default class Validate extends SharedInstanceCommand {
       description: 'Output format: human-readable, json, or yaml.',
       options: ['human', 'json', 'yaml']
     }),
-    ...GENERAL_VALIDATION_FLAG_HELPERS.flags,
-    ...SharedInstanceCommand.flags
+    ...GENERAL_VALIDATION_FLAG_HELPERS.flags
   };
   static summary = 'Validate config schema, connections, and sync config before deploy.';