[SLOP(claude-opus-4-8[1m]-high)] docs(examples): wire quickstart examples, clients, and dev tools links

.github/workflows/publish.yaml

@@ -157,6 +157,44 @@ jobs:
             upload_prefix: engine
             platform: windows-x64
             release_only: true
+          # Rivet Cloud CLI: 4 platforms for preview, 5 for release. The publish
+          # job also places the matching rivet-engine artifact next to the CLI
+          # binary so `rivet dev` works from the npm package.
+          - name: cli (linux-x64-musl)
+            build_target: cli
+            docker: docker/build/linux-x64-musl.Dockerfile
+            artifact: rivet-x86_64-unknown-linux-musl
+            upload_prefix: cli
+            platform: linux-x64-musl
+            release_only: false
+          - name: cli (linux-arm64-musl)
+            build_target: cli
+            docker: docker/build/linux-arm64-musl.Dockerfile
+            artifact: rivet-aarch64-unknown-linux-musl
+            upload_prefix: cli
+            platform: linux-arm64-musl
+            release_only: false
+          - name: cli (darwin-x64)
+            build_target: cli
+            docker: docker/build/darwin-x64.Dockerfile
+            artifact: rivet-x86_64-apple-darwin
+            upload_prefix: cli
+            platform: darwin-x64
+            release_only: false
+          - name: cli (darwin-arm64)
+            build_target: cli
+            docker: docker/build/darwin-arm64.Dockerfile
+            artifact: rivet-aarch64-apple-darwin
+            upload_prefix: cli
+            platform: darwin-arm64
+            release_only: false
+          - name: cli (windows-x64)
+            build_target: cli
+            docker: docker/build/windows-x64.Dockerfile
+            artifact: rivet-x86_64-pc-windows-gnu.exe
+            upload_prefix: cli
+            platform: windows-x64
+            release_only: true
     runs-on: depot-ubuntu-24.04-8
     permissions:
       contents: read
@@ -363,6 +401,12 @@ jobs:
           path: engine-artifacts
           pattern: engine-*
           merge-multiple: true
+      - name: Download CLI artifacts
+        uses: actions/download-artifact@v4
+        with:
+          path: cli-artifacts
+          pattern: cli-*
+          merge-multiple: true
       - name: Place native binaries in platform packages
         run: |
           NATIVE_DIR=rivetkit-typescript/packages/rivetkit-napi
@@ -408,6 +452,72 @@ jobs:
             fi
           done
 
+      - name: Place CLI binaries in CLI platform packages
+        run: |
+          CLI_DIR=rivetkit-typescript/packages/cli/npm
+          declare -A TRIPLE_TO_PLATFORM=(
+            [rivet-x86_64-unknown-linux-musl]=linux-x64-musl
+            [rivet-aarch64-unknown-linux-musl]=linux-arm64-musl
+            [rivet-x86_64-apple-darwin]=darwin-x64
+            [rivet-aarch64-apple-darwin]=darwin-arm64
+            [rivet-x86_64-pc-windows-gnu.exe]=win32-x64
+          )
+          for f in cli-artifacts/rivet-*; do
+            [ -e "$f" ] || continue
+            filename=$(basename "$f")
+            platform="${TRIPLE_TO_PLATFORM[$filename]:-}"
+            if [ -z "$platform" ]; then
+              echo "Skipping CLI artifact not mapped to a platform package: $filename"
+              continue
+            fi
+            dest="${CLI_DIR}/${platform}"
+            if [ ! -d "$dest" ]; then
+              echo "Missing CLI platform dir: $dest" >&2
+              exit 1
+            fi
+            if [ "$platform" = "win32-x64" ]; then
+              cp "$f" "$dest/rivet.exe"
+              echo "Placed $filename -> npm/${platform}/rivet.exe"
+            else
+              cp "$f" "$dest/rivet"
+              chmod +x "$dest/rivet"
+              echo "Placed $filename -> npm/${platform}/rivet"
+            fi
+          done
+
+      - name: Place bundled engine in CLI platform packages
+        run: |
+          CLI_DIR=rivetkit-typescript/packages/cli/npm
+          declare -A ENGINE_TO_PLATFORM=(
+            [rivet-engine-x86_64-unknown-linux-musl]=linux-x64-musl
+            [rivet-engine-aarch64-unknown-linux-musl]=linux-arm64-musl
+            [rivet-engine-x86_64-apple-darwin]=darwin-x64
+            [rivet-engine-aarch64-apple-darwin]=darwin-arm64
+            [rivet-engine-x86_64-pc-windows-gnu.exe]=win32-x64
+          )
+          for f in engine-artifacts/rivet-engine-*; do
+            [ -e "$f" ] || continue
+            filename=$(basename "$f")
+            platform="${ENGINE_TO_PLATFORM[$filename]:-}"
+            if [ -z "$platform" ]; then
+              echo "Skipping engine artifact not mapped to a CLI platform package: $filename"
+              continue
+            fi
+            dest="${CLI_DIR}/${platform}"
+            if [ ! -d "$dest" ]; then
+              echo "Missing CLI platform dir: $dest" >&2
+              exit 1
+            fi
+            if [ "$platform" = "win32-x64" ]; then
+              cp "$f" "$dest/rivet-engine.exe"
+              echo "Placed $filename -> npm/${platform}/rivet-engine.exe"
+            else
+              cp "$f" "$dest/rivet-engine"
+              chmod +x "$dest/rivet-engine"
+              echo "Placed $filename -> npm/${platform}/rivet-engine"
+            fi
+          done
+
       - name: Bump package versions for build
         run: |
           pnpm --filter=publish exec tsx src/ci/bin.ts bump-versions \
@@ -418,7 +528,9 @@ jobs:
       - name: Build TypeScript packages
         env:
           SKIP_WASM_BUILD: "1"
-        run: pnpm build -F rivetkit -F '@rivetkit/*' -F '!@rivetkit/shared-data' -F '!@rivetkit/engine-frontend' -F '!@rivetkit/mcp-hub' -F '!@rivetkit/rivetkit-napi' -F '!@rivetkit/rivetkit-wasm'
+        run: |
+          pnpm build -F rivetkit
+          pnpm build -F rivetkit -F '@rivetkit/*' -F '!@rivetkit/shared-data' -F '!@rivetkit/engine-frontend' -F '!@rivetkit/mcp-hub' -F '!@rivetkit/rivetkit-napi' -F '!@rivetkit/rivetkit-wasm'
 
       # ---- shared publish (runs for all triggers) ----
       - name: Finalize package versions for publish

CLAUDE.md

@@ -131,6 +131,7 @@ docker-compose up -d
 - Use `scripts/cargo/check-rivetkit-core-wasm.sh` as the canonical wasm gate for `rivetkit-core`; it checks the wasm build, scans native dependency leaks, and verifies native transport/runtime features fail on wasm.
 - The high-level `rivetkit` crate stays a thin typed wrapper over `rivetkit-core` and re-exports shared transport/config types instead of redefining them.
 - When `rivetkit` needs ergonomic helpers on a `rivetkit-core` type it re-exports, prefer an extension trait plus `prelude` re-export instead of wrapping and replacing the core type.
+- RivetKit action and event protocol `args` must always be array-shaped before crossing the client protocol boundary. Normalize at the server/source side, not in client delivery code: named structs/objects become `[object]`, tuples/arrays stay positional, scalars become `[scalar]`, and unit/null becomes `[]`.
 - `engine/sdks/*/api-*` are auto-generated SDK outputs; update the source API schema and regenerate them instead of editing them by hand.
 
 ### RivetKit Test Fixtures
@@ -336,7 +337,7 @@ When the user asks to track something in a note, store it in `~/.agents/notes/`
 ### Comments
 
 - Write comments as normal, complete sentences. Avoid fragmented structures with parentheticals and dashes like `// Spawn engine (if configured) - regardless of start kind`. Instead, write `// Spawn the engine if configured`. Especially avoid dashes (hyphens are OK).
-- Do not use em dashes (—). Use periods to separate sentences instead.
+- Never use em dashes (—) in any plain-English writing (docs, comments, PR descriptions, prose). Use periods to separate sentences instead.
 - Documenting deltas is not important or useful. A developer who has never worked on the project will not gain extra information if you add a comment stating that something was removed or changed because they don't know what was there before. The only time you would be adding a comment for something NOT being there is if its unintuitive for why its not there in the first place.
 
 ### Match statements

Cargo.toml

@@ -11,6 +11,7 @@ members = [
   "engine/packages/cache",
   "engine/packages/cache-purge",
   "engine/packages/cache-result",
+  "engine/packages/cli",
   "engine/packages/config",
   "engine/packages/config-schema-gen",
   "engine/packages/datacenter",
@@ -67,6 +68,7 @@ members = [
   "engine/sdks/rust/ups-protocol",
   "rivetkit-rust/packages/actor-persist",
   "rivetkit-rust/packages/client",
+  "rivetkit-rust/packages/engine-process",
   "rivetkit-rust/packages/rivetkit",
   "rivetkit-rust/packages/rivetkit-core",
   "rivetkit-rust/packages/shared-types",
@@ -619,6 +621,10 @@ members = [
     path = "rivetkit-rust/packages/rivetkit-core"
     version = "=2.3.0-rc.12"
 
+    [workspace.dependencies.rivetkit-engine-process]
+    path = "rivetkit-rust/packages/engine-process"
+    version = "=2.3.0-rc.12"
+
     [workspace.dependencies.rivetkit-shared-types]
     path = "rivetkit-rust/packages/shared-types"
     version = "=2.3.0-rc.12"

docker/build/darwin-arm64.Dockerfile

@@ -70,6 +70,9 @@ RUN --mount=type=cache,id=cargo-registry-darwin-arm64,target=/usr/local/cargo/re
     if [ "$BUILD_TARGET" = "engine" ]; then \
         cargo build -p rivet-engine --bin rivet-engine $CARGO_FLAG --target aarch64-apple-darwin && \
         cp target/aarch64-apple-darwin/$PROFILE_DIR/rivet-engine /artifacts/rivet-engine-aarch64-apple-darwin; \
+    elif [ "$BUILD_TARGET" = "cli" ]; then \
+        cargo build -p rivet-cli --bin rivet $CARGO_FLAG --target aarch64-apple-darwin && \
+        cp target/aarch64-apple-darwin/$PROFILE_DIR/rivet /artifacts/rivet-aarch64-apple-darwin; \
     elif [ "$BUILD_TARGET" = "rivetkit-napi" ]; then \
         cd rivetkit-typescript/packages/rivetkit-napi && \
         NAPI_RS_CROSS_COMPILE=1 napi build --platform $CARGO_FLAG --target aarch64-apple-darwin && \

docker/build/darwin-x64.Dockerfile

@@ -70,6 +70,9 @@ RUN --mount=type=cache,id=cargo-registry-darwin-x64,target=/usr/local/cargo/regi
     if [ "$BUILD_TARGET" = "engine" ]; then \
         cargo build -p rivet-engine --bin rivet-engine $CARGO_FLAG --target x86_64-apple-darwin && \
         cp target/x86_64-apple-darwin/$PROFILE_DIR/rivet-engine /artifacts/rivet-engine-x86_64-apple-darwin; \
+    elif [ "$BUILD_TARGET" = "cli" ]; then \
+        cargo build -p rivet-cli --bin rivet $CARGO_FLAG --target x86_64-apple-darwin && \
+        cp target/x86_64-apple-darwin/$PROFILE_DIR/rivet /artifacts/rivet-x86_64-apple-darwin; \
     elif [ "$BUILD_TARGET" = "rivetkit-napi" ]; then \
         cd rivetkit-typescript/packages/rivetkit-napi && \
         NAPI_RS_CROSS_COMPILE=1 napi build --platform $CARGO_FLAG --target x86_64-apple-darwin && \

docker/build/linux-arm64-musl.Dockerfile

@@ -63,7 +63,13 @@ RUN --mount=type=cache,id=cargo-registry-linux-arm64-musl,target=/usr/local/carg
     if [ "$BUILD_TARGET" = "engine" ]; then \
         RUSTFLAGS="--cfg tokio_unstable -C target-feature=+crt-static -C link-arg=-static-libgcc" \
             cargo build -p rivet-engine --bin rivet-engine $CARGO_FLAG --target aarch64-unknown-linux-musl && \
+        /opt/aarch64-linux-musl-cross/bin/aarch64-linux-musl-strip target/aarch64-unknown-linux-musl/$PROFILE_DIR/rivet-engine && \
         cp target/aarch64-unknown-linux-musl/$PROFILE_DIR/rivet-engine /artifacts/rivet-engine-aarch64-unknown-linux-musl; \
+    elif [ "$BUILD_TARGET" = "cli" ]; then \
+        RUSTFLAGS="-C target-feature=+crt-static -C link-arg=-static-libgcc" \
+            cargo build -p rivet-cli --bin rivet $CARGO_FLAG --target aarch64-unknown-linux-musl && \
+        /opt/aarch64-linux-musl-cross/bin/aarch64-linux-musl-strip target/aarch64-unknown-linux-musl/$PROFILE_DIR/rivet && \
+        cp target/aarch64-unknown-linux-musl/$PROFILE_DIR/rivet /artifacts/rivet-aarch64-unknown-linux-musl; \
     elif [ "$BUILD_TARGET" = "rivetkit-napi" ]; then \
         cd rivetkit-typescript/packages/rivetkit-napi && \
         RUSTFLAGS="--cfg tokio_unstable -C target-feature=-crt-static" \

docker/build/linux-x64-musl.Dockerfile

@@ -62,7 +62,13 @@ RUN --mount=type=cache,id=cargo-registry-linux-x64-musl,target=/usr/local/cargo/
     if [ "$BUILD_TARGET" = "engine" ]; then \
         RUSTFLAGS="--cfg tokio_unstable -C target-feature=+crt-static -C link-arg=-static-libgcc" \
             cargo build -p rivet-engine --bin rivet-engine $CARGO_FLAG --target x86_64-unknown-linux-musl && \
+        /opt/x86_64-unknown-linux-musl/bin/x86_64-unknown-linux-musl-strip target/x86_64-unknown-linux-musl/$PROFILE_DIR/rivet-engine && \
         cp target/x86_64-unknown-linux-musl/$PROFILE_DIR/rivet-engine /artifacts/rivet-engine-x86_64-unknown-linux-musl; \
+    elif [ "$BUILD_TARGET" = "cli" ]; then \
+        RUSTFLAGS="-C target-feature=+crt-static -C link-arg=-static-libgcc" \
+            cargo build -p rivet-cli --bin rivet $CARGO_FLAG --target x86_64-unknown-linux-musl && \
+        /opt/x86_64-unknown-linux-musl/bin/x86_64-unknown-linux-musl-strip target/x86_64-unknown-linux-musl/$PROFILE_DIR/rivet && \
+        cp target/x86_64-unknown-linux-musl/$PROFILE_DIR/rivet /artifacts/rivet-x86_64-unknown-linux-musl; \
     elif [ "$BUILD_TARGET" = "rivetkit-napi" ]; then \
         cd rivetkit-typescript/packages/rivetkit-napi && \
         RUSTFLAGS="--cfg tokio_unstable -C target-feature=-crt-static" \

docker/build/windows-x64.Dockerfile

@@ -70,6 +70,9 @@ RUN --mount=type=cache,id=cargo-registry-windows-x64,target=/usr/local/cargo/reg
     if [ "$BUILD_TARGET" = "engine" ]; then \
         cargo build -p rivet-engine --bin rivet-engine $CARGO_FLAG --target x86_64-pc-windows-gnu && \
         cp target/x86_64-pc-windows-gnu/$PROFILE_DIR/rivet-engine.exe /artifacts/rivet-engine-x86_64-pc-windows-gnu.exe; \
+    elif [ "$BUILD_TARGET" = "cli" ]; then \
+        cargo build -p rivet-cli --bin rivet $CARGO_FLAG --target x86_64-pc-windows-gnu && \
+        cp target/x86_64-pc-windows-gnu/$PROFILE_DIR/rivet.exe /artifacts/rivet-x86_64-pc-windows-gnu.exe; \
     elif [ "$BUILD_TARGET" = "rivetkit-napi" ]; then \
         cd rivetkit-typescript/packages/rivetkit-napi && \
         napi build --platform $CARGO_FLAG --target x86_64-pc-windows-gnu && \

engine/packages/cli/Cargo.toml

@@ -0,0 +1,27 @@
+[package]
+name = "rivet-cli"
+publish = false
+version.workspace = true
+authors.workspace = true
+license.workspace = true
+edition.workspace = true
+
+[[bin]]
+name = "rivet"
+path = "src/main.rs"
+
+[dependencies]
+anyhow.workspace = true
+clap.workspace = true
+dirs.workspace = true
+reqwest.workspace = true
+rivetkit-engine-process.workspace = true
+serde.workspace = true
+serde_json.workspace = true
+tokio.workspace = true
+tracing.workspace = true
+tracing-subscriber.workspace = true
+url.workspace = true
+
+[dev-dependencies]
+tempfile.workspace = true