org refresh sandbox command - Useful or not?

[shetzel]

We have commands to create, delete, and resume sandboxes from the sf CLI. There is currently no way to refresh/update a sandbox from the CLI.

Would this be a useful command? If so, tell us why?

What are your usecases?

• Automate refreshes via CI?
• Refresh a sandbox you're authed to from the CLI?

[sjurgis]

Yes, very much so. With instant Hyperforce cloning (if it's coming back) you could do a refresh after each PR merge!

IMO aligns very well with recent change Select Who Has Access To a Sandbox

[rbklaassen]

It would be useful because you could perform this task with a non-UI user license, like the integration user, from the local CLI. Also, this task could be embedded in an automated pipeline, so that there's no need to login to the production org to do so.

[sjurgis]

Good point - sometimes people shouldn't have prod access but should be able to clone a sandbox somehow.

[infocynic]

My use for something like this would be to automatically refresh a staging environment that we use to test complex deployments, like those with pre or post tasks (apex scripts, data loads, manual changes) that are hard if not impossible to test safely in production. This is in a "post-UAT" state where we just want to validate and rehearse the deployment. Setting up a nightly job to refresh that sandbox so it's ready first-thing in my morning would mean I could get rocking on that task without having to wait for the sandbox lottery (earlier this week, a dev sandbox took 7.5 hours to refresh, which is atypical, but if I could have scripted it, that would have been great).

Keeping the same sandbox name means I don't have to update URLs or anything for existing scripts that are prepared, just update an auth token.

[RupertBarrow]

Yes !!

This is necessary for CI of org-dependent packages : every new package version should be installed in a refreshed sandbox for tests.

My need is to designate 1 such sandbox and refresh it automatically every night + run post-install Apex, and keep the possibility to auth

[mcarvin8]

Yes, please allow this.

This would be useful to allow my team to initiate their own sandbox refreshes from a CI pipeline through an integration user.

We currently have to use the Tooling API to allow this in our CI pipeline, but we would prefer to use the Salesforce CLI since we use the CLI for our deployment jobs.

[mcarvin8]

I would like the ability to declare the Sandbox Name via the command line and declare other attributes like Apex Class ID, Sandbox License, etc. in the sandbox definition file.

Desired command usage:

sf org create sandbox --name Carvin -f config/dev-sandbox-def.json

When trying to run the command shown above, this error is thrown:

Error (2): The following errors occurred:
  --definition-file=config/dev-sandbox-def.json cannot also be provided when using --name
  --name={NAME} cannot also be provided when using --definition-file

As long as the user provides the sandbox name in 1 of 2 ways (command line arg or sandbox definition file), it should not throw an error. If the user provides it in both or none, then throw an error.

[shetzel]

@mcarvin8 - Seems reasonable, and inline with what org create scratch does as well. Is name the only override? I'd think that would be the most common, but maybe license type as well (another already existing flag)?

[mcarvin8]

@shetzel - having license type be another override makes sense to me as well.

[shetzel]

@mcarvin8 - look for this support in the next CLI release candidate tomorrow. In fact, I believe it's in the nightly created last night so you could even try it there.

[alan-morey]

I would love to see this feature implemented. My team and I always use the Salesforce UI for all our sandbox creation/refreshes, partly because there is no option in the CLI to refresh them and we are mostly refreshing sandboxes rather than creating new sandboxes. We have a bunch of predefined sandbox names that we reuse and they are configured with various jobs in our CI/CD for running tests, validating deployments, etc...

Having sandbox refresh support in the CLI would also be benefical for automating the entire sandbox refresh process with CI/CD systems. Currently we have team members manually performing refreshes, this occurs during common work hours and can lead to some false-postive build failures as the environments get activated and replaced. So being able to schedule a refresh to occur during the night when it is less likely to conflict with others would be ideal.

Additionally, as others have mentioned we would like to be able to limit the number of users that have access to Production. Many of our team members have access to Production for the purpose of being able to create/refresh sandboxes. So if we were able to provide our team with the ability to create/refresh from CI/CD instead we could remove their access to Production.

[shetzel]

W-15042183

[mpaul1]

Please implement this functionality!

[shetzel]

Here is the proposed command. Please provide feedback especially if it would not solve your usecases. If it looks good, just leave a 👍

UPDATE: This is outdated. See the latest command help output in a February 27th post.

org refresh sandbox

Refresh (update) a sandbox org by the sandbox name.

USAGE
  $ sf org refresh sandbox -n <value> -o <value> [--json] [--auto-activate] [-w <value> | --async] [-i <value>
    | ] [--no-prompt]

FLAGS
  -i, --poll-interval=<seconds>  [default: 30 seconds] Number of seconds to wait between status polling
                                 requests.
  -n, --name=<value>             (required) Name of the existing sandbox org in your production org.
  -o, --target-org=<value>       (required) Username or alias of the production org that contains the sandbox
                                 license.
  -w, --wait=<minutes>           [default: 30 minutes] Number of minutes to poll for sandbox refresh status.
      --async                    Request the sandbox refresh, but don't wait for it to complete.
      --[no-]auto-activate       [default: true] Activates the sandbox after successful refresh.
      --no-prompt                Don't prompt for confirmation about the sandbox configuration.

GLOBAL FLAGS
  --json  Format output as json.

EXAMPLES
  Refresh the sandbox named "devSbx1". The production org that contains the sandbox license has the alias
  "prodOrg".

    $ sf org refresh sandbox -n devSbx1 --target-org prodOrg

[shetzel]

@jongpie - The command docs for org create sandbox contain details for the --definition-file flag, which refers to the Create a Sandbox Definition File doc. If you want to define a template during org create sandbox you would add it to the definition file. The same template ID would be used for refresh.

Would you want to change the template ID as part of a refresh? The SandboxInfo API allows it, but before supporting that usecase I'd first want to know it's something people plan to use.

[mcarvin8]

Just my two cents, I would prefer to have the definition file be used to change attributes during refreshes like sandbox template, license, apex class ID, public group ID, etc. Like you said, the tooling API allows you to change those attributes for refreshes, which is something my team was actively using until public groups were removed.

I think the CLI should replicate what the tooling API allows for refreshes since I think it's useful to change things if required. By default, if you don't supply changes, use what the sandbox was created with.

[shetzel]

I think the CLI should replicate what the tooling API allows for refreshes since I think it's useful to change things if required. By default, if you don't supply changes, use what the sandbox was created with.

Gotcha, thanks for your feedback Matt!

[jongpie]

@shetzel I don't have an actual need for this right now (I don't manage sandboxes in my current role), so I wouldn't consider it a high priority thing.

But in a previous role, I managed several sandboxes for a big implementation, and we frequently used different sandbox templates when doing refreshes:

• We had a few partial & full-copy sandboxes. During some QA & UAT test cycles, we'd refresh the sandboxes & would use different templates based on what area of functionality we planned to test. The refresh process was done manually (in the prod org, under Setup --> Sandboxes).
• We also wanted to limit who had prod access, but we had a huge dev team (20+ Salesforce developers), so we needed a few people to have prod access to help manage sandbox refreshes.
• Ideally, I would have been able to setup a pipeline job (we used Jenkins at the time) that would use a prod API-only user (for handling the actual sandbox create/refresh commands), with the ability to specify in the pipeline job a sandbox template to use.

If the new proposed command had existed, and it had a way to specify a sandbox template (either using a definition file, or as a separate parameter), then we would have been able to streamline our refresh process & further limit how many people had prod access. Hope that helps, but let me know if you have any questions!

And I like @mcarvin8's suggestion to use the definition file as a way to change attributes (and if any attributes aren't provided, use the existing sandbox's values).

[shetzel]

@jongpie - thanks, this is great feedback!

[shetzel]

The proposed command assumes auto-activation will be the popular choice. To not auto-activate you would provide, --no-auto-activate. Please let me know if this assumption fits your usecases with 👍 or 👎 .

[mcarvin8]

@shetzel - Does the above proposed command still accept a path to a sandbox definition file for other characteristics like Apex Class ID, Public Group ID, etc?

Having the sandbox name via a command flag is perfect for my use case. But I still would like to be able to set the apex class ID and public group ID for refreshes. Either via a flag or the definition file.

Edit: I'm aware of an existing sandbox selective access bug which is why public groups were removed from the Sandbox Refresh UI. But restoring that would be the biggest roadblock resolver for my use case.

My use case in basics:

• provide sandbox name via command flag
• provide public group ID for selective access (flag or definition file would suffice)
• provide Apex Class Id so I can run my apex class in the sandbox post activation (flag or definition file would suffice)

[mcarvin8]

Before Public Groups were removed, I was able to create and refresh them via SandboxInfo on the tooling api. Roughly a month or so ago.

https://github.com/mcarvin8/prepare-sandboxes

I was also able to run the Apex Class on sandbox creations and refreshes via the tooling api methods as well. This apex class just changed people's profiles in the sandbox and sent their emails password resets. That method is still supported for both creates and refreshes via SandboxInfo.

I'm basically looking for the CLI to replace the project I linked above which was working as required for my use case before Public Groups were removed from SandboxInfo.

[shetzel]

With the exception of ActivationUserGroupId the CLI should be able to do the same thing. I don't control anything about the SandboxInfo API unfortunately so that won't work until they add support back.

As for edits to SandboxInfo during refresh, I'd really like to know how common that usecase is. I know you want that behavior but it can complicate things particularly when the sandbox name is changed as part of a refresh. The name is part of the username and the CLI uses usernames for auth, which has repercussions. So it's definitely possible but it can cause some problems that wouldn't exist without that support. Might be better to just delete the sandbox and create a new one when you want to change the name.

[shetzel]

Unofficially, support for ActivationUserGroupId may return in the Summer '24 release.

[mcarvin8]

Looks like ActivationUserGroupId has been restored in the Sandbox UI in Summer 24/API version 61.

If you're using Simple Salesforce to contact the Tooling API, you have to set the API version to 61 when you make the request to force it to authenticate at the latest version.

@shetzel - Can you check if the Sandbox Definition File that the Salesforce CLI can use for sandbox creations/refreshes can now use ActivationUserGroupId when on API version 61? https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_sandbox_definition.htm doesn't call out Activation User Group ID. I can submit a new issue in this repo if you'd like too.

[shetzel]

Sorry @mcarvin8 I missed this but we'll be adding CLI support for it very soon. 👍

[shetzel]

Here is what the command help looks like for org refresh sandbox. If all goes as planned, it will be in the CLI release candidate tomorrow.

Refresh a sandbox org using the sandbox name.

USAGE
  $ sf org refresh sandbox -o <value> [--json] [--auto-activate] [-w <value> | --async] [-i <value> | ]
    [-n <value>] [-f <value>] [--no-prompt]

FLAGS
  -f, --definition-file=<value>  Path to a sandbox definition file for overriding its configuration when
                                 you refresh it.
  -i, --poll-interval=<seconds>  [default: 30 seconds] Number of seconds to wait between status polling
                                 requests.
  -n, --name=<value>             Name of the existing sandbox org in your production org that you want
                                 to refresh.
  -o, --target-org=<value>       (required) Username or alias of the production org that contains the
                                 sandbox license.
  -w, --wait=<minutes>           [default: 30 minutes] Number of minutes to poll for sandbox refresh
                                 status.
      --async                    Request the sandbox refresh, but don't wait for it to complete.
      --[no-]auto-activate       Activates the sandbox after a successful refresh.
      --no-prompt                Don't prompt for confirmation about the sandbox refresh.

GLOBAL FLAGS
  --json  Format output as json.

DESCRIPTION
  Refresh a sandbox org using the sandbox name.

  Refreshing a sandbox copies the metadata, and optionally data, from your production org to the
  refreshed sandbox org. You can optionally specify a definition file if you want to change the
  configuration of the refreshed sandbox, such as its license type or template ID.

  You're not allowed to change the sandbox name when you refresh it with this command. If you want to
  change the sandbox name, first delete it with the "org delete sandbox" command. And then recreate it
  with the "org create sandbox" command and give it a new name.

EXAMPLES
  Refresh the sandbox named "devSbx1". The production org that contains the sandbox license has the
  alias "prodOrg".

    $ sf org refresh sandbox --name devSbx1 --target-org prodOrg

  Refresh the sandbox named "devSbx2", and override the configuration of the refreshed sandbox with
  the properties in the specified defintion file. The default target org is the production org, so you
  don't need to specify the `--target-org` flag in this case.

    $ sf org refresh sandbox --name devSbx2 --definition-file devSbx2-config.json

  Refresh the sandbox using the name defined in the definition file. The production org that contains
  the sandbox license has the alias "prodOrg".

    $ sf org refresh sandbox --definition-file devSbx3-config.json --target-org prodOrg

FLAG DESCRIPTIONS
  -f, --definition-file=<value>

    Path to a sandbox definition file for overriding its configuration when you refresh it.

    The sandbox definition file is a blueprint for the sandbox; use the file to change the sandbox
    configuration during a refresh. If you don't want to change the sandbox configuration when you
    refresh it, then simply use the --name flag to specify the sandbox and don't use this flag. See
    <https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_sandbox_definitio
    n.htm> for all the options you can specify in the definition file.

  -w, --wait=<minutes>  Number of minutes to poll for sandbox refresh status.

    If the command continues to run after the wait period, the CLI returns control of the terminal to
    you and displays the "sf org resume sandbox" command for you run to check the status of the refresh.
    The displayed command includes the job ID for the running sandbox refresh.

  --async  Request the sandbox refresh, but don't wait for it to complete.

    The command immediately displays the job ID and returns control of the terminal to you. This way,
    you can continue to use the CLI. To check the status of the sandbox refresh, run "sf org resume
    sandbox".

[shetzel]

can we run sf org resume sandbox to log in to the refreshed sandbox, the same way we do after running 'sf org create sandbox' to create one ?

Yes! Absolutely. The caching works the same as well, so you can resume with (e.g.) sf org resume sandbox -l. All other permutations work as well.

Re. sandbox definition file : you might want to make sure that we can use the same file to create a sandbox and later update the same sandbox.

That works too. For an update of a sandbox that was created with that same definition file it wouldn't be necessary since it's the same SandboxInfo details, but you could if you wanted.

[alan-morey]

The usage shows auto-activate is an optional flag.

USAGE
  $ sf org refresh sandbox -o <value> [--json] [--auto-activate] [-w <value> | --async] [-i <value> | ]
    [-n <value>] [-f <value>] [--no-prompt]

Does that mean the sandbox is not going to be auto-activated unless I explicitly use the flag --auto-activate in the command? Based on earlier comments I thought auto-activation would be the default?

It's a little unclear to me, maybe the help just needs to define what is the default behavior here and whether to use --auto-activate or --no-auto-activate to opt in or out of that default.

[shetzel]

@alan-morey - there's a bug in the help text generation for boolean flags with a default value. The command help should be showing that --auto-activate defaults to true but unfortunately doesn't. If you try it out and just cancel at the confirmation prompt you should see AutoActivate: true (unless you're overriding it in a sandbox definition file). That bug should hopefully be fixed very soon. I hardcoded the default at first, then we decided to remove it and fix the bug properly later, but now I'm regretting that decision. It's an excellent callout!

https://github.com/salesforcecli/plugin-org/blob/main/src/commands/org/refresh/sandbox.ts#L52

[shetzel]

I'm going to change the flag to be no-auto-activate instead and update the help text to make it clear what will happen by default. As it is now, it wouldn't make sense to ever use --auto-activate as a flag, so only providing the negative makes more sense.

[alan-morey]

I ran the refresh command today to test it out, I did not specify --auto-activate, the prompt shows the information as you mentioned AutoActivate: true and it activated as expected.
Loving this command, thanks for getting it done @shetzel 🙏

[jshackell-sfdc]

This new feature was released in version 2.31.10 of Salesforce CLI.

[vt89]

The documentation says Refreshing a sandbox copies the metadata, and optionally data, from your production org to the refreshed sandbox org but when I test the command I see the sandbox is refreshed from its Source which might be another sandbox instead of Production.
Is it a typo on the documentation? @shetzel @jshackell-sfdc

[shetzel]

We can update the docs. Thanks for pointing that out.

[jshackell-sfdc]

Fixed in 2.37.4 -- thanks for letting us know!

[vt89]

When the refresh sandbox process is performed using the Salesforce UI is possible to change the sandbox name.
Currently, it is not possible using the sf cli.
Any work in progress about this feature? @shetzel @jshackell-sfdc

[shetzel]

No, this will not be implemented from the CLI. See: #2511 (reply in thread)