# Packages

> Status: Beta

> For the complete documentation index, see [llms.txt](https://developer.rippling.com/llms.txt). Every page is available as Markdown by adding .md to its URL.

> Closed beta. Create and manage packages using the Rippling CLI.

Source: https://developer.rippling.com/documentation/rippling-platform/rippling-cli/packages

> **Rippling:**
> Access to the Rippling CLI is gated behind the **Developer Program**, which is currently in a closed beta.

## Package

### `rippling package create`

Creates a package in the developer account.

| Flag | Type | Required | Description |
| --- | --- | --- | --- |
| `--name` | string | yes | Display name. |
| `--key` | string | yes | Unique package key in the publisher company. |
| `--type` | string | yes | Package type. Allowed values: `MANAGED`, `UNMANAGED`. |
| `--description` | string | no | Package description. |
| `--input` | file | no | Full JSON body. Cannot be combined with field flags. |
| `--json` | boolean | no | Print the response as indented JSON. |

*Example:*

```bash
rippling --context developer-account package create --name "My App" --key my_app --type MANAGED
rippling --context developer-account package create --name "My App" --key my_app --type MANAGED --description "Recognition workflows" --json
```

### `rippling package list`

Lists packages.

| Flag | Type | Required | Description |
| --- | --- | --- | --- |
| `--cursor` | string | no | Pagination cursor. |
| `--filter` | string | no | Filter expression. |
| `--limit` | string | no | Maximum results. Default 10, maximum 100. |
| `--order-by` | string | no | Sort expression. |
| `--json` | boolean | no | Print the response as indented JSON. |

*Example:*

```bash
rippling --context developer-account package list
rippling --context developer-account package list --json
```

### `rippling package get`

Reads one package.

| Flag | Type | Required | Description |
| --- | --- | --- | --- |
| `--package-key` | string | yes | Package key in the publisher company. |
| `--json` | boolean | no | Print the response as indented JSON. |

*Example:*

```bash
rippling package get --package-key my_app
rippling package get --package-key my_app --json
```

### `rippling package update`

Updates a package's display name, description, or type. This does not change version components.

| Flag | Type | Required | Description |
| --- | --- | --- | --- |
| `--package-key` | string | yes | Package key to update. |
| `--package-display-name` | string | no | New display name. |
| `--description` | string | no | New description. |
| `--package-type` | string | no | Package type. Allowed values: `MANAGED`, `UNMANAGED`. |
| `--body-package-key` | string | no | Package key field inside the request body. |
| `--input` | file | no | Full JSON body. Cannot be combined with field flags. |
| `--json` | boolean | no | Print the response as indented JSON. |

*Example:*

```bash
rippling package update --package-key my_app --description "Updated description"
rippling package update --package-key my_app --input package-update.json
```

## Sandbox link

### `rippling package sandbox link`

Links a sandbox company to a package. Run this from the developer account and use the sandbox context's `companyID` for `--sandbox-company-id`.

| Flag | Type | Required | Description |
| --- | --- | --- | --- |
| `--package-key` | string | yes | Package key to link. |
| `--sandbox-company-id` | string | yes | Company ID of the sandbox. |
| `--mode` | string | yes | Link mode. Allowed values: `EDIT`, `INSTALL`. |
| `--input` | file | no | Full JSON body. Cannot be combined with field flags. |
| `--json` | boolean | no | Print the response as indented JSON. |

*Example:*

```bash
rippling --context developer-account package sandbox link --package-key my_app --sandbox-company-id <editor-company-id> --mode EDIT --json
rippling --context developer-account package sandbox link --package-key my_app --sandbox-company-id <installer-company-id> --mode INSTALL --json
```

### `rippling package sandbox status`

Reads a sandbox link when a package sandbox link returns a tracker ID.

| Flag | Type | Required | Description |
| --- | --- | --- | --- |
| `--tracker-id` | string | yes | Package sandbox link tracker ID. |
| `--json` | boolean | no | Print the response as indented JSON. |

*Example:*

```bash
rippling package sandbox status --tracker-id <link-tracker-id> --json
```

## Versions

### `rippling package version create`

Creates an empty unpublished draft. Run this from the developer account.

| Flag | Type | Required | Description |
| --- | --- | --- | --- |
| `--package-key` | string | yes | Package key. |
| `--version-number` | string | yes | Semantic version, such as `1.0.0`. |
| `--description` | string | no | Draft description. |
| `--input` | file | no | Full JSON body. Cannot be combined with field flags. |
| `--json` | boolean | no | Print the response as indented JSON. |

*Example:*

```bash
rippling --context developer-account package version create --package-key my_app --version-number 1.0.0 --json
rippling --context developer-account package version create --package-key my_app --input version.json --json
```

### `rippling package version next`

Creates the next unpublished draft from the latest published version. Run this from the editor sandbox.

| Flag | Type | Required | Description |
| --- | --- | --- | --- |
| `--package-key` | string | yes | Package key. |
| `--version-number` | string | yes | Version number for the new draft. |
| `--description` | string | no | Draft description. |
| `--input` | file | no | Full JSON body. Cannot be combined with field flags. |
| `--json` | boolean | no | Print the response as indented JSON. |

*Example:*

```bash
rippling --context sandbox-editor package version next --package-key my_app --version-number 1.0.1 --json
rippling --context sandbox-editor package version next --package-key my_app --input next-version.json --json
```

### `rippling package version list`

Lists versions of a package.

| Flag | Type | Required | Description |
| --- | --- | --- | --- |
| `--package-key` | string | yes | Package key. |
| `--cursor` | string | no | Pagination cursor. |
| `--limit` | string | no | Maximum results. Default 10; maximum 100. |
| `--json` | boolean | no | Print the response as indented JSON. |

*Example:*

```bash
rippling package version list --package-key my_app
rippling package version list --package-key my_app --json
```

### `rippling package version get`

Reads one package version.

| Flag | Type | Required | Description |
| --- | --- | --- | --- |
| `--version-id` | string | yes | Package version ID. |
| `--json` | boolean | no | Print the response as indented JSON. A published version reports `is_published: true`. |

*Example:*

```bash
rippling package version get --version-id <version-id>
rippling package version get --version-id <version-id> --json
```

### `rippling package version update`

Edits the description of an unpublished version.

| Flag | Type | Required | Description |
| --- | --- | --- | --- |
| `--version-id` | string | yes | Draft version ID. |
| `--description` | string | no | New description. |
| `--input` | file | no | Full JSON body. Cannot be combined with field flags. |
| `--json` | boolean | no | Print the response as indented JSON. |

*Example:*

```bash
rippling package version update --version-id <draft-version-id> --description "Release notes"
rippling package version update --version-id <draft-version-id> --input version-update.json
```

## Components

### `rippling package version components available`

Lists components in the editor sandbox that can be added to a draft. Omit `--q` to include custom object list views.

| Flag | Type | Required | Description |
| --- | --- | --- | --- |
| `--q` | string | no | Text search. Limits the result to a subset of component types. |
| `--limit` | string | no | Maximum search results when `--q` is set. |
| `--json` | boolean | no | Print the response as indented JSON. |

*Example:*

```bash
rippling --context sandbox-editor package version components available --json
rippling --context sandbox-editor package version components available --q Kudos --limit 100 --json
```

### `rippling package version components update`

Adds, removes, or refreshes components on an unpublished draft. Run this from the editor sandbox. `--nodes-file` is the `nodes` array and is required for `ADD` and `REMOVE`.

| Flag | Type | Required | Description |
| --- | --- | --- | --- |
| `--version-id` | string | yes | Draft package version ID. |
| `--action` | string | yes | Update action. Allowed values: `ADD`, `REMOVE`, `REFRESH`. |
| `--nodes-file` | file | no | Component identifiers. `-` reads `stdin`. Required for `ADD` and `REMOVE`. |
| `--is-preview-mode` | boolean | no | Compute the diff without saving. Default false. |
| `--input` | file | no | Full JSON body. Cannot be combined with field flags. |
| `--json` | boolean | no | Print the response as indented JSON. |

*Example:*

```bash
rippling --context sandbox-editor package version components update --version-id <draft-version-id> --action ADD --nodes-file nodes.json --json
rippling --context sandbox-editor package version components update --version-id <draft-version-id> --action REFRESH --is-preview-mode=true --json
```

### `rippling package version components status`

Reads a component update. Repeat while `status` is `IN_PROGRESS`. Success is `COMPLETE` with `error_message` null.

| Flag | Type | Required | Description |
| --- | --- | --- | --- |
| `--tracker-id` | string | yes | The `id` or `tracker_id` returned by package version components update. |
| `--json` | boolean | no | Print the response as indented JSON. |

*Example:*

```bash
rippling --context sandbox-editor package version components status --tracker-id <update-tracker-id> --json
```

## Publish

### `rippling package version publish`

Publishes a completed draft. Run this from the editor sandbox after component updates are complete.

| Flag | Type | Required | Description |
| --- | --- | --- | --- |
| `--version-id` | string | yes | Draft version ID. |
| `--json` | boolean | no | Print the response as indented JSON. |

*Example:*

```bash
rippling --context sandbox-editor package version publish --version-id <draft-version-id> --json
```

## Install & upgrade

### `rippling package install`

Check progress with package installation status. Use `--install-id` for a managed install's returned `id`, or `--tracker-id` for an unmanaged install's tracker `id`.

| Flag | Type | Required | Description |
| --- | --- | --- | --- |
| `--version-id` | string | yes | Published package version ID. |
| `--managed` | boolean | no | Use a managed installation. |
| `--package-key` | string | no | Package key. Required with `--managed`. |
| `--install-key` | string | no | Install key. Required with `--managed`. |
| `--input` | file | no | Full JSON body. Cannot be combined with field flags. |
| `--json` | boolean | no | Print the response as indented JSON. |

*Example:*

```bash
rippling --context sandbox-installer package install --version-id <published-version-id> --json
rippling --context sandbox-installer package install --managed --package-key my_app --install-key docs --version-id <published-version-id> --json
```

### `rippling package installation status`

Reads install progress or a managed installation. Pass exactly one of `--install-id` or `--tracker-id`.

| Flag | Type | Required | Description |
| --- | --- | --- | --- |
| `--install-id` | string | no | Managed installation ID returned by package install. |
| `--tracker-id` | string | no | Tracker `id` returned by an unmanaged package install. |
| `--json` | boolean | no | Print the response as indented JSON. |

*Example:*

```bash
rippling package installation status --install-id <managed-install-id> --json
rippling package installation status --tracker-id <install-tracker-id> --json
```

### `rippling package installation upgrades`

Lists published versions available for upgrade.

| Flag | Type | Required | Description |
| --- | --- | --- | --- |
| `--package-key` | string | yes | Package key. |
| `--install-key` | string | yes | Install key. |
| `--json` | boolean | no | Print the response as indented JSON. |

*Example:*

```bash
rippling package installation upgrades --package-key my_app --install-key docs
rippling package installation upgrades --package-key my_app --install-key docs --json
```

### `rippling package upgrade`

Starts an upgrade of a managed installation.

| Flag | Type | Required | Description |
| --- | --- | --- | --- |
| `--package-key` | string | yes | Package key. |
| `--install-key` | string | yes | Install key. |
| `--version-id` | string | yes | Published version to upgrade to. |
| `--input` | file | no | Full JSON body. Cannot be combined with field flags. |
| `--json` | boolean | no | Print the response as indented JSON. |

*Example:*

```bash
rippling --context sandbox-installer package upgrade --package-key my_app --install-key docs --version-id <published-version-id>
rippling --context sandbox-installer package upgrade --package-key my_app --install-key docs --version-id <published-version-id> --json
```

### `rippling package installation upgrade-status`

Reads an in-progress upgrade. This command checks once and does not wait.

| Flag | Type | Required | Description |
| --- | --- | --- | --- |
| `--tracker-id` | string | yes | Tracker ID returned by package upgrade. |
| `--json` | boolean | no | Print the response as indented JSON. |

*Example:*

```bash
rippling package installation upgrade-status --tracker-id <upgrade-tracker-id> --json
```

### `rippling package uninstall`

Starts an uninstall of a managed installation.

| Flag | Type | Required | Description |
| --- | --- | --- | --- |
| `--package-key` | string | yes | Package key. |
| `--install-key` | string | yes | Install key. |
| `--input` | file | no | Full JSON body. Cannot be combined with field flags. |
| `--json` | boolean | no | Print the response as indented JSON. |

*Example:*

```bash
rippling --context sandbox-installer package uninstall --package-key my_app --install-key docs
rippling --context sandbox-installer package uninstall --package-key my_app --install-key docs --json
```

### `rippling package installation uninstall-status`

Reads an in-progress uninstall. This command checks once and does not wait.

| Flag | Type | Required | Description |
| --- | --- | --- | --- |
| `--tracker-id` | string | yes | Tracker ID returned by package uninstall. |
| `--json` | boolean | no | Print the response as indented JSON. |

*Example:*

```bash
rippling package installation uninstall-status --tracker-id <uninstall-tracker-id> --json
```