diff --git a/README.md b/README.md
index 41b4b21971..398dd5d194 100644
--- a/README.md
+++ b/README.md
@@ -53,6 +53,14 @@ npm run action src/www/storybook
 >
 > to your shell, then try `outline www/start`!
 
+## Passing configuration flags to actions
+
+Certain actions take configuration flags - but since we're running them through `npm`, you'll have to use the `--` seperator to funnel them through to the underlying process. For example, to set up a MacOS project in release mode, you'd run:
+
+```sh
+SENTRY_DSN=<your sentry dsn> npm run action cordova/setup macos -- --buildMode=release --versionName=<your version name>
+```
+
 ## Life of a Packet
 
 [How does the Outline Client work?](docs/life_of_a_packet.md)
diff --git a/src/cordova/setup.action.mjs b/src/cordova/setup.action.mjs
index d7b55f5509..ac6ff7560e 100644
--- a/src/cordova/setup.action.mjs
+++ b/src/cordova/setup.action.mjs
@@ -25,6 +25,7 @@ import {getRootDir} from '../build/get_root_dir.mjs';
 import {runAction} from '../build/run_action.mjs';
 import {getBuildParameters} from '../build/get_build_parameters.mjs';
 import {spawnStream} from '../build/spawn_stream.mjs';
+import chalk from 'chalk';
 
 const WORKING_CORDOVA_OSX_COMMIT = '07e62a53aa6a8a828fd988bc9e884c38c3495a67';
 
@@ -140,6 +141,10 @@ async function appleMacOsDebug(verbose) {
     throw new Error('Building an Apple binary requires xcodebuild and can only be done on MacOS');
   }
 
+  console.warn(
+    chalk.yellow('Debug mode on the MacOS client is currently broken. Try running with `--buildMode=release` instead.')
+  );
+
   await cordova.platform('add', [`github:apache/cordova-osx#${WORKING_CORDOVA_OSX_COMMIT}`], {save: false});
 
   await cordova.prepare({