---
url: https://veles.beyondthecloud.dev/docs/developer/cli-plugin.md
description: Flags, steps, output and errors of sf veles setup.
---

# sf veles CLI plugin

`@beyondthecloud/sf-veles` adds one command to the Salesforce CLI: `sf veles setup`. It sets up Veles on an existing scratch org or sandbox and connects it to your Hub.

```bash
sf plugins install @beyondthecloud/sf-veles
sf veles setup --target-org <alias> [--target-dev-hub <hub>] [--group <name>]... [--installation-key <key>]
```

## Prerequisites

* The target org exists and is authorised in the CLI. The command does not create orgs.
* Veles 0.110.0 or later on the Hub. The command checks both versions before changing anything.
* Your Hub user holds **Veles Developer** (included in **Veles Admin**).
* Scratch org: a group marked **Scratch Org Group** exists on the Hub, or you pass `--group`.
* Sandbox: its environment row already exists on the Hub (**New Environment > From Sandbox**). `--group` is refused for a sandbox; it takes its groups from that row.

## Flags

| Flag                    | Short | Meaning                                                                                                    |
| ----------------------- | ----- | ---------------------------------------------------------------------------------------------------------- |
| `--target-org`          | `-o`  | The scratch org or sandbox to set up. Required.                                                            |
| `--target-dev-hub`      | `-v`  | The Hub. Defaults to the CLI's default Dev Hub.                                                            |
| `--group`               | `-g`  | Environment group on the Hub. Repeatable, first wins. Scratch orgs only.                                   |
| `--installation-key`    | `-k`  | Installation key for the package, if it has one.                                                           |
| `--integration-permset` |       | Name of the unmanaged clone of **Veles Hub Integration** to create and assign. Default `VelesIntegration`. |
| `--integration-user`    |       | Username in the target org to set up as the integration user. Default: the CLI user.                       |
| `--verbose`             |       | Sub-steps, warnings and a summary.                                                                         |
| `--json`                |       | Machine-readable result; exit code reflects success.                                                       |

## What it does

1. **Resolving org & Hub**: registers the org on the Hub (environment row and connection token).
2. **Installing Veles package**: installs the Hub's version if Veles is missing.
3. **Deploying connection metadata**: the Remote Site Setting for the Hub.
4. **Configuring Hub connection**: Hub URL, Hub integration username, the org's own environment row.
5. **Pre-authorizing integration user**: clones the permission set, assigns it, grants a seat if needed, pre-authorises it on the ECA. Problems here are warnings, not failures.
6. **Connecting to Hub**.
7. **Setting up environment (RSS)**: waits up to 3 minutes for the Hub's Remote Site Setting and for the Hub to sign in to the org.

Success ends with `Veles setup complete.` A failed step prints `✖`, the reason as `Error (1): ...` with a `Try this:` hint, and exits 1.

## Errors you may see

| Error                                                    | Meaning                                                                                       |
| -------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| `VelesDev permission set not assigned.`                  | Assign **Veles Developer** or **Veles Admin** to your user on the Hub.                        |
| `No Environment Group is marked as a Scratch Org Group.` | Create one on the Hub, or pass `--group`.                                                     |
| `Sandbox not found on this Hub`                          | Add the sandbox on the Hub first.                                                             |
| `The Hub <url> refused to connect this org: ...`         | Usually the connected-orgs limit of your plan. The text says so.                              |
| `The Hub cannot sign in to this org as <user>: ...`      | The integration user is not pre-authorised in the target org. Finish Step 1 of its Setup tab. |
| `Connecting to Hub did not finish within 3 minutes`      | Run the command again; it skips what is done.                                                 |