From ad88650577baa4570e41720e54fbe285aad0f5ed Mon Sep 17 00:00:00 2001
From: Raymond Ng <rng@roblox.com>
Date: Wed, 8 Apr 2026 18:08:56 -0700
Subject: [PATCH] update readme with run usage and add a contributing.md

---
 CONTRIBUTING.md | 74 +++++++++++++++++++++++++++++++++++++++++++++++++
 README.md       | 37 +++++++++++++++++++++----
 2 files changed, 106 insertions(+), 5 deletions(-)
 create mode 100644 CONTRIBUTING.md

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..34bd882
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,74 @@
+# Contributing to rocale-cli
+
+Thank you for your interest in contributing to rocale-cli! This document covers how to get set up, make changes, and submit contributions.
+
+## Getting Started
+
+### Setup
+
+1. Fork and clone the repository:
+   ```sh
+   git clone https://github.com/<your-username>/rocale-cli.git
+   cd rocale-cli
+   ```
+
+2. Install toolchain dependencies:
+   ```sh
+   foreman install
+   ```
+   This installs Lute (Luau compiler), StyLua (formatter), and Rojo (build tool) at the pinned versions in `foreman.toml`.
+
+3. Build:
+   ```sh
+   lute scripts/build
+   ```
+   The binary is output to `build/rocale-cli`.
+
+## Development Workflow
+
+### Building
+
+```sh
+lute scripts/build
+```
+
+### Running Tests
+
+Tests run against a real Roblox place via Open Cloud APIs, so you'll need to set up a test environment:
+
+1. [Create a new place](https://create.roblox.com/dashboard/creations) to use for testing.
+2. Generate an [Open Cloud API Key](https://create.roblox.com/dashboard/credentials) with the following permissions for your place:
+   - `universe-places:write`
+   - `luau-execution-sessions:write`
+3. Set the required environment variables:
+   ```sh
+   export TEST_UNIVERSE_ID=<your-universe-id>
+   export TEST_PLACE_ID=<your-place-id>
+   export ROBLOX_API_KEY=<your-api-key>
+   ```
+4. Run the tests:
+   ```sh
+   lute scripts/test
+   ```
+
+CI runs tests automatically on pull requests after a maintainer approves the change.
+
+## Submitting Changes
+
+1. Create a feature branch from `master`.
+2. Make your changes.
+3. Ensure the project builds and code is formatted with StyLua.
+4. Open a pull request from your fork targeting the `master` branch.
+5. Once a maintainer approves, CI will execute the test suite.
+
+## Releases
+
+Releases are handled by maintainers. To publish a new version:
+
+1. [Draft a new release](https://github.com/Roblox/rocale-cli/releases/new) and create a new tag with the format `vx.x.x`.
+2. CI automatically builds platform binaries (macOS, Linux, Windows) and attaches them to the release.
+3. The release build bakes the version and commit hash into the binary via `lute scripts/build <version> $(git rev-parse HEAD)`.
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the [MIT License](LICENSE).
diff --git a/README.md b/README.md
index 9625471..0febc2f 100644
--- a/README.md
+++ b/README.md
@@ -20,6 +20,37 @@ To spawn an OCALE task and use `rocale-cli run`, you will need to [create a new
 - `universe-places:write`
 - `luau-execution-sessions:write`
 
+```
+USAGE:
+  rocale-cli run [options]
+
+REQUIRED:
+  -u, --universeId <id>      	Target universe ID to spawn an Open Cloud instance of
+  -p, --placeId <id>         	Target place ID to spawn an Open Cloud instance of
+  --apiKey <key>            	Roblox API key (or set ROBLOX_API_KEY env var)
+
+LOAD OPTIONS:
+  --load.project <file>      	Rojo project.json/rbxp to build and load (requires rojo or robloxdev-cli)
+  --load.place <file>       	Load an rbxl
+  --load.version <num>      	Load existing place version without building/uploading
+                            	(set to 0 to rerun last uploaded version)
+
+BUILD OPTIONS:
+  --output <file>            	Output file path for the built place file
+                             	(default: output.rbxl)
+  --script <file>            	Luau script to load and set as entrypoint
+
+EXECUTION OPTIONS:
+  --lua.globals <key=value,...>	Comma-separated list of Lua globals to inject
+  --timeout <seconds>        	Timeout for polling task completion (default: 300)
+  --pollInterval <seconds>   	Interval between polling attempts (default: 2)
+  --binaryOutput <file>      	Path to save binary output from the task
+
+FLAGS:
+  -v, --verbose              	Enable verbose logging
+  --help                     	Show this help message
+```
+
 ## Building
 
 First, run `foreman install` to install dependencies.
@@ -28,8 +59,4 @@ To build, run `lute scripts/build`. The build artifacts will be created in the `
 
 To build for release, run `lute scripts/build <version> $(git rev-parse HEAD)` to bake the version and commit hash of the build into the binary.
 
-To test, follow the instructions above to create a new test place. Set the `TEST_UNIVERSE_ID`, `TEST_PLACE_ID` and `ROBLOX_API_KEY` environment variables. Then, run `lute scripts/test`. 
-
-## Publishing
-
-To publish a new version, [draft a new release](https://github.com/Roblox/rocale-cli/releases/new) and create a new tag with a version string format `vx.x.x`.
+To run tests, see [Contributing](CONTRIBUTING.md#running-tests).