rippling-onboarding CLI

rippling-onboarding is a command-line tool for onboarding your company to Rippling. The intended workflow is to install the CLI, then let an AI assistant (Claude Code, Cursor, Codex, or ChatGPT Desktop) drive onboarding on your behalf.

Requires Node.js 18 or later.

Installation

You can install the CLI in either of these ways:

• Agent-led — ask your AI assistant to install it
• Manual — run npm yourself

Agent-led installation

In ChatGPT Desktop, Claude Code, or the Claude Desktop app (Code tab), paste:

Install this npm package for me https://www.npmjs.com/package/@rippling/rippling-onboarding and make sure you run rippling-onboarding version to check that the package has been installed.

Manual installation

npm install -g @rippling/rippling-onboarding
rippling-onboarding version

To upgrade later:

npm update -g @rippling/rippling-onboarding
# or
rippling-onboarding upgrade

Getting Started

After the CLI is installed, open your AI assistant and ask it to start onboarding. For example:

"Please onboard my company to Rippling."

The AI will handle everything — creating your account if you don't have one, fetching your onboarding plan, walking through each step, and submitting the required data. It will ask you for input where needed.

If your AI assistant can't find the CLI, it may not have access to your system PATH. Copy the binary into the root of the workspace you are running your AI assistant from, then try again:

cp "$(which rippling-onboarding)" /path/to/your/workspace/rippling-onboarding

Manual Command Reference

While the AI handles most commands, you can also run them directly.

login

Opens a browser window for OAuth authentication. Credentials are stored securely in your OS keychain.

rippling-onboarding login

logout

Clears all stored OAuth tokens and API keys from the keychain.

rippling-onboarding logout

create-account

Creates a new Rippling company account.

rippling-onboarding create-account \
  --product-type PAYROLL \
  --email [email protected] \
  --company-name "Acme Corp" \
  --first-name Jane \
  --last-name Smith \
  --national-number 5550001234

--product-type is one of: PAYROLL, IT, TIME, or SPEND.

install-skills

Installs onboarding skills into your AI assistant's config directories.

rippling-onboarding install-skills                      # all supported agents
rippling-onboarding install-skills --agent claude-code
rippling-onboarding install-skills --agent cursor
rippling-onboarding install-skills --agent codex
rippling-onboarding install-skills --force              # overwrite existing files
rippling-onboarding install-skills --dry-run            # preview without writing

After upgrading the CLI, re-install with --force to replace local skill files with the versions embedded in the new binary.

plan

rippling-onboarding plan          # table view
rippling-onboarding plan --json   # raw JSON

step

rippling-onboarding step <step_id>

action

rippling-onboarding action <step_id> submit --data '{"field": "value"}'
rippling-onboarding action <step_id> skip
rippling-onboarding action <step_id> review_run --data '{"query_id": "q1", "arguments": {}}'
rippling-onboarding action <step_id> review_complete

upload-document

rippling-onboarding upload-document --file /path/to/file.pdf
rippling-onboarding upload-document --file /path/to/onboarding-doc.pdf --provider-id general_onboarding
rippling-onboarding upload-document --file /path/to/payroll-export.csv --provider-id payroll_import
rippling-onboarding upload-document --file /path/to/benefits-plan.pdf --provider-id benefits
rippling-onboarding upload-document --file /path/to/onboarding-doc.pdf --base-legal-entity-id <entity_id>

Uploads the file to Rippling storage, registers it in the onboarding document library, and prints the document ID and S3 URL. --provider-id defaults to general_onboarding; use --provider-id payroll_import only for prior payroll export files; use --provider-id benefits for SBC and plan documents.

Pass --base-legal-entity-id (repeatable) to scope the document to one or more base legal entities immediately after registration. To set entities on a document that's already registered:

rippling-onboarding update-document-entity <document_id> --base-legal-entity-id <entity_id>

upgrade

Upgrades the CLI to the latest version.

rippling-onboarding upgrade

version

Prints the current version of the CLI.

rippling-onboarding version

config

Manages the CLI configuration file at ~/.rippling/config.

rippling-onboarding config create    # create a config file interactively

departments

List or create company departments. Useful when onboarding steps need department IDs.

rippling-onboarding org departments list
rippling-onboarding org departments list --json
rippling-onboarding org departments list --limit 50

rippling-onboarding org departments create --name "Engineering"
rippling-onboarding org departments create --name "Platform" --parent-id <parent_department_id>

work-locations

List or create work locations (offices / sites). Useful when steps need location IDs.

rippling-onboarding org work-locations list
rippling-onboarding org work-locations list --json

rippling-onboarding org work-locations create \
  --name "SF HQ" \
  --address-type WORK \
  --street-address "123 Market St" \
  --locality "San Francisco" \
  --region "CA" \
  --postal-code "94105" \
  --country US

--address-type is one of: HOME, WORK, OTHER.

titles

List or create job titles.

rippling-onboarding org titles list
rippling-onboarding org titles create --name "Software Engineer"

levels

List company levels (job levels / bands). Read-only.

rippling-onboarding org levels list
rippling-onboarding org levels list --json
rippling-onboarding org levels list --limit 50

employment-types

List employment types (e.g. full-time, contractor). Read-only.

rippling-onboarding org employment-types list
rippling-onboarding org employment-types list --json
rippling-onboarding org employment-types list --limit 50

teams

List teams. Read-only.

rippling-onboarding org teams list
rippling-onboarding org teams list --json
rippling-onboarding org teams list --limit 50

job-dimensions

List, get, create, update, or delete job dimensions (categories for job codes).

rippling-onboarding org job-dimensions list
rippling-onboarding org job-dimensions list --json
rippling-onboarding org job-dimensions get <job_dimension_id>

rippling-onboarding org job-dimensions create --data '{"name":"Department","roster_type":"PER_DIMENSION"}'
rippling-onboarding org job-dimensions update <job_dimension_id> --data '{"name":"Cost Center"}'
rippling-onboarding org job-dimensions delete <job_dimension_id>

job-codes

List, get, create, update, or delete job codes (labels within a job dimension).

rippling-onboarding org job-codes list
rippling-onboarding org job-codes list --json
rippling-onboarding org job-codes get <job_code_id>

rippling-onboarding org job-codes create --data '{"name":"Engineering","job_dimension_id":"<job_dimension_id>"}'
rippling-onboarding org job-codes update <job_code_id> --data '{"name":"Eng"}'
rippling-onboarding org job-codes delete <job_code_id>

supergroups

List supergroups and manage members / inclusion / exclusion members.

rippling-onboarding org supergroups list
rippling-onboarding org supergroups list --json
rippling-onboarding org supergroups list --limit 50

rippling-onboarding org supergroups members list <supergroup_id>

rippling-onboarding org supergroups inclusion-members list <supergroup_id>
rippling-onboarding org supergroups inclusion-members update <supergroup_id> --data '{...}'

rippling-onboarding org supergroups exclusion-members list <supergroup_id>
rippling-onboarding org supergroups exclusion-members update <supergroup_id> --data '{...}'

group-rule

Interactively build a GroupRuleConfig JSON payload (prompts for real IDs from the Platform API). Omit --submit to print JSON only; pass a step ID to submit it as an onboarding action.

rippling-onboarding group-rule build
rippling-onboarding group-rule build --submit <step_id>

users

List company user accounts (login/identity records). A user is who someone is in Rippling.

rippling-onboarding people users list
rippling-onboarding people users list --json
rippling-onboarding people users list --limit 50

workers

List worker / employment records (role records tied to a user). A worker is someone's job at the company — status, work email, and a link back to their user via user_id.

One user can map to a worker record. Many onboarding and group-rule flows need the worker ID (also called a role ID), not the user ID.

rippling-onboarding people workers list
rippling-onboarding people workers list --json
rippling-onboarding people workers list --limit 50
rippling-onboarding people workers list --status ACTIVE
rippling-onboarding people workers list --user-id <user_id>

Users vs workers: users are account identities. workers are employment/role records linked to a user. When a step or group rule asks for a person/role ID, use the worker ID.

cart

Manage product selections.

rippling-onboarding cart list
rippling-onboarding cart add PAYROLL
rippling-onboarding cart remove PAYROLL
rippling-onboarding cart pricing
rippling-onboarding cart details PAYROLL

Run any command with --help for full usage.

Global Flags

| Flag | Description | |---|---| | --config | Path to a custom config file | | -c, --context | Context to use when managing multiple accounts | | -v, --verbose | Enable verbose/debug logging | | -h, --help | Show help for any command |

Common issues

rippling-onboarding: command not found

The npm global bin directory is not on your PATH. Find it with:

npm prefix -g

Then add <that-path>/bin to your shell PATH, or reinstall after confirming Node/npm are on PATH. Restart the terminal afterward.

"Apple could not verify “rippling-onboarding” is free of malware…"

1. Open System Settings → Privacy & Security.
2. Scroll down. If macOS blocked the app, you may see a message saying it was blocked.
3. Click Open Anyway.
4. Confirm when prompted.

Claude Desktop app is not invoking the CLI

Make sure you're on the Code tab in the Claude Desktop app.