Access to the Developer Program is gated behind a closed beta.

Build process

Build, deploy, test, and install a managed package using the Developer Platform.

1. Set up your local development environment, install the Rippling CLI, and sign in.
2. Create an editor sandbox and switch your CLI context to it before you deploy.
3. Create a local project with rippling project init.
4. Add components with rippling project add, or write them directly in rippling.manifest.ts.
5. Deploy the project to the editor sandbox with rippling project deploy. Edit the manifest and deploy again to preview each change.
6. When the build is complete, create and publish the package from your Developer account with rippling project package.
7. Create an installer sandbox and link it to the package.
8. Install the published version in that sandbox and test.
9. Create a draft App Shop listing for the published package.
10. Submit the App Shop listing for review and publish after approval.

---

CLI syntax & concepts

The Rippling CLI lets you build the package locally and reuse the same commands to deploy it, publish a version, and install it for testing. Each command runs against a context: your Developer account, an editor sandbox, or an installer sandbox.

See Get started with the Rippling CLI for installation, shared flags, and the command list.

CLI commands follow this standard syntax:

rippling [--context <name>] <command> <subcommand> [--flag value]

• Developer account: Use this primary context to create sandboxes, publish packages, and create an App Shop listing.
• Editor sandbox: The account where you deploy and preview the project while you build.
• Installer sandbox: A separate account where you install and test a published package version.
• Local project: rippling project init creates your files locally without calling the API. Once you’ve edited rippling.manifest.ts and your components, run rippling project deploy <context> to apply the manifest to that sandbox.
• Input handling: Pass --input <file> to provide a full JSON payload, or --input - to read directly from standard input (stdin). Do not combine --input with specific field flags.

---

Set up your local development environment

Install the required CLI binaries, verify dependencies, and configure your credentials.

Verify prerequisites

Ensure Node.js, pnpm, and jq are available locally:

node --version
pnpm --version
jq --version

If jq is missing (macOS), run:

brew install jq

If pnpm fails with Cannot find matching keyid, update Corepack and re-enable:

npm install -g corepack@latest
corepack enable

Install the CLI

Install the Rippling CLI from the public npm registry and verify the installation:

npm install -g @rippling/cli@beta
rippling version

Keep the CLI updated with rippling update. To preserve installed agent skills while upgrading the CLI binary, run:

rippling update --skip-skills

Authenticate the CLI

Authenticate your session and confirm your context configuration:

rippling login
rippling config context list --json
export EDITOR_SANDBOX_NAME="My app editor"
export INSTALLER_SANDBOX_NAME="My app installer"
export PACKAGE_NAME="My app"
export PACKAGE_KEY="my_app"
export INSTALL_KEY="demo"
export LISTING_NAME="My app"

rippling login launches a browser authentication workflow and stores session tokens securely in the system keychain. Ensure developer-account appears in the returned context list.

---

Create an editor sandbox

Prepare the target sandbox for your deployed project. First, check for existing sandboxes:

rippling --context developer-account sandbox list --json

Each company has a sandbox quota of three sandboxes. When that quota is at capacity, sandbox create returns HTTP 403 with You've already created the maximum number of sandboxes.

To reuse an existing sandbox, copy handle from the sandbox you want and skip the next step.

export EDITOR_HANDLE="<handle>"

Provision the sandbox

Sandbox names must be unique within your organization. The company_size property accepts SMALL or MEDIUM.

cat > editor-sandbox-config.json <<'EOF'
{
  "developer": {
    "company_size": "MEDIUM"
  }
}
EOF

rippling --context developer-account sandbox create \
  --name "$EDITOR_SANDBOX_NAME" \
  --type developer \
  --description "Editor sandbox" \
  --config-override-file editor-sandbox-config.json \
  --json

Copy handle from that response, then run:

export EDITOR_HANDLE="<handle>"

To verify status if the sandbox is not ready immediately:

rippling --context developer-account sandbox get --id "<sandbox-id>" --json

Delete a sandbox you no longer need with:

rippling --context developer-account sandbox delete --id "SANDBOX_ID"

Use the editor sandbox

Store the sandbox as the named context. sandbox use also makes that context the default, so later deploy commands push to this account.

rippling --context developer-account sandbox use \
  --alias "$EDITOR_HANDLE" \
  --context-name sandbox-editor

---

Manage your project & package

Create the project locally. Note that this does not deploy or publish the project.

# Optional: create and enter a workspace directory if you don't have one
mkdir -p ~/projects && cd ~/projects

rippling project init --name "my-app"
cd my-app

Note for pnpm 10+

If prompted regarding lifecycle build scripts, approve and rebuild esbuild:

pnpm approve-builds esbuild
pnpm rebuild esbuild

If migrating an older repository with lockfile references pointing to npm.pkg.github.com, configure a local .npmrc file with @rippling:registry=https://registry.npmjs.org/ and execute pnpm install without the --frozen-lockfile flag.

You can also scaffold the first components during init by repeating --with:

rippling project init --name "my-app" \
  --with custom-app:my-app \
  --with function:page \
  --with function:grid

Allowed --with values include:

• custom-app:<name>
• function:<name>
• custom-object:<name>
• agent:<name>
• workflow:<name>

Add components

Add more components to your project with project add, or write them directly in the component files in rippling.manifest.ts. project add is local-only and updates the manifest and source files while preserving what is already included.

rippling project add custom-app --name my-app
rippling project add function --name page
rippling project add function --name grid

Component kinds include custom-app, function, custom-object, agent, and workflow.

rippling project add custom-object --name employee
rippling project add agent --name directory-helper

Keep the marker comments inside rippling.manifest.ts intact so future project add commands know where to inject new entries. Once added, you can build out your logic directly within the local files.

Deploy & preview

Once you’ve completed adding components, deploy the current rippling.manifest.ts from into the editor sandbox. After the deployment finishes, a custom app will populate in the sandbox's UI.

First, cd into the directory in which the project was created:

cd my-app

Validate the project first, then deploy:

rippling --context sandbox-editor project validate
rippling --context sandbox-editor project deploy

Wait for deployment to complete

--timeout sets how long the command waits (the default is 5 minutes). Pass --yes to skip the confirmation prompt:

rippling --context sandbox-editor project deploy --yes --timeout 5m

If needed, make changes to rippling.manifest.ts and the component files, then run project deploy again to verify the changes in the sandbox UI. CLI authentication does not sign you into the browser. After the deployment finishes, a custom app will populate in the sandbox's UI.

Publish the package

Once everything has been deployed and verified via the UI, create and publish an installable package from rippling.manifest.ts. Run these commands from the project root, with the developer-account context.

rippling --context developer-account project package \
  --name "$PACKAGE_NAME" \
  --type managed \
  --key "$PACKAGE_KEY" \
  --description "Employee directory." \
  --json

Copy the version id, then run:

export VERSION_ID="<id>"

rippling --context developer-account package get \
  --package-key "$PACKAGE_KEY" \
  --json

Copy id, then run:

export PACKAGE_ID="<id>"

Notes:

• --name and --type are required when initially publishing the package. --type can be managed or unmanaged.
• --key is optional. If omitted, the key is derived from --name. Set --key when a later install and listing commands need a stable key such as my_app.
• Edit the name and description in package.manifest.ts if the saved package copy needs to differ.
• For later releases, run project package again from the same project.

---

Create the installer sandbox

Install the published package in a second sandbox. First, list your existing sandboxes:

rippling --context developer-account sandbox list --json

To reuse an existing non-editor sandbox, assign its handle directly (for example: export INSTALLER_HANDLE="<handle>"). Otherwise, provision a new installer sandbox:

cat > installer-sandbox-config.json <<'EOF'
{
  "developer": {
    "company_size": "SMALL"
  }
}
EOF

rippling --context developer-account sandbox create \
  --name "$INSTALLER_SANDBOX_NAME" \
  --type developer \
  --description "Installer sandbox" \
  --config-override-file installer-sandbox-config.json \
  --json

Copy handle, then run:

export INSTALLER_HANDLE="<handle>"

Store a sandbox as a named context and set that context as the default. Keep each command on separate lines:

rippling --context developer-account sandbox use \
  --alias "$INSTALLER_HANDLE" \
  --context-name sandbox-installer

rippling config context get --context sandbox-installer --json

Copy companyID, then run:

export INSTALLER_COMPANY_ID="<companyID>"

Link the sandbox to the package in INSTALL mode:

rippling --context developer-account package sandbox link --package-key "$PACKAGE_KEY" --sandbox-company-id "$INSTALLER_COMPANY_ID" --mode INSTALL --json

A successful payload confirms the targeted package_key, sandbox_company_id, "mode": "INSTALL", and "status": "COMPLETE".

---

Install & verify the package

Install the published package into your installer sandbox:

rippling --context sandbox-installer package install \
  --managed \
  --package-key "$PACKAGE_KEY" \
  --install-key "$INSTALL_KEY" \
  --version-id "$VERSION_ID" \
  --json

Copy id, then run:

export MANAGED_INSTALL_ID="<id>"

rippling --context sandbox-installer package installation status \
  --install-id "$MANAGED_INSTALL_ID" \
  --json

Poll package installation status until the state resolves to ACTIVE or ACTIVE_WITH_WARNINGS. If the installation response provides a tracking identifier instead of an installation ID, pass --tracker-id instead.

To open and test the app in the Rippling UI:

1. Sign into your installer sandbox via the Rippling web application (CLI authentication does not persist browser cookies).
2. Navigate directly to /custom-apps/<PACKAGE_KEY>__<INSTALL_KEY>__my_app (for example: /custom-apps/my_app__demo__my_app).

---

Create an App Shop listing

Create a draft listing from the Developer account:

rippling --context developer-account listing create \
  --name "$LISTING_NAME" \
  --package-id "$PACKAGE_ID" \
  --package-version-id "$VERSION_ID" \
  --package-version-name "0.1.0" \
  --json

Copy id, then run:

export LISTING_ID="<id>"

Submit the listing for Rippling review:

rippling --context developer-account listing submit --listing-id "$LISTING_ID"

Upon review and approval, the application will become available for customers to install from the Rippling App Shop.

---

See also

• Get started with the Developer Program
• Get started with the Rippling CLI
• When to use Rippling primitives
• Overview of developer sandboxes