Workbench CLI commands

Use the Workbench CLI to clone, edit, test, publish, and inspect collection modules from your local machine.

Run rp --help or rp <command> --help for the full flag list — this page may lag the CLI.

Quick reference

Command	Purpose
`rp clone -cm`	Initial download of a collection module
`rp pull`	Re-sync local files from Root
`rp push`	Upload local changes as a new draft
`rp publish`	Promote the draft to a new live version
`rp logs`	Tail collection module execution logs
`rp test`	Run unit tests
`rp diff`	Show local vs. remote differences

rp invoke and rp generate are product-module-only and aren't documented on this page.

Before you start

Run rp clone once for a collection module. It writes a .root-auth file with your API key and a .root-config.json file with the module identity. Subsequent rp pull, rp push, rp publish, and operational commands read these files automatically, so they do not need the API key or collection module key as arguments.

After cloning, run cd <collection-module-directory> before using the other commands.

Authoring lifecycle

`rp clone -cm`

rp clone -cm <api-key> <collection-module-key> [--live] [--host <host>]

Clones a collection module from Root to your local machine for local editing. By default, clones the current draft.

The -cm flag tells the CLI you're cloning a collection module rather than a product module — the clone command is shared between both.

Flag	Purpose
`-l`, `--live`	Clone the most recent live version instead of the draft
`-h`, `--host <host>`	Use a specific Root host

`rp pull`

rp pull [--live] [--force] [--no-sort]

Pulls files and configuration from Root and overwrites the local files. By default, pulls the current draft.

Flag	Purpose
`-l`, `--live`	Pull the most recent live version instead of the draft
`-f`, `--force`	Force the pull even when local changes may be overwritten
`-ns`, `--no-sort`	Preserve file ordering instead of sorting generated output

`rp push`

rp push [--force] [--no-sort]

Pushes local files to Root, creating a new draft version of the collection module. Draft versions are usable from the sandbox dashboard and API for testing.

Flag	Purpose
`-f`, `--force`	Force the push when the CLI detects a conflict or unsafe change
`-ns`, `--no-sort`	Preserve file ordering instead of sorting generated output

`rp publish`

rp publish [--force]

Promotes the current draft to a new live version of the collection module. Publishing bumps the sandbox version automatically and prompts you for confirmation unless --force is passed.

Live versions are immutable. Existing policies stay bound to the version they were issued against.

Requires rp ≥ 1.4.26.

Flag	Purpose
`--force`	Publish without an interactive confirmation prompt

Operational commands

`rp logs`

rp logs [options]

Tails execution logs for the collection module. Calls to console.log/warn/error/debug/info from your hooks are captured and stored in DynamoDB for about 30 days.

Flag	Purpose
`-w`, `--watch`	Stream logs in real time
`-t`, `--time <duration>`	Set the lookback window, for example `30m`, `1h`, or `2d`
`-l`, `--level <level>`	Filter by `info`, `warn`, `error`, or `debug`
`-p`, `--policy-id <id>`	Filter to a single policy
`-f`, `--function-name <name>`	Filter to one lifecycle hook
`-s`, `--status <status>`	Filter by `COMPLETE`, `FAILED`, or `RUNNING`
`-c`, `--count <n>`	Limit the maximum number of log lines

Example:

rp logs -w -l error -t 1h

`rp test`

rp test [options]

Runs unit tests under code/unit-tests/.

Flag	Purpose
`-u`, `--unit`	Run only unit tests
`-w`, `--watch`	Re-run on file change

`rp diff`

rp diff [options]

Shows what has changed locally compared with the remote draft. Use this before rp push to review the files that will be uploaded.

Flag	Purpose
`-c`, `--code`	Show code changes only
`-w`, `--workflows`	Show workflow JSON changes only
`-ut`, `--unit-tests`	Show unit test changes only
`-rm`, `--read-me`	Show README changes only
`-d`, `--documents`	Show document changes only
`-ad`, `--api-docs`	Show API documentation changes only

Workbench CLI commands

Quick reference

Before you start

Authoring lifecycle

rp clone -cm

rp pull

rp push

rp publish

Operational commands

rp logs

rp test

rp diff